buninu-linux 0.13.56 → 0.15.58

package/build-image.sh

@@ -25,7 +25,16 @@ done
 temporary_esp="$(mktemp --tmpdir=. .esp.XXXXXX.img)"
 trap 'rm -f "$temporary_esp"' EXIT
 
-disk_sectors=$((128 * 1024 * 1024 / 512))
+# Match scripts/build.js: payload + 1/16 + 4 MiB, rounded to 64 MiB.
+payload_bytes=$(stat -c %s "vda/EFI/BOOT/$efi_boot_name")
+if ((payload_bytes > 4294967295)); then
+    echo "error: EFI payload exceeds the FAT32 single-file limit" >&2
+    exit 1
+fi
+unit=$((64 * 1024 * 1024))
+disk_bytes=$(((payload_bytes + (payload_bytes + 15) / 16 + 4 * 1024 * 1024 + unit - 1) / unit * unit))
+((disk_bytes >= 128 * 1024 * 1024)) || disk_bytes=$((128 * 1024 * 1024))
+disk_sectors=$((disk_bytes / 512))
 esp_start=2048
 esp_end=$((disk_sectors - 34))
 esp_sectors=$((esp_end - esp_start + 1))

package/build-uki.sh

@@ -5,7 +5,9 @@ cd "$(dirname "$0")"
 
 . ./scripts/arch.sh
 
-if [ ! -s "$kernel_image" ] || [ ! -s "$kernel_dir/$efi_stub" ] || [ ! -s "$modules_root/modules.dep" ] || \
+gpu_js=$(command -v bun || command -v node)
+
+if [ ! -s "$kernel_image" ] || [ ! -s "$kernel_dir/$efi_stub" ] || [ ! -s "$modules_root/modules.dep" ] || ! "$gpu_js" scripts/fetch-gpu.js --check || \
     { [ "${REAL_MACHINE:-}" = 1 ] && \
     { [ ! -s "$modules_root/kernel/drivers/hid/usbhid/usbhid.ko" ] || \
       [ ! -s "$modules_root/kernel/drivers/acpi/battery.ko" ]; }; }; then

package/fetch-alpine.sh

@@ -33,6 +33,9 @@ depfile="$(mktemp)"
 selected="$(mktemp)"
 trap 'rm -f "$depfile" "$selected" "$selected.names"' EXIT
 extract "$linux_package" "lib/modules/$kernel_release/modules.dep" > "$depfile"
