buninu 0.4.21 → 0.6.0

package/apps/jsgotty/static/js/kitty-keyboard.js

@@ -0,0 +1,193 @@
+// Kitty keyboard transport for the shipped xterm wrapper (no build step).
+// Spec: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+(function (root) {
+  'use strict';
+  // Supported progressive enhancements: disambiguation, event types, all keys.
+  // Do not advertise alternate-layout/text reporting until those are implemented.
+  const SUPPORTED = 1 | 2 | 8;
+  const functional = {
+    Escape:[27,'u'], Enter:[13,'u'], Tab:[9,'u'], Backspace:[127,'u'],
+    Insert:[2,'~'], Delete:[3,'~'], ArrowLeft:[1,'D'], ArrowRight:[1,'C'],
+    ArrowUp:[1,'A'], ArrowDown:[1,'B'], PageUp:[5,'~'], PageDown:[6,'~'],
+    Home:[1,'H'], End:[1,'F'], CapsLock:[57358,'u'], ScrollLock:[57359,'u'],
+    NumLock:[57360,'u'], PrintScreen:[57361,'u'], Pause:[57362,'u'], ContextMenu:[57363,'u'],
+    MediaPlay:[57428,'u'], MediaPause:[57429,'u'], MediaPlayPause:[57430,'u'],
+    MediaStop:[57432,'u'], MediaFastForward:[57433,'u'], MediaRewind:[57434,'u'],
+    MediaTrackNext:[57435,'u'], MediaTrackPrevious:[57436,'u'], MediaRecord:[57437,'u'],
+    AudioVolumeDown:[57438,'u'], AudioVolumeUp:[57439,'u'], AudioVolumeMute:[57440,'u'],
+  };
+  [11,12,13,14,15,17,18,19,20,21,23,24].forEach((n,i) => functional['F'+(i+1)] = [n,'~']);
+  for (let i=13;i<=35;i++) functional['F'+i] = [57376+i-13,'u'];
+  const punctuation = {
+    Backquote:['`','~'], Minus:['-','_'], Equal:['=','+'], BracketLeft:['[','{'],
+    BracketRight:[']','}'], Backslash:['\\','|'], Semicolon:[';',':'], Quote:["'",'"'],
+    Comma:[',','<'], Period:['.','>'], Slash:['/','?'], Space:[' ',' '],
+  };
+  const modifiers = {Shift:[1,57441], Control:[4,57442], Alt:[2,57443], Meta:[8,57444],
+    OS:[8,57444], Super:[8,57444], Hyper:[16,57445], AltGraph:[0,57453]};
+  const has = (object,key) => Object.prototype.hasOwnProperty.call(object,key);
+  const lock = (e,name) => Boolean(e.getModifierState?.(name));
+  function physicalCode(e) {
+    if (e.code && e.code !== 'Unidentified') return e.code;
+    if (e.keyCode>=65 && e.keyCode<=90) return 'Key'+String.fromCharCode(e.keyCode);
+    if (e.keyCode>=48 && e.keyCode<=57) return 'Digit'+String.fromCharCode(e.keyCode);
+    return ({32:'Space',186:'Semicolon',187:'Equal',188:'Comma',189:'Minus',190:'Period',
+      191:'Slash',192:'Backquote',219:'BracketLeft',220:'Backslash',221:'BracketRight',222:'Quote'})[e.keyCode] || '';
+  }
+  function baseCharacter(e, android) {
+    const code=physicalCode(e);
+    // Android's Alt accent conversion must not turn an E/I/N/U shortcut into a dead key.
+    const recover=android && e.altKey && !lock(e,'AltGraph');
+    if (recover || ([...e.key || ''].length===1 && e.key.codePointAt(0)<32)) {
+      if (/^Key[A-Z]$/.test(code)) return code.slice(3).toLowerCase();
+      if (/^Digit[0-9]$/.test(code)) return code.slice(5);
+      if (has(punctuation,code)) return punctuation[code][0];
+    }
+    if ([...e.key || ''].length!==1) return null;
+    if (e.shiftKey) {
+      if (has(punctuation,code) && punctuation[code][1]===e.key) return punctuation[code][0];
+      if (/^Digit[0-9]$/.test(code) && ')!@#$%^&*('[Number(code.slice(5))]===e.key) return code.slice(5);
+    }
+    const lower=e.key.toLowerCase();
+    return [...lower].length===1 ? lower : e.key;
+  }
+  function keyDefinition(e, flags, android) {
+    if (has(modifiers,e.key)) {
+      const [bit,left]=modifiers[e.key];
+      const right=e.location===2 || /Right$/.test(e.code || '');
+      return {number:left+(right && e.key!=='AltGraph'?6:0),suffix:'u',modifier:bit};
+    }
+    if ((flags & 9) && (e.location===3 || /^Numpad/.test(e.code || ''))) {
+      const numpad={NumpadDecimal:57409,NumpadDivide:57410,NumpadMultiply:57411,
+        NumpadSubtract:57412,NumpadAdd:57413,NumpadEnter:57414,NumpadEqual:57415,
+        NumpadComma:57416};
+      const nav={ArrowLeft:57417,ArrowRight:57418,ArrowUp:57419,ArrowDown:57420,
+        PageUp:57421,PageDown:57422,Home:57423,End:57424,Insert:57425,Delete:57426,Clear:57427};
+      const number=has(nav,e.key)?nav[e.key]:/^Numpad[0-9]$/.test(e.code || '')
+        ?57399+Number(e.code.slice(6)):numpad[e.code];
+      if (number) return {number,suffix:'u'};
+    }
+    if (has(functional,e.key)) {
+      const [number,suffix]=functional[e.key];
+      return {number,suffix,recovery:['Enter','Tab','Backspace'].includes(e.key)};
+    }
+    const ch=baseCharacter(e,android);
+    return ch===null?null:{number:ch.codePointAt(0),suffix:'u',text:true};
+  }
+  class KittyKeyboard {
+    constructor(term, {android=false}={}) {
+      this.term=term; this.android=android; this.disposables=[];
+      this.metaKeys=new Set(); this.down=new Map(); this.suppressed=new Set(); this.reset();
+      const register=(prefix,fn) => this.disposables.push(term.parser.registerCsiHandler({prefix,final:'u'},p=>{fn(p);return true;}));
+      const value=(p,i,fallback=0) => Number.isInteger(p[i])?p[i]:fallback;
+      register('?',()=>term.input(`\x1b[?${this.flags}u`,false));
+      register('>',p=>{const s=this.state;s.stack.push(s.flags);if(s.stack.length>32)s.stack.shift();s.flags=value(p,0)&SUPPORTED;});
+      register('<',p=>{const s=this.state;let count=Math.min(value(p,0)||1,33);while(count--)s.flags=s.stack.pop()??0;});
+      register('=',p=>{const s=this.state,f=value(p,0)&SUPPORTED,m=value(p,1)||1;if(m===1)s.flags=f;else if(m===2)s.flags|=f;else if(m===3)s.flags&=~f;});
+      this.disposables.push(term.parser.registerEscHandler({final:'c'},()=>{this.reset();return false;}));
+      this.disposables.push(term.parser.registerCsiHandler({intermediates:'!',final:'p'},()=>{this.reset();return false;}));
+    }
+    get state() { return this.states[this.term.buffer.active.type==='alternate'?'alternate':'normal']; }
+    get flags() { return this.state.flags; }
+    reset() {
+      this.states={normal:{flags:0,stack:[]},alternate:{flags:0,stack:[]}};
+      this.clearHeld(false);
+    }
+    clearHeld(report=true) {
+      // Release keys reported to the client before losing focus, avoiding stuck remote keys.
+      if (report && (this.flags & 2)) for (const key of this.down.values()) {
+        if(key.reported) this.term.input(this.sequence(key.def,0,3),true);
+      }
+      this.metaKeys.clear();this.down.clear();this.suppressed.clear();this.suppressKeypress=false;
+    }
+    attach(element) {
+      const doc=element.ownerDocument, win=doc.defaultView;
+      const blur=()=>this.clearHeld();
+      const visibility=()=>{if(doc.hidden)this.clearHeld();};
+      element.addEventListener('blur',blur);win.addEventListener('blur',blur);
+      doc.addEventListener('visibilitychange',visibility);
+      this.disposables.push({dispose:()=>{element.removeEventListener('blur',blur);win.removeEventListener('blur',blur);doc.removeEventListener('visibilitychange',visibility);}});
+    }
+    dispose() {this.clearHeld(false);for(const d of this.disposables)d.dispose();}
+    sequence(def,bits,type) {
+      const event=(this.flags&2) && type!==1?':'+type:'';
+      const mods=bits+1;
+      if(def.suffix!=='u' && mods===1 && !event)
+        return '\x1b['+(def.number===1?'':def.number)+def.suffix;
+      return `\x1b[${def.number}${mods!==1||event?';'+mods+event:''}${def.suffix}`;
+    }
+    handle(event) {
+      if (!['keydown','keyup','keypress'].includes(event.type)) return true;
+      const identity=physicalCode(event)||event.key;
+      const metaKey=['Meta','OS','Super'].includes(event.key);
+      if(this.android && metaKey) {
+        if(event.type==='keydown')this.metaKeys.add(event.code||String(event.location||0));
+        if(event.type==='keyup')this.metaKeys.delete(event.code||String(event.location||0));
+      }
+      // Patch only this terminal's Android event, preserving the native DOM event.
+      if(this.android && this.metaKeys.size && !event.metaKey) {
+        const original=event.getModifierState?.bind(event);
+        Object.defineProperties(event,{
+          metaKey:{configurable:true,value:true},
+          getModifierState:{configurable:true,value:name=>name==='Meta'||Boolean(original?.(name))},
+        });
+      }
+      if(!this.flags || this.term.options.disableStdin) return true;
+      const consume=()=>{event.preventDefault();event.stopPropagation();return false;};
+      if(event.type==='keypress')return this.suppressKeypress?consume():true;
+      let previous=this.down.get(identity);
+      if(event.type==='keyup') {
+        // Some Android IMEs emit only the release of an Alt dead key. Recover
+        // that chord here too, never falling back to legacy ESC text in Kitty mode.
+        if(!previous && this.android && event.altKey && event.key==='Dead' &&
+           !event.isComposing && !lock(event,'AltGraph') && (this.flags&9)) {
+          const def=keyDefinition(event,this.flags,this.android);
+          if(def) {
+            this.term.input(this.sequence(def,this.bits(event),1),true);
+            previous={def,reported:true};this.suppressed.add(identity);
+          }
+        }
+        this.down.delete(identity);
+        const suppressed=this.suppressed.delete(identity);
+        this.suppressKeypress=false;
+        if(previous?.reported && (this.flags&2)) {
+          let bits=this.bits(event);
+          if(previous.def.modifier && ![...this.down.values()].some(k=>k.def.modifier===previous.def.modifier)) bits &= ~previous.def.modifier;
+          if(metaKey && this.metaKeys.size) bits|=8;
+          this.term.input(this.sequence(previous.def,bits,3),true);
+        }
+        return suppressed?consume():true;
+      }
+      this.suppressKeypress=false;
+      if(event.isComposing || event.keyCode===229 && event.key==='Unidentified')return true;
+      if(event.key==='Dead' && !(this.android && event.altKey && !lock(event,'AltGraph')))return true;
+      const def=keyDefinition(event,this.flags,this.android);
+      if(!def)return true;
+      let bits=this.bits(event);
+      if(def.modifier!==undefined) {
+        if(!(this.flags&8))return true;
+        bits|=def.modifier;
+      }
+      const all=Boolean(this.flags&8);
+      // Enter/Tab/Backspace remain recovery keys unless modified or report-all is requested.
+      if(!all && def.recovery && !(bits&~192))return true;
+      const shortcut=Boolean(bits&62);
+      if(def.text && !all && !(this.flags&1 && shortcut))return true;
+      // With only event reporting requested, leave legacy printable shortcuts untouched.
+      if(def.text && !all && !(this.flags&1))return true;
+      const type=event.repeat?2:1;
+      this.down.set(identity,{def,reported:!(def.recovery && !all)});this.suppressed.add(identity);this.suppressKeypress=true;
+      this.term.input(this.sequence(def,bits,type),true);
+      return consume();
+    }
+    bits(e) {
+      const altgr=lock(e,'AltGraph');
+      return (e.shiftKey?1:0)|(!altgr&&e.altKey?2:0)|(!altgr&&e.ctrlKey?4:0)|
+        (e.metaKey || this.android&&this.metaKeys.size?8:0)|
+        (lock(e,'Hyper')?16:0)|(lock(e,'CapsLock')?64:0)|(lock(e,'NumLock')?128:0);
+    }
+  }
+  const api={KittyKeyboard,SUPPORTED};
+  if(typeof module==='object' && module.exports)module.exports=api;
+  else root.GoTTYKittyKeyboard=api;
+})(globalThis);

