buninu-linux 0.4.0 → 0.5.1

package/initramfs/init.js

@@ -94,6 +94,79 @@ const mountFilesystems = () => {
 mountFilesystems();
 console.log("init.js: mounted /proc, /sys, /dev, /tmp, /dev/pts");
 
+// Num Lock. The keypad's lock state lives per virtual console in the
+// kernel's keyboard table, and the kernel starts every console with it off,
+// so the keypad types arrows instead of digits. KDSKBLED carries the current
+// flags in its low nibble and the ones a console is reset to in its high
+// nibble; KDSETLED with a value above 7 puts the physical LED back to
+// following those flags. A console allocated later (Ctrl-Alt-F3 for the
+// first time) starts from the kernel default again, so numlock() is left in
+// the REPL for that case.
+const KDSETLED = 0x4b32;
+const KDGKBLED = 0x4b64;
+const KDSKBLED = 0x4b65;
+const LED_NUM = 0x02;
+
+// Nothing here is essential to booting, so a console that is not a virtual
+// terminal, a missing device node or a rejected ioctl is skipped rather than
+// reported: the remaining consoles are still set, and the system comes up
+// either way.
+const setNumLock = (enabled = true) => {
+  const consoles = [];
+  const paths = ["/dev/tty0", "/dev/console", "/dev/tty"];
+  for (let index = 1; index <= 12; index++) paths.push(`/dev/tty${index}`);
+  for (const path of paths) {
+    let fd = -1;
+    try {
+      fd = libc.symbols.open(cString(path), 2, 0);
+      if (fd < 0) continue;
+      const state = new Uint8Array(1);
+      if (libc.symbols.ioctl(fd, KDGKBLED, ptr(state)) !== 0) continue;
+      const current = enabled ? state[0] | LED_NUM : state[0] & ~LED_NUM;
+      const fallback = enabled ? (state[0] >> 4) | LED_NUM : (state[0] >> 4) & ~LED_NUM;
+      const flags = (current & 7) | ((fallback & 7) << 4);
+      if (libc.symbols.ioctl(fd, KDSKBLED, flags) !== 0) continue;
+      libc.symbols.ioctl(fd, KDSETLED, 0x80);
+      consoles.push(path);
+    } catch {
+      // This console keeps whatever state it had; the others still get set.
+    } finally {
+      if (fd >= 0) {
+        try { libc.symbols.close(fd); } catch {}
+      }
+    }
+  }
+  return consoles;
+};
+
+globalThis.numlock = setNumLock;
+try {
+  const consoles = setNumLock(true);
+  console.log(consoles.length
+    ? `init.js: num lock on (${consoles.join(" ")})`
+    : "init.js: no virtual console accepted a num lock setting");
+} catch (error) {
+  console.error(`init.js: num lock: ${error?.message ?? error}`);
+}
+
+// The input layer's character devices, so a pointing device has a
+// /dev/input/event* node for `bunterm --mouse` to read. Loading them only
+// creates those nodes: the console keyboard is unaffected, and nothing reads
+// a pointer unless it is asked to. A USB mouse also needs the usbhid stack,
+// which `cfg.all` or a --real boot brings in.
+try {
+  const { tryModprobe } = await import("/lib/modprobe.js");
+  const loaded = ["evdev", "psmouse"].filter((module) => tryModprobe(module) !== null);
+  const { readdirSync } = await import("node:fs");
+  const devices = (() => {
+    try { return readdirSync("/dev/input").filter((name) => name.startsWith("event")); } catch { return []; }
+  })();
+  console.log(`init.js: input modules ${loaded.length ? loaded.join(" ") : "none"}`
+    + ` (${devices.length} event device${devices.length === 1 ? "" : "s"})`);
+} catch (error) {
+  console.error(`init.js: input modules: ${error?.message ?? error}`);
+}
+
 const { default: repl } = await import("node:repl");
 const { mkdirSync, writeFileSync } = await import("node:fs");
 
@@ -354,7 +427,7 @@ Type bunterm in bunmsh: Graphical Terminal
   ], {
     env: {
       ...process.env,
-      PATH:"/bin:/usr/bin:/buninu/bin",
+      PATH:"/bin:/sbin:/usr/bin:/usr/sbin:/buninu/.bun/bin:/buninu/bin",
       HOME:"/buninu"
     },
     stdin: "inherit",

package/initramfs/lib/bunterm/mouse.js

@@ -0,0 +1,222 @@
+// /lib/bunterm/mouse.js — pointing devices through the Linux input layer.
+//
+// Read from /dev/input/event*, where the kernel reports one 24-byte
+// input_event per axis, button or wheel notch, ending each batch with an
+// EV_SYN. Relative devices (a mouse) move the pointer by their deltas;
+// absolute ones (QEMU's USB tablet, a touchscreen) place it directly, which
+// needs the axis range from EVIOCGABS. This module is only loaded when
+// bunterm is asked for a mouse.
+
+import { closeSync, existsSync, openSync, read, readFileSync, readdirSync } from "node:fs";
+import { libc, ptr } from "../dlopen.js";
+
+const EVENT_SIZE = 24;
+const EV_SYN = 0x00;
+const EV_KEY = 0x01;
+const EV_REL = 0x02;
+const EV_ABS = 0x03;
+const REL_X = 0x00;
+const REL_Y = 0x01;
+const REL_WHEEL = 0x08;
+const REL_HWHEEL = 0x06;
+const ABS_X = 0x00;
+const ABS_Y = 0x01;
+const BTN_LEFT = 0x110;
+const BTN_RIGHT = 0x111;
+const BTN_MIDDLE = 0x112;
+const BTN_TOUCH = 0x14a;
+
+// struct input_absinfo { s32 value, minimum, maximum, fuzz, flat, resolution }
+const EVIOCGABS = (axis) => 0x80184540 + axis;
+
+const buttonNames = {
+  [BTN_LEFT]: "left",
+  [BTN_RIGHT]: "right",
+  [BTN_MIDDLE]: "middle",
+  [BTN_TOUCH]: "left",
+};
+
+const capability = (directory, name) => {
+  try {
+    // A capability file is a space-separated list of 64-bit hex words, most
+    // significant first, so the last word holds bits 0-63.
+    const words = readFileSync(`${directory}/${name}`, "utf8").trim().split(/\s+/u).reverse();
+    return (bit) => {
+      const word = words[Math.floor(bit / 64)];
+      return word ? (BigInt(`0x${word}`) >> BigInt(bit % 64)) & 1n ? true : false : false;
+    };
+  } catch {
+    return () => false;
+  }
+};
+
+// Every /dev/input/event* that looks like a pointer, with how it reports
+// position. A device with both relative and absolute axes counts as absolute.
+export const findPointers = (directory = "/dev/input") => {
+  const found = [];
+  let names = [];
+  try {
+    names = readdirSync(directory).filter((name) => /^event\d+$/u.test(name));
+  } catch {
+    return found;
+  }
+  for (const name of names.sort()) {
+    const sysfs = `/sys/class/input/${name}/device/capabilities`;
+    if (!existsSync(sysfs)) continue;
+    const relative = capability(sysfs, "rel");
+    const absolute = capability(sysfs, "abs");
+    const keys = capability(sysfs, "key");
+    const hasRelative = relative(REL_X) && relative(REL_Y);
+    const hasAbsolute = absolute(ABS_X) && absolute(ABS_Y);
+    const hasButton = keys(BTN_LEFT) || keys(BTN_TOUCH);
+    if (!hasButton || (!hasRelative && !hasAbsolute)) continue;
+    let label = name;
+    try {
+      label = readFileSync(`/sys/class/input/${name}/device/name`, "utf8").trim() || name;
+    } catch {}
+    found.push({
+      path: `${directory}/${name}`,
+      name: label,
+      kind: hasAbsolute ? "absolute" : "relative",
+      wheel: relative(REL_WHEEL),
+    });
+  }
+  return found;
+};
+
+const absoluteRange = (fd, axis) => {
+  const info = new Int32Array(6);
+  if (libc.symbols.ioctl(fd, EVIOCGABS(axis), ptr(info)) === -1) return null;
+  const [, minimum, maximum] = info;
+  return maximum > minimum ? { minimum, maximum } : null;
+};
+
+// Opens every pointer in `devices` and reports the pointer state after each
+// EV_SYN: { x, y, buttons: { left, middle, right }, wheel, hwheel, moved,
+// pressed, released }. Coordinates are pixels clamped to width x height.
+// `speed` scales relative motion. close() releases the devices.
+export const openPointer = ({
+  devices = findPointers(),
+  width,
+  height,
+  speed = 1,
+  x = Math.floor(width / 2),
+  y = Math.floor(height / 2),
+  onSync,
+  onError = () => {},
+}) => {
+  const state = {
+    x, y,
+    buttons: { left: false, middle: false, right: false },
+    wheel: 0,
+    hwheel: 0,
+    moved: false,
+    pressed: [],
+    released: [],
+  };
+  const open = [];
+
+  for (const device of devices) {
+    let fd = -1;
+    try {
+      fd = openSync(device.path, "r");
+      const ranges = device.kind === "absolute"
+        ? { x: absoluteRange(fd, ABS_X), y: absoluteRange(fd, ABS_Y) }
+        : null;
+      // An absolute device without a usable range is read as relative.
+      const kind = ranges?.x && ranges?.y ? "absolute" : "relative";
+      open.push({ ...device, fd, kind, ranges, buffer: Buffer.alloc(EVENT_SIZE * 64), reading: true });
+    } catch (error) {
+      if (fd >= 0) {
+        try { closeSync(fd); } catch {}
+      }
+      onError(new Error(`${device.path}: ${error.message}`));
+    }
+  }
+
+  const clamp = (value, maximum) => Math.max(0, Math.min(maximum - 1, value));
+
+  const apply = (entry, type, code, value) => {
+    if (type === EV_REL) {
+      if (code === REL_X) { state.x = clamp(Math.round(state.x + value * speed), width); state.moved = true; }
+      else if (code === REL_Y) { state.y = clamp(Math.round(state.y + value * speed), height); state.moved = true; }
+      else if (code === REL_WHEEL) state.wheel += value;
+      else if (code === REL_HWHEEL) state.hwheel += value;
+      return;
+    }
+    if (type === EV_ABS && entry.kind === "absolute") {
+      const range = code === ABS_X ? entry.ranges.x : code === ABS_Y ? entry.ranges.y : null;
+      if (!range) return;
+      const span = range.maximum - range.minimum;
+      const fraction = (value - range.minimum) / span;
+      if (code === ABS_X) state.x = clamp(Math.round(fraction * width), width);
+      else state.y = clamp(Math.round(fraction * height), height);
+      state.moved = true;
+      return;
+    }
+    if (type === EV_KEY) {
+      const button = buttonNames[code];
+      if (!button) return;
+      const down = value !== 0;
+      if (state.buttons[button] === down) return; // key repeat
+      state.buttons[button] = down;
+      (down ? state.pressed : state.released).push(button);
+    }
+  };
+
+  const flush = () => {
+    const report = {
+      x: state.x,
+      y: state.y,
+      buttons: { ...state.buttons },
+      wheel: state.wheel,
+      hwheel: state.hwheel,
+      moved: state.moved,
+      pressed: state.pressed,
+      released: state.released,
+    };
+    state.wheel = 0;
+    state.hwheel = 0;
+    state.moved = false;
+    state.pressed = [];
+    state.released = [];
+    if (report.moved || report.wheel || report.hwheel || report.pressed.length || report.released.length) {
+      try { onSync(report); } catch (error) { onError(error); }
+    }
+  };
+
+  const pump = (entry) => {
+    if (!entry.reading) return;
+    read(entry.fd, entry.buffer, 0, entry.buffer.length, null, (error, count) => {
+      if (!entry.reading) return;
+      if (error) {
+        if (error.code === "EAGAIN") { setTimeout(() => pump(entry), 10); return; }
+        entry.reading = false;
+        onError(new Error(`${entry.path}: ${error.message}`));
+        return;
+      }
+      for (let offset = 0; offset + EVENT_SIZE <= count; offset += EVENT_SIZE) {
+        const type = entry.buffer.readUInt16LE(offset + 16);
+        const code = entry.buffer.readUInt16LE(offset + 18);
+        const value = entry.buffer.readInt32LE(offset + 20);
+        if (type === EV_SYN) flush();
+        else apply(entry, type, code, value);
+      }
+      pump(entry);
+    });
+  };
+
+  for (const entry of open) pump(entry);
+
+  return {
+    devices: open.map(({ path, name, kind }) => ({ path, name, kind })),
+    state,
+    close() {
+      for (const entry of open) {
+        entry.reading = false;
+        try { closeSync(entry.fd); } catch {}
+      }
+      open.length = 0;
+    },
+  };
+};

package/initramfs/lib/bunterm/renderer.js

@@ -105,6 +105,7 @@ export class Renderer {
     this.forcedRows = new Set();
     this.dirtyAll = true;
     this.lastCursor = { x: -1, y: -1, visible: false };
+    this.lastPointer = null;
   }
 
   fontFor(typeface, size, { bold = false, italic = false } = {}) {
@@ -355,11 +356,46 @@ export class Renderer {
     }
   }
 
+  // Draws the mouse pointer at (x, y) in pixels: an arrow outlined in the
+  // background colour so it stays visible over any cell.
+  drawPointer({ x, y }) {
+    const { CanvasKit, canvas } = this;
+    const size = Math.max(10, Math.round(this.fontSize * 0.9));
+    const builder = new CanvasKit.PathBuilder();
+    builder.moveTo(x, y);
+    builder.lineTo(x, y + size);
+    builder.lineTo(x + size * 0.28, y + size * 0.74);
+    builder.lineTo(x + size * 0.46, y + size * 1.08);
+    builder.lineTo(x + size * 0.63, y + size * 1.0);
+    builder.lineTo(x + size * 0.45, y + size * 0.66);
+    builder.lineTo(x + size * 0.72, y + size * 0.66);
+    builder.close();
+    const path = builder.detach();
+    builder.delete();
+    const outline = this.paintFor(this.background).copy();
+    outline.setStyle(CanvasKit.PaintStyle.Stroke);
+    outline.setStrokeWidth(Math.max(1, size / 8));
+    canvas.drawPath(path, outline);
+    canvas.drawPath(path, this.paintFor(this.cursorColor));
+    outline.delete();
+    path.delete();
+  }
+
+  // The rows an arrow at (x, y) covers, so they are repainted when it moves.
+  pointerRows({ x, y }) {
+    void x;
+    const size = Math.max(10, Math.round(this.fontSize * 0.9));
+    const first = Math.floor((y - this.offsetY) / this.cellHeight);
+    const last = Math.ceil((y + size * 1.1 - this.offsetY) / this.cellHeight);
+    return [first, last];
+  }
+
   // Repaints what changed and flushes to the framebuffer. `cursor` is
   // { x, y, visible }; `images` is a list of { image, rect } placements in
-  // screen pixels, from images.js, drawn over the text. Returns true when
-  // anything was painted.
-  render(term, { cursor, images = [] } = {}) {
+  // screen pixels, from images.js, drawn over the text; `pointer` is the
+  // mouse position in pixels, drawn last. Returns true when anything was
+  // painted.
+  render(term, { cursor, images = [], pointer = null } = {}) {
     const buffer = term.buffer.active;
     const top = buffer.viewportY;
     const dirty = [];
@@ -375,6 +411,13 @@ export class Renderer {
     const cursorRows = new Set();
     if (this.lastCursor.visible) cursorRows.add(this.lastCursor.y);
     if (cursor?.visible) cursorRows.add(cursor.y);
+    // Wherever the pointer was and is has to be repainted: the text under it
+    // has not changed, so no row hash would say so.
+    for (const position of [this.lastPointer, pointer]) {
+      if (!position) continue;
+      const [first, last] = this.pointerRows(position);
+      for (let row = Math.max(0, first); row < Math.min(this.rows, last); row++) cursorRows.add(row);
+    }
     for (const row of cursorRows) {
       if (row >= 0 && row < this.rows && !dirty.includes(row)) dirty.push(row);
     }
@@ -390,6 +433,8 @@ export class Renderer {
     }
     this.lastCursor = { x: cursor?.x ?? -1, y: cursor?.y ?? -1, visible: Boolean(cursor?.visible) };
     if (images.length) this.drawImages(images, dirty);
+    if (pointer) this.drawPointer(pointer);
+    this.lastPointer = pointer ? { x: pointer.x, y: pointer.y } : null;
     this.screen.flush();
     return true;
   }

package/initramfs/lib/bunterm/terminal.js

@@ -50,6 +50,7 @@ export const createSession = ({
   theme = defaultTheme,
   scrollback = 1000,
   cursorBlink = true,
+  mouse = true,
   env = {},
   onError = (error) => console.error(`bunterm: ${error?.stack ?? error}`),
 }) => {
@@ -82,13 +83,24 @@ export const createSession = ({
   let frameTimer = null;
   let blinkOn = true;
   const cursorHidden = () => Boolean(term._core?.coreService?.isCursorHidden);
+  // Only set when a pointer is attached; without one the renderer is called
+  // exactly as before.
+  let pointer = null;
   const paint = () => {
     if (frameTimer) clearTimeout(frameTimer);
     frameTimer = null;
     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.
+    const row = buffer.baseY + buffer.cursorY - buffer.viewportY;
     return renderer.render(term, {
-      cursor: { x: buffer.cursorX, y: buffer.cursorY, visible: blinkOn && !cursorHidden() },
+      cursor: {
+        x: buffer.cursorX,
+        y: row,
+        visible: blinkOn && !cursorHidden() && row >= 0 && row < renderer.rows,
+      },
       images: images.visible(),
+      pointer,
     });
   };
   const requestFrame = () => {
@@ -137,10 +149,102 @@ export const createSession = ({
     const applicationCursorKeys = Boolean(term._core?.coreService?.decPrivateModes?.applicationCursorKeys);
     const text = translateKeys(bytes.toString("latin1"), { applicationCursorKeys });
     backend.write(Buffer.from(text, "latin1"));
+    // Typing returns to the live screen, as every terminal does.
+    if (term.buffer.active.viewportY !== term.buffer.active.baseY) {
+      term.scrollToBottom();
+      renderer.invalidate();
+    }
     resetBlink();
     requestFrame();
   };
 
+  // Turns a pointer report from mouse.js into the mouse sequences the
+  // program asked for. xterm.js's CoreMouseService owns the protocol: it
+  // knows which events the program enabled (DECSET 1000/1002/1003), encodes
+  // them (SGR 1006 or the default form) and sends them through onData, so
+  // nothing here builds an escape sequence. Reports arrive only while a
+  // pointer is open, and this is the only place the terminal sees one.
+  const CoreMouseButton = { LEFT: 0, MIDDLE: 1, RIGHT: 2, NONE: 3, WHEEL: 4 };
+  const CoreMouseAction = { UP: 0, DOWN: 1, LEFT: 2, RIGHT: 3, MOVE: 32 };
+  const heldButton = (buttons) => (buttons.left ? CoreMouseButton.LEFT
+    : buttons.middle ? CoreMouseButton.MIDDLE
+    : buttons.right ? CoreMouseButton.RIGHT
+    : CoreMouseButton.NONE);
+
+  // Scrolls the viewport when the program is not reading the mouse itself:
+  // through the scrollback on the normal screen, and as arrow keys on the
+  // alternate screen, which has no scrollback and is what a pager expects.
+  const wheelScroll = (notches) => {
+    const lines = notches * 3;
+    if (term.buffer.active.type === "alternate") {
+      const application = Boolean(term._core?.coreService?.decPrivateModes?.applicationCursorKeys);
+      const key = `\u001b${application ? "O" : "["}${lines > 0 ? "A" : "B"}`;
+      backend.write(Buffer.from(key.repeat(Math.abs(lines)), "latin1"));
+      return;
+    }
+    const before = term.buffer.active.viewportY;
+    term.scrollLines(-lines);
+    if (term.buffer.active.viewportY !== before) {
+      // Every row on screen is different now, and identical text at the same
+      // row would otherwise hash the same as before.
+      renderer.invalidate();
+      requestFrame();
+    }
+  };
+
+  const reportMouse = (report) => {
+    pointer = { x: report.x, y: report.y };
+    requestFrame();
+    const service = term._core?.coreMouseService;
+    if (!service?.areMouseEventsActive) {
+      if (report.wheel) wheelScroll(report.wheel);
+      return;
+    }
+    const column = Math.floor((report.x - renderer.offsetX) / renderer.cellWidth);
+    const row = Math.floor((report.y - renderer.offsetY) / renderer.cellHeight);
+    const send = (button, action) => {
+      try {
+        service.triggerMouseEvent({ col: column, row, button, action, ctrl: false, alt: false, shift: false });
+      } catch (error) {
+        onError(error);
+      }
+    };
+    for (const name of report.released) {
+      send(CoreMouseButton[name.toUpperCase()], CoreMouseAction.UP);
+    }
+    for (const name of report.pressed) {
+      send(CoreMouseButton[name.toUpperCase()], CoreMouseAction.DOWN);
+    }
+    if (report.moved) send(heldButton(report.buttons), CoreMouseAction.MOVE);
+    for (let notch = 0; notch < Math.abs(report.wheel); notch++) {
+      send(CoreMouseButton.WHEEL, report.wheel > 0 ? CoreMouseAction.UP : CoreMouseAction.DOWN);
+    }
+    for (let notch = 0; notch < Math.abs(report.hwheel); notch++) {
+      send(CoreMouseButton.WHEEL, report.hwheel > 0 ? CoreMouseAction.RIGHT : CoreMouseAction.LEFT);
+    }
+  };
+
+  // The pointer is opened only when asked for, by a module that is imported
+  // only then, so a machine without one — or a broken input layer — cannot
+  // affect a plain session.
+  let pointerDevice = null;
+  const attachPointer = async () => {
+    if (!mouse) return null;
+    const { openPointer, findPointers } = await import("./mouse.js");
+    const devices = findPointers();
+    if (!devices.length) throw new Error("no pointing device in /dev/input (is the evdev module loaded?)");
+    pointerDevice = openPointer({
+      devices,
+      width: screen.width,
+      height: screen.height,
+      onSync: reportMouse,
+      onError,
+    });
+    pointer = { x: pointerDevice.state.x, y: pointerDevice.state.y };
+    paint();
+    return pointerDevice;
+  };
+
   // Waits until every byte received so far has been parsed, then paints.
   const settle = async () => {
     await queue;
@@ -154,13 +258,18 @@ export const createSession = ({
     if (frameTimer) clearTimeout(frameTimer);
     frameTimer = null;
     backend.close();
+    pointerDevice?.close();
+    pointerDevice = null;
     images.delete();
     renderer.delete();
     term.dispose();
   };
 
   paint();
-  return { term, backend, renderer, images, kitty, paint, requestFrame, settle, input, exited, close };
+  return {
+    term, backend, renderer, images, kitty,
+    paint, requestFrame, settle, input, exited, close, attachPointer, reportMouse, wheelScroll,
+  };
 };
 
 // Runs a session on the framebuffer with the console in graphics mode and
@@ -193,6 +302,18 @@ export const runTerminal = async ({ console: consoleDevice = null, device = "/de
         },
       });
       onRestore(() => keyboard.close());
+      if (options.mouse !== false) {
+        // A pointer that cannot be opened is reported and the session
+        // continues as a keyboard-only terminal.
+        try {
+          const attached = await session.attachPointer();
+          if (attached?.devices.length) {
+            console.error(`bunterm: mouse: ${attached.devices.map((device) => device.name).join(", ")}`);
+          }
+        } catch (error) {
+          console.error(`bunterm: mouse: ${error.message}`);
+        }
+      }
       return await session.exited;
     } finally {
       keyboard?.close();

package/initramfs/lib/dlopen.js

@@ -85,6 +85,10 @@ export const libc = dlopen(libcPath, {
     args: [FFIType.i32, FFIType.ptr, FFIType.i32],
     returns: FFIType.i32,
   },
+  chroot: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
 });
 
 export const cString = (value) => new TextEncoder().encode(`${value}\0`);

package/initramfs/lib/document.js

@@ -1,6 +1,10 @@
 // Shared renderer for /usr/share/doc/buninu-linux/<name>.md command manuals.
+import { resolve } from "node:path";
+
 export const showDocument = async (name) => {
-  const path = `${import.meta.dir}/../usr/share/doc/buninu-linux/${name}.md`;
+  const path = resolve(`${import.meta.dir}/../usr/share/doc/buninu-linux/${name}.md`);
   const rendered = Bun.markdown.ansi(await Bun.file(path).text(), { hyperlinks: true });
   process.stdout.write(rendered.endsWith("\n") ? rendered : `${rendered}\n`);
+  // Where the page lives, for anyone who wants to read or edit the source.
+  process.stdout.write(`\u001b[2m${path}\u001b[0m\n`);
 };

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

@@ -10,6 +10,7 @@ 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 -e bun /buninu/apps/jsmdcui/src/index.js --demo
+bunterm --no-mouse          # keyboard only
 bunterm -h
 ```
 
@@ -28,6 +29,7 @@ text mode and `bunterm` exits with its status.
 | `--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`. |
 
 ## What is drawn
 
@@ -59,13 +61,40 @@ screen. A few console-specific
 sequences are rewritten to xterm's (`F1`–`F5`, `Home`, `End`), and arrow keys
 follow the program's application cursor mode.
 
+## Mouse
+
+Every pointing device under `/dev/input/event*` is opened and an arrow is
+drawn on the screen. Clicks, drags and wheel notches reach the program as
+the xterm mouse sequences it asked for: nothing is sent unless the program
+enabled reporting (`DECSET 1000`, `1002` or `1003`), and what is sent follows
+the mode it chose, SGR (`1006`) included. `jsmdcui`, `micro`, `htop`, `vim`
+and anything else that speaks the protocol work with no configuration.
+
+When the program is not reading the mouse, the wheel scrolls instead: back
+through the scrollback on the normal screen, three lines per notch, and as
+arrow keys on the alternate screen, which has no scrollback and is what a
+pager expects. Typing returns to the live screen, and the text cursor is
+hidden while it is scrolled out of view.
+
+`--no-mouse` turns all of this off: the terminal then never looks at
+`/dev/input` and never loads the mouse module.
+
+`init.js` loads `evdev` and `psmouse` at boot, so a PS/2 mouse — which is
+what QEMU's q35 machine and most PCs present — has a device node ready. A USB
+mouse also needs the `usbhid` stack, which a `--real` image carries and
+`cfg.all` loads. The pointer follows relative devices (a mouse) and absolute
+ones (a tablet or touchscreen) alike; a device that cannot be opened is
+reported and the session continues without it.
+
 ## Limits
 
 - Needs a framebuffer: `linux-lts` has one built in, while the default
   `linux-virt` builds it as modules the image does not ship, so build with
   `--linux-lts` or `--real` (efifb/simpledrm from UEFI).
-- No mouse, no selection, no scrollback viewing (the buffer keeps 1000
-  lines for programs that query it).
+- No selection, and no keyboard way to scroll back: the wheel is it. The
+  buffer keeps 1000 lines. A program that does not enable mouse reporting
+  sees no clicks — the arrow still moves, so the pointer is visibly alive.
+  `--no-mouse` removes the pointer entirely.
 - A program that prints a terminal reply while the tty echoes (that is, one
   not in raw mode) will see the reply echoed, as on any terminal.
 - Kitty images are drawn above text; `z` ordering below text and animation