+# Recreate the generated module tree so removed selections cannot linger.
+rm -rf "$modules_root"
+mkdir -p "$modules_root"
 extract "$linux_package" "lib/modules/$kernel_release/modules.builtin" > "$modules_root/modules.builtin"
 
 select_module() {
@@ -63,8 +66,15 @@ select_optional_module() {
 # Network: virtio-net for QEMU (init.js loads these at boot). virtio_pci is
 # the PCI transport for every virtio device, disk included; linux-virt builds
 # it in, linux-lts has it as a module that nothing in modules.dep pulls in.
-for module in failover net_failover virtio_net; do select_module "$module"; done
+for module in failover net_failover virtio_net af_packet; do select_module "$module"; done
 select_optional_module virtio_pci
+# GPU modules are packaged only; init and cfg.all leave them unloaded.
+if [ "${BUNINU_NO_GPU:-}" != 1 ]; then
+    for module in virtio-gpu vmwgfx; do select_optional_module "$module"; done
+    if [ "$arch" = x86_64 ]; then
+        for module in i915 xe amdgpu radeon nouveau; do select_optional_module "$module"; done
+    fi
+fi
 # Storage: what /bin/mount loads on demand. ext4 brings jbd2, mbcache and
 # crc16; FAT, exFAT and NTFS ask the kernel for the NLS tables at mount
 # time, which has no /sbin/modprobe to answer, so mount preloads them.
@@ -145,4 +155,8 @@ extract "$linux_package" "lib/modules/$kernel_release/modules.alias" \
 
 chmod 0755 "$native_dir/lib/$musl_loader"
 
+# Share the verified firmware extraction and cache marker with the JS build.
+js=$(command -v bun || command -v node)
+"$js" scripts/fetch-gpu.js
+
 echo "Fetched Alpine $arch linux-$linux_flavor kernel, $(wc -l < "$selected") modules, musl, and the $efi_stub UKI stub."

package/graphics.md

@@ -158,6 +158,28 @@ screen and xterm.js's `CoreMouseService` → PTY. Terminal
 replies (cursor position, device attributes, kitty acks) go from the
 emulator straight to the PTY.
 
+## Raw image fast path
+
+Native bunterm can negotiate BGRA (`f=1111970369`, a private Buninu format) or
+standard RGBA (`f=32`) with Casty. `images.js` retains the received raw bytes;
+`raw-image.js` creates a Skia image only when a fallback operation needs one.
+For an opaque, integer-aligned 1:1 placement matching the framebuffer channel
+order, `canvas.js` copies these bytes into the existing raster back buffer.
+This avoids `MakeImage` followed by `readPixels`, but still performs the raster
+copy and the final framebuffer flush. Opacity is checked from the actual alpha
+bytes once per image, not assumed from its format or filename.
+
+Rows completely covered by such an image skip text hashing and painting.
+Partially covered rows keep normal rendering, and uncovering a row forces its
+current text to repaint. Pointer and menu overlays are still drawn afterwards.
+Scaling, transparency, other channel orders and 16-bit framebuffers retain
+CanvasKit rendering. Encoded PNG/JPEG handling is unchanged.
+
+原始像素只有在通道排列一致、1:1 整數座標且經檢查確定不透明時，才直接複製到
+繪圖緩衝區，省去先建立 Skia Image 再讀回像素的步驟。完全被圖片覆蓋的文字列
+略過雜湊與重畫；圖片移開後會重畫當下的文字。縮放、透明、格式不符時仍使用
+CanvasKit，最後寫入 framebuffer 的複製也仍然存在。
+
 ## Sizes
 
 | Component | Raw | In the gzip initramfs |
@@ -222,6 +244,15 @@ at once and draws on VT 2; and keys sent with the monitor's `sendkey` reach
 it: `showimg /buninu/icon.png` places the kitty image, and the prompt's
 colour emoji and the pointer render, all checked with `screendump`.
 
+## Optional client GPU acceleration
+
+Client GPU rendering can be enabled separately with the PID 1 REPL's `cfg.gpu`,
+before opening framebuffer clients. It loads matched GPU drivers and exposes
+render nodes, while this CanvasKit/bunterm stack remains software-rendered.
+Boot and `cfg.all` do not load those GPU drivers. See the README's
+[optional client GPU acceleration](README.md#optional-client-gpu-acceleration-cfggpu)
+for firmware, device permissions and framebuffer handoff constraints.
+
 ## Not done yet
 
 - Selection and scrollback viewing in `bunterm` (the pointer itself works,

package/index.js

@@ -79,7 +79,7 @@ function usage() {
 
 Usage:
   ${pkg.name} [-f] [-b] [-r] [--arch ARCH] [--docker] [--export] [--linux-lts]
-               [--real] [-- qemu arguments]
+               [--real] [--no-gpu] [-- qemu arguments]
   ${pkg.name} --check [FILE...]
 
 Stages (always run in this order, whichever you pick):
@@ -107,6 +107,8 @@ Stages (always run in this order, whichever you pick):
                 primary console, and include USB xHCI/HID keyboard modules
                 (x86_64 only)
 
+  --no-gpu      omit the added GPU modules/firmware; retain the original framebuffer path
+
   --check [FILE...]
                 print content checksums of the build outputs that ignore
                 mtimes, timestamps and GUIDs, and exit (check_build.js; the
@@ -116,6 +118,8 @@ Stages (always run in this order, whichever you pick):
   -h, --help    show this
   -V, --version show name, version, runtime and platform
   --readme      render README.md in the terminal and exit
+  --readme-zh, --docs
+                render README.zh.md in the terminal and exit
 
 Short flags combine: -fbr is the whole pipeline, -br is what an edit to
 initramfs/init.js needs, -r just boots what is already there. Anything after
@@ -134,11 +138,12 @@ reported before anything starts.
 `;
 }
 
-function parse(argv) {
+async function parse(argv) {
   const selected = new Set();
   const passthrough = [];
   let linuxLts = false;
   let real = false;
+  let noGpu = false;
   let exportImage = false;
   let docker = false;
   // BUNINU_ARCH is what scripts/arch.sh reads; --arch overrides it.
@@ -165,12 +170,17 @@ function parse(argv) {
       printVersion();
       process.exit(0);
     } else if (argument === "--readme") {
-      printReadme();
+      await printReadme();
+      process.exit(0);
+    } else if (argument === "--readme-zh" || argument === "--docs") {
+      await printReadme("README.zh.md");
       process.exit(0);
     } else if (argument === "--check") {
       runCheck(argv.slice(index + 1));
     } else if (argument === "--linux-lts") {
       linuxLts = true;
+    } else if (argument === "--no-gpu") {
+      noGpu = true;
     } else if (argument === "--real") {
       real = true;
     } else if (argument === "--export") {
@@ -197,8 +207,8 @@ function parse(argv) {
   if (passthrough.length > 0 && !selected.has(stages[2])) {
     fail("arguments after -- only make sense with -r/--run");
   }
-  if ((linuxLts || real) && !selected.has(stages[0]) && !selected.has(stages[1])) {
-    fail("--linux-lts/--real only make sense with -f/--fetch or -b/--build");
+  if ((linuxLts || real || noGpu) && !selected.has(stages[0]) && !selected.has(stages[1])) {
+    fail("--linux-lts/--real/--no-gpu only make sense with -f/--fetch or -b/--build");
   }
   if (exportImage && !selected.has(stages[1])) {
     fail("--export requires -b/--build (use -fb --export for a clean build)");
@@ -206,7 +216,7 @@ function parse(argv) {
   if (real && arch === "aarch64") {
     fail("--real builds an x86_64 PC image; it cannot be combined with --arch aarch64");
   }
-  return { selected, passthrough, linuxLts, real, exportImage, docker, arch };
+  return { selected, passthrough, linuxLts, real, noGpu, exportImage, docker, arch };
 }
 
 // Same shape as Buninu's --version. The runtime line tells you whether this
@@ -222,8 +232,8 @@ function printVersion() {
 
 // Same as Buninu's --readme: Bun renders the Markdown to ANSI with clickable
 // links. Under node there is no renderer, so the file is printed as-is.
-function printReadme() {
-  const path = resolve(rootDir, "README.md");
+function printReadme(filename = "README.md") {
+  const path = resolve(rootDir, filename);
   let markdown;
   try {
     markdown = readFileSync(path, "utf8");
@@ -234,7 +244,12 @@ function printReadme() {
     typeof Bun !== "undefined" && typeof Bun.markdown?.ansi === "function"
       ? Bun.markdown.ansi(markdown, { hyperlinks: true })
       : markdown;
-  process.stdout.write(rendered.endsWith("\n") ? rendered : rendered + "\n");
+  // Wait for the whole document to flush before parse() exits. Large README
+  // output can otherwise be truncated when stdout is a pipe.
+  return new Promise((resolve, reject) => {
+    process.stdout.write(rendered.endsWith("\n") ? rendered : rendered + "\n",
+      (error) => error ? reject(error) : resolve());
+  });
 }
 
 // --check hands everything after it to check_build.js, under the same
@@ -316,7 +331,7 @@ function dockerImage() {
 // into the bind-mounted checkout stays owned by that user; fakeroot provides
 // the root ownership the initramfs records.
 function dockerRun(script, env) {
-  const passEnv = ["BUNINU_ARCH", "LINUX_FLAVOR", "REAL_MACHINE", "ALPINE_MIRROR", "BUNINU_JS_UKI", "BUNINU_JS_CPIO"]
+  const passEnv = ["BUNINU_ARCH", "LINUX_FLAVOR", "REAL_MACHINE", "BUNINU_NO_GPU", "ALPINE_MIRROR", "BUNINU_JS_UKI", "BUNINU_JS_CPIO"]
     .filter((name) => env[name] !== undefined)
     .flatMap((name) => ["--env", `${name}=${env[name]}`]);
   const user = typeof process.getuid === "function"
@@ -344,7 +359,7 @@ function runScript(stage, script, args = [], env = process.env) {
   }
 }
 
-const { selected, passthrough, linuxLts, real, exportImage, docker, arch } = parse(process.argv.slice(2));
+const { selected, passthrough, linuxLts, real, noGpu, exportImage, docker, arch } = await parse(process.argv.slice(2));
 const ordered = stages.filter((stage) => selected.has(stage));
 const useDocker = docker || process.platform === "darwin";
 const buildArch = arch ?? "x86_64";
@@ -357,6 +372,7 @@ const stageEnv = {
   ...(arch && { BUNINU_ARCH: arch }),
   ...((linuxLts || real) && { LINUX_FLAVOR: "lts" }),
   ...(real && { REAL_MACHINE: "1" }),
+  ...(noGpu && { BUNINU_NO_GPU: "1" }),
 };
 
 // The arch.js config for the JS stages, from the same settings as stageEnv.
@@ -364,6 +380,7 @@ const jsConfig = async (env) => (await import("./scripts/arch.js")).config({
   arch: env.BUNINU_ARCH,
   flavor: env.LINUX_FLAVOR,
   real: env.REAL_MACHINE === "1",
+  noGpu: env.BUNINU_NO_GPU === "1",
   mirror: env.ALPINE_MIRROR,
 });
 

package/initramfs/bin/buninu-browser

@@ -14,9 +14,12 @@ const { chooseFrontend } = await import(pathToFileURL(entry).href);
 const args = process.argv.slice(2);
 const choice = chooseFrontend(args);
 const casty = choice.frontend === "casty";
+const forwarded = casty ? choice.args : args;
+// Preserve Casty's separator when Bun consumes the first one after the script.
+const runtimeArgs = forwarded[0] === "--" ? ["--", ...forwarded] : forwarded;
 const child = Bun.spawn({
   cmd: [process.execPath, casty ? join(modules, "@drxiaozhi/casty/index.js") : entry,
-    ...(casty ? choice.args : args)],
+    ...runtimeArgs],
   env: casty ? { ...process.env, CASTY_BROWSER: join(browser, "buninu-browser.js") } : process.env,
   stdio: ["inherit", "inherit", "inherit"],
 });

package/initramfs/bin/buninu-land

@@ -14,7 +14,7 @@ const { chooseFrontend } = await import(pathToFileURL(entry).href);
 const args = process.argv.slice(2);
 const choice = chooseFrontend(args);
 const casty = choice.frontend === "casty";
-const forwarded = casty ? choice.args : args;
+const forwarded = casty ? ["--no-shortcuts", ...choice.args] : args;
 // Bun consumes a leading separator after the script path; preserve Casty's
 // own separator when --casty is followed directly by -- engine flags.
 const runtimeArgs = forwarded[0] === "--" ? ["--", ...forwarded] : forwarded;

package/initramfs/bin/bunterm

@@ -4,7 +4,7 @@
 import { showDocument } from "../lib/document.js";
 import { runTerminal } from "../lib/bunterm/terminal.js";
 import { activeConsole, openConsole } from "../lib/fbdev.js";
-import { virtualConsoleNumber } from "../lib/bunterm/vt.js";
+import { virtualConsoleNumber, nextVirtualTerminal } from "../lib/bunterm/vt.js";
 import { closeSync, openSync, readFileSync } from "node:fs";
 
 const CANONICAL_BUNTERM = "/bin/bunterm";
@@ -79,7 +79,7 @@ const main = async () => {
   } finally {
     probe.close();
   }
-  if (!options.console) options.console = `/dev/tty${activeConsoleNumber}`;
+  if (!options.console) options.console = `/dev/tty${nextVirtualTerminal()}`;
 
   // Every live bunterm converges on one unambiguous /proc/<pid>/cmdline:
   //   /bin/bunterm /bin/bunterm /dev/ttyN [options...]
@@ -94,7 +94,7 @@ const main = async () => {
       Object.entries(process.env).filter((entry) => typeof entry[1] === "string"),
     );
     const targetConsoleNumber = virtualConsoleNumber(options.console);
-    if (consoleArgumentIndex !== -1 && targetConsoleNumber !== activeConsoleNumber) {
+    if (targetConsoleNumber !== activeConsoleNumber) {
       const consoleFd = openSync(options.console, "r+");
       try {
         const child = Bun.spawn(

package/initramfs/bin/chroot

@@ -53,6 +53,19 @@ try { bindings = resolveBindings(options.binds); }
 catch (error) { fail(`invalid bind: ${error.message}`); }
 
 
+// dlopen.js resolves each symbol lazily. Bind everything needed after mounts
+// or chroot before the host libc path can disappear from this process's root.
+// Even --keep-mounts needs umount2 when setup fails and must be rolled back.
+try {
+  void libc.symbols.chroot;
+  if (options.mount || bindings.length) {
+    void libc.symbols.mount;
+    void libc.symbols.umount2;
+  }
+  errno();
+  void libc.symbols.strerror;
+} catch (error) { fail(error.message); }
+
 const report = (message) => { if (options.verbose) console.error(`chroot: ${message}`); };
 
 // ---------------------------------------------------------------- mounts --

package/initramfs/bin/chvt

@@ -0,0 +1,11 @@
+#!/bin/bun
+import { parseChvt, switchVt } from "../lib/chvt.js";
+import { showDocument } from "../lib/document.js";
+try {
+  const options = parseChvt(process.argv.slice(2));
+  if (options.help) await showDocument("chvt");
+  else await switchVt(options.number);
+} catch (error) {
+  console.error(`chvt: ${error.message}`);
+  process.exitCode = 1;
+}

package/initramfs/bin/dhclient

@@ -0,0 +1,8 @@
+#!/bin/bun
+import {parseDhclient,runDhclient} from '../lib/dhclient.js';
+import {showDocument} from '../lib/document.js';
+try {
+  const options=parseDhclient(Bun.argv.slice(2));
+  if(options.help)await showDocument('dhclient');
+  else process.exitCode=await runDhclient(options);
+}catch(error){console.error(`dhclient: ${error.message}`);process.exitCode=1;}

package/initramfs/bin/mount

@@ -325,6 +325,10 @@ const doMount = (source, target, type, flags, data, { verbose, fake }) => {
     console.log(`mount(${source}, ${target}, ${type ?? "(none)"}, [${words.join(",")}], "${data}")`);
   }
   if (fake) return;
+  // A bind over /lib can hide libc before the read-only remount pass fails.
+  void libc.symbols.mount;
+  errno();
+  void libc.symbols.strerror;
   const dataBytes = data ? cString(data) : null;
   const typeBytes = type ? cString(type) : null;
   const result = libc.symbols.mount(

package/initramfs/bin/ping

@@ -0,0 +1,8 @@
+#!/bin/bun
+import {parsePing,runPing} from '../lib/ping.js';
+import {showDocument} from '../lib/document.js';
+try {
+  const options=parsePing(Bun.argv.slice(2));
+  if(options.help)await showDocument('ping');
+  else process.exitCode=await runPing(options);
+} catch(error) {console.error(`ping: ${error.message}`);process.exitCode=2;}

package/initramfs/bin/umount

@@ -58,6 +58,12 @@ const unmount = (target) => {
   return false;
 };
 
+// A previous target may contain libc; later failures still need strerror.
+if (targets.length) {
+  try { void libc.symbols.umount2; errno(); void libc.symbols.strerror; }
+  catch (error) { console.error(`umount: ${error.message}`); process.exit(1); }
+}
+
 let status = 0;
 for (const target of targets) {
   const path = target.length > 1 ? target.replace(/\/+$/, "") : target;

package/initramfs/bin/xdg-open

@@ -0,0 +1,33 @@
+#!/bin/bun
+import { browserTarget, parseOpenArgs, openError, openExitCode, releaseVersion } from "../lib/xdg-open.js";
+import { showDocument } from "../lib/document.js";
+
+try {
+  const options = parseOpenArgs(process.argv.slice(2));
+  if (options.help) {
+    await showDocument("xdg-open");
+  } else if (options.version) {
+    // Both image builders already generate this from buninu-linux's version.
+    const release = new URL("../usr/lib/os-release", import.meta.url);
+    let version;
+    if (await Bun.file(release).exists()) version = releaseVersion(await Bun.file(release).text());
+    else version = (await Bun.file(new URL("../../package.json", import.meta.url)).json()).version;
+    console.log(`xdg-open (Buninu Linux) ${version}`);
+  } else {
+    const url = browserTarget(options.target);
+    for (const tool of ["bunterm", "buninu-browser"])
+      if (!Bun.which(tool)) throw openError(`Required tool not found: ${tool}`, 3);
+    let child;
+    try {
+      child = Bun.spawn(["bunterm", "-e", "buninu-browser", url], {
+        stdio: ["inherit", "inherit", "inherit"],
+      });
+    } catch (error) {
+      throw openError(error.message, error.code === "ENOENT" ? 3 : 4);
+    }
+    process.exitCode = await child.exited === 0 ? 0 : 4;
+  }
+} catch (error) {
+  console.error(`xdg-open: ${error.message}`);
+  process.exitCode = openExitCode(error);
+}

package/initramfs/buninu/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.5.0 - 2026-10-21
+
+- Sync jsgotty to 1.2.0:
+  * Add opt-in Kitty keyboard support for disambiguated shortcuts, including
+    Super, and press/repeat/release events. Support flags 1, 2 and 8, mode
+    queries, and independent mode stacks for normal and alternate screens;
+    legacy keyboard encoding remains the default.
+  * Recover Super state on Android WebViews that deliver Meta key events but
+    omit the modifier state. Handle Android Alt shortcuts without accent
+    dead-key conversion, including recognizable keyup-only events.
+  * Preserve Alt on arrow, Insert, PageUp and PageDown shortcuts, and encode
+    Ctrl+/ as the conventional US control character.
+  * Add a manual keyboard tester with readable, colored shortcut names and
+    raw sequences; restore keyboard and raw modes when it exits.
+  * Allow local Kitty graphics consumers to request binary image data,
+    avoiding a base64 conversion; browser clients retain base64 by default.
+- Sync bunmsh to 0.4.1: use the existing linker-aware shell launcher for the
+  awk fallback's subprocess commands instead of bypassing linker handling.
+
 ## 0.4.21 - 2026-10-15
 
 - Sync jsgotty to 1.1.16: Turn on pixel report

package/initramfs/buninu/apps/bunmsh/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable user-visible changes to bunmsh are documented here.
 
+## [0.4.1] - 2026-10-13
+
+- Fixed awk bypassing linker protection
+
 ## [0.4.0] - 2026-10-13
 
 ### Added and fixed

package/initramfs/buninu/apps/bunmsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunmsh",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Cross-platform command shell for Bun JavaScript",
   "license": "MIT",
   "type": "module",

package/initramfs/buninu/apps/bunmsh/src/main.js

@@ -302,7 +302,7 @@ async function interactive(state) {
     const timer = setTimeout(() => {
       if (pendingCursorQuery?.resolve === resolve) pendingCursorQuery = null;
       resolve(null);
-    }, 60);
+    }, 400);
     pendingCursorQuery = {
       resolve(position) {
         clearTimeout(timer);

package/initramfs/buninu/apps/jsgotty/README.en.md

@@ -3,6 +3,11 @@
 [中文 README](README.md)
 
 ## News
+
+### 2026/10/21
+
+- Added [Kitty keyboard](#kitty-keyboard) support for distinct modifier combinations, including Super, and press/repeat/release events.
+
 ### 2026/08/16
 - Fixed the disconnected-screen `Reconnect` button not being clickable in WebGL mode.
 - The `Reconnect` UI now stays above the WebGL canvas and receives mouse and touch events correctly; Kitty image handling no longer intercepts right-click / long-press for entering a reconnect token or PID.
@@ -238,6 +243,41 @@ The `jsgotty` server has two connection modes:
 - On disconnect, the overlay provides a `Reconnect` button for immediate manual retry.
 - Right-click / long-press on that button lets you enter a custom reconnect token or PID.
 
+## Kitty keyboard
+
+The web terminal supports the shortcut-related parts of the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), separately from Kitty graphics. Legacy keyboard encoding remains the default. A terminal application can opt in:
+
+```sh
+printf '\033[>11u'  # 1: disambiguation + 2: repeat/release + 8: all keys
+printf '\033[<u'    # restore the previous mode when the application exits
+```
+
+The receiving application must decode these sequences and restore the mode in its exit/finally handler; do not leave an ordinary shell in this mode. Negotiation supports `CSI ? u`, `CSI = flags ; mode u`, push and pop. Normal and alternate screens have independent stacks, limited to 32 entries. Reconnection, full reset and soft reset clear the state. Use flag `1` for unambiguous shortcuts, or `11` for modifier keys and press/repeat/release reporting.
+
+DOM Meta maps to Kitty **Super (bit 8)**, not the separate Meta bit (32). Super+X is `CSI 120;9u`; Ctrl+Shift+Super+X is `CSI 120;14u`. Release events add `:3` when enabled.
+
+Supported flags are **1, 2 and 8**; alternate keys (4) and associated text (16) are not implemented or reflected in the negotiated flags. IME composition/text commits and paste retain their existing paths; physical keys and releases cannot be inferred from committed text. Letters, digits, punctuation, navigation, Tab/Enter, function keys, keypad keys and standard Kitty media keys retain distinct modifiers. OS/browser-reserved shortcuts may never reach the page. Keys without standard Kitty codes, such as brightness and microphone mute, are not assigned private encodings.
+
+This implements **jsgotty → PTY** encoding. Controlling Hyprland/Omarchy still requires Casty or another receiver to enable/decode Kitty keyboard and forward Super and release events. It does not complete the remote desktop input chain or change the mouse protocol.
+
+Reload the jsgotty page after updating. Run the manual tester inside its terminal:
+
+```sh
+bun tests/manual/kitty-keyboard.js
+```
+
+It prints negotiated flags, raw sequences, modifiers and event types, exits after 60 seconds or unmodified Escape/q/Ctrl-C, and restores the previous keyboard/raw modes. An optional real bundled-xterm test uses an already installed browser:
+
+```sh
+CHROMIUM_HEADLESS=/path/to/chromium-headless-shell node --test tests/kitty-keyboard-browser.test.js
+```
+
+## Android Keyboards
+
+For Android WebViews that deliver Meta down/up but lose `metaKey`, jsgotty tracks both Meta keys inside its own input handler. Blur or page hiding clears held state and sends releases for reported keys when event reporting is enabled.
+
+In the Android terminal, Alt with letters, digits, punctuation, or space sends terminal Alt sequences based on physical key positions (US layout, including Shift), bypassing accent dead-key handling. Alt-E/I/N/U therefore no longer compose characters such as é, ê, ñ, and ü; input methods and paste remain available. When WebView omits `code`, recognized legacy `keyCode` values provide a fallback. Dead keys delivered only as `keyup` send the shortcut on release, without duplicating a previously handled `keydown`. Active composition, Ctrl, Meta, AltGr, and unidentified keys retain their existing handling. This applies only inside the jsgotty terminal and does not modify Android system keyboard settings.
+
 ## Tested platforms
 - Windows x64: Windows 11
 - Linux x64: CachyOS

package/initramfs/buninu/apps/jsgotty/README.md

@@ -3,6 +3,11 @@
 [English README](README.en.md)
 
 ## News
+
+### 2026/10/21
+
+- 新增 [Kitty keyboard](#kitty-keyboard) 支援，可區分 Super 等修飾鍵組合，並回報按下、重複與放開事件。
+
 ### 2026/08/16
 - 修正 WebGL 模式下斷線畫面的 `Reconnect` 按鈕無法點擊。
 - `Reconnect` 介面現在會正確位於 WebGL canvas 上方並接收滑鼠與觸控事件；右鍵／長按輸入 reconnect token 或 PID 也不會被 Kitty 圖片事件攔截。
@@ -238,6 +243,41 @@ bun gotty.js --client -k <token|pid> [target]
 - 斷線時會提供 `Reconnect` 按鈕，可手動立即重試。
 - 該按鈕右鍵/長按可輸入自訂 reconnect token 或 PID。
 
+## Kitty keyboard
+
+網頁終端現在支援 [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) 的快捷鍵相關功能，與 Kitty 圖片協定分開。預設仍是原本的鍵盤編碼；由終端內的程式選擇開啟：
+
+```sh
+printf '\033[>11u'  # 1：消除歧義 + 2：重複／放開事件 + 8：回報所有按鍵
+printf '\033[<u'    # 程式退出時還原上一層模式
+```
+
+程式必須能解析新編碼，並在 finally／退出處理中還原模式，不建議直接在一般 shell 長期開啟。支援 `CSI ? u` 查詢、`CSI = flags ; mode u` 設定／加上／移除旗標、`CSI > flags u` push 與 `CSI < count u` pop。主畫面與 alternate screen 各有獨立堆疊（上限 32 層）；重連、完整重設或 soft reset 會清除狀態。只需要無歧義快捷鍵時可用旗標 `1`；需要獨立修飾鍵及所有按鍵的 down/repeat/up 時使用 `11`。
+
+網頁的 Meta 對應 Kitty 的 **Super（bit 8）**，不是協定中的另一個 Meta（bit 32）。例如 Super+X 是 `CSI 120;9u`，Ctrl+Shift+Super+X 是 `CSI 120;14u`；啟用事件回報後，放開會帶 `:3`。
+
+目前支援旗標 **1、2、8**；尚未實作替代鍵位（4）與附帶文字（16），查詢只回報實際啟用的旗標。IME 組字／文字提交與貼上保留既有路徑，不保證能回報實體按鍵或放開事件。字母、數字、標點、方向鍵、Tab、Enter、功能鍵、數字鍵盤與有標準 Kitty 編碼的媒體鍵可區分修飾組合；系統／瀏覽器先攔截的快捷鍵不會到達網頁，亮度、麥克風靜音等沒有標準 Kitty 鍵碼的鍵也不會擅自編成私有序列。
+
+這完成的是 **jsgotty → PTY** 的鍵盤編碼。要操作 Hyprland／Omarchy，Casty 或其他接收程式仍須啟用、解析 Kitty keyboard 並轉送 Super 與放開事件；此項改動不代表整條遠端桌面輸入鏈已完成，也不改變滑鼠協定。
+
+在 jsgotty 終端內手動確認（60 秒後自動退出，或按未修飾的 Esc／q／Ctrl+C）：
+
+```sh
+bun tests/manual/kitty-keyboard.js
+```
+
+測試會印出協商結果、原始序列、修飾鍵及 press/repeat/release；結束時還原鍵盤模式與 raw mode。更新後請重新載入 jsgotty 網頁。可用既有 Chromium 執行真正 xterm 前端測試，不會自動安裝瀏覽器：
+
+```sh
+CHROMIUM_HEADLESS=/path/to/chromium-headless-shell node --test tests/kitty-keyboard-browser.test.js
+```
+
+## Android 鍵盤
+
+Android WebView 若有 `Meta` down/up 卻漏掉 `metaKey`，jsgotty 會在自己的輸入處理中追蹤左右 Meta 並還原 Super。失焦或頁面隱藏時清除按住狀態；已送出的按鍵在事件回報模式下會補送放開。
+
+Android 終端的 Alt＋字母、數字、標點及空白會依實體按鍵位置（美式配置，支援 Shift）送出終端 Alt 序列，不進入重音死鍵流程。因此 Alt-E/I/N/U 等組合不再用來輸入 é、ê、ñ、ü；仍可使用輸入法或貼上。若 WebView 省略 `code`，會回退使用可辨識的 `keyCode`；若死鍵只送出 `keyup`，則在放開時補送一次，避免與已處理的 `keydown` 重複。正在組字、Ctrl、Meta、AltGr，以及無法辨識按鍵的事件維持原本處理。此規則只作用於 jsgotty 終端，不修改 Android 的系統鍵盤配置。
+
 ## Tested platforms 已測試作業系統
 - Windows x64: Windows 11
 - Linux x64: CachyOS

package/initramfs/buninu/apps/jsgotty/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "jsgotty",
-  "version": "1.1.16",
+  "version": "1.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "jsgotty",
-      "version": "1.1.16",
+      "version": "1.2.0",
       "dependencies": {
         "node-addon-api": "^7.1.1",
         "ws": "^8.18.3"

package/initramfs/buninu/apps/jsgotty/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgotty",
-  "version": "1.1.16",
+  "version": "1.2.0",
   "description": "Share your terminal as a web application: A JavaScript rewrite of GoTTY",
   "license": "MIT",
   "bin": {

package/initramfs/buninu/apps/jsgotty/static/index.html

@@ -30,6 +30,7 @@
   <script src="./js/windows_bridge.js"></script>
   <script src="./js/zmodem.js"></script>
   <script src="./js/xterm-addon-unicode11.js"></script>
+  <script src="./js/kitty-keyboard.js"></script>
   <script src="./js/gotty.js"></script>