package/apps/jsgotty/terminal-modes.js

@@ -0,0 +1,332 @@
+"use strict";
+
+// All flags defined by the kitty keyboard protocol. Kept unmasked so a CLI
+// client on a real kitty terminal can restore them; the browser masks its own.
+const KITTY_KEYBOARD_FLAGS = 0x1f;
+const TRACKED_DEC_FLAGS = {
+  1: "applicationCursorKeys",
+  6: "origin",
+  7: "wraparound",
+  45: "reverseWraparound",
+  66: "applicationKeypad",
+  1004: "sendFocus",
+  2004: "bracketedPasteMode",
+};
+const MOUSE_PROTOCOLS = { 9: "X10", 1000: "VT200", 1002: "DRAG", 1003: "ANY" };
+const MOUSE_ENCODINGS = { 1006: "SGR", 1016: "SGR_PIXELS" };
+
+// Mirrors the PTY's input/protocol modes so a resumed client can be brought
+// back in sync. Mode semantics follow xterm.js, which renders the output.
+class TerminalModeTracker {
+  constructor() {
+    this.reset();
+    this._state = "text";
+    this._seq = "";
+  }
+
+  reset() {
+    this.dec = {
+      applicationCursorKeys: false,
+      applicationKeypad: false,
+      bracketedPasteMode: false,
+      origin: false,
+      reverseWraparound: false,
+      sendFocus: false,
+      wraparound: true,
+    };
+    this.cursorHidden = false;
+    this.mouse = "NONE";
+    this.encoding = "DEFAULT";
+    this.alternate = false;
+    this.kitty = { normal: { flags: 0, stack: [] }, alternate: { flags: 0, stack: [] } };
+  }
+
+  snapshot() {
+    return {
+      dec: { ...this.dec },
+      cursorHidden: this.cursorHidden,
+      mouse: this.mouse,
+      encoding: this.encoding,
+      alternate: this.alternate,
+      kitty: {
+        normal: { flags: this.kitty.normal.flags, stack: [...this.kitty.normal.stack] },
+        alternate: { flags: this.kitty.alternate.flags, stack: [...this.kitty.alternate.stack] },
+      },
+    };
+  }
+
+  consume(buffer) {
+    // Control sequences are ASCII, so bytes can be scanned without UTF-8 decoding.
+    for (let i = 0; i < buffer.length; i += 1) {
+      const byte = buffer[i];
+      switch (this._state) {
+        case "text":
+          if (byte === 0x1b) {
+            this._state = "esc";
+          }
+          break;
+        case "esc":
+          if (byte === 0x5b) {
+            this._state = "csi";
+            this._seq = "";
+          } else if (byte === 0x5d || byte === 0x50 || byte === 0x5f || byte === 0x5e || byte === 0x58) {
+            this._state = "string";
+            this._osc = byte === 0x5d ? "" : null;
+          } else if (byte === 0x1b) {
+            this._state = "esc";
+          } else if (byte >= 0x20 && byte <= 0x2f) {
+            this._state = "esc-intermediate";
+          } else {
+            this._state = "text";
+            this.handleEsc(byte);
+          }
+          break;
+        case "esc-intermediate":
+          if (byte < 0x20 || byte > 0x2f) {
+            this._state = byte === 0x1b ? "esc" : "text";
+          }
+          break;
+        case "csi":
+          if (byte >= 0x40 && byte <= 0x7e) {
+            this._state = "text";
+            this.handleCsi(this._seq, String.fromCharCode(byte));
+          } else if (byte === 0x1b) {
+            this._state = "esc";
+          } else if (byte === 0x18 || byte === 0x1a || this._seq.length >= 64) {
+            this._state = "text";
+          } else if (byte >= 0x20) {
+            this._seq += String.fromCharCode(byte);
+          }
+          break;
+        case "string":
+          if (byte === 0x07 || byte === 0x18 || byte === 0x1a) {
+            if (byte === 0x07) this.handleOsc();
+            this._state = "text";
+          } else if (byte === 0x1b) {
+            this._state = "string-esc";
+          } else if (this._osc != null) {
+            this._osc = this._osc.length < 256 ? this._osc + String.fromCharCode(byte) : null;
+          }
+          break;
+        case "string-esc":
+          if (byte === 0x5c) this.handleOsc();
+          else this._osc = null;
+          this._state = byte === 0x1b ? "string-esc" : byte === 0x5c ? "text" : "string";
+          break;
+      }
+    }
+  }
+
+  handleOsc() {
+    const match = /^777;jsgotty-kitty-v1;(normal|alternate);(\d{1,2});(\d{1,2}(?:,\d{1,2})*)?$/.exec(this._osc || '');
+    if (!match) return;
+    const flags = +match[2], stack = match[3] ? match[3].split(',').map(Number) : [];
+    if (flags > 31 || stack.length > 32 || stack.some(n=>n > 31)) return;
+    this.kitty[match[1]] = {flags, stack};
+  }
+
+  handleEsc(byte) {
+    if (byte === 0x3d) {
+      this.dec.applicationKeypad = true;
+    } else if (byte === 0x3e) {
+      this.dec.applicationKeypad = false;
+    } else if (byte === 0x63) {
+      this.reset();
+    }
+  }
+
+  handleCsi(seq, final) {
+    const prefix = /^[<=>?]/.test(seq) ? seq[0] : "";
+    const body = prefix ? seq.slice(1) : seq;
+    if (!/^[0-9;:]*$/.test(body)) {
+      if (body === "!" && final === "p") {
+        this.softReset();
+      }
+      return;
+    }
+    const params = body === "" ? [] : body.split(";").map((part) => {
+      const value = Number.parseInt(part, 10);
+      return Number.isFinite(value) ? value : 0;
+    });
+    if (prefix === "?" && (final === "h" || final === "l")) {
+      for (const mode of params) {
+        this.setPrivateMode(mode, final === "h");
+      }
+    } else if (final === "u" && prefix !== "?") {
+      this.handleKittyKeyboard(prefix, params);
+    }
+  }
+
+  softReset() {
+    // DECSTR keeps the active screen and mouse reporting, like xterm.js.
+    const { alternate, mouse, encoding } = this;
+    this.reset();
+    Object.assign(this, { alternate, mouse, encoding });
+  }
+
+  setPrivateMode(mode, enabled) {
+    if (TRACKED_DEC_FLAGS[mode]) {
+      this.dec[TRACKED_DEC_FLAGS[mode]] = enabled;
+    } else if (MOUSE_PROTOCOLS[mode]) {
+      this.mouse = enabled ? MOUSE_PROTOCOLS[mode] : "NONE";
+    } else if (MOUSE_ENCODINGS[mode]) {
+      this.encoding = enabled ? MOUSE_ENCODINGS[mode] : "DEFAULT";
+    } else if (mode === 25) {
+      this.cursorHidden = !enabled;
+    } else if (mode === 47 || mode === 1047 || mode === 1049) {
+      this.alternate = enabled;
+    }
+  }
+
+  handleKittyKeyboard(prefix, params) {
+    const state = this.kitty[this.alternate ? "alternate" : "normal"];
+    const value = (index, fallback = 0) => (Number.isInteger(params[index]) ? params[index] : fallback);
+    if (prefix === ">") {
+      state.stack.push(state.flags);
+      if (state.stack.length > 32) {
+        state.stack.shift();
+      }
+      state.flags = value(0) & KITTY_KEYBOARD_FLAGS;
+    } else if (prefix === "<") {
+      let count = Math.min(value(0) || 1, 33);
+      while (count--) {
+        state.flags = state.stack.pop() ?? 0;
+      }
+    } else if (prefix === "=") {
+      const flags = value(0) & KITTY_KEYBOARD_FLAGS;
+      const mode = value(1) || 1;
+      if (mode === 1) {
+        state.flags = flags;
+      } else if (mode === 2) {
+        state.flags |= flags;
+      } else if (mode === 3) {
+        state.flags &= ~flags;
+      }
+    }
+  }
+}
+
+const DEFAULT_MODES = new TerminalModeTracker().snapshot();
+const MOUSE_PROTOCOL_MODES = { X10: 9, VT200: 1000, DRAG: 1002, ANY: 1003 };
+const MOUSE_ENCODING_MODES = { SGR: 1006, SGR_PIXELS: 1016 };
+
+function sameKitty(a, b) {
+  return a.flags === b.flags && a.stack.length === b.stack.length &&
+    a.stack.every((flags, index) => flags === b.stack[index]);
+}
+
+// Work only on the observed stack; never pop an arbitrary number of entries.
+// With a terminal that cannot report its stack, [] denotes the unseen baseline.
+function kittyTransition(from, to) {
+  if (to.flags == null) return "";
+  let common = 0;
+  while (common < from.stack.length && common < to.stack.length &&
+    from.stack[common] === to.stack[common]) common++;
+  let sequence = "";
+  let flags = from.flags;
+  const pops = from.stack.length - common;
+  if (pops) {
+    sequence += `\x1b[<${pops}u`;
+    flags = from.stack[common];
+  }
+  const first = to.stack[common] ?? to.flags;
+  if (flags !== first) sequence += `\x1b[=${first};1u`;
+  for (let i = common; i < to.stack.length; i++)
+    sequence += `\x1b[>${to.stack[i + 1] ?? to.flags}u`;
+  return sequence;
+}
+
+// Escape sequence that moves a terminal known to be in `from` to `to`, emitting
+// only differences: DECOM homes the cursor and 1049 overwrites the saved cursor.
+function modeTransition(from, to = DEFAULT_MODES, { normalizeMouse = false, kittyRestore = false } = {}) {
+  let sequence = "";
+  const fromScreen = from.alternate ? "alternate" : "normal";
+  const toScreen = to.alternate ? "alternate" : "normal";
+  // Kitty keyboard stacks are per screen, so each is fixed while it is active.
+  if (from.alternate != null && !sameKitty(from.kitty[fromScreen], to.kitty[fromScreen])) {
+    sequence += kittyTransition(from.kitty[fromScreen], to.kitty[fromScreen]);
+  }
+  if (to.alternate != null && from.alternate !== to.alternate) {
+    sequence += `\x1b[?1049${to.alternate ? "h" : "l"}`;
+    if (!sameKitty(from.kitty[toScreen], to.kitty[toScreen])) {
+      sequence += kittyTransition(from.kitty[toScreen], to.kitty[toScreen]);
+    }
+  }
+  const inactive = toScreen === "normal" ? "alternate" : "normal";
+  // Switching screens just to edit a hidden stack destroys alternate contents.
+  // Only emit this extension after the actual terminal advertised support.
+  const hidden = to.kitty[inactive];
+  if (kittyRestore && from.alternate != null && to.alternate != null && fromScreen === toScreen &&
+      !sameKitty(from.kitty[inactive], hidden) && hidden.flags != null && hidden.stack.every(Number.isInteger)) {
+    sequence += `\x1b]777;jsgotty-kitty-v1;${inactive};${hidden.flags};${hidden.stack.join(',')}\x07`;
+  }
+  for (const [mode, name] of Object.entries(TRACKED_DEC_FLAGS)) {
+    if (to.dec[name] == null || from.dec[name] === to.dec[name]) {
+      continue;
+    }
+    if (name === "applicationKeypad") {
+      sequence += to.dec[name] ? "\x1b=" : "\x1b>"; // more widely supported than ?66
+    } else {
+      sequence += `\x1b[?${mode}${to.dec[name] ? "h" : "l"}`;
+    }
+  }
+  if (to.cursorHidden != null && from.cursorHidden !== to.cursorHidden) {
+    sequence += `\x1b[?25${to.cursorHidden ? "l" : "h"}`;
+  }
+  // Raw query results preserve independent switches on native terminals. Reset
+  // first, then enable in priority order so exclusive terminals also end in the
+  // intended effective mode. Unanswered switches are never guessed.
+  for (const [name, bitsName, table] of [
+    ['mouse', 'mouseModeBits', MOUSE_PROTOCOL_MODES],
+    ['encoding', 'mouseEncodingBits', MOUSE_ENCODING_MODES],
+  ]) {
+    const bits = to[bitsName];
+    if (bits) {
+      for (const mode of Object.values(table))
+        if (bits[mode] === false) sequence += `\x1b[?${mode}l`;
+      for (const mode of Object.values(table))
+        if (bits[mode] === true) sequence += `\x1b[?${mode}h`;
+    } else if (to[name] != null && (normalizeMouse || from[name] !== to[name])) {
+      for (const mode of Object.values(table)) sequence += `\x1b[?${mode}l`;
+      if (table[to[name]]) sequence += `\x1b[?${table[to[name]]}h`;
+    }
+  }
+  return sequence;
+}
+
+function validateSnapshot(value) {
+  if (!value || !value.dec || !value.kitty) throw Error("Invalid terminal modes");
+  const result = new TerminalModeTracker().snapshot();
+  for (const key of Object.values(TRACKED_DEC_FLAGS)) {
+    if (typeof value.dec[key] !== 'boolean' && value.dec[key] !== null) throw Error("Invalid DEC mode");
+    result.dec[key] = value.dec[key];
+  }
+  for (const key of ['alternate', 'cursorHidden']) {
+    if (typeof value[key] !== 'boolean' && value[key] !== null) throw Error("Invalid screen mode");
+    result[key] = value[key];
+  }
+  for (const [key, choices] of [['mouse', ['NONE', ...Object.values(MOUSE_PROTOCOLS)]], ['encoding', ['DEFAULT', ...Object.values(MOUSE_ENCODINGS)]]]) {
+    if (value[key] !== null && !choices.includes(value[key])) throw Error("Invalid mouse mode");
+    result[key] = value[key];
+  }
+  for (const [key, table] of [['mouseModeBits', MOUSE_PROTOCOLS], ['mouseEncodingBits', MOUSE_ENCODINGS]]) {
+    if (value[key] === undefined) continue;
+    if (!value[key] || typeof value[key] !== 'object') throw Error('Invalid mouse bits');
+    result[key] = {};
+    for (const mode of Object.keys(table)) {
+      const bit = value[key][mode];
+      if (bit !== null && typeof bit !== 'boolean') throw Error('Invalid mouse bit');
+      result[key][mode] = bit;
+    }
+  }
+  for (const key of ['normal', 'alternate']) {
+    const state = value.kitty[key];
+    const flag = n => Number.isInteger(n) && n >= 0 && n <= KITTY_KEYBOARD_FLAGS;
+    if (!state || (state.flags !== null && !flag(state.flags)) || !Array.isArray(state.stack) ||
+      state.stack.length > 32 || !state.stack.every(n => n === null || flag(n))) throw Error("Invalid Kitty state");
+    result.kitty[key] = {flags: state.flags, stack: [...state.stack]};
+  }
+  return result;
+}
+
+module.exports = { TerminalModeTracker, modeTransition, validateSnapshot, TRACKED_DEC_FLAGS, MOUSE_PROTOCOLS, MOUSE_ENCODINGS };

