buninu-linux 0.14.57 → 0.16.59

package/scripts/build.js

@@ -28,6 +28,7 @@ import { format, openVolume } from "../initramfs/lib/fat.js";
 import { TYPES, randomGuid, writeGpt } from "../initramfs/lib/gpt.js";
 import { config, jsRuntime, rootDir, runIfMain } from "./arch.js";
 import { fetchAlpine } from "./fetch.js";
+import { gpuReady } from "./fetch-gpu.js";
 import { pack } from "./pack.js";
 
 const nonEmpty = (path) => existsSync(path) && statSync(path).size > 0;
@@ -64,6 +65,7 @@ export const uki = async (cfg = config()) => {
   const missing = !nonEmpty(cfg.kernelImage)
     || !nonEmpty(join(cfg.kernelDir, cfg.efiStub))
     || !nonEmpty(join(cfg.modulesRoot, "modules.dep"))
+    || !gpuReady(cfg)
     || (cfg.real && (
       !nonEmpty(join(cfg.modulesRoot, "kernel/drivers/hid/usbhid/usbhid.ko"))
       || !nonEmpty(join(cfg.modulesRoot, "kernel/drivers/acpi/battery.ko"))
@@ -94,11 +96,22 @@ export const uki = async (cfg = config()) => {
   console.log(`Built ${cfg.arch} UKI with Alpine linux-${cfg.flavor} at vda/EFI/BOOT/${cfg.efiBootName}`);
 };
 
-/** build-image.sh: vda.img, 128 MiB, GPT with the ESP from sector 2048 to the last usable one. */
+// Keep small images at 128 MiB. Reserve 1/16 payload size plus 4 MiB for
+// FAT metadata, directories, GPT/alignment and free space, rounded to 64 MiB.
+// Keep this calculation aligned with build-image.sh.
+export const imageBytes = (payloadBytes) => {
+  if (!Number.isSafeInteger(payloadBytes) || payloadBytes < 0 || payloadBytes > 0xffffffff)
+    throw new Error("EFI payload exceeds the FAT32 single-file limit or has an invalid size");
+  const unit = 64 * 1024 * 1024;
+  return Math.max(128 * 1024 * 1024,
+    Math.ceil((payloadBytes + Math.ceil(payloadBytes / 16) + 4 * 1024 * 1024) / unit) * unit);
+};
+
+/** build-image.sh: dynamically sized GPT disk with one FAT32 ESP. */
 export const image = (cfg = config()) => {
   const efi = join(rootDir, "vda/EFI/BOOT", cfg.efiBootName);
   if (!nonEmpty(efi)) throw new Error(`no ${cfg.arch} EFI payload ${efi} yet; build the UKI first`);
-  const diskSectors = (128 * 1024 * 1024) / 512;
+  const diskSectors = imageBytes(statSync(efi).size) / 512;
   const espStart = 2048;
   const espEnd = diskSectors - 34;
   const path = join(rootDir, "vda.img");
@@ -134,7 +147,7 @@ export const image = (cfg = config()) => {
   } finally {
     volume.close();
   }
-  console.log(`Packed vda/EFI/BOOT/${cfg.efiBootName} into vda.img`);
+  console.log(`Packed vda/EFI/BOOT/${cfg.efiBootName} into vda.img (${diskSectors * 512 / 1024 / 1024} MiB)`);
 };
 
 export const buildAll = async (cfg = config()) => {

package/scripts/fetch-gpu.js

@@ -0,0 +1,105 @@
+// Firmware is image data, not a running service. Only cfg.gpu loads GPU drivers.
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, symlinkSync, statSync, mkdtempSync, renameSync } from "node:fs";
+import { join, dirname, posix } from "node:path";
+import pins from "./gpu-firmware.json" with { type: "json" };
+import { config, runIfMain, withUmask022 } from "./arch.js";
+import { download, readTar } from "./fetch.js";
+
+const fingerprint = (cfg) => createHash("sha256").update(JSON.stringify({ revision: 2, arch: cfg.arch, release: cfg.kernelRelease, real: !!cfg.real, noGpu: !!cfg.noGpu, pins })).digest("hex");
+const marker = (cfg) => join(cfg.modulesRoot, "gpu-support.json");
+
+export const gpuReady = (cfg) => {
+  try {
+    const state = JSON.parse(readFileSync(marker(cfg), "utf8"));
+    if (cfg.noGpu && existsSync(join(cfg.nativeDir, "lib/firmware"))) return false;
+    return state.fingerprint === fingerprint(cfg) && state.files.every(path => statSync(join(cfg.nativeDir, path)).size > 0);
+  } catch { return false; }
+};
+
+// Validate paths before writing; firmware packages can link across GPU folders.
+export const firmwarePath = (name) => {
+  if (!name.startsWith("lib/firmware/") || name.includes("\\") || posix.normalize(name) !== name || name.endsWith("/"))
+    throw Error(`Invalid firmware path: ${name}`);
+  return name;
+};
+export const firmwareLinkTarget = (name, { target, hard }) => {
+  firmwarePath(name);
+  if (target.startsWith("/") || target.includes("\\")) throw Error(`Invalid firmware link: ${name} -> ${target}`);
+  return firmwarePath(posix.normalize(hard ? target : posix.join(posix.dirname(name), target)));
+};
+
+export const extractFirmware = (archives, staging) => {
+  const files = new Map(), links = new Map();
+  for (const archive of archives) {
+    for (const [name, bytes] of archive.entries()) if (name.startsWith("lib/firmware/")) files.set(firmwarePath(name), bytes);
+    for (const [name, link] of archive.links()) if (name.startsWith("lib/firmware/")) {
+      firmwareLinkTarget(name, link);
+      links.set(name, link);
+    }
+  }
+  const directories = new Set();
+  for (const name of [...files.keys(), ...links.keys()])
+    for (let parent = posix.dirname(name); parent !== "."; parent = posix.dirname(parent)) directories.add(parent);
+  // NVIDIA also aliases entire GPU firmware directories. Resolve links in any
+  // path component, without following host filesystem links during validation.
+  const resolve = (name, seen = new Set()) => {
+    if (seen.has(name)) throw Error(`Firmware link cycle: ${name}`);
+    seen.add(name);
+    for (let prefix = name; prefix !== "."; prefix = posix.dirname(prefix)) {
+      const link = links.get(prefix);
+      if (link) {
+        if (seen.has("link:" + prefix)) throw Error(`Firmware link cycle: ${prefix}`);
+        seen.add("link:" + prefix);
+        return resolve(firmwareLinkTarget(prefix, link) + name.slice(prefix.length), seen);
+      }
+    }
+    if (files.has(name)) return files.get(name);
+    if (directories.has(name)) return null;
+    throw Error(`Missing firmware link target: ${name}`);
+  };
+  for (const name of [...files.keys(), ...links.keys()]) {
+    for (let parent = posix.dirname(name); parent !== "."; parent = posix.dirname(parent))
+      if (links.has(parent) || files.has(parent)) throw Error(`Firmware parent is not a directory: ${parent}`);
+    if (links.has(name)) {
+      if (files.has(name)) throw Error(`Duplicate firmware file/link: ${name}`);
+      if (resolve(name) === null && links.get(name).hard) throw Error(`Firmware hardlink to directory: ${name}`);
+    }
+  }
+  for (const [name, bytes] of files) {
+    const path = join(staging, name); mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, bytes);
+  }
+  for (const [name, link] of links) {
+    const path = join(staging, name); mkdirSync(dirname(path), { recursive: true });
+    if (files.has(name)) throw Error(`Duplicate firmware file/link: ${name}`);
+    if (link.hard) writeFileSync(path, resolve(name));
+    else symlinkSync(link.target, path);
+  }
+  return [...files.keys(), ...links.keys()];
+};
+
+export const fetchGpuFirmware = (cfg = config()) => withUmask022(async () => {
+  const dep = readFileSync(join(cfg.modulesRoot, "modules.dep"), "utf8");
+  const builtin = readFileSync(join(cfg.modulesRoot, "modules.builtin"), "utf8");
+  const pc = !cfg.noGpu && cfg.arch === "x86_64" && /\/(?:i915|xe|amdgpu|radeon|nouveau)\.ko(?:[:\n]|$)/.test(dep + "\n" + builtin);
+  // Firmware bytes are architecture-independent; these pins refer to the x86_64 APKs.
+  const packages = pc ? pins : [];
+  const archives = [];
+  for (const pkg of packages) archives.push(readTar(await download(cfg, `${cfg.alpineBase}/${pkg.name}`, pkg.name, pkg.sha256)));
+  mkdirSync(join(cfg.nativeDir, "lib"), { recursive: true });
+  const staging = mkdtempSync(join(cfg.nativeDir, "lib", ".gpu-firmware-"));
+  try {
+    const files = extractFirmware(archives, staging);
+    const target = join(cfg.nativeDir, "lib/firmware");
+    // This generated directory is owned by the firmware fetch stage.
+    rmSync(target, { recursive: true, force: true });
+    if (files.length) renameSync(join(staging, "lib/firmware"), target);
+    writeFileSync(marker(cfg), JSON.stringify({ fingerprint: fingerprint(cfg), packages, files }, null, 2) + "\n");
+    console.log(`GPU support: ${packages.length} firmware packages, ${files.length} files/links; drivers stay opt-in via cfg.gpu`);
+  } finally { rmSync(staging, { recursive: true, force: true }); }
+});
+
+runIfMain(import.meta.url, async () => {
+  if (process.argv.includes("--check")) process.exitCode = gpuReady(config()) ? 0 : 1;
+  else await fetchGpuFirmware();
+});

package/scripts/fetch.js

@@ -73,7 +73,9 @@ export const download = async (cfg, url, name, sha256) => {
 export const readTar = (path) => {
   const data = gunzipSync(readFileSync(path));
   const files = new Map();
+  const links = new Map();
   let longName = null;
+  let longLink = null;
   for (let offset = 0; offset + 512 <= data.length;) {
     const header = data.subarray(offset, offset + 512);
     if (header.every((byte) => byte === 0)) { offset += 512; continue; }
@@ -87,19 +89,25 @@ export const readTar = (path) => {
       for (const record of body.toString("utf8").split("\n")) {
         const match = /^\d+ path=(.*)$/.exec(record);
         if (match) longName = match[1];
+        const link = /^\d+ linkpath=(.*)$/.exec(record);
+        if (link) longLink = link[1];
       }
       continue;
     }
     if (type === "L") { longName = body.toString("utf8").replace(/\0.*$/s, ""); continue; }
+    if (type === "K") { longLink = body.toString("utf8").replace(/\0.*$/s, ""); continue; }
     if (type === "g") continue;
     const prefix = field(345, 155);
     const name = longName ?? (prefix ? `${prefix}/${field(0, 100)}` : field(0, 100));
     longName = null;
     if (type === "0" || type === "\0") files.set(name.replace(/^\.\//, ""), body);
+    if (type === "1" || type === "2") links.set(name.replace(/^\.\//, ""), { target: longLink ?? field(157, 100), hard: type === "1" });
+    longLink = null;
   }
   return {
     // Enumerate regular files without exposing the Map's mutation methods.
     entries() { return files.entries(); },
+    links() { return links.entries(); },
     get(name) {
       const bytes = files.get(name);
       if (!bytes) throw new Error(`${path}: no ${name}`);
@@ -132,7 +140,7 @@ export const fetchAlpine = (cfg = config()) => withUmask022(async () => {
   const release = `lib/modules/${cfg.kernelRelease}`;
   const dep = linux.get(`${release}/modules.dep`).toString();
   const builtin = linux.get(`${release}/modules.builtin`);
-  const { selected, notes } = select({ dep, builtin: builtin.toString(), packageName: cfg.linuxPackage, arch: cfg.arch, flavor: cfg.flavor, real: cfg.real });
+  const { selected, notes } = select({ dep, builtin: builtin.toString(), packageName: cfg.linuxPackage, arch: cfg.arch, flavor: cfg.flavor, real: cfg.real, noGpu: cfg.noGpu });
   for (const note of notes) console.error(note);
   rmSync(cfg.modulesRoot, { recursive: true, force: true });
   writeTo(join(cfg.modulesRoot, "modules.builtin"), builtin);
@@ -142,6 +150,8 @@ export const fetchAlpine = (cfg = config()) => withUmask022(async () => {
   writeTo(join(cfg.modulesRoot, "modules.dep"), trimDependencies(dep, selected));
   writeTo(join(cfg.modulesRoot, "modules.alias"), filterAliases(linux.get(`${release}/modules.alias`).toString(), selected));
 
+  await (await import("./fetch-gpu.js")).fetchGpuFirmware(cfg);
+
   chmodSync(join(cfg.nativeDir, "lib", cfg.muslLoader), 0o755);
   console.log(`Fetched Alpine ${cfg.arch} linux-${cfg.flavor} kernel, ${selected.length} modules, musl, and the ${cfg.efiStub} UKI stub.`);
 });

package/scripts/gpu-firmware.json

@@ -0,0 +1,22 @@
+[
+  {
+    "name": "linux-firmware-amdgpu-20260519-r0.apk",
+    "sha256": "70bc5c972a2da62b84b53e06b6d4c5aec0a8e9d6d280802755c3c8643f3bb8c6"
+  },
+  {
+    "name": "linux-firmware-i915-20260519-r0.apk",
+    "sha256": "3946f8b0a8f0dd187bd71d9aa9b3085a10cb1e8cf4700aa876799e6368309fa4"
+  },
+  {
+    "name": "linux-firmware-nvidia-20260519-r0.apk",
+    "sha256": "9fd3fa7eff65792ef8558c01a27246862e2701a99ef97dba5111b9f6db2c80ee"
+  },
+  {
+    "name": "linux-firmware-radeon-20260519-r0.apk",
+    "sha256": "3b0d6d3982563d17df0c33c2d695a5a547487cb56f2fd9a004ed729fac8f0684"
+  },
+  {
+    "name": "linux-firmware-xe-20260519-r0.apk",
+    "sha256": "6ebc37da64ecb48973c1814d1499c2c2f8f38593e8cf7227811d840c8b17172f"
+  }
+]

package/scripts/modules.js

@@ -16,7 +16,10 @@
 const required = (names) => names.map((name) => ({ name }));
 const optional = (names) => names.map((name) => ({ name, optional: true }));
 
-export const requests = ({ arch, flavor, real }) => [
+export const requests = ({ arch, flavor, real, noGpu = false }) => [
+  // Pack, but never coldplug at boot or through cfg.all. cfg.gpu matches hardware.
+  ...(!noGpu ? optional(["virtio-gpu", "vmwgfx"]) : []),
+  ...(!noGpu && arch === "x86_64" ? optional(["i915", "xe", "amdgpu", "radeon", "nouveau"]) : []),
   ...required([
     "failover",
     "net_failover",

package/scripts/npm-packages.md

@@ -1,24 +1,25 @@
 # npm packages
 # Latest versions checked on 2026-10-11; SHA-256 pins verified against registry SHA-512 integrity.
-# buninu-browser 0.2.4 and buninu-land 0.1.4 verified on 2026-10-18.
-# casty 1.3.7 verified on 2026-10-16.
+# buninu-browser 0.6.0, buninu-land 0.3.1, and casty 1.5.1 verified on 2026-10-29.
+# jspulse 0.2.3 verified on 2026-10-22.
+# jspinyin 0.2.0 verified on 2026-10-22.
 
-"buninu-browser@0.2.4":
-  - https://registry.npmjs.org/buninu-browser/-/buninu-browser-0.2.4.tgz
-  - sha256:247c1ae9644b5016d1dc3f74d1c6c18a986e3961b1d86d2497862e4007bc50aa
+"buninu-browser@0.6.0":
+  - https://registry.npmjs.org/buninu-browser/-/buninu-browser-0.6.0.tgz
+  - sha256:81929d903239f615f6265e0b8bf52cc36e34c622486c517bc58d70078c28f72c
 
-"buninu-land@0.1.4":
-  - https://registry.npmjs.org/buninu-land/-/buninu-land-0.1.4.tgz
-  - sha256:5cda65c60a7af8c7a05ec519a254e0af3f9913ea94f6ae493e5ddc93a8d87407
+"buninu-land@0.3.1":
+  - https://registry.npmjs.org/buninu-land/-/buninu-land-0.3.1.tgz
+  - sha256:6a2df4b52e12bd20972b195903b72a8a1fdefb62a60391c5f090764283731d22
 
-"@drxiaozhi/casty@1.3.7":
-  - https://registry.npmjs.org/@drxiaozhi/casty/-/casty-1.3.7.tgz
-  - sha256:acc0641fb68c00222ba1cd2b7520ba99c269b996e145e82f18466be4d126b811
+"@drxiaozhi/casty@1.5.1":
+  - https://registry.npmjs.org/@drxiaozhi/casty/-/casty-1.5.1.tgz
+  - sha256:821b9ca5e726afa691c4761d9ec917f862bb1a14592a7e590713c5fc735f71fa
 
-"@drxiaozhi/jspulse@0.2.1":
-  - https://registry.npmjs.org/@drxiaozhi/jspulse/-/jspulse-0.2.1.tgz
-  - sha256:9a34a76b1edac6767fa90e33cbc4d3a511c082e9ab73fb196390f841aad37839
+"@drxiaozhi/jspulse@0.2.3":
+  - https://registry.npmjs.org/@drxiaozhi/jspulse/-/jspulse-0.2.3.tgz
+  - sha256:c4a1a7adb559f94096243bebaac0890dc5096d518f7f83ed489c38d5cdfaa263
 
-"@drxiaozhi/jspinyin@0.1.1":
-  - https://registry.npmjs.org/@drxiaozhi/jspinyin/-/jspinyin-0.1.1.tgz
-  - sha256:c6d10a40b6c93a942d85dff69ed2e45dacf506b15caab6821688e8e29df810ed
+"@drxiaozhi/jspinyin@0.2.0":
+  - https://registry.npmjs.org/@drxiaozhi/jspinyin/-/jspinyin-0.2.0.tgz
+  - sha256:b6dfb18f8a8602b9449b75823bce1790fd9682fac68fcbc57c55b4ebd98baa6e

package/test/bunterm-fps.test.js

@@ -0,0 +1,17 @@
+import {test,expect} from 'bun:test';
+import {createFpsMeter} from '../initramfs/lib/bunterm/fps.js';
+test('FPS counts new image presentations, ignores redraws, idles at zero and resets on toggle',()=>{
+ let time=0;const meter=createFpsMeter(()=>time),old={},a={},b={};
+ meter.presented([{image:old}]);expect(meter.enabled).toBe(false);
+ expect(meter.toggle([{image:old}])).toBe(true);
+ meter.presented([{image:old}]);
+ meter.presented([{image:a}]);meter.presented([{image:a}]);
+ meter.presented([{image:a},{image:b}]);meter.presented([]);
+ time=1000;expect(meter.sample()).toBe(2);
+ time=2000;expect(meter.sample()).toBe(0);
+ expect(meter.toggle()).toBe(false);
+ meter.presented([{image:{}}]);
+ time=3000;expect(meter.sample()).toBe(0);
+ meter.toggle([{image:b}]);meter.presented([{image:b}]);
+ meter.presented([{image:{}}]);time=3500;expect(meter.sample()).toBe(2);
+});

package/test/bunterm-image-bytes.test.js

@@ -53,3 +53,18 @@ test('raw RGBA bytes pass directly to CanvasKit', async () => {
   expect(received).toBe(image.data);
   expect(received.equals(pixels)).toBe(true);
 });
+
+import {rawImageOpaque} from '../initramfs/lib/raw-image.js';
+test('raw opacity checks every pixel in aligned and unaligned byte views', () => {
+  for (const length of [0, 1, 7, 8, 9, 15, 16, 17, 33]) for (const offset of [0, 1, 4]) {
+    const storage = new Uint8Array(length * 4 + offset);
+    const pixels = storage.subarray(offset);
+    for (let i = 3; i < pixels.length; i += 4) pixels[i] = 255;
+    expect(rawImageOpaque({pixels})).toBe(true);
+    for (let i = 3; i < pixels.length; i += 4) {
+      pixels[i] = 254;
+      expect(rawImageOpaque({pixels})).toBe(false);
+      pixels[i] = 255;
+    }
+  }
+});

package/test/bunterm-keyboard.test.js

@@ -0,0 +1,116 @@
+import {test,expect} from "bun:test";
+import {Terminal} from "../initramfs/lib/xterm/xterm-headless.mjs";
+import {ConsoleKeys,MediumRawDecoder,legacyKey} from "../initramfs/lib/bunterm/keycodes.js";
+import {attachKeyboard} from "../initramfs/lib/bunterm/keyboard.js";
+const write = (term,text) => new Promise(resolve=>term.write(text,resolve));
+const letters = {16:"q",17:"w",18:"e",19:"r",20:"t",21:"y",22:"u",23:"i",24:"o",25:"p",
+  30:"a",31:"s",32:"d",33:"f",34:"g",35:"h",36:"j",37:"k",38:"l",44:"z",45:"x",46:"c",
+  47:"v",48:"b",49:"n",50:"m"};
+const keys = () => new ConsoleKeys({lookup:(table,n) => {
+  const letter = letters[n];
+  if (letter) return 0xb00 | (table & 1 ? letter.toUpperCase() : letter).charCodeAt(0);
+  return n === 57 ? 32 : n === 53 ? (table & 1 ? 63 : 47) : null;
+}});
+function fixture(extra = {}) {
+  const term = new Terminal({allowProposedApi:true}), output = [], modes = [], switches = [];
+  const keyboard = attachKeyboard({term,write:text=>output.push(text),
+    setEnhanced:v=>modes.push(v),switchVT:n=>switches.push(n),...extra});
+  return {term,output,modes,switches,keyboard,close(){keyboard.dispose();term.dispose();}};
+}
+test("mediumraw extended codes survive every possible read boundary", () => {
+  const bytes = Buffer.from([30,158,0,129,183,128,129,183]); // F13 = 183
+  for (let split=0;split<=bytes.length;split++) {
+    const decoder = new MediumRawDecoder(), events=[];
+    decoder.feed(bytes.subarray(0,split),(c,d)=>events.push([c,d]));
+    decoder.feed(bytes.subarray(split),(c,d)=>events.push([c,d]));
+    expect(events).toEqual([[30,true],[30,false],[183,true],[183,false]]);
+  }
+});
+test("all Ctrl/Alt/Shift/Super letter combinations stay distinct", async () => {
+  const f=fixture();
+  try {
+    await write(f.term,"\x1b[>9u");
+    for (let bits=0;bits<16;bits++) for (const [number,letter] of Object.entries(letters)) {
+      const state=keys();
+      for (const [mask,code] of [[1,42],[2,56],[4,29],[8,125]]) if(bits&mask) f.keyboard.event(state.event(code,true));
+      f.output.length=0;
+      f.keyboard.event(state.event(Number(number),true));
+      expect(f.output).toEqual([`\x1b[${letter.charCodeAt(0)}${bits?";"+(bits+1):""}u`]);
+      f.keyboard.blur();
+    }
+  } finally {f.close();}
+});
+test("push/pop, repeat/release, recovery keys, independent buffers and reset", async () => {
+  const f=fixture(), state=keys();
+  try {
+    await write(f.term,"\x1b[?u\x1b[>11u");
+    expect(f.output).toEqual(["\x1b[?0u"]);
+    f.output.length=0;
+    f.keyboard.event(state.event(125,true));
+    f.keyboard.event(state.event(50,true));
+    f.keyboard.event(state.event(50,true));
+    f.keyboard.event(state.event(50,false));
+    f.keyboard.event(state.event(125,false));
+    expect(f.output).toEqual(["\x1b[57444;9u","\x1b[109;9u","\x1b[109;9:2u","\x1b[109;9:3u","\x1b[57444;1:3u"]);
+    await write(f.term,"\x1b[>1u");
+    f.output.length=0;
+    f.keyboard.event(state.event(28,true));
+    f.keyboard.event(state.event(28,false));
+    f.keyboard.event(state.event(30,true));
+    expect(f.output).toEqual(["\r","a"]);
+    await write(f.term,"\x1b[<u");
+    expect(f.keyboard.flags).toBe(11);
+    await write(f.term,"\x1b[?1049h");
+    expect(f.keyboard.flags).toBe(0);
+    await write(f.term,"\x1b[?1049l");
+    expect(f.keyboard.flags).toBe(11);
+    await write(f.term,"\x1bc");
+    expect(f.keyboard.flags).toBe(0);
+    expect(f.modes).toEqual([true,false,true,false]);
+  } finally {f.close();}
+});
+test("local menu and reserved VT keys never reach the child", async () => {
+  let menu=false;
+  const f=fixture({localInput:()=>menu}), state=keys();
+  try {
+    await write(f.term,"\x1b[>11u");
+    f.keyboard.event(state.event(29,true));
+    f.keyboard.event(state.event(56,true));
+    f.output.length=0;
+    f.keyboard.event(state.event(60,true));
+    f.keyboard.event(state.event(60,false));
+    expect(f.switches).toEqual([2]);
+    expect(f.output).toEqual([]);
+    f.keyboard.blur(); f.output.length=0;
+    menu=true;
+    f.keyboard.event(state.event(30,true));
+    f.keyboard.event(state.event(30,false));
+    expect(f.output).toEqual([]);
+  } finally {f.close();}
+});
+test("layout translation, caps, AltGr, keypad and Unicode map", () => {
+  const state=keys();
+  state.event(58,true); state.event(58,false);
+  expect(state.event(30,true).key).toBe("A");
+  state.event(42,true);
+  expect(state.event(30,true).key).toBe("a");
+  expect(state.event(100,true).key).toBe("AltGraph");
+  expect(state.event(53,true).getModifierState("AltGraph")).toBe(true);
+  const unicode=new ConsoleKeys({lookup:()=>0xf000^0x4e2d});
+  expect(unicode.event(30,true).key).toBe("中");
+  const num=keys();
+  num.event(69,true);
+  expect(num.event(79,true).key).toBe("1");
+  expect(num.event(79,false).location).toBe(3);
+  expect(legacyKey({type:"keydown",key:"/",ctrlKey:true})).toBe("\x1f");
+});
+test("failed console transition resets flags and does not strand the protocol", async () => {
+  const errors=[];
+  const f=fixture({setEnhanced(){throw new Error("not a VT");},onError:e=>errors.push(e.message)});
+  try {
+    await write(f.term,"\x1b[>11u\x1b[?u");
+    expect(f.keyboard.flags).toBe(0);
+    expect(f.output).toEqual(["\x1b[?0u"]);
+    expect(errors).toEqual(["not a VT"]);
+  } finally {f.close();}
+});

package/test/bunterm-mapped-lifetime.test.js

@@ -0,0 +1,147 @@
+import {test, expect} from 'bun:test';
+import fs from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {createRequire} from 'node:module';
+import {bgraParser, BGRA_FORMAT} from '../initramfs/lib/bunterm/raw-protocol.js';
+import {ownMapping, retainMapping} from '../initramfs/lib/mapped-frame.js';
+import {createRawImage, rawImageData, skiaImage} from '../initramfs/lib/raw-image.js';
+import {ImageStore} from '../initramfs/lib/bunterm/images.js';
+const {KittyGraphicsParser} = createRequire(import.meta.url)('../initramfs/buninu/apps/jsgotty/gotty.js');
+const CK = {ColorType:{RGBA_8888:1,BGRA_8888:2}};
+function fixture() {
+  const dir=fs.mkdtempSync(join(tmpdir(),'tty-graphics-protocol-lifetime-'));
+  const parser=new (bgraParser(KittyGraphicsParser))({binaryData:true});
+  const term={buffer:{active:{type:'alternate',baseY:0,cursorY:0,cursorX:0,viewportY:0}}};
+  const store=new ImageStore({CanvasKit:CK,term,renderer:{cellWidth:1,cellHeight:1,offsetX:0,offsetY:0,rows:10,invalidateRows(){}}});
+  const parse=(control,payload='')=>parser.parsePacket(Buffer.from(control+';'+payload),{row:1,col:1});
+  let serial=0;
+  return {parser,store,parse,frame(id=1,format=BGRA_FORMAT){
+    const path=join(dir,'frame'+serial++);fs.writeFileSync(path,Buffer.from([1,2,3,255]));
+    return parse(`a=T,t=t,f=${format},s=1,v=1,i=${id},C=1`,Buffer.from(path).toString('base64'));
+  },close(){parser.dispose();store.delete();fs.rmSync(dir,{recursive:true,force:true});}};
+}
+
+test('replacement protects parser results and renderer until their independent owners release',async()=>{
+  const f=fixture();
+  try {
+    using first=f.frame();const bytes=first.image.data;
+    await f.store.handle(first);
+    using second=f.frame();
+    expect(bytes.byteLength).toBe(4); // parser replaced, renderer/result still own old frame
+    await f.store.handle(second);
+    expect(bytes.byteLength).toBe(4); // result is still borrowed
+    first[Symbol.dispose]();first[Symbol.dispose]();
+    expect(bytes.byteLength).toBe(0);
+    const next=second.image.data;
+    f.parser.dispose();second[Symbol.dispose]();
+    expect(next.byteLength).toBe(4); // renderer outlives parser
+    f.store.delete();expect(next.byteLength).toBe(0);
+  } finally {f.close();}
+});
+
+test('multiple placements and lowercase deletion retain pixels for re-placement',async()=>{
+  const f=fixture();
+  try {
+    using first=f.frame(1,32);const bytes=first.image.data;
+    await f.store.handle(first);first[Symbol.dispose]();
+    using second=f.parse('a=p,i=1,p=two,C=1');await f.store.handle(second);second[Symbol.dispose]();
+    expect(f.store.visible()).toHaveLength(2);
+    await f.store.handle(f.parse('a=d,d=i,i=1,p=two'));
+    expect(f.store.visible()).toHaveLength(1);expect(bytes.byteLength).toBe(4);
+    await f.store.handle(f.parse('a=d,d=a'));
+    expect(f.store.visible()).toHaveLength(0);expect(bytes.byteLength).toBe(4);
+    using again=f.parse('a=p,i=1,C=1');await f.store.handle(again);again[Symbol.dispose]();
+    expect(rawImageData(f.store.visible()[0].image).pixels[0]).toBe(1);
+    await f.store.handle(f.parse('a=d,d=A'));
+    expect(bytes.byteLength).toBe(0);
+  } finally {f.close();}
+});
+
+test('queued frames survive replacement and parser shutdown before consumer handles them',async()=>{
+  const f=fixture();
+  try {
+    using first=f.frame();using second=f.frame();f.parser.dispose();
+    await f.store.handle(first);first[Symbol.dispose]();
+    expect(first.image.data.byteLength).toBe(4);
+    await f.store.handle(second);expect(first.image.data.byteLength).toBe(0);
+    second[Symbol.dispose]();f.store.delete();expect(second.image.data.byteLength).toBe(0);
+    expect(f.frame()).toBeNull();
+  } finally {f.close();}
+});
+
+test('closing while decode awaits cannot repopulate the image store',async()=>{
+  const f=fixture();
+  try {
+    using first=f.frame();const handling=f.store.handle(first);
+    f.store.delete();f.parser.dispose();await handling;
+    expect(f.store.images.size).toBe(0);expect(f.store.placements.size).toBe(0);
+    first[Symbol.dispose]();expect(first.image.data.byteLength).toBe(0);
+  } finally {f.close();}
+});
+
+test('using releases a borrowed frame when processing throws; ordinary buffers never detach',()=>{
+  const f=fixture();let bytes;
+  try {
+    expect(()=>{using first=f.frame();bytes=first.image.data;f.parser.dispose();throw Error('test');}).toThrow('test');
+    expect(bytes.byteLength).toBe(0);
+    const ordinary=Buffer.alloc(4);const image=createRawImage(CK,ordinary,1,1,1);
+    image.delete();expect(ordinary.byteLength).toBe(4);
+  } finally {f.close();}
+});
+
+test('failed/unsupported transfer falls back to GC without breaking cleanup',()=>{
+  for(const transfer of [undefined,()=>{throw Error('not detachable');}]){
+    const bytes=new Uint8Array(4);Object.defineProperty(bytes.buffer,'transfer',{value:transfer});
+    const release=ownMapping(bytes),other=retainMapping(bytes);
+    release();expect(bytes.byteLength).toBe(4);
+    expect(()=>{other();other();release();}).not.toThrow();
+    expect(bytes.byteLength).toBe(4);
+  }
+});
+
+test('query/error mappings are released even though they never enter the image cache',()=>{
+  const f=fixture();const mapped=[];
+  const read=f.parser._readImageFile.bind(f.parser);
+  f.parser._readImageFile=(...args)=>{const bytes=read(...args);mapped.push(bytes);return bytes;};
+  try {
+    // A query validates its file then drops its data. Exercise the same packet
+    // cleanup on an exception after the read, before the cache can retain it.
+    for(const fail of [false,true]){
+      const path=join(tmpdir(),'tty-graphics-protocol-query-'+process.pid);fs.writeFileSync(path,Buffer.from([1,2,3,255]));
+      const resolve=f.parser._resolveImageData.bind(f.parser);
+      if(fail)f.parser._resolveImageData=(...args)=>{resolve(...args);throw Error('validation failed');};
+      const result=f.parse(`a=q,t=t,f=${BGRA_FORMAT},s=1,v=1,i=7`,Buffer.from(path).toString('base64'));
+      expect(result.responseMessage).toStartWith(fail?'ERROR:':'OK');
+      expect(mapped.at(-1).byteLength).toBe(0);
+    }
+    expect(f.parser.images.size).toBe(0);
+  } finally {f.close();}
+});
+
+test('materialized Skia images and mapped bytes both release even if Skia cleanup throws',()=>{
+  const bytes=new Uint8Array(4),owner=ownMapping(bytes);
+  const image=createRawImage({...CK,AlphaType:{Unpremul:1},ColorSpace:{SRGB:1},MakeImage(){return {delete(){throw Error('Skia cleanup');}};}},bytes,1,1,1);
+  owner();skiaImage(image);
+  expect(()=>image.delete()).toThrow('Skia cleanup');expect(bytes.byteLength).toBe(0);
+  expect(()=>image.delete()).not.toThrow();
+});
+
+test('repeated mapped replacements unmap promptly without waiting for a GC',async()=>{
+  const f=fixture();let previous;
+  try {
+    for(let i=0;i<200;i++){
+      using frame=f.frame();await f.store.handle(frame);
+      if(previous)expect(previous.byteLength).toBe(0);
+      previous=frame.image.data;
+      expect(previous[3]).toBe(255);
+    }
+    f.parser.dispose();f.store.delete();expect(previous.byteLength).toBe(0);
+    if(process.platform==='linux'){
+      const maps=fs.readFileSync('/proc/self/maps','utf8');
+      // Files were unlinked at read time; lingering mappings would still have
+      // their original name followed by '(deleted)' here.
+      expect(maps.split('\n').filter(line=>line.includes('tty-graphics-protocol-lifetime-'))).toHaveLength(0);
+    }
+  } finally {f.close();}
+});

package/test/bunterm-next-vt.test.js

@@ -0,0 +1,9 @@
+import {expect,test} from 'bun:test';
+import {nextVirtualTerminal} from '../initramfs/lib/bunterm/vt.js';
+test('new bunterm appends after known sessions and reserves the initial console',()=>{
+ expect(nextVirtualTerminal([])).toBe(2);
+ expect(nextVirtualTerminal([{number:1}])).toBe(2);
+ expect(nextVirtualTerminal([{number:1},{number:2},{number:6}])).toBe(7);
+ expect(nextVirtualTerminal([{number:4}])).toBe(5);
+ expect(()=>nextVirtualTerminal([{number:63}])).toThrow('No next tty');
+});

package/test/bunterm-raw-protocol.test.js

@@ -0,0 +1,39 @@
+import {test,expect} from 'bun:test';
+import {createRequire} from 'node:module';
+import {preferredPixelFormat,bgraParser,BGRA_FORMAT} from '../initramfs/lib/bunterm/raw-protocol.js';
+const {KittyGraphicsParser}=createRequire(import.meta.url)('../initramfs/buninu/apps/jsgotty/gotty.js');
+const field=offset=>({offset,length:8,msbRight:0});
+const fb=(red=16,blue=0)=>({bitsPerPixel:32,fields:{red:field(red),green:field(8),blue:field(blue),transp:{length:0}}});
+test('native preference follows framebuffer bitfields; browser parser remains unchanged',()=>{
+ for(const [display,preferred] of [[fb(),'bgra'],[fb(0,16),'rgba'],[{bitsPerPixel:16},'png'],[undefined,'png']]){
+  expect(preferredPixelFormat(display)).toBe(preferred);
+  const p=new (bgraParser(KittyGraphicsParser,display))({binaryData:true});
+  const packet=Buffer.from(`a=q,f=${BGRA_FORMAT},s=1,v=1,i=41;AAAA/w==`);
+  expect(p.parsePacket(packet,{}).responseMessage).toBe('OK Buninu1 '+preferred);
+  expect(new KittyGraphicsParser().parsePacket(packet,{}).responseMessage).toBe('OK');
+  expect(p.images.size).toBe(0);
+  expect(p.parsePacket(Buffer.from(`a=q,f=${BGRA_FORMAT},s=2,v=1,i=41;AAAA/w==`),{}).responseMessage).toStartWith('ERROR:');
+ }
+ const bad=fb();bad.fields.red.msbRight=1;
+ expect(preferredPixelFormat(bad)).toBe('png');expect(preferredPixelFormat(fb(),false)).toBe('png');
+});
+
+import fs from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+test('raw temporary mappings survive unlink; regular and partial files retain copying behavior',()=>{
+ const dir=fs.mkdtempSync(join(tmpdir(),'tty-graphics-protocol-mmap-'));
+ const parser=new (bgraParser(KittyGraphicsParser,fb()))({binaryData:true});
+ const bytes=Buffer.from([1,2,3,255,4,5,6,255]);
+ try{
+  for(const format of [32,BGRA_FORMAT]){
+   const path=join(dir,'frame');fs.writeFileSync(path,bytes);
+   const got=parser._readImageFile({f:String(format),s:'2',v:'1'},Buffer.from(path).toString('base64'),true);
+   expect(fs.existsSync(path)).toBe(false);expect(got).toEqual(bytes);
+  }
+  const path=join(dir,'regular');fs.writeFileSync(path,bytes);
+  const payload=Buffer.from(path).toString('base64'),control={f:String(BGRA_FORMAT),s:'2',v:'1'};
+  expect(parser._readImageFile(control,payload,false)).toEqual(bytes);expect(fs.existsSync(path)).toBe(true);
+  expect(parser._readImageFile({...control,O:'4',S:'4'},payload,true)).toEqual(bytes.subarray(4));
+ }finally{parser.dispose();fs.rmSync(dir,{recursive:true,force:true});}
+});