buninu 0.4.21 → 0.6.0

package/apps/jsgotty/tests/manual/keyboard-debug.js

@@ -0,0 +1,74 @@
+// Manually loaded diagnostic helper. Never loaded by the production frontend.
+window.startGottyKeyboardDebug = ({ endpoint, term } = {}) => {
+  window.stopGottyKeyboardDebug?.();
+  term ??= Array.from(document.querySelectorAll("*")).find(el => el.__gottyXterm)?.__gottyXterm;
+  if (!term) throw new Error("No jsgotty xterm found; connect the terminal first.");
+  const listeners = [];
+  let stopped = false;
+  const records = [];
+  const started = Date.now();
+  const session = Math.random().toString(36).slice(2);
+  window.__gottyKeyboardRecords = records;
+  window.__gottyKeyboardDebug = (stage, details = {}) => {
+    if (stopped || records.length >= 2000 || Date.now() - started > 600000) return;
+    const record = { session, sequence: records.length, time: new Date().toISOString(), stage, ...details };
+    records.push(record);
+    console.log("[gotty-keyboard]", record);
+    if (endpoint) fetch(endpoint, {
+      method: "POST", headers: { "Content-Type": "text/plain" },
+      body: JSON.stringify(record),
+    }).catch(error => { window.__gottyKeyboardDeliveryError = String(error); });
+  };
+  window.__gottyKeyboardDebug("ready", {
+    userAgent: navigator.userAgent, platform: navigator.platform,
+    userAgentData: navigator.userAgentData?.platform,
+  });
+  for (const type of ["keydown", "keypress", "keyup", "beforeinput", "input",
+    "compositionstart", "compositionupdate", "compositionend"]) {
+    const listener = event => {
+      const details = {
+        type, key: event.key, code: event.code, keyCode: event.keyCode,
+        charCode: event.charCode, which: event.which, altKey: event.altKey,
+        ctrlKey: event.ctrlKey, metaKey: event.metaKey, shiftKey: event.shiftKey,
+        altGraph: event.getModifierState?.("AltGraph"),
+        isComposing: event.isComposing, repeat: event.repeat,
+        cancelable: event.cancelable, defaultPrevented: event.defaultPrevented,
+        inputType: event.inputType, data: event.data?.slice(0, 64),
+        target: event.target?.tagName, trusted: event.isTrusted,
+      };
+      window.__gottyKeyboardDebug("capture", details);
+      setTimeout(() => window.__gottyKeyboardDebug("after-dispatch", {
+        ...details, defaultPrevented: event.defaultPrevented,
+      }));
+    };
+    window.addEventListener(type, listener, true);
+    listeners.push([type, listener]);
+  }
+  // Preserve the existing Android handler, including its return value.
+  const previousHandler = term._core?._customKeyEventHandler;
+  if (!term._core) throw new Error("Unsupported xterm internals");
+  const handler = event => {
+    const result = previousHandler ? previousHandler.call(term._core, event) : true;
+    window.__gottyKeyboardDebug("alt-handler", {
+      type: event.type, key: event.key, code: event.code,
+      result, defaultPrevented: event.defaultPrevented,
+    });
+    return result;
+  };
+  term.attachCustomKeyEventHandler(handler);
+  const subscription = term.onData(text => {
+    const bytes = new TextEncoder().encode(text);
+    window.__gottyKeyboardDebug("terminal-data", {
+      length: bytes.length, bytes: Array.from(bytes.slice(0, 64)),
+    });
+  });
+  window.stopGottyKeyboardDebug = () => {
+    stopped = true;
+    for (const [type, listener] of listeners) window.removeEventListener(type, listener, true);
+    subscription.dispose();
+    if (term._core._customKeyEventHandler === handler)
+      term.attachCustomKeyEventHandler(previousHandler);
+  };
+  return { records, stop: window.stopGottyKeyboardDebug };
+};
+

