buninu-linux 0.6.0 → 0.7.0

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,12 +33,14 @@
 - 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
   * 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
@@ -341,7 +343,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 +374,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 |
 | --- | --- |
@@ -457,6 +481,7 @@ needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
 
 | 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 +494,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 +539,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,9 +556,11 @@ 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
 
 
 
@@ -581,7 +610,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,
@@ -1101,8 +1130,10 @@ 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)
 - [Commands inside /bin](#commands-inside-bin)

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] [-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,64 @@ const main = async () => {
       options.mouse = true;
     } else if (argument === "--no-mouse") {
       options.mouse = false;
-    } else if (argument.startsWith("/dev/")) {
-      options.console = argument;
+    } 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/lib/bunterm/terminal.js

@@ -20,6 +20,7 @@ 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";
 
 const require = createRequire(import.meta.url);
 
@@ -81,6 +82,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 +91,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 +107,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;
@@ -193,6 +208,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 +286,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 +300,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 +336,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,8 +7,9 @@ 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 -h
@@ -19,13 +20,21 @@ 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. |
@@ -57,7 +66,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.
 
@@ -104,7 +117,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.0",
   "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