package/apps/jsgotty/tests/android-alt.test.js

@@ -0,0 +1,115 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const vm = require('node:vm');
+const path = require('node:path');
+
+// Exercise the shipped bundle's wrapper method, without a DOM or new dependencies.
+const bundle = fs.readFileSync(path.join(__dirname, '../static/js/gotty.js'), 'utf8');
+const start = bundle.indexOf('          handleAndroidAltKey(event) {');
+assert.ok(start >= 0);
+const end = bundle.indexOf('          info() {', start);
+assert.ok(end > start);
+const method = bundle.slice(start, end);
+function setup(userAgent = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 wv') {
+  const handler = vm.runInNewContext(`({${method}}).handleAndroidAltKey`, {
+    navigator: { userAgent },
+  });
+  const sent = [];
+  const target = { term: { input: (text, userInput) => sent.push([text, userInput]) } };
+  function dispatch(overrides = {}) {
+    const event = {
+      type: 'keydown', code: 'KeyE', key: 'Dead', keyCode: 69,
+      altKey: true, ctrlKey: false, metaKey: false, shiftKey: false,
+      isComposing: false, getModifierState: () => false,
+      prevented: false, stopped: false,
+      preventDefault() { this.prevented = true; },
+      stopPropagation() { this.stopped = true; },
+      ...overrides,
+    };
+    return { result: handler.call(target, event), event };
+  }
+  return { sent, dispatch };
+}
+
+test('Android accent shortcuts emit one ESC sequence; keypress/keyup do not duplicate it', () => {
+  for (const letter of ['E', 'I', 'N', 'U']) {
+    for (const keyCode of [letter.charCodeAt(0), 229]) {
+      const { sent, dispatch } = setup();
+      const { event, result } = dispatch({ code: `Key${letter}`, keyCode });
+      assert.equal(result, false);
+      assert.equal(event.prevented, true);
+      assert.equal(event.stopped, true);
+      dispatch({ type: 'keypress', code: `Key${letter}`, keyCode });
+      dispatch({ type: 'keyup', code: `Key${letter}`, keyCode });
+      assert.deepEqual(sent, [[`\x1b${letter.toLowerCase()}`, true]]);
+      // No dead-key state is retained in this handler for the next ordinary key.
+      assert.equal(dispatch({ altKey: false, key: 'e' }).result, true);
+      assert.equal(sent.length, 1);
+    }
+  }
+});
+
+test('all printable physical Alt keys bypass dead-key handling, including Shift and repeat', () => {
+  const { sent, dispatch } = setup();
+  for (const [code, shiftKey, expected] of [
+    ['KeyA', false, 'a'], ['KeyE', true, 'E'], ['Digit0', false, '0'],
+    ['Digit1', true, '!'], ['Digit0', true, ')'], ['Quote', false, "'"],
+    ['Backquote', true, '~'], ['Backslash', false, '\\'], ['Space', false, ' '],
+  ]) {
+    dispatch({ code, shiftKey, key: 'Dead' });
+    assert.deepEqual(sent.at(-1), [`\x1b${expected}`, true]);
+  }
+  dispatch({ code: 'KeyE', key: 'é', repeat: true });
+  assert.deepEqual(sent.at(-1), ['\x1be', true]);
+});
+
+test('composition, AltGr, other modifiers, and unmapped keys retain existing handling', () => {
+  for (const overrides of [
+    { isComposing: true, keyCode: 229 }, { getModifierState: key => key === 'AltGraph' },
+    { altKey: false }, { ctrlKey: true }, { metaKey: true },
+    { code: '', keyCode: 229 }, { code: 'ArrowLeft' }, { code: 'Enter' },
+    { code: 'Unidentified', keyCode: 229 }, { code: 'toString' },
+    { type: 'keyup', key: 'e' },
+  ]) {
+    const { sent, dispatch } = setup();
+    const { result, event } = dispatch(overrides);
+    assert.equal(result, true);
+    assert.equal(event.prevented, false);
+    assert.deepEqual(sent, []);
+  }
+});
+
+test('non-Android browsers retain existing Alt/dead-key handling', () => {
+  for (const ua of ['Mozilla/5.0 (X11; Linux x86_64)', 'Mozilla/5.0 (Macintosh)', 'Windows']) {
+    const { sent, dispatch } = setup(ua);
+    assert.equal(dispatch().result, true);
+    assert.deepEqual(sent, []);
+  }
+});
+
+// Replay the actual Android 16 WebView trace: no letter keydown and empty code.
+test('Android keyup-only dead keys use legacy keyCode, and ordinary IME input stays untouched', () => {
+  const { sent, dispatch } = setup();
+  for (const keyCode of [69, 78, 85, 73]) {
+    dispatch({ type: 'keydown', code: '', key: 'Alt', keyCode: 18 });
+    assert.equal(dispatch({ type: 'keyup', code: '', key: 'Dead', keyCode }).result, false);
+    dispatch({ type: 'keyup', code: '', key: 'Alt', keyCode: 18 });
+  }
+  assert.deepEqual(sent, ['e', 'n', 'u', 'i'].map(c => ['\x1b' + c, true]));
+  assert.equal(dispatch({ code: '', key: 'Unidentified', keyCode: 229, altKey: false }).result, true);
+  assert.equal(sent.length, 4);
+});
+
+test('legacy keydown plus dead keyup emits once, even with different code availability', () => {
+  for (const [downCode, upCode] of [['', ''], ['KeyE', ''], ['', 'KeyE']]) {
+    const { sent, dispatch } = setup();
+    dispatch({ code: downCode, keyCode: 69 });
+    dispatch({ type: 'keypress', code: downCode, keyCode: 69 });
+    dispatch({ type: 'keyup', code: upCode, keyCode: 69 });
+    assert.deepEqual(sent, [['\x1be', true]]);
+    // The next keyup-only shortcut must not be suppressed by the preceding press.
+    dispatch({ type: 'keyup', code: '', keyCode: 69 });
+    assert.equal(sent.length, 2);
+  }
+});