package/apps/jsgotty/tests/manual/kitty-keyboard.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Run inside jsgotty. Exits after 60 seconds or unmodified Escape/q/Ctrl-C.
+// Uses only built-ins and restores the prior Kitty mode and raw mode on exit.
+const input=process.stdin, output=process.stdout;
+const cyan = '\x1b[96m', reset = '\x1b[0m';
+const keyNames = {
+  9: 'tab', 13: 'enter', 27: 'esc', 32: 'space', 127: 'backspace',
+  57358: 'caps-lock', 57359: 'scroll-lock', 57360: 'num-lock',
+  57361: 'print-screen', 57362: 'pause', 57363: 'menu',
+  57409: 'kp-decimal', 57410: 'kp-divide', 57411: 'kp-multiply',
+  57412: 'kp-subtract', 57413: 'kp-add', 57414: 'kp-enter',
+  57415: 'kp-equal', 57416: 'kp-separator',
+  57417: 'kp-left', 57418: 'kp-right', 57419: 'kp-up', 57420: 'kp-down',
+  57421: 'kp-page-up', 57422: 'kp-page-down', 57423: 'kp-home',
+  57424: 'kp-end', 57425: 'kp-insert', 57426: 'kp-delete', 57427: 'kp-begin',
+  57428: 'media-play', 57429: 'media-pause', 57430: 'media-play-pause',
+  57431: 'media-reverse', 57432: 'media-stop', 57433: 'media-fast-forward',
+  57434: 'media-rewind', 57435: 'media-next', 57436: 'media-previous',
+  57437: 'media-record', 57438: 'volume-down', 57439: 'volume-up',
+  57440: 'volume-mute', 57453: 'altgr', 57454: 'iso-level5-shift',
+};
+for (let n=13; n<=35; n++) keyNames[57376+n-13] = 'f'+n;
+for (let n=0; n<=9; n++) keyNames[57399+n] = 'kp-'+n;
+const modifierKeys = ['shift', 'ctrl', 'alt', 'super', 'hyper', 'meta'];
+const modifierBits = [1, 4, 2, 8, 16, 32];
+function readableChord(key, suffix, bits) {
+  const number = Number(key.split(':')[0] || 1);
+  let name;
+  if (suffix === 'u') {
+    if (number >= 57441 && number <= 57452) {
+      const index = (number-57441)%6;
+      name = modifierKeys[index] + (number >= 57447 ? '-right' : '-left');
+      bits &= ~modifierBits[index]; // "super-left", not "super-super-left".
+    } else {
+      name = keyNames[number];
+      if (!name) name = number >= 33 && number <= 0x10ffff &&
+        !(number >= 0x7f && number <= 0x9f) &&
+        !(number >= 0xd800 && number <= 0xf8ff)
+        ? String.fromCodePoint(number) : 'key-'+number;
+    }
+  } else if (suffix === '~') {
+    name = {2:'insert', 3:'delete', 5:'page-up', 6:'page-down', 7:'home', 8:'end',
+      11:'f1', 12:'f2', 13:'f3', 14:'f4', 15:'f5', 17:'f6',
+      18:'f7', 19:'f8', 20:'f9', 21:'f10', 23:'f11', 24:'f12'}[number];
+  } else {
+    name = {A:'up', B:'down', C:'right', D:'left', E:'begin',
+      F:'end', H:'home', P:'f1', Q:'f2', S:'f4'}[suffix];
+  }
+  const modifiers = [[4,'ctrl'], [2,'alt'], [1,'shift'], [8,'super'],
+    [16,'hyper'], [32,'meta'], [64,'caps-lock'], [128,'num-lock']]
+    .filter(([bit]) => bits & bit).map(([,label]) => label);
+  return [...modifiers, name || `key-${number}${suffix}`].join('-');
+}
+if(!input.isTTY || !output.isTTY) {console.error('Run this inside an interactive jsgotty terminal.');process.exit(1);}
+const wasRaw=Boolean(input.isRaw);let closed=false,buffer='';
+const finish=()=>{if(closed)return;closed=true;clearTimeout(timer);output.write('\x1b[<u\r\nKeyboard mode restored.\r\n');input.setRawMode(wasRaw);input.pause();};
+const timer=setTimeout(finish,60000);
+process.on('SIGINT',finish);process.on('SIGTERM',finish);process.on('exit',finish);
+input.setRawMode(true);input.setEncoding('utf8');input.resume();
+output.write('Kitty keyboard test: try SUP, CTRL, ALT, SHFT + letters/arrows.\r\nEscape, q or Ctrl-C exits; automatic exit in 60 seconds.\r\n\x1b[>11u\x1b[?u');
+input.on('data',data=>{
+ if(closed)return;
+ buffer+=data;
+ while(buffer) {
+  const match=/^\x1b\[([?]?)([0-9:;]*)([u~A-Z])/.exec(buffer);
+  if(!match) {
+   if(buffer==='\x1b' || /^\x1b\[[?0-9:;]*$/.test(buffer))break;
+   const ch=[...buffer][0];buffer=buffer.slice(ch.length);output.write('legacy '+JSON.stringify(ch)+'\r\n');
+   if(ch==='q'||ch==='\x03') {finish();return;}continue;
+  }
+  buffer=buffer.slice(match[0].length);
+  if(match[1]==='?'){output.write('negotiated flags='+match[2]+' (expected 11)\r\n');continue;}
+  const [key,mod='1']=match[2].split(';');const [encoded,type='1']=mod.split(':');const bits=Number(encoded)-1;
+  const names=[[1,'Shift'],[2,'Alt'],[4,'Ctrl'],[8,'Super'],[16,'Hyper'],[32,'Meta'],[64,'CapsLock'],[128,'NumLock']].filter(([bit])=>bits&bit).map(([,name])=>name);
+  const chord = readableChord(key, match[3], bits);
+  output.write(`${cyan}${chord}${reset}  ${{1:'press',2:'repeat',3:'release'}[type]||type}  raw=${JSON.stringify(match[0])} key=${key}${match[3]} modifiers=${names.join('+')||'none'}\r\n`);
+  if(match[3]==='u' && type==='1' && ((!(bits&63)&&['27','113'].includes(key)) || ((bits&63)===4 && key==='99'))) {finish();return;}
+ }
+ if(buffer.length>4096)buffer='';
+});

package/apps/jsgotty/tests/manual-touch-diagnostics.js

@@ -0,0 +1,33 @@
+// Injected only by manual-touch-diagnostics.mjs. Observes without cancelling events.
+(()=>{
+ const endpoint=globalThis.__touchDiagnosticEndpoint, rows=[];
+ const state=()=>({viewport:document.querySelector('meta[name=viewport]')?.content,
+  width:innerWidth,clientWidth:document.documentElement.clientWidth,dpr:devicePixelRatio,
+  visual:visualViewport&&{scale:visualViewport.scale,width:visualViewport.width,height:visualViewport.height,x:visualViewport.offsetLeft,y:visualViewport.offsetTop},
+  mouse:globalThis.__gottyXterm?.modes?.mouseTrackingMode});
+ const push=row=>{rows.push({time:Date.now(),...row});if(rows.length>500)rows.shift()};
+ const describe=el=>el?.tagName+'.'+String(el?.className||'');
+ for(const type of ['touchstart','touchend','touchcancel','pointerdown','pointerup','pointercancel','mousedown','mouseup','click','dblclick','contextmenu']){
+  document.addEventListener(type,e=>{
+   const point=e.changedTouches?.[0]||e;
+   const row={type,target:describe(e.target),trusted:e.isTrusted,cancelable:e.cancelable,
+    prevented:e.defaultPrevented,detail:e.detail,touches:e.touches?.length,
+    pointerType:e.pointerType,x:point.clientX,y:point.clientY,
+    touchAction:e.target?.nodeType===1?getComputedStyle(e.target).touchAction:null,...state()};
+   queueMicrotask(()=>push({...row,preventedAfter:e.defaultPrevented}));
+  },{capture:true,passive:true});
+ }
+ for(const type of ['resize','scroll'])visualViewport?.addEventListener(type,()=>push({type:'visual-'+type,...state()}));
+ new MutationObserver(()=>push({type:'viewport-change',...state()})).observe(document.head,{attributes:true,subtree:true,childList:true});
+ let term;
+ setInterval(()=>{
+  const current=globalThis.__gottyXterm;
+  if(current&&current!==term){term=current;term.onData(data=>{
+   // Only terminal mouse reports; never collect typed commands or clipboard data.
+   if(/^\x1b\[<(\d+;){2}\d+[mM]$/.test(data)||data.startsWith('\x1b[M'))push({type:'xterm-mouse',data,...state()});
+  });push({type:'xterm-ready',...state()});}
+  if(rows.length)fetch(endpoint,{method:'POST',headers:{'Content-Type':'text/plain'},body:JSON.stringify(rows.splice(0)),keepalive:true}).catch(()=>{});
+ },500);
+ push({type:'diagnostic-ready',...state()});
+ globalThis.__touchDiagnostics={state,mark:label=>push({type:'mark',label,...state()})};
+})();

package/apps/jsgotty/tests/manual-touch-diagnostics.mjs

@@ -0,0 +1,22 @@
+// bun tests/manual-touch-diagnostics.mjs [shell]
+// Isolated custom index: production assets are unchanged. Ctrl-C stops both servers.
+import {join,resolve} from 'node:path';
+import {mkdtempSync,appendFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+const root=resolve(import.meta.dir,'..'),dir=mkdtempSync(join(tmpdir(),'jsgotty-touch-'));
+const log=join(dir,'events.jsonl'),token=crypto.randomUUID();
+const collector=Bun.serve({hostname:'127.0.0.1',port:0,async fetch(req){
+ if(new URL(req.url).pathname!=='/'+token)return new Response('',{status:404});
+ if(req.method==='POST'){
+  const data=await req.text();if(data.length<256000){try{for(const row of JSON.parse(data))appendFileSync(log,JSON.stringify(row)+'\n')}catch{}}
+ }
+ return new Response('ok',{headers:{'Access-Control-Allow-Origin':'*'}});
+}});
+const script=await Bun.file(join(import.meta.dir,'manual-touch-diagnostics.js')).text();
+const injection=`<script>globalThis.__touchDiagnosticEndpoint=${JSON.stringify('http://127.0.0.1:'+collector.port+'/'+token)};${script}</script>`;
+const html=(await Bun.file(join(root,'static/index.html')).text()).replace('</body>',injection+'\n</body>');
+const index=join(dir,'index.html');await Bun.write(index,html);
+console.log('Touch diagnostic log:',log);
+const child=Bun.spawn([process.execPath,join(root,'gotty.js'),'-w','-r','--session','-p','0','--index',index,process.argv[2]||process.env.SHELL||'/system/bin/sh'],{stdio:['inherit','inherit','inherit']});
+for(const sig of ['SIGINT','SIGTERM'])process.on(sig,()=>child.kill(sig));
+try{process.exitCode=await child.exited;}finally{collector.stop(true)}

package/apps/jsgotty/tests/nested-cli-pty.test.mjs

@@ -0,0 +1,116 @@
+// Actual client.mjs processes and PTYs over WebSockets; servers below simulate
+// only attach/detach and preserve the production TerminalModeTracker snapshots.
+// bun test tests/nested-cli-pty.test.mjs
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import modes from '../terminal-modes.js';
+const {TerminalModeTracker}=modes;
+const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+async function until(check,label){for(let i=0;i<300;i++){if(check())return;await sleep(10);}throw Error('Timed out: '+label);}
+function tracker(sequence=''){const t=new TerminalModeTracker();t.consume(Buffer.from(sequence));return t;}
+function simulatedServer(initial, viewer=false){
+ const state=tracker(initial);let socket=null,input=()=>{};
+ const server=Bun.serve({hostname:'127.0.0.1',port:0,
+  fetch(req,server){if(server.upgrade(req))return;return new Response('fixture');},
+  websocket:{
+   message(ws,message){const text=String(message);
+    if(text[0]==='{'){
+     socket=ws;ws.send('m'+JSON.stringify({...state.snapshot(),kittyRestore:1}));
+     ws.send('a'+JSON.stringify({role:viewer?'viewer':'writer',writable:!viewer}));
+    }else if(text[0]==='1')input(Buffer.from(text.slice(1),'base64'));
+    else if(text[0]==='2')ws.send('2');
+   },close(ws){if(socket===ws)socket=null;}
+  }});
+ return {state,server,get socket(){return socket;},set input(fn){input=fn;},
+  output(data){state.consume(Buffer.from(data));socket?.send('1'+Buffer.from(data).toString('base64'));},
+  detach(){socket?.close(1000,'test detach');},
+  url:`ws://127.0.0.1:${server.port}/ws`};
+}
+const client=path.resolve(import.meta.dirname,'../client.mjs');
+function spawnClient(url,onData){
+ return Bun.spawn([process.execPath,client,url,'-r','preserved'],{
+  terminal:{cols:100,rows:30,data(terminal,data){onData(terminal,Buffer.from(data));}},
+ });
+}
+// Emulate the outer browser's private parser reply; the separate Chromium test
+// checks this against the real bundled xterm parser and rendering queue.
+function terminalEndpoint(parent){
+ const state=tracker();Object.assign(state,structuredClone(parent));let pending='',output='';
+ return {state,get output(){return output;},data(terminal,data){
+  output+=data.toString('latin1');
+  state.consume(data);pending+=data.toString('latin1');
+  const re=/\x1b\]777;jsgotty-modes;([a-f0-9]{32})\x07/g;let m;
+  while((m=re.exec(pending)))terminal.write(`\x1b]777;jsgotty-modes;${m[1]};${Buffer.from(JSON.stringify({...state.snapshot(),kittyRestore:1})).toString('base64')}\x07`);
+  const start=pending.lastIndexOf('\x1b]');pending=start>=0&&!pending.slice(start).includes('\x07')?pending.slice(start):'';
+ }};
+}
+test('real nested CLI PTYs: detach each client, preserve parents, direct fresh attach', {skip:typeof Bun==='undefined',timeout:30000},async()=>{
+ const parentA=tracker('\x1b[=1u\x1b[>9u\x1b[?2004h').snapshot();
+ const b=simulatedServer('\x1b[>3u\x1b[?1049h\x1b[>11u\x1b[?1002h\x1b[?1006h');
+ const c=simulatedServer('\x1b[>9u\x1b[?1049h\x1b[>1u\x1b[>11u\x1b[?1003h\x1b[?1016h');
+ const parentB=b.state.snapshot(),outer=terminalEndpoint(parentA);const children=[];
+ const spawn=(url,onData)=>{const p=spawnClient(url,onData);children.push(p);return p;};
+ let first,second;
+ const equals=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+ const freshAttach=async server=>{
+  const clean=terminalEndpoint(tracker().snapshot());
+  const proc=spawn(server.url,clean.data);await until(()=>server.socket,'fresh socket');
+  await until(()=>equals(clean.state.snapshot(),server.state.snapshot()),'fresh terminal restore');
+  server.detach();await proc.exited;proc.terminal.close();
+  assert.deepEqual(clean.state.snapshot(),tracker().snapshot(),'fresh terminal cleanup');
+ };
+ try{
+  first=spawn(b.url,outer.data);await until(()=>b.socket,'middle attach');
+  await until(()=>equals(outer.state.snapshot(),parentB),'middle initial state');
+  b.input=data=>second?.terminal.write(data);
+  second=spawn(c.url,(_,data)=>b.output(data));await until(()=>c.socket,'inner attach');
+  await until(()=>equals(outer.state.snapshot(),c.state.snapshot()),'nested initial state');
+  // Close innermost transport, keeping both its PTY state and the middle server.
+  c.detach();await second.exited;second.terminal.close();
+  await until(()=>equals(outer.state.snapshot(),parentB),'inner cleanup restores parent');
+  c.output('\x1b[<u\x1b[?1049l\x1b[>3u\x1b[?1000l');
+  await freshAttach(c);
+  second=spawn(c.url,(_,data)=>b.output(data));await until(()=>c.socket,'inner reattach');
+  await until(()=>equals(outer.state.snapshot(),c.state.snapshot()),'inner resumed state');
+  // Drop middle transport; innermost CLI remains alive and keeps tracking.
+  b.detach();await first.exited;first.terminal.close();
+  assert.deepEqual(outer.state.snapshot(),parentA,'middle cleanup restores original parent stack');
+  c.output('\x1b[?1049h\x1b[>9u\x1b[?1002h\x1b[?1006h');
+  await until(()=>equals(b.state.snapshot(),c.state.snapshot()),'output while middle detached');
+  await freshAttach(b);
+  first=spawn(b.url,outer.data);await until(()=>b.socket,'middle reattach');
+  await until(()=>equals(outer.state.snapshot(),c.state.snapshot()),'middle resumed state');
+  // CLI clients must forward OSC52 untouched to the actual outer emulator.
+  const osc52='\x1b]52;c;dGVzdA==\x07\x1b]52;c;?\x1b\\';
+  c.output(osc52);await until(()=>outer.output.includes(osc52),'OSC52 pass-through');
+  // Real input still traverses both clients after querying/restoring.
+  let received='';c.input=data=>{received+=data.toString();};
+  first.terminal.write('\x1b[120;9u');await until(()=>received.includes('\x1b[120;9u'),'Super-X input through both clients');
+  c.detach();await second.exited;second.terminal.close();
+  await until(()=>equals(outer.state.snapshot(),parentB),'final inner cleanup');
+  b.detach();await first.exited;first.terminal.close();
+  assert.deepEqual(outer.state.snapshot(),parentA);
+ }finally{
+  for(const p of children){try{p.kill();p.terminal.close();}catch{}}
+  b.server.stop(true);c.server.stop(true);
+ }
+});
+test('real viewer PTYs exit with legacy and Kitty Ctrl-C/D/Q and restore parent', {skip:typeof Bun==='undefined',timeout:30000},async()=>{
+ for(const [key,code] of [[3,130],[4,0],[17,0],[99,130],[100,0],[113,0]]){
+  const server=simulatedServer('\x1b[>11u',true);
+  const outer=terminalEndpoint(tracker().snapshot());
+  const proc=spawnClient(server.url,outer.data);
+  try{
+   await until(()=>outer.output.includes('Exit by Ctrl+C/D/Q'),'viewer ready');
+   const sequence=key<32?String.fromCharCode(key):'\x1b['+key+';5u';
+   for(const byte of Buffer.from(sequence)) proc.terminal.write(Buffer.from([byte]));
+   await until(()=>proc.exitCode!==null,'viewer exited');
+   assert.equal(await proc.exited,code);
+   assert.deepEqual(outer.state.snapshot(),tracker().snapshot());
+  }finally{
+   if(proc.exitCode===null){proc.kill();await proc.exited;}
+   proc.terminal.close();server.server.stop(true);
+  }
+ }
+});

package/apps/jsgotty/tests/reconnect-modes-browser.test.js

@@ -0,0 +1,144 @@
+// Opt-in real bundled-xterm integration; no browser/dependency downloads.
+// CHROMIUM_HEADLESS=/path/to/chromium-headless-shell node --test tests/kitty-keyboard-browser.test.js
+const test=require('node:test');
+const assert=require('node:assert/strict');
+const fs=require('node:fs');
+const path=require('node:path');
+const http=require('node:http');
+const {spawn}=require('node:child_process');
+const {once}=require('node:events');
+const WebSocket=require('ws');
+const root=path.join(__dirname,'../static');
+test('browser -> CLI -> CLI: independent disconnects preserve terminal modes', {skip:!process.env.CHROMIUM_HEADLESS,timeout:60000},async()=>{
+ const bundle=fs.readFileSync(path.join(root,'js/gotty.js'),'utf8').replace('(i.nc = void 0));','(i.nc = void 0)); window.TestGoTTYXterm = i(634).GoTTYXterm;');
+ const modesSource=fs.readFileSync(path.join(__dirname,'../terminal-modes.js'),'utf8');
+ const server=http.createServer((req,res)=>{
+  if(req.url==='/modes.js'){res.setHeader('Content-Type','text/javascript');res.end('(function(){var module={exports:{}};'+modesSource+';window.modes=module.exports;})();');}
+  else if(req.url==='/bundle.js'){res.setHeader('Content-Type','text/javascript');res.end(bundle);}
+  else if(req.url==='/keyboard.js'){res.setHeader('Content-Type','text/javascript');res.end(fs.readFileSync(path.join(root,'js/kitty-keyboard.js')));}
+  else res.end('<!doctype html><div id="fixture" style="width:800px;height:600px"></div><script src="/modes.js"></script><script src="/keyboard.js"></script><script src="/bundle.js"></script><script>window.wrapper=new TestGoTTYXterm(document.getElementById("fixture"));window.sent=[];wrapper.onInput(b=>sent.push(new TextDecoder().decode(b)));wrapper.kittyKeyboard.android=true;</script>');
+ });
+ server.listen(0,'127.0.0.1');await once(server,'listening');
+ const child=spawn(process.env.CHROMIUM_HEADLESS,['--no-sandbox','--disable-gpu','--remote-debugging-port=0','http://127.0.0.1:'+server.address().port],{detached:true,stdio:['ignore','ignore','pipe']});
+ let ws;
+ try{
+  const endpoint=await new Promise((resolve,reject)=>{let log='';const timer=setTimeout(()=>reject(Error('Browser startup timeout: '+log)),15000);child.on('error',reject);child.on('exit',code=>{clearTimeout(timer);reject(Error('Browser exited '+code+': '+log));});child.stderr.on('data',b=>{log+=b;const m=log.match(/DevTools listening on (ws:\/\/[^\s]+)/);if(m){clearTimeout(timer);resolve(m[1]);}});});
+  const u=new URL(endpoint);let tab;
+  for(let i=0;i<50;i++){tab=(await (await fetch('http://'+u.host+'/json/list')).json()).find(x=>x.type==='page');if(tab)break;await new Promise(r=>setTimeout(r,100));}
+  ws=new WebSocket(tab.webSocketDebuggerUrl);await once(ws,'open');let id=0;const pending=new Map();ws.on('message',data=>{const m=JSON.parse(data);if(pending.has(m.id)){const {resolve,reject}=pending.get(m.id);pending.delete(m.id);m.error?reject(m.error):resolve(m.result);}});
+  const call=(method,params)=>new Promise((resolve,reject)=>{pending.set(++id,{resolve,reject});ws.send(JSON.stringify({id,method,params}));});
+  for(let i=0;i<50;i++){const r=await call('Runtime.evaluate',{expression:'Boolean(window.wrapper)',returnByValue:true});if(r.result.value)break;await new Promise(r=>setTimeout(r,100));}
+  const result=await call('Runtime.evaluate',{awaitPromise:true,returnByValue:true,expression:`(async()=>{
+
+   const term=wrapper.term;
+   const {TerminalModeTracker,validateSnapshot}=modes;
+   const modeTransition=(from,to)=>modes.modeTransition(from,to,{kittyRestore:true});
+   const tracker=()=>new TerminalModeTracker();
+   const equal=(a,b,label)=>{if(JSON.stringify(a)!==JSON.stringify(b))throw Error(label+JSON.stringify({actual:a,expected:b}));};
+   const snapshot=()=>validateSnapshot(wrapper.sessionModes());
+   const drain=()=>new Promise(r=>wrapper.enqueueTerminal(done=>{done();r();}));
+   const write=s=>new Promise(r=>term.write(s,r));
+
+   // Mode-only restoration must preserve visible cells and cursor on either
+   // screen, even if the other screen's Kitty stack differs.
+   for(const alternate of [false,true]){
+    await write('\\x1bcNORMAL CONTENT');
+    if(alternate)await write('\\x1b[?1049hVISIBLE FULLSCREEN CONTENT');
+    await write('\\x1b[4;9H');
+    const view=()=>({type:term.buffer.active.type,x:term.buffer.active.cursorX,y:term.buffer.active.cursorY,
+      lines:Array.from({length:term.rows},(_,i)=>term.buffer.active.getLine(i)?.translateToString(true))});
+    const before=view(),from=snapshot(),to=structuredClone(from);
+    const inactive=alternate?'normal':'alternate';
+    to.kitty[inactive]={flags:9,stack:[0,1]};
+    // No negotiated support: do not switch screens to repair a hidden stack.
+    const fallback=modes.modeTransition(from,to);
+    equal(fallback,'','unnegotiated hidden restore');
+    await write(fallback);equal(view(),before,'fallback preserves cells/cursor');
+    const sequence=modeTransition(from,to);
+    if(sequence.includes('[?1047')||sequence.includes('[?1049'))throw Error('hidden restore switched screens');
+    await write(sequence);
+    equal(view(),before,'negotiated restore preserves cells/cursor');
+    equal(snapshot(),to,'hidden stack restored without switching');
+   }
+   await write('\\x1bc');
+   // Regression: raw xterm writes already queued before a restore, followed by
+   // newer output. Restoration must happen between these two generations.
+   term.write('\\x1b[?1002h\\x1b[>11u');
+   wrapper.applySessionModes(tracker().snapshot());
+   wrapper.writeTerminal('\\x1b[>1u');await drain();
+   equal(snapshot().mouse,'NONE','pending mouse output');
+   equal(snapshot().kitty.normal,{flags:1,stack:[0]},'pending Kitty output');
+   await write('\\x1bc');
+   const outer=tracker(),middle=tracker(),inner=tracker();
+   let browserConnected=true,middleConnected=true,innerConnected=true;
+   const outerOutput=s=>{outer.consume(new TextEncoder().encode(s));if(browserConnected)wrapper.writeTerminal(s);};
+   const middleOutput=s=>{middle.consume(new TextEncoder().encode(s));if(middleConnected)outerOutput(s);};
+   const innerOutput=s=>{inner.consume(new TextEncoder().encode(s));if(innerConnected)middleOutput(s);};
+   const browserResume=async()=>{browserConnected=true;wrapper.applySessionModes(outer.snapshot());await drain();equal(snapshot(),outer.snapshot(),'browser resume');};
+
+   const freshAttach=async(state,label)=>{
+    const div=document.createElement('div');document.body.append(div);
+    const fresh=new TestGoTTYXterm(div);
+    // A new terminal attaches directly to that server's preserved session.
+    fresh.applySessionModes(state);
+    await new Promise(r=>fresh.enqueueTerminal(done=>{done();r();}));
+    equal(validateSnapshot(fresh.sessionModes()),state,label+' fresh direct attach');
+    // Applying the snapshot twice is idempotent, including Kitty stack depth.
+    fresh.applySessionModes(state);
+    await new Promise(r=>fresh.enqueueTerminal(done=>{done();r();}));
+    equal(validateSnapshot(fresh.sessionModes()),state,label+' repeated snapshot');
+    fresh.close();div.remove();
+   };
+   const a='\\x1b[=1u\\x1b[>9u\\x1b[?2004h';
+   const b='\\x1b[>3u\\x1b[?1049h\\x1b[>11u\\x1b[?1002h\\x1b[?1006h';
+   const c='\\x1b[>9u\\x1b[?1049h\\x1b[>1u\\x1b[>11u\\x1b[?1003h\\x1b[?1016h\\x1b[?25l';
+   outerOutput(a);await drain();const parentA=outer.snapshot();
+   middle.consume(new TextEncoder().encode(b));
+   outerOutput(modeTransition(outer.snapshot(),middle.snapshot()));await drain();const parentB=middle.snapshot();
+   inner.consume(new TextEncoder().encode(c));
+   middleOutput(modeTransition(middle.snapshot(),inner.snapshot()));await drain();
+   equal(snapshot(),inner.snapshot(),'both clients attached');
+   // Outermost browser transport drops: both CLI sessions keep tracking output.
+   browserConnected=false;wrapper.setDisconnected(true);
+   innerOutput('\\x1b[<u\\x1b[?1002h\\x1b[?1006h');
+   await freshAttach(outer.snapshot(),'outer disconnected');
+   await browserResume();wrapper.setDisconnected(false);
+   equal(snapshot(),inner.snapshot(),'browser sees offline changes');
+   // Innermost CLI disconnects. Its cleanup must restore middle parent, not
+   // defaults, and its remote PTY continues changing while detached.
+   innerConnected=false;
+   middleOutput(modeTransition(middle.snapshot(),parentB));await drain();
+   equal(snapshot(),parentB,'inner CLI cleanup');
+   innerOutput('\\x1b[?1049l\\x1b[>3u\\x1b[?1000l\\x1b[?1016l');
+   await freshAttach(inner.snapshot(),'inner disconnected');
+   innerConnected=true;middleOutput(modeTransition(middle.snapshot(),inner.snapshot()));await drain();
+   equal(snapshot(),inner.snapshot(),'inner CLI resume');
+   // Middle CLI disconnects while its inner CLI stays alive.
+   middleConnected=false;outerOutput(modeTransition(outer.snapshot(),parentA));await drain();
+   equal(snapshot(),parentA,'middle CLI cleanup');
+   innerOutput('\\x1b[?1049h\\x1b[>9u\\x1b[?1002h\\x1b[?1006h');
+   await freshAttach(middle.snapshot(),'middle disconnected');
+   middleConnected=true;outerOutput(modeTransition(outer.snapshot(),middle.snapshot()));await drain();
+   equal(snapshot(),inner.snapshot(),'middle CLI resume');
+   // Drop all transports, reconnect inside-out, then repeat the browser snapshot.
+   browserConnected=middleConnected=innerConnected=false;
+   innerOutput('\\x1b[<u\\x1b[?2004h');
+   innerConnected=true;middleOutput(modeTransition(middle.snapshot(),inner.snapshot()));
+   middleConnected=true;outerOutput(modeTransition(outer.snapshot(),middle.snapshot()));
+   await browserResume();await browserResume();
+   equal(snapshot(),inner.snapshot(),'all layers resumed; no stack duplication');
+   // Private query traverses output and returns the exact current state once.
+   sent.length=0;
+   await write('\\x1b]777;jsgotty-modes;0123456789abcdef0123456789abcdef\\x07');
+   equal(sent.length,1,'private query reply count');
+   const encoded=sent[0].split(';')[3].slice(0,-1);
+   equal(JSON.parse(atob(encoded)).kittyRestore,1,'restore capability advertised');
+   equal(validateSnapshot(JSON.parse(atob(encoded))),snapshot(),'private query state');
+   wrapper.close();return 'ok';
+  })()`});
+  assert.equal(result.exceptionDetails,undefined,JSON.stringify(result.exceptionDetails));assert.equal(result.result.value,'ok');
+ }finally{
+  ws?.close();if(child.pid){try{process.kill(-child.pid,'SIGTERM');}catch{}}
+  server.closeAllConnections();await new Promise(r=>server.close(r));
+ }
+});

package/apps/jsgotty/tests/reconnect-modes.md

@@ -0,0 +1,44 @@
+# Reconnect mode tests
+
+No extra dependencies are needed. Use an already installed Chromium:
+
+```sh
+node --test tests/client-modes.test.mjs tests/client-exit.test.mjs tests/reconnect-modes.test.js
+bun test tests/nested-cli-pty.test.mjs
+CHROMIUM_HEADLESS=/usr/local/bin/chromium-headless-shell node --test tests/reconnect-modes-browser.test.js tests/kitty-keyboard-browser.test.js
+```
+
+- `reconnect-modes-browser.test.js` runs the shipped xterm in real Chromium. It simulates browser → CLI → CLI output routing using the production mode trackers and transition code. It drops the browser, middle, and inner connections independently, changes modes while disconnected, and reconnects. Each dropped session is also attached directly to a newly constructed, clean xterm. It checks queued old output, new output after restoration, idempotent snapshots, mouse protocol/encoding, DEC flags, both screens' Kitty stacks, and the private reply.
+- `nested-cli-pty.test.mjs` runs two actual `client.mjs` processes using Bun PTYs and WebSockets. Minimal server fixtures implement attach/output/detach with production mode trackers. It checks inner and middle disconnects, direct attachments from clean terminal models, changes while detached, parent restoration, and Super-X forwarding through both clients. The outer terminal model's reply is independently checked against real xterm by the browser test.
+- `client-modes.test.mjs` checks fragmented replies, unknown modes, fallback, raw-mode restoration, transparent ordinary input/large pastes, foreign nonces, and that startup reply filtering does not consume later application queries indefinitely.
+
+These are mode/input-state tests, not screen-content replay tests. The minimal servers are not a replacement for testing the full GoTTY server's session lifecycle. Forced process death (SIGKILL), without a chance to execute cleanup, cannot restore the local terminal.
+
+## Private query and native terminal compatibility
+
+The query is `ESC ] 777 ; jsgotty-modes ; <32 hex nonce> BEL`. The browser replies once with `ESC ] 777 ; jsgotty-modes ; <same nonce> ; <base64 JSON snapshot> BEL`. A new nonce prevents replies intended for a nested client from being consumed by a different layer. Only the browser extension implements this query; it is not a standard terminal query.
+
+Upstream source inspection (not GUI runtime testing):
+
+- Ghostty, revision `8ef0ec1238220a5a714be452ed2844f0691fcf83`: [OSC dispatch](https://github.com/ghostty-org/ghostty/blob/8ef0ec1238220a5a714be452ed2844f0691fcf83/src/terminal/osc.zig), [rxvt extension parser](https://github.com/ghostty-org/ghostty/blob/8ef0ec1238220a5a714be452ed2844f0691fcf83/src/terminal/osc/parsers/rxvt_extension.zig). OSC 777 accepts `notify`; `jsgotty-modes` takes the unknown-extension branch, logs `unknown rxvt extension: jsgotty-modes`, returns null, and produces no terminal reply or notification. Thus this probe is not silent in Ghostty's diagnostic log.
+- Konsole, revision `a25cd724d5790fbe9cda01db63d478ff7eba8d7b`: [Vt102Emulation](https://github.com/KDE/konsole/blob/a25cd724d5790fbe9cda01db63d478ff7eba8d7b/src/Vt102Emulation.cpp), [Session](https://github.com/KDE/konsole/blob/a25cd724d5790fbe9cda01db63d478ff7eba8d7b/src/session/Session.cpp), [ContainerRegistry](https://github.com/KDE/konsole/blob/a25cd724d5790fbe9cda01db63d478ff7eba8d7b/src/containers/ContainerRegistry.cpp). OSC 777 emits an internal Qt signal; its built-in handlers accept `notify` or `container`. `jsgotty-modes` matches neither, so no terminal reply, notification, or container change results.
+
+OSC 777 is already used for rxvt-style extensions; the jsgotty subcommand avoids `notify` and `container`, but future or third-party terminal handlers are not covered by this review.
+
+After 200 ms without the private reply, the CLI requests standard DECRQM and Kitty flags, with a total startup timeout of 1 second. Unsupported/unanswered fields remain unknown rather than becoming guessed defaults. Standard Kitty queries report current flags, not the hidden stack. Full stack restoration is therefore available between updated jsgotty clients/browser; native terminals cannot promise restoration of pre-existing hidden entries if the remote application itself pops them. The CLI never clears an arbitrary 100 entries.
+
+Startup standard replies are consumed at most once per requested mode, with a bounded late-reply window. Standard replies have no nonce: a reply to an application's identical query during that short outstanding window cannot be distinguished perfectly from a delayed startup reply.
+
+## Native mouse switches and exit ordering
+
+Standard probing also retains optional `mouseModeBits` and `mouseEncodingBits`, with boolean values for answered switches and null for silence. For multiple active replies, the effective priority is explicitly ANY > DRAG > VT200 > X10 and SGR_PIXELS > SGR. This is a compatibility policy for the represented modes, not a claim that larger DEC numbers universally win. Cleanup restores the recorded switches (known disabled first, enabled in increasing priority); partial replies do not invent values for unanswered switches. CLI attachment to a known session normalizes the whole represented group before enabling its effective mode, even when the local aggregate name matches, because native terminals may retain independent hidden switches. Server tracking continues to follow xterm's exclusive-mode semantics.
+
+The tests exercise both independent-switch and exclusive-mode terminal models, downgrade from stronger modes, unchanged aggregates with conflicting underlying switches, and partial replies. `client-exit.test.mjs` executes the production exit handlers with delayed stdout callbacks: the first exit request wins, subsequent bytes/signals do not schedule a second exit, and exit still waits for stdout to flush.
+
+## Preserve screen contents during hidden Kitty restoration
+
+A private snapshot reply now advertises `kittyRestore: 1`. Only after receiving that capability may the CLI emit `OSC 777 ; jsgotty-kitty-v1 ; normal|alternate ; flags ; comma-separated-stack BEL` (an empty stack has an empty last field). This updates the named Kitty state in place; it never activates either screen. The browser masks unsupported flags as usual. Intermediate session trackers recognize bounded, validated BEL/ST-terminated commands so reconnect snapshots continue to match the terminal.
+
+Without this capability, a mode-only transition leaves the inactive stack unchanged. It must not use a temporary `?1047l`/`?1047h` roundtrip: xterm clears the alternate buffer when leaving it, destroying the visible fullscreen contents even if the final active screen is unchanged. A requested screen change can still restore each stack while that screen is naturally active. Native/older terminals therefore retain a limitation on restoring inactive Kitty state; preserving visible contents takes precedence.
+
+The real Chromium test now checks visible rows and cursor coordinates on both normal and alternate screens, with negotiated restoration and without the capability. It also checks that the advertised extension restores the hidden stack, alongside the existing nested-disconnect/direct-fresh-attach scenarios. Tracker tests cover byte-split commands, BEL/ST termination, cancellation, malformed values, oversized stacks, and unrelated DCS strings.