buninu-linux 0.6.0 → 0.7.1

package/README.md

@@ -20,7 +20,7 @@
   * There is no BusyBox and no C bootstrap.
 
 - Homepage: <https://buninu.org>
-- Souce: [github.com/jjtseng93/buninu-linux](https://github.com/jjtseng93/buninu-linux)
+- Source: [github.com/jjtseng93/buninu-linux](https://github.com/jjtseng93/buninu-linux)
 - Buninu userspace source: [github.com/jjtseng93/buninu](https://github.com/jjtseng93/buninu)
   + **BUNinu Is Not Unix** 🐮
   + **幫你牛** 🐂 ・ **Bunに入魂** 🔥
@@ -33,16 +33,20 @@
 - Still in the early stages
 - [Video here](https://www.reddit.com/r/bun/comments/1wkpraj/buninu_linux_a_distro_with_bun_as_pid_1): Booted successfully on real x86-64 UEFI hardware with `--real`:
   * Bun reaches its interactive REPL
-  * start() starts the Buninu userspace shell
+  * `start` starts the Buninu userspace shell
   * `cfg.disk` + shell `mount` mounts local disks
   * `cfg.net` loads common wired NIC and Android USB-tethering drivers
+  * `cfg.sound` loads every packaged ALSA sound module
   * Android phone USB tethering over RNDIS has been tested successfully, allowing Buninu Linux to access the Internet through an Android phone
   * IP addresses and routes are configured manually because the image does not yet include a DHCP client.
-  * The bundled `jmi` editor, jsmdcui editor/terminal multitasking, and local JavaScript execution also work.
+  * The bundled `jmi` editor, jsmdcui App runtime, and local JavaScript execution also work.
+  * Multi-tasking with kernel VT or jsmdcui
+    + See [Multitasking modes](#multitasking-modes)
   * The graphical terminal `bunterm` draws on the framebuffer with CJK, colour emoji and kitty images; see [Showing images](#showing-images)
     + Also has mouse click, wheel, and cursor drawing
     + Simplified browser works: @sanohiro/casty in chroot debian
     + (Use at your own risk: We haven't fully examined its code)
+    + Playing YouTube with sound(experimental)
     + See [Commands inside `/bin`](#commands-inside-bin) for browser usage instructions
 
 ---
@@ -140,7 +144,7 @@ display and USB keyboard with a welcome ending like this:
 Welcome to Buninu Linux!
 Bun 1.4.2 is now PID 1
 Type start() to run buninu --local
-Configuration getters: cfg.all, cfg.disk, cfg.net, cfg.power
+Configuration getters: cfg.all, cfg.disk, cfg.net, cfg.power, cfg.sound
 
 bun-repl>
 ```
@@ -155,6 +159,7 @@ Load only the subsystem needed, then enter the Buninu shell:
 cfg.net       // wired NIC and Android USB-tethering drivers
 cfg.disk      // SATA/NVMe/USB storage drivers and detected block devices
 cfg.power     // battery, AC, button and thermal drivers
+cfg.sound     // all packaged ALSA sound modules and detected sound devices
 start()
 ```
 
@@ -206,6 +211,8 @@ bun ./index.js -fbr
 The first boot line from `run-qemu.sh` names the guest, machine, accelerator
 and firmware it picked. A bare `-r` boots whichever architecture `vda.img`
 was last built for; `-br --arch arm64` is the aarch64 edit-and-boot loop.
+To run `bunterm` in a QEMU window on the aarch64 guest, see
+[What differs on aarch64](#what-differs-on-aarch64).
 
 #### amd64 Linux
 
@@ -229,9 +236,32 @@ qemu-efi-aarch64` to run.
   Alpine's aarch64 packages and `bun-linux-aarch64-musl`.
 * The serial console is `ttyAMA0` (QEMU `virt`'s PL011) instead of `ttyS0`.
 * `--real` is x86_64 only: its module set is PC hardware.
-* The current aarch64 QEMU configuration supplies no framebuffer or PS/2
-  devices, so `bunterm` has nothing to draw on yet; the serial REPL and the
-  Buninu shell work as on x86_64.
+* QEMU's `virt` machine has no display or PS/2 devices, so by default
+  `bunterm` has nothing to draw on; the serial REPL and the Buninu shell work
+  as on x86_64. To run `bunterm`, build with `--linux-lts` and give QEMU a
+  `ramfb` display and virtio input devices. On a Mac, `-display cocoa` opens
+  the window:
+
+  ```sh
+  bun ./index.js -fbr --arch arm64 --linux-lts -- \
+      -device ramfb -device virtio-keyboard-pci -device virtio-mouse-pci -display cocoa
+  ```
+
+  Once that image is built, boot it again without rebuilding (and without
+  Docker). `--linux-lts` belongs to the build, so leave it off `-r`:
+
+  ```sh
+  bun ./index.js -r --arch arm64 -- \
+      -device ramfb -device virtio-keyboard-pci -device virtio-mouse-pci -display cocoa
+  ```
+
+  `start()` in the serial REPL, then `bunterm 2` opens bunterm on VT 2 in the
+  QEMU window and returns to the serial shell; type into the window. The
+  serial console is not a VT, so a bare `bunterm` there takes the active VT 1
+  and holds the serial shell until it exits; naming another VT starts it
+  detached (see [Multiple virtual consoles with bunterm](#multiple-virtual-consoles-with-bunterm)). The
+  firmware sets up ramfb at 800×600, and `init.js` loads `simpledrm` so it
+  becomes `/dev/fb0` (see [graphics.md](graphics.md#trying-it)).
 * `--export` writes `buninu-linux-<version>-aarch64.img`.
 * Before the kernel starts, Homebrew's aarch64 EDK2 prints a few
   `Error: Image at … start failed` lines (its own drivers for hardware `virt`
@@ -281,6 +311,7 @@ Load only the hardware subsystem you need:
 cfg.net
 cfg.disk
 cfg.power
+cfg.sound
 ```
 
 `cfg.net` loads the packaged wired-network and Android USB-tethering drivers and prints detected
@@ -296,7 +327,10 @@ ip route add default via 192.168.1.1
 The real image initializes `/etc/resolv.conf` with `1.1.1.1` and `8.8.8.8`;
 replace them if your network requires different DNS servers. `cfg.disk` loads
 common SATA/PATA/SCSI, NVMe/VMD and USB-storage drivers so detected disks and
-partitions appear in `/dev`. To inspect a filesystem without mounting it:
+partitions appear in `/dev`. `cfg.sound` unconditionally loads every sound
+module packaged in the image, then lists the resulting `/dev/snd` devices; it
+does not probe the hardware before loading modules. To inspect a filesystem
+without mounting it:
 
 ```sh
 mount -fv /dev/sda1 /mnt
@@ -341,7 +375,29 @@ If `Enter` is not recognized in a particular terminal, try `Ctrl-J` or
 - `jsmdcui --cdp-maze` runs a self-solving maze game
   * Run `bunterm` first to show its Emojis
 
-### Panes, terminals, and tabs
+### Multitasking modes
+
+#### Multiple virtual consoles with bunterm
+
+Run a separate `bunterm` on each Linux virtual console. A numeric positional
+argument is a short form of the corresponding device, so `bunterm 2` means
+`bunterm /dev/tty2`:
+
+```sh
+bunterm 2
+bunterm 3 -s 13
+```
+
+When the named VT is not the active one, `bunterm` starts there as a detached
+session, switches the display to it, and immediately returns control to the
+calling shell. Switch among VTs with `Ctrl+Alt+F1` through `Ctrl+Alt+F12`, or
+move to the previous or next VT with `Alt+Left` and `Alt+Right`. Each VT keeps
+its own terminal session; an inactive bunterm continues processing its PTY but
+stops drawing until its VT becomes active again. Only one bunterm can control a
+given VT. If one is already in use, the error identifies its PID and suggests
+another VT number.
+
+#### Panes, terminals, and tabs with jsmdcui
 
 `jmi` and jsmdcui can keep editors and terminal sessions open together. Press
 `Ctrl-E`, type `term`, and press `Enter` to open the default Buninu shell in a
@@ -350,7 +406,7 @@ terminal pane. `term COMMAND` starts a specific command instead. Use `vsplit`,
 editor pane or tab; each command optionally accepts a filename. From an editor
 pane, `Ctrl-T` is the direct shortcut for a new empty tab.
 
-#### Pane and tab controls
+##### Pane and tab controls
 
 | Input | Result |
 | --- | --- |
@@ -451,12 +507,38 @@ below a shown image, and images scroll with the text. When the program you
 started exits, the console returns to text mode. `bunterm --help` has the
 options; [graphics.md](graphics.md) describes how it is built. The image
 needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
-(the default `linux-virt` builds one only as modules the image omits).
+(the default `linux-virt` builds one only as modules the image omits). The
+aarch64 guest also needs a QEMU display; see
+[What differs on aarch64](#what-differs-on-aarch64).
+
+### Clipboard
+
+`bunterm` supports copy and paste through OSC 52, so programs such as
+`casty` and `jsmdcui` can use the clipboard. bunterm keeps nothing itself; it
+passes every copy and paste to Buninu's `xclip -selection clipboard`. For
+now that clipboard is a file, `$HOME/.xclip.clipboard`, read and written in
+the ramdisk, so all bunterm sessions share it and it is gone after a reboot.
+`bunterm --no-clipboard` turns OSC 52 off.
+
+For Chinese input, run the pinyin input method
+[jspinyin](https://www.npmjs.com/package/@drxiaozhi/jspinyin) in a bunterm
+that is not inside a chroot, so it uses Buninu's `xclip`:
+
+```sh
+bun x @drxiaozhi/jspinyin
+```
+
+- jspinyin → casty: press `Ctrl-C` in jspinyin to copy its result box, then
+  `Ctrl-V` in casty pastes it through OSC 52.
+- casty → jsmdcui / jspinyin: `Alt-C` in casty copies the selection through
+  OSC 52, and `Ctrl-V` pastes it in jsmdcui or jspinyin, since jsmdcui reads
+  from `xclip` first by default.
 
 ## Commands inside /bin
 
 | command | does | manual |
 | --- | --- | --- |
+| `buninu-linux-help` | render this buninu-linux README from `/usr/share/doc/buninu-linux/README.md` | `buninu-linux-help` |
 | `mount` | `mount(2)` with type detection, `-o` parsing, `LABEL=`/`UUID=`, bind/move/remount; loads required filesystem and disk modules | `mount --help` → `/usr/share/doc/buninu-linux/mount.md` |
 | `umount` | `umount2(2)` with `-l`, `-f`, `-R` | `umount --help` |
 | `ip` | iproute2 grammar over `SIOC*` ioctls and `/proc/net`: `link`, `addr`, `route`, `neigh` | `ip --help` |
@@ -469,7 +551,7 @@ needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
 | `chroot` | `chroot(2)` into another root directory, mounting `/proc`, `/sys`, `/dev`, `/dev/pts`, `/run`, `/tmp` and `/etc/resolv.conf` for you and unmounting them afterwards | `chroot --help` |
 | `bunterm` | a graphical terminal on the framebuffer: Skia (CanvasKit) text with CJK, colour emoji, seamless box drawing, kitty graphics images, with the mouse working, wheel scrollback included (`--no-mouse` turns it off); xterm.js's emulator core over Bun's built-in PTY | `bunterm --help` |
 
-Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes eleven commands
+Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes twelve commands
 implemented as Bun scripts.
 
 The small `tar` reads the archive's own headers for links and listing, so
@@ -514,11 +596,13 @@ bun udocker.js create --name db debian:13
 cd ~/.udocker/containers/db/ROOT
 chroot . /bin/bash
 apt update
-apt install curl unzip chromium fonts-noto-cjk fonts-noto-color-emoji npm
+apt install --no-install-recommends ca-certificates curl unzip chromium-headless-shell fonts-noto-cjk fonts-noto-color-emoji git
 curl -fsSL https://bun.sh/install | bash
 bun x bunmsh
 # We haven't fully reviewed
 # @sanohiro/casty's safety
+# below is a fork of mine
+# fixing some issues
 # !!!Use at your own risk!!!
 # !!!Use at your own risk!!!
 # !!!Use at your own risk!!!
@@ -529,10 +613,15 @@ bun x bunmsh
 # !!!Use at your own risk!!!
 # !!!Use at your own risk!!!
 # !!!Use at your own risk!!!
-bun i -g @sanohiro/casty
+cd
+git clone https://github.com/jjtseng93/casty
+cd casty/bin
 # When clicking around, don’t release the mouse button immediately after pressing it, to make sure the mouse-down event is triggered
-casty https://github.com/jjtseng93/buninu-linux
-
+bun casty.js buninu.org
+# Playing YouTube with sound(experimental)
+# make sure you have run `cfg.sound` in bun-repl
+# follow the dumped instructions
+bun x bunproot --setup.pulse
 
 
 # Download and enter an x64 Alpine minirootfs
@@ -581,7 +670,7 @@ tar czvf /tmp/buninu.tar.gz README.md package.json
 
 # On a virtual console: a graphical terminal with CJK, emoji and images
 bunterm
-bunterm /dev/tty1 --font-size 20 -e bun /buninu/apps/jsmdcui/src/index.js --demo
+bunterm /dev/tty1 --font-size 13 -e bun /buninu/apps/jsmdcui/src/index.js --demo
 ```
 
 The graphics stack behind `bunterm` — the framebuffer module, CanvasKit,
@@ -724,7 +813,7 @@ its own.
 ```text
 index.js                  entry point: -f / -b / -r / --arch / --docker / --export / --linux-lts / --real
 Dockerfile                the Debian 13 build toolchain for --docker (and macOS)
-fetch-alpine.sh           [fetch]  kernel, EFI stub, musl, network/input modules
+fetch-alpine.sh           [fetch]  kernel, EFI stub, musl, network/input/display modules
 fetch-bun.sh              [fetch]  Bun, libstdc++, libgcc
 build-uki.sh              [build]  UKI; calls scripts/pack-initramfs.sh
 build-image.sh            [build]  GPT disk image; shared with the hello-world EFI
@@ -1060,7 +1149,7 @@ until `cfg.net` loads the packaged drivers and the user assigns an address and
 route.
 
 On a `--real` image the REPL also offers the getter-based `cfg` namespace:
-`cfg.net`, `cfg.disk`, `cfg.power` and `cfg.all` run as soon as the property is read, without
+`cfg.net`, `cfg.disk`, `cfg.power`, `cfg.sound` and `cfg.all` run as soon as the property is read, without
 parentheses. `cfg.net` loads every packaged network module (including PHY and bus support),
 then reads the `modalias` of every PCI and USB network device, matches it
 against the `pci:`/`usb:` lines
@@ -1072,7 +1161,10 @@ declared dependencies. `--real` ships Intel `e1000`/`e1000e`/`igb`/`igc`,
 Realtek `r8169`, Atheros `alx`, Broadcom `tg3`, common USB dongles, and
 `rndis_host`/`cdc_ether`/`cdc_ncm`/`cdc_eem`/`cdc_subset`/`zaurus` for Android
 USB tethering. `cfg.net` unconditionally attempts all of these packaged
-network modules. `cfg.power` loads the ACPI
+network modules. `cfg.sound` likewise unconditionally attempts every packaged
+module below `kernel/sound/`, then lists `/dev/snd`; it does no hardware probe.
+The packaged sound set covers QEMU ES1371/HDA and common PC HDA/HDMI and USB
+audio where the selected kernel flavor provides them. `cfg.power` loads the ACPI
 `battery`, `ac`, `button` and `thermal` modules through `/lib/modprobe.js`
 and lists `/sys/class/power_supply` (a desktop without a battery simply
 reports nothing registered). Nothing loads them at boot. PID 1 also installs
@@ -1101,10 +1193,13 @@ for the userspace session.
   * [Basic configuration](#basic-configuration)
   * [Editor quick start](#editor-quick-start)
     + [jsmdcui](#jsmdcui)
-  * [Panes, terminals, and tabs](#panes-terminals-and-tabs)
-    + [Pane and tab controls](#pane-and-tab-controls)
+  * [Multitasking modes](#multitasking-modes)
+    + [Multiple virtual consoles with bunterm](#multiple-virtual-consoles-with-bunterm)
+    + [Panes, terminals, and tabs with jsmdcui](#panes-terminals-and-tabs-with-jsmdcui)
+      - [Pane and tab controls](#pane-and-tab-controls)
   * [Using Bun Modern Shell](#using-bun-modern-shell)
   * [Showing images](#showing-images)
+  * [Clipboard](#clipboard)
 - [Commands inside /bin](#commands-inside-bin)
 - [Environment and dependencies](#environment-and-dependencies)
   * [Build environment](#build-environment)

package/fetch-alpine.sh

@@ -81,6 +81,22 @@ if [ "$arch" = x86_64 ]; then
 else
     select_module virtio_input
 fi
+# The framebuffer for bunterm. Both lts kernels set CONFIG_SYSFB_SIMPLEFB, so
+# the UEFI GOP (QEMU's ramfb on aarch64 virt) becomes a simple-framebuffer
+# device that only simpledrm drives: x86_64 lts builds it in, aarch64 lts has
+# it as a module. init.js loads it at boot, which is what makes /dev/fb0.
+if [ "$linux_flavor" = lts ]; then
+    select_optional_module simpledrm
+fi
+
+# Sound: a compact set covering QEMU's emulated AC97/HDA devices and the
+# usual PC HDA/HDMI and USB-audio paths. Dependencies pull in the ALSA core,
+# PCM, timer, codec and USB support needed by each available leaf driver.
+# Some kernel flavors build fewer of these, so keep every leaf optional.
+for module in snd-ens1371 snd-hda-intel snd-hda-codec-generic \
+              snd-hda-codec-hdmi snd-usb-audio; do
+    select_optional_module "$module"
+done
 
 if [ "${REAL_MACHINE:-}" = 1 ]; then
     # USB keyboard for the console; common storage paths (SATA/AHCI HDD and

package/graphics.md

@@ -174,13 +174,22 @@ needs about 1 GB.
 
 ## Trying it
 
-The framebuffer needs a kernel that provides one. Alpine's `linux-lts` has
-`CONFIG_FB`, `CONFIG_FB_EFI` and `CONFIG_DRM_SIMPLEDRM` built in; the default
-`linux-virt` builds them as modules, and the image ships only the network,
-storage, USB and HID modules, so there `/dev/fb0` never appears. Build with
-`./index.js -b --linux-lts` (or `--real`); under QEMU the lts kernel gets a
-1280×800 `simpledrm` framebuffer from the UEFI GOP even with `-display none`,
-and the monitor's `screendump` shows it. From a virtual console in the guest:
+The framebuffer needs a kernel that provides one. Both `linux-lts` kernels
+set `CONFIG_SYSFB_SIMPLEFB`, so the UEFI GOP becomes a `simple-framebuffer`
+device, which only `simpledrm` drives (`efifb` never sees it). The x86_64
+`linux-lts` builds `simpledrm` in. The aarch64 one has it as a module:
+`fetch-alpine.sh` ships it and its DRM dependencies for lts builds, and
+`init.js` loads it at boot. The default `linux-virt` builds the framebuffer
+drivers as modules, and the image ships only the network, storage, USB and
+HID modules, so there `/dev/fb0` never appears. Build with
+`./index.js -b --linux-lts` (or `--real` on x86_64). Under QEMU, the x86_64
+lts kernel gets a 1280×800 `simpledrm` framebuffer from the UEFI GOP even
+with `-display none`, and the monitor's `screendump` shows it. QEMU's aarch64
+`virt` machine has no display until you add `-device ramfb`; EDK2 then
+provides an 800×600 GOP, and `virtio-keyboard-pci` gives the VTs a keyboard
+(see the README's
+[What differs on aarch64](README.md#what-differs-on-aarch64)). From a virtual
+console in the guest:
 
 ```sh
 bunterm                                  # /bin/sh on this console
@@ -206,6 +215,13 @@ host, `jsmdcui --tui` on a Markdown file with a JPEG (bunterm sets
 `JSMDCUI_KITTY_MODE=extended` for the program it runs) places the image
 through its transmit / `a=p` / `a=d` sequence exactly as in the browser.
 
+Verified on aarch64 (lts kernel, Hypervisor.framework, `-device ramfb
+-device virtio-keyboard-pci -device virtio-mouse-pci`, `-display none`):
+`/proc/fb` lists `simpledrmdrmfb`; `bunterm 2` from the serial shell returns
+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`.
+
 ## Not done yet
 
 - Selection and scrollback viewing in `bunterm` (the pointer itself works,

package/initramfs/bin/buninu-linux-help

@@ -0,0 +1,12 @@
+#!/bin/bun
+
+import { resolve } from "node:path";
+import { showDocument } from "../lib/document.js";
+
+// The packed image has README.md under /usr/share/doc/buninu-linux. During
+// development, address the checkout's canonical copy relative to that same
+// document directory so this command runs as-is and still uses showDocument.
+const installedReadme = resolve(import.meta.dir, "../usr/share/doc/buninu-linux/README.md");
+await showDocument(await Bun.file(installedReadme).exists()
+  ? "README"
+  : "../../../../../README");

package/initramfs/bin/bunterm

@@ -3,16 +3,22 @@
 
 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 { closeSync, openSync, readFileSync } from "node:fs";
+
+const CANONICAL_BUNTERM = "/bin/bunterm";
 
 const usage = () => {
   console.error(`Usage:
-  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [--no-mouse] [-e command [argument...]]
+  bunterm [N | /dev/ttyN] [-s N | --font-size N] [--fb /dev/fb0] [--no-mouse] [--no-clipboard] [-e command [argument...]]
   bunterm -h | --help`);
 };
 
 const main = async () => {
   const options = { argv: [] };
   const arguments_ = process.argv.slice(2);
+  let consoleArgumentIndex = -1;
   for (let index = 0; index < arguments_.length; index++) {
     const argument = arguments_[index];
     if (argument === "-h" || argument === "--help") {
@@ -36,8 +42,10 @@ const main = async () => {
       }
       return value;
     };
-    if (argument === "--font-size" || argument.startsWith("--font-size=")) {
-      options.fontSize = Number(valued("--font-size"));
+    if (argument === "-s" || argument.startsWith("-s=")
+        || argument === "--font-size" || argument.startsWith("--font-size=")) {
+      const name = argument === "-s" || argument.startsWith("-s=") ? "-s" : "--font-size";
+      options.fontSize = Number(valued(name));
       if (!Number.isFinite(options.fontSize) || options.fontSize < 6) throw new Error("--font-size must be a number of at least 6");
     } else if (argument === "--line-height" || argument.startsWith("--line-height=")) {
       options.lineHeight = Number(valued("--line-height"));
@@ -50,13 +58,66 @@ const main = async () => {
       options.mouse = true;
     } else if (argument === "--no-mouse") {
       options.mouse = false;
-    } else if (argument.startsWith("/dev/")) {
-      options.console = argument;
+    } else if (argument === "--no-clipboard") {
+      options.clipboard = false;
+    } else if (/^[1-9][0-9]*$/.test(argument) || argument.startsWith("/dev/")) {
+      const number = /^[1-9][0-9]*$/.test(argument) ? Number(argument) : virtualConsoleNumber(argument);
+      if (number === null) throw new Error(`expected N or /dev/ttyN, got ${argument}`);
+      if (consoleArgumentIndex !== -1) throw new Error("only one virtual console may be specified");
+      options.console = `/dev/tty${number}`;
+      consoleArgumentIndex = index;
     } else {
       usage();
       throw new Error(`unexpected argument: ${argument}`);
     }
   }
+
+  const probe = openConsole(["/dev/tty0"]);
+  let activeConsoleNumber;
+  try {
+    activeConsoleNumber = activeConsole(probe);
+  } finally {
+    probe.close();
+  }
+  if (!options.console) options.console = `/dev/tty${activeConsoleNumber}`;
+
+  // Every live bunterm converges on one unambiguous /proc/<pid>/cmdline:
+  //   /bin/bunterm /bin/bunterm /dev/ttyN [options...]
+  // execve replaces the original process, so no forwarding parent remains.
+  const remaining = arguments_.filter((_argument, index) => index !== consoleArgumentIndex);
+  const canonicalArgv = [CANONICAL_BUNTERM, CANONICAL_BUNTERM, options.console, ...remaining];
+  const currentArgv = readFileSync("/proc/self/cmdline").toString("utf8").split("\0");
+  if (currentArgv.at(-1) === "") currentArgv.pop();
+  if (currentArgv.length !== canonicalArgv.length
+      || currentArgv.some((argument, index) => argument !== canonicalArgv[index])) {
+    const environment = Object.fromEntries(
+      Object.entries(process.env).filter((entry) => typeof entry[1] === "string"),
+    );
+    const targetConsoleNumber = virtualConsoleNumber(options.console);
+    if (consoleArgumentIndex !== -1 && targetConsoleNumber !== activeConsoleNumber) {
+      const consoleFd = openSync(options.console, "r+");
+      try {
+        const child = Bun.spawn(
+          [process.execPath, CANONICAL_BUNTERM, options.console, ...remaining],
+          {
+            argv0: CANONICAL_BUNTERM,
+            detached: true,
+            env: environment,
+            stdin: "ignore",
+            stdout: consoleFd,
+            stderr: consoleFd,
+          },
+        );
+        child.unref();
+      } finally {
+        closeSync(consoleFd);
+      }
+      return 0;
+    }
+    process.execve(process.execPath, canonicalArgv, environment);
+    throw new Error("process.execve returned unexpectedly");
+  }
+
   return runTerminal(options);
 };
 

package/initramfs/init.js

@@ -179,6 +179,16 @@ try {
   console.error(`init.js: input modules: ${error?.message ?? error}`);
 }
 
+// The framebuffer for bunterm: the firmware's GOP is a simple-framebuffer
+// device, and simpledrm turns it into /dev/fb0. x86_64 linux-lts builds it
+// in and linux-virt images do not ship it; tryModprobe skips both.
+try {
+  const { tryModprobe } = await import("/lib/modprobe.js");
+  if (tryModprobe("simpledrm")?.length) console.log("init.js: loaded simpledrm");
+} catch (error) {
+  console.error(`init.js: simpledrm: ${error?.message ?? error}`);
+}
+
 const { default: repl } = await import("node:repl");
 const { mkdirSync, writeFileSync } = await import("node:fs");
 
@@ -549,11 +559,26 @@ const configureDisks = () => {
   return devices;
 };
 
+// Load the complete sound stack packaged in the image. Like cfg.net this is
+// deliberately unconditional: it does not probe modaliases first, so codec
+// and helper modules without their own discoverable device are loaded too.
+const configureSound = () => {
+  const { modprobeAll } = require("/lib/modprobe.js");
+  const { readdirSync } = require("node:fs");
+  const report = modprobeAll({ accept: (_module, path) => path.startsWith("kernel/sound/") });
+  console.log(`sound: loaded all packaged sound modules (${report.inserted.length} newly loaded, ${report.errors.length} failed)`);
+  for (const { module, error } of report.errors) console.log(`sound: ${module}: ${error}`);
+  const devices = (() => { try { return readdirSync("/dev/snd"); } catch { return []; } })();
+  console.log(`sound: ${devices.length ? devices.map((name) => `/dev/snd/${name}`).join(" ") : "no sound devices registered"}`);
+  return devices;
+};
+
 globalThis.cfg = Object.freeze(Object.defineProperties({}, {
   all: { enumerable: true, get: configureModules },
   disk: { enumerable: true, get: configureDisks },
   net: { enumerable: true, get: configureEthernet },
   power: { enumerable: true, get: configureBattery },
+  sound: { enumerable: true, get: configureSound },
 }));
 
 // Compatibility aliases for images and notes that used the original API.
@@ -562,6 +587,7 @@ globalThis.cfgNet = configureEthernet;
 globalThis.cfgDisk = configureDisks;
 globalThis.cfgMod = configureModules;
 globalThis.cfgBat = configureBattery;
+globalThis.cfgSound = configureSound;
 
 const showWelcome = () => {
   console.log(`

package/initramfs/lib/bunterm/clipboard.js

@@ -0,0 +1,51 @@
+// /lib/bunterm/clipboard.js — OSC 52 clipboard for bunterm, backed by xclip.
+//
+//   program ── ESC ] 52 ; c ; <base64> BEL ──▶ xclip -selection clipboard
+//   program ── ESC ] 52 ; c ; ? BEL ─────────▶ xclip -selection clipboard -o
+//           ◀── ESC ] 52 ; c ; <base64> BEL ──
+//
+// bunterm keeps nothing itself: every copy and paste goes through xclip, so
+// all bunterm sessions (and anything else using xclip) share one clipboard.
+// Buninu's xclip prints status lines on stderr, which must not reach the
+// console under the framebuffer, so stderr is discarded.
+
+const runXclip = async (args, input) => {
+  const command = ["xclip", "-selection", "clipboard", ...args];
+  const proc = Bun.spawn(command, {
+    stdin: input === undefined ? "ignore" : input,
+    stdout: input === undefined ? "pipe" : "ignore",
+    stderr: "ignore",
+  });
+  const [output, exitCode] = await Promise.all([
+    input === undefined ? new Response(proc.stdout).arrayBuffer() : null,
+    proc.exited,
+  ]);
+  if (exitCode !== 0) throw new Error(`${command.join(" ")} exited with ${exitCode}`);
+  return output;
+};
+
+// Registers the OSC 52 handler on an xterm.js terminal. `reply` sends bytes
+// back to the program, as the terminal's other replies do. A read the xclip
+// call cannot answer is still answered, with empty contents, so the program
+// does not wait out its own timeout.
+export const attachClipboard = ({ term, reply, onError = () => {} }) =>
+  term.parser.registerOscHandler(52, (data) => {
+    const separator = data.indexOf(";");
+    if (separator < 0) return true;
+    const target = data.slice(0, separator);
+    const payload = data.slice(separator + 1);
+
+    if (payload === "?") {
+      // The reply is sent after xclip returns, when the program may have exited
+      // and the PTY closed; writing then throws, and an unhandled rejection
+      // would end bunterm before it restores the console.
+      runXclip(["-o"])
+        .catch((error) => { onError(error); return new ArrayBuffer(0); })
+        .then((bytes) => reply(`\u001b]52;${target};${Buffer.from(bytes).toString("base64")}\u0007`))
+        .catch(onError);
+      return true;
+    }
+
+    runXclip([], Buffer.from(payload, "base64")).catch(onError);
+    return true;
+  });

package/initramfs/lib/bunterm/terminal.js

@@ -20,6 +20,8 @@ import { UnicodeGraphemesAddon } from "../xterm/addon-unicode-graphemes.mjs";
 import { Renderer, defaultTheme } from "./renderer.js";
 import { ImageStore } from "./images.js";
 import { openKeyboard, translateKeys } from "./input.js";
+import { claimVirtualConsole } from "./vt.js";
+import { attachClipboard } from "./clipboard.js";
 
 const require = createRequire(import.meta.url);
 
@@ -51,6 +53,7 @@ export const createSession = ({
   scrollback = 1000,
   cursorBlink = true,
   mouse = true,
+  clipboard = true,
   env = {},
   onError = (error) => console.error(`bunterm: ${error?.stack ?? error}`),
 }) => {
@@ -81,6 +84,7 @@ export const createSession = ({
   });
 
   let frameTimer = null;
+  let active = true;
   let blinkOn = true;
   const cursorHidden = () => Boolean(term._core?.coreService?.isCursorHidden);
   // Only set when a pointer is attached; without one the renderer is called
@@ -89,6 +93,7 @@ export const createSession = ({
   const paint = () => {
     if (frameTimer) clearTimeout(frameTimer);
     frameTimer = null;
+    if (!active) return false;
     const buffer = term.buffer.active;
     // cursorY counts from the buffer's base, so a scrolled-back viewport
     // moves the cursor down the screen and eventually off it.
@@ -104,8 +109,20 @@ export const createSession = ({
     });
   };
   const requestFrame = () => {
+    if (!active) return;
     frameTimer ??= setTimeout(paint, 16);
   };
+  const suspend = () => {
+    active = false;
+    if (frameTimer) clearTimeout(frameTimer);
+    frameTimer = null;
+  };
+  const resume = () => {
+    if (active) return;
+    active = true;
+    renderer.invalidate();
+    paint();
+  };
   const blinkTimer = cursorBlink
     ? setInterval(() => { blinkOn = !blinkOn; requestFrame(); }, 500)
     : null;
@@ -143,6 +160,9 @@ export const createSession = ({
   });
   backend.onData(pump);
   term.onData((data) => backend.write(Buffer.from(data, "utf8")));
+  // OSC 52 copy and paste go straight to xclip; replies return to the program.
+  // Without it (--no-clipboard) xterm.js ignores OSC 52 and nothing reaches xclip.
+  if (clipboard) attachClipboard({ term, reply: (text) => backend.write(Buffer.from(text, "utf8")), onError });
 
   // Keyboard bytes from the console, rewritten for the program's key mode.
   const input = (bytes) => {
@@ -193,6 +213,9 @@ export const createSession = ({
   };
 
   const reportMouse = (report) => {
+    // /dev/input is global rather than routed through the active VT.  Do not
+    // draw or send mouse input to a terminal whose console is off-screen.
+    if (!active) return;
     pointer = { x: report.x, y: report.y };
     requestFrame();
     const service = term._core?.coreMouseService;
@@ -268,7 +291,7 @@ export const createSession = ({
   paint();
   return {
     term, backend, renderer, images, kitty,
-    paint, requestFrame, settle, input, exited, close, attachPointer, reportMouse, wheelScroll,
+    paint, requestFrame, suspend, resume, settle, input, exited, close, attachPointer, reportMouse, wheelScroll,
   };
 };
 
@@ -282,15 +305,13 @@ export const runTerminal = async ({ console: consoleDevice = null, device = "/de
   const fonts = loadFontSet(CanvasKit, "terminal");
   const consolePaths = consoleDevice ? [consoleDevice] : undefined;
 
-  return runGraphics(async (display, { onRestore, onAcquire }) => {
+  return runGraphics(async (display, { onRestore, onRelease, onAcquire }) => {
     const screen = openCanvas(CanvasKit, display);
     const session = createSession({ CanvasKit, screen, fonts, ...options });
-    // Coming back from another console (Ctrl-Alt-Fn): fbcon has drawn over
-    // the framebuffer, so repaint everything.
-    onAcquire(() => {
-      session.renderer.invalidate();
-      session.paint();
-    });
+    onRelease(session.suspend);
+    // Coming back from another console (Ctrl-Alt-Fn): fbcon or another
+    // bunterm has drawn over the framebuffer, so repaint everything.
+    onAcquire(session.resume);
     let keyboard = null;
     try {
       keyboard = openKeyboard({
@@ -320,5 +341,5 @@ export const runTerminal = async ({ console: consoleDevice = null, device = "/de
       session.close();
       screen.close();
     }
-  }, { device, console: consolePaths });
+  }, { device, console: consolePaths, prepareConsole: claimVirtualConsole });
 };

package/initramfs/lib/bunterm/vt.js

@@ -0,0 +1,91 @@
+// Cooperative ownership for one Linux virtual console.
+//
+// Linux VT_SETMODE replaces an existing VT_PROCESS owner rather than failing,
+// and VT_GETMODE does not expose that owner's pid.  bunterm therefore publishes
+// a short per-VT task name and verifies that another such process does not also
+// hold the console device open.  Both facts live under /proc/<pid> and disappear
+// with the process; there is no persistent pid or lock file to become stale.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { libc, cString, check } from "../dlopen.js";
+
+const PR_SET_NAME = 15;
+const PR_GET_NAME = 16;
+
+export const virtualConsoleNumber = (path) => {
+  const match = /^\/dev\/tty([1-9][0-9]*)$/.exec(path);
+  return match ? Number(match[1]) : null;
+};
+
+const taskName = (number) => `bunterm:tty${number}`;
+
+const getTaskName = () => {
+  const name = new Uint8Array(16);
+  check("prctl(PR_GET_NAME)", libc.symbols.prctl(PR_GET_NAME, name, 0n, 0n, 0n));
+  const zero = name.indexOf(0);
+  return new TextDecoder().decode(zero === -1 ? name : name.subarray(0, zero));
+};
+
+const setTaskName = (name) => {
+  const encoded = cString(name);
+  if (encoded.byteLength > 16) throw new Error(`Linux task name is too long: ${name}`);
+  check("prctl(PR_SET_NAME)", libc.symbols.prctl(PR_SET_NAME, encoded, 0n, 0n, 0n));
+};
+
+const processHoldsDevice = (pid, deviceId) => {
+  let descriptors;
+  try {
+    descriptors = readdirSync(`/proc/${pid}/fd`);
+  } catch {
+    return false;
+  }
+  for (const descriptor of descriptors) {
+    try {
+      if (statSync(`/proc/${pid}/fd/${descriptor}`).rdev === deviceId) return true;
+    } catch {
+      // The process or descriptor disappeared between readdir and stat.
+    }
+  }
+  return false;
+};
+
+export const claimVirtualConsole = (consoleDevice) => {
+  const number = virtualConsoleNumber(consoleDevice.path);
+  if (number === null) throw new Error(`bunterm needs a canonical virtual console, got ${consoleDevice.path}`);
+  const name = taskName(number);
+  const previousName = getTaskName();
+  const deviceId = statSync(consoleDevice.path).rdev;
+
+  // Publish before scanning.  Two simultaneous starters can then reject each
+  // other, but they cannot both scan an unpublished peer and proceed.
+  setTaskName(name);
+  try {
+    const pids = readdirSync("/proc")
+      .filter((entry) => /^[0-9]+$/.test(entry) && Number(entry) !== process.pid);
+    for (const pid of pids) {
+      let otherName;
+      try {
+        otherName = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+      } catch {
+        continue;
+      }
+      if (otherName !== name || !processHoldsDevice(pid, deviceId)) continue;
+
+      throw new Error(`
+${consoleDevice.path} is occupied
+  Controlled by bunterm pid: ${pid}
+See --help or try another VT:
+  bunterm ${number- -1}
+Switch between TTYs by Ctrl+Alt+F1-12
+  or Alt-Left / Alt-Right
+`);
+    }
+  } catch (error) {
+    try { setTaskName(previousName); } catch {}
+    throw error;
+  }
+
+  return () => {
+    try { setTaskName(previousName); } catch {}
+  };
+};

package/initramfs/lib/dlopen.js

@@ -85,6 +85,10 @@ export const libc = dlopen(libcPath, {
     args: [FFIType.i32, FFIType.ptr, FFIType.i32],
     returns: FFIType.i32,
   },
+  prctl: {
+    args: [FFIType.i32, FFIType.ptr, FFIType.u64, FFIType.u64, FFIType.u64],
+    returns: FFIType.i32,
+  },
   chroot: {
     args: [FFIType.ptr],
     returns: FFIType.i32,

package/initramfs/lib/fbdev.js

@@ -355,8 +355,12 @@ const setConsoleSwitchMode = (consoleDevice, mode) => {
 // when it comes back (answered with VT_ACKACQ), at which point `onAcquire`
 // runs so the caller can repaint what fbcon left on the screen. Returns a
 // function that puts the console back into automatic switching.
-export const watchConsoleSwitches = (consoleDevice, onAcquire) => {
+export const watchConsoleSwitches = (consoleDevice, callbacks) => {
+  // Keep the original (console, onAcquire) public form working.
+  const onRelease = typeof callbacks === "function" ? () => {} : callbacks.onRelease;
+  const onAcquire = typeof callbacks === "function" ? callbacks : callbacks.onAcquire;
   const release = () => {
+    try { onRelease(); } catch {}
     try { ioctlValue(consoleDevice.fd, VT_RELDISP, 1, "VT_RELDISP"); } catch {}
   };
   const acquire = () => {
@@ -429,6 +433,7 @@ const defaultTriangle = (display) => [
 // before text mode returns, such as putting a keyboard back into cooked mode.
 export const runGraphics = async (draw, {
   device = "/dev/fb0", console: consolePaths, switchConsole = true,
+  prepareConsole = null,
 } = {}) => {
   const display = openFramebuffer(device);
   let consoleDevice;
@@ -442,6 +447,7 @@ export const runGraphics = async (draw, {
   let previousConsole = null;
   let unwatch = null;
   const restoreCallbacks = [];
+  const releaseCallbacks = [];
   const acquireCallbacks = [];
   const restore = () => {
     while (restoreCallbacks.length) {
@@ -470,6 +476,10 @@ export const runGraphics = async (draw, {
   for (const [signal, handler] of signalHandlers) process.on(signal, handler);
   process.on("exit", restore);
   try {
+    if (prepareConsole) {
+      const cleanup = await prepareConsole(consoleDevice);
+      if (typeof cleanup === "function") restoreCallbacks.push(cleanup);
+    }
     const target = switchConsole ? consoleNumber(consoleDevice.path) : null;
     if (target !== null) {
       const active = activeConsole(consoleDevice);
@@ -480,22 +490,35 @@ export const runGraphics = async (draw, {
     }
     setConsoleGraphics(consoleDevice);
     graphics = true;
+    // An async draw callback runs synchronously until its first await.  Start
+    // it before enabling VT_PROCESS so it can register release/acquire hooks;
+    // otherwise a switch in that small window could be acknowledged without
+    // giving the renderer a chance to stop.
+    const drawing = draw(display, {
+      console: consoleDevice,
+      onRestore: (callback) => { restoreCallbacks.push(callback); },
+      onRelease: (callback) => { releaseCallbacks.push(callback); },
+      onAcquire: (callback) => { acquireCallbacks.push(callback); },
+    });
     if (switchConsole) {
       try {
-        unwatch = watchConsoleSwitches(consoleDevice, () => {
-          for (const callback of acquireCallbacks) {
-            try { callback(); } catch {}
-          }
+        unwatch = watchConsoleSwitches(consoleDevice, {
+          onRelease: () => {
+            for (const callback of releaseCallbacks) {
+              try { callback(); } catch {}
+            }
+          },
+          onAcquire: () => {
+            for (const callback of acquireCallbacks) {
+              try { callback(); } catch {}
+            }
+          },
         });
       } catch {
         // Not a virtual console (or no permission): switches stay automatic.
       }
     }
-    return await draw(display, {
-      console: consoleDevice,
-      onRestore: (callback) => { restoreCallbacks.push(callback); },
-      onAcquire: (callback) => { acquireCallbacks.push(callback); },
-    });
+    return await drawing;
   } finally {
     restore();
     process.off("exit", restore);

package/initramfs/usr/share/doc/buninu-linux/bunterm.md

@@ -7,10 +7,12 @@ box drawing and kitty graphics protocol images — no X11, Wayland or GPU.
 
 ```sh
 bunterm                      # run /bin/sh on the console you are on
-bunterm /dev/tty1            # use virtual console 1 for graphics and keys
-bunterm --font-size 20
+bunterm 2                    # start a detached bunterm on /dev/tty2
+bunterm /dev/tty1            # the full virtual-console spelling also works
+bunterm -s 20                # short for --font-size 20
 bunterm -e bun /buninu/apps/jsmdcui/src/index.js --demo
 bunterm --no-mouse          # keyboard only
+bunterm --no-clipboard      # ignore OSC 52 copy and paste
 bunterm -h
 ```
 
@@ -19,17 +21,26 @@ The program's `TERM` is `xterm-256color`, `COLORTERM=truecolor`,
 Markdown images without `--kitty`). When it exits, the console returns to
 text mode and `bunterm` exits with its status.
 
+Every live session has a canonical `/bin/bunterm /dev/ttyN ...` command line.
+When no console is named, the currently active VT is used in the foreground.
+Naming a different VT starts bunterm as a detached session and returns
+immediately to the calling shell. Only one bunterm may control a given VT;
+ownership is
+identified from the process task name and its open console descriptor under
+`/proc`, so it disappears automatically when the process exits.
+
 ## Options
 
 | Option | Meaning |
 | --- | --- |
-| `/dev/ttyN` | The virtual console to use for graphics and the keyboard. If another console is on screen, the display switches to this one first and back when `bunterm` exits. Without it the process's own console and stdin are used, so run it from a VT (not a serial line or a PTY). |
+| `N`, `/dev/ttyN` | The virtual console to use for graphics and the keyboard; for example, `2` means `/dev/tty2`. Naming a VT other than the active one starts a detached bunterm there, switches the display to it, and immediately returns control to the calling shell. Without this argument, bunterm uses the active VT in the foreground. |
 | `-e command [argument...]` | The program to run; everything after `-e` belongs to it. Default `/bin/sh`. |
-| `--font-size N` | Font size in pixels (default 16). The cell is 0.6 × N wide and 1.16 × N tall with DejaVu Sans Mono, so 1024×768 at 16 px gives 106 × 41 cells. |
+| `-s N`, `--font-size N` | Font size in pixels (default 16). The cell is 0.6 × N wide and 1.16 × N tall with DejaVu Sans Mono, so 1024×768 at 16 px gives 106 × 41 cells. |
 | `--line-height F` | Multiplies the cell height (default 1). |
 | `--fb /dev/fbN` | The framebuffer device (default `/dev/fb0`). |
 | `--no-blink` | A steady cursor. |
 | `--no-mouse` | Do not attach a pointing device; nothing then reads `/dev/input`. |
+| `--no-clipboard` | Ignore OSC 52: programs can neither copy to nor read from the clipboard, and `xclip` is never run. |
 
 ## What is drawn
 
@@ -57,7 +68,11 @@ text mode and `bunterm` exits with its status.
 
 The console stays in the kernel's translated keyboard mode, so
 `Ctrl-Alt-F2` and friends still switch consoles; coming back repaints the
-screen. A few console-specific
+screen. While its VT is inactive, bunterm continues consuming PTY output and
+updating its scrollback and kitty images, but neither writes the framebuffer
+nor forwards global `/dev/input` mouse events. This allows separate bunterm
+processes on `/dev/tty1`, `/dev/tty2`, and so on to hand the display back and
+forth through the normal Linux VT switch. A few console-specific
 sequences are rewritten to xterm's (`F1`–`F5`, `Home`, `End`), and arrow keys
 follow the program's application cursor mode.
 
@@ -88,6 +103,16 @@ mouse also needs the `usbhid` stack, which a `--real` image carries and
 ones (a tablet or touchscreen) alike; a device that cannot be opened is
 reported and the session continues without it.
 
+## Clipboard
+
+Programs copy and paste through OSC 52, as `casty` and `jsmdcui` do.
+bunterm keeps no clipboard of its own: `ESC ] 52 ; c ; <base64>` is passed to
+`xclip -selection clipboard`, and a query (`ESC ] 52 ; c ; ?`) is answered
+with the output of `xclip -selection clipboard -o`, so every bunterm session
+shares the same clipboard as `xclip`. A query xclip cannot answer is replied
+to with empty contents. `--no-clipboard` turns this off, so a program can
+neither set nor read the clipboard through the terminal.
+
 ## Limits
 
 - Needs a framebuffer: `linux-lts` has one built in, while the default
@@ -104,7 +129,8 @@ reported and the session continues without it.
 - Kitty images are drawn above text; `z` ordering below text and animation
   frames are not implemented, and file transmission (`t=f`/`t=t`) works only
   for files under `/tmp`, `/dev/shm` or `$TMPDIR`.
-- One framebuffer, one session. For panes and tabs run `jsmdcui` inside it.
+- One bunterm per virtual console may use the framebuffer; only the active VT
+  draws. For panes and tabs within one VT, run `jsmdcui` inside it.
 
 ## See also
 

package/initramfs/usr/share/doc/buninu-linux/fbdev.md

@@ -84,7 +84,7 @@ than an X11 `Display`. Colours are `{ r, g, b, a }` objects.
 | `openConsole`, `setConsoleGraphics`, `setConsoleText` | Explicit Linux virtual-console control for callers that need it. |
 | `activeConsole(console)`, `activateConsole(console, n)`, `consoleNumber(path)` | `VT_GETSTATE` / `VT_ACTIVATE` + `VT_WAITACTIVE`, and the number in a `/dev/ttyN` path. |
 | `watchConsoleSwitches(console, onAcquire)` | `VT_SETMODE` with `VT_PROCESS`: answers the kernel's switch-away and switch-back signals and calls `onAcquire` when the display returns. Returns a function restoring automatic switching. |
-| `runGraphics(draw, { device, console, switchConsole }?)` | Open the framebuffer, put the console in graphics mode, run `await draw(display, { console, onRestore, onAcquire })`, and restore text mode however the call ends (return, throw, `process.exit()`, `SIGHUP`/`SIGINT`/`SIGQUIT`/`SIGTERM`). `console` lists console devices to try, such as `["/dev/tty1"]`; when the one opened is a `/dev/ttyN` other than the console on screen, the display is switched to it first and back afterwards (`switchConsole: false` disables this). Console switches with Ctrl-Alt-Fn keep working; `onAcquire(callback)` runs when the display comes back so the caller can repaint, and `onRestore(callback)` registers cleanup to run before text mode returns. |
+| `runGraphics(draw, { device, console, switchConsole, prepareConsole }?)` | Open the framebuffer, optionally call `await prepareConsole(console)`, put the console in graphics mode, run `await draw(display, { console, onRestore, onRelease, onAcquire })`, and restore text mode however the call ends (return, throw, `process.exit()`, `SIGHUP`/`SIGINT`/`SIGQUIT`/`SIGTERM`). `console` lists console devices to try, such as `["/dev/tty1"]`; when the one opened is a `/dev/ttyN` other than the console on screen, the display is switched to it first and back afterwards (`switchConsole: false` disables this). Console switches with Ctrl-Alt-Fn keep working: `onRelease(callback)` runs before the switch is acknowledged so drawing can stop, `onAcquire(callback)` runs when the display comes back, and `onRestore(callback)` registers cleanup to run before text mode returns. A cleanup function returned by `prepareConsole` is registered the same way. |
 | `runDemo({ polygons, device }?)` | Run the CLI demo through `runGraphics()`. Each item in `polygons` is drawn separately. |
 
 The module supports 16-, 24-, and 32-bit packed-pixel framebuffers and uses

package/initramfs/usr/share/licenses/README.md

@@ -0,0 +1,4 @@
+# Licenses in the built image
+
+The packaging step copies the project `LICENSE`, `NOTICE.md`, and third-party
+`LICENSES/` directory here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "A Linux distribution running Bun as PID 1 with the Buninu userspace.",
   "type": "module",
   "main": "./index.js",
@@ -13,7 +13,7 @@
     "type": "git",
     "url": "git+https://github.com/jjtseng93/buninu-linux.git"
   },
-  "homepage": "https://github.com/jjtseng93/buninu-linux#readme",
+  "homepage": "https://buninu.org",
   "bugs": {
     "url": "https://github.com/jjtseng93/buninu-linux/issues"
   },

package/scripts/pack-initramfs.sh

@@ -22,6 +22,10 @@ trap 'rm -rf "$staging"; rm -f "$archive"' EXIT
 cp -a --reflink=auto initramfs/. "$staging/"
 rm -rf "$staging/bin/bun" "$staging/lib/modules"
 cp -a --reflink=auto "$native_dir/." "$staging/"
+# Keep the project README canonical while making it available to
+# buninu-linux-help from the conventional installed-document path.
+cp README.md "$staging/usr/share/doc/buninu-linux/README.md"
+cp -a LICENSE NOTICE.md LICENSES "$staging/usr/share/licenses/"
 
 # fakeroot lets cpio record the character devices without real root. Nothing
 # has mounted devtmpfs when the kernel execs Bun as PID 1, so every device