buninu-linux 0.13.56 → 0.15.58

package/README.md

@@ -28,17 +28,20 @@
 
 ---
 
+- [繁體中文](README.zh.md)
 - [Table of contents](#contents)
+- Terminal documentation: `bun x buninu-linux --readme` (English),
+  `bun x buninu-linux --readme-zh` or `--docs` (Traditional Chinese).
 - .
 - 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
   * `cfg.disk` + shell `mount` mounts local disks
-  * `cfg.net` loads common wired NIC and Android USB-tethering drivers
+  * `cfg.net` loads common wired NIC and Android USB-tethering drivers and automatically attempts DHCP configuration
   * `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.
+  * After a DHCP lease expires or when you need fresh network settings, run `dhclient usb0` (using your interface name). Manual configuration with `ip` remains available.
   * 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)
@@ -117,6 +120,20 @@ bun ./index.js -fb --real --export
 This fetches the pinned Alpine/Bun/npm inputs, selects the physical-hardware
 modules, builds `vda.img`, and exports `buninu-linux-<version>.img`.
 
+For a smaller image, add `--no-gpu` to either build command:
+
+```sh
+bun x buninu-linux -fb --real --no-gpu --export
+# From a source checkout:
+bun ./index.js -fb --real --no-gpu --export
+```
+
+The reference x86-64 `--real` builds produce a **128 MiB** image with
+`--no-gpu`, versus **320 MiB** with the default GPU modules and firmware.
+This omits the optional GPU bundle while retaining the framebuffer/bunterm
+software display path. Image size is calculated from the packaged contents
+and may change with later versions.
+
 #### Write the image to a USB drive
 
 The recommended method is **Ventoy**: install it on the USB drive once using
@@ -197,7 +214,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, cfg.sound
+Configuration getters: cfg.all, cfg.disk, cfg.net, cfg.power, cfg.sound, cfg.gpu
 
 bun-repl>
 ```
@@ -227,8 +244,7 @@ It supports Chinese text, emoji and the browser's terminal graphics. Use
 `Ctrl+Alt+F1` to return to the original console and `Ctrl+Alt+F2` to return
 to this terminal.
 
-There is no DHCP client yet; configure a detected wired interface with `ip` as
-described under [Basic configuration](#basic-configuration). Run `poweroff` for a synced
+Run `poweroff` for a synced
 shutdown. After editing the initramfs, `bun ./index.js -b --real --export` rebuilds the
 image; `-h` lists all flags.
 
@@ -327,9 +343,8 @@ toolchain (including `binutils-aarch64-linux-gnu` for aarch64), or set
 
   `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
+  bare `bunterm` also defaults to VT 2, leaving VT 1 available for hardware
+  setup. Using a VT other than the active one 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`.
@@ -384,9 +399,16 @@ cfg.power
 cfg.sound
 ```
 
-`cfg.net` loads the packaged wired-network and Android USB-tethering drivers and prints detected
-interfaces and MAC addresses. There is no DHCP client yet, so configure the
-interface manually after entering the Buninu shell with `start()`:
+`cfg.net` loads the packaged wired-network and Android USB-tethering drivers,
+prints detected interfaces and MAC addresses, and automatically attempts DHCP
+configuration. If it succeeds, no additional DHCP command is needed.
+
+After a lease expires or when you need to obtain network settings again,
+enter the Buninu shell with `start()` and run `dhclient usb0` (replace `usb0`
+with your interface name). It configures the interface once and exits;
+there is no automatic renewal.
+
+For a manually configured static address, use:
 
 ```sh
 ip link set eth0 up
@@ -408,6 +430,120 @@ mount -fv /dev/sda1 /mnt
 
 Run `poweroff` for a synced shutdown.
 
+### Using bunterm
+
+Click the FPS button on the right of the bunterm menu title to toggle a cyan counter at the top-right of the terminal. It reports newly presented Kitty image frames per second (such as Casty/Land output), sampled once per second; mouse/menu redraws are excluded. Static images and text-only sessions show 0 FPS. The setting is local to this bunterm session and defaults off.
+
+Native bunterm advertises its preferred raw pixel format from the framebuffer bitfields: BGRA or RGBA for supported 32-bit layouts, otherwise PNG. Updated Casty, buninu-browser and Land negotiate this automatically over shared-file Kitty transport; BGRA uses the private format `f=1111970369`, RGBA uses standard `f=32`. Other terminals and jsgotty retain their existing protocol.
+
+To inspect the current picture path in Casty, press `Ctrl-E`, type `kitty`,
+and press Enter. In Land, click **@** instead to open the command line.
+For example, `Kitty: file · format=bgra` reports shared-file raw frames;
+`rgba` is also raw, while PNG/JPEG indicate encoded images. Raw is negotiated
+automatically with supported local peers; no extra launch flag is needed.
+The bunterm FPS counter measures presented images, not a client's rendering FPS.
+
+`bunterm` is the graphical terminal on the Linux framebuffer. It displays CJK
+text, colour emoji and Kitty graphics without starting X11 or Wayland. On the
+real-hardware image, enter the shell with `start()` at the `bun-repl>` prompt,
+then run:
+
+```sh
+bunterm                     # open a new VT after the last session; first is tty2
+bunterm 3 -s 16             # another session, with a 16 px font (default: 13)
+# Alternatively, start a specific application on an unused VT:
+bunterm 4 -e jsmdcui --allow-url README.md
+```
+
+To open a web URL or an existing local file in a new browser terminal:
+
+```sh
+xdg-open https://buninu.org
+xdg-open "./page with spaces.html"
+```
+
+`xdg-open` runs `bunterm -e buninu-browser URL` on a new VT. HTTP/HTTPS URLs
+and `about:` URLs open directly; local paths and `file://` URLs are resolved to existing regular
+files and encoded as absolute file URLs. Directories and other URL schemes
+are not supported. Run `xdg-open --help` for usage.
+
+Use `Ctrl+Alt+F1` to return to the initial console, `Ctrl+Alt+F2` to return to
+VT 2, or `Alt+Left` / `Alt+Right` to switch VTs. From a shell, `chvt 1` and
+`chvt 2` do the same. Switching preserves the running sessions; exiting a
+session's shell or application ends that bunterm.
+
+Click the screen's top-left **2×2 pixels** to open its menu:
+
+| Control | Usage |
+| --- | --- |
+| 🔤 Font − / + | Resize the current session's text and terminal grid. The size is centred between the buttons. |
+| 📋 Copy | Left-drag to select terminal text, then copy it to the shared xclip clipboard. Selection is available only when the application has not enabled mouse reporting. |
+| 📥 Paste | Paste from xclip. Applications that enable bracketed paste receive its delimiters; other applications receive plain text. |
+| Command input | Click the light input field or press Tab. Type `font 16`, `font +`, `font -`, `copy`, `paste`, `vt 2` or `help`, then press Enter. These are local bunterm commands. |
+| VT list | Switch to an existing bunterm or the initial tty. The active VT is marked `(current)`. |
+| + New bunterm | Start bunterm on the tty after the highest listed number, using the current font size. |
+
+Press Esc to close the menu. Font changes last for the current session.
+The mouse wheel scrolls terminal history when the application does not request
+mouse events. `--no-mouse` disables mouse input and the menu;
+`--no-clipboard` disables both menu clipboard actions and OSC 52.
+See [Clipboard](#clipboard) for sharing text between applications.
+
+**Kitty keyboard:** applications can negotiate flags **1, 2 and 8**, using the
+same encoder as jsgotty, to distinguish Ctrl/Alt/Shift/Super combinations and
+request press, repeat and release events. No launch flag is needed. Ordinary
+applications retain the console's translated input; the original keyboard mode is restored
+when the application disables Kitty or bunterm exits. VT-switching shortcuts stay
+reserved. Dead-key/Compose sequences are not yet implemented in Kitty mode.
+Use `bunterm --help` for full options and keyboard details.
+
+### Using Bun Modern Shell
+
+bunmsh is the dependency-free, mksh-inspired shell bundled with Buninu. Its
+main features are:
+
+- Lines beginning with `Bun.*` run as JavaScript; returned values are printed
+  and promises are awaited automatically. Use `Bun.e;` or `Bun.e,` for
+  arbitrary JavaScript.
+- Lightweight cwd tabs keep several working directories ready. In bunmsh,
+  `Ctrl-T` creates or cycles right through tabs, while `Alt-T` cycles left.
+  * Also useful cmds: `tab n`, `tab c`(Alt-C)
+- Shell variables and JavaScript share a live variable table by `$.`, and `Bun.sha`
+  can retain JavaScript values across commands and cwd tabs.
+- Saved history, Bash/Fish history import, completions, and ghost suggestions
+  are available interactively.
+- `serve [directory]` starts a browsable HTTP file server. Together with
+  Android USB tethering, it provides a simple way to transfer files between
+  Buninu Linux and the connected phone.
+- Cross-platform builtins and PATH-fallback commands.
+- `Ctrl-U` removes and saves the text before the cursor; press it again at the
+  beginning of the line to restore it. `Ctrl-K` independently toggles the text
+  after the cursor when at the end of the line.
+- Unquoted pathname patterns use `Bun.Glob` and follow directory symbolic
+  links used as intermediate path components, as traditional shells do. This
+  matters for sysfs, where class entries are normally links. For example:
+
+```sh
+ls /sys/class/net/*/device
+```
+
+For a readable process overview, run:
+
+```sh
+pspac
+
+# Kernel threads show as [name]; filter them out to see only userspace
+pspac | grep -v '\[[a-z]'
+```
+
+`pspac` shows the real `PID COMMAND` process table and highlights each command
+line as shell syntax with micro's Monokai colours. Leading directories are
+dimmed so the program name stands out. Use `pspa` for the same table as plain
+text.
+
+See the [bunmsh repository](https://github.com/jjtseng93/bunmsh) for its full
+syntax, interactive controls, builtins, and current compatibility details.
+
 ### Editor quick start
 
 The bundled `jmi` terminal editor works without a network connection:
@@ -451,7 +587,7 @@ If `Enter` is not recognized in a particular terminal, try `Ctrl-J` or
 
 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`:
+`bunterm /dev/tty2`. Omitting the argument opens a new VT after the last known session (tty2 initially):
 
 ```sh
 bunterm 2
@@ -500,53 +636,6 @@ terminal panes, it creates a new editor tab instead of wrapping back to the
 first terminal tab. In every other case it performs the normal next-tab cycle.
 Use `Esc` only when you actually want to close the current terminal pane.
 
-### Using Bun Modern Shell
-
-bunmsh is the dependency-free, mksh-inspired shell bundled with Buninu. Its
-main features are:
-
-- Lines beginning with `Bun.*` run as JavaScript; returned values are printed
-  and promises are awaited automatically. Use `Bun.e;` or `Bun.e,` for
-  arbitrary JavaScript.
-- Lightweight cwd tabs keep several working directories ready. In bunmsh,
-  `Ctrl-T` creates or cycles right through tabs, while `Alt-T` cycles left.
-  * Also useful cmds: `tab n`, `tab c`(Alt-C)
-- Shell variables and JavaScript share a live variable table by `$.`, and `Bun.sha`
-  can retain JavaScript values across commands and cwd tabs.
-- Saved history, Bash/Fish history import, completions, and ghost suggestions
-  are available interactively.
-- `serve [directory]` starts a browsable HTTP file server. Together with
-  Android USB tethering, it provides a simple way to transfer files between
-  Buninu Linux and the connected phone.
-- Cross-platform builtins and PATH-fallback commands.
-- `Ctrl-U` removes and saves the text before the cursor; press it again at the
-  beginning of the line to restore it. `Ctrl-K` independently toggles the text
-  after the cursor when at the end of the line.
-- Unquoted pathname patterns use `Bun.Glob` and follow directory symbolic
-  links used as intermediate path components, as traditional shells do. This
-  matters for sysfs, where class entries are normally links. For example:
-
-```sh
-ls /sys/class/net/*/device
-```
-
-For a readable process overview, run:
-
-```sh
-pspac
-
-# Kernel threads show as [name]; filter them out to see only userspace
-pspac | grep -v '\[[a-z]'
-```
-
-`pspac` shows the real `PID COMMAND` process table and highlights each command
-line as shell syntax with micro's Monokai colours. Leading directories are
-dimmed so the program name stands out. Use `pspa` for the same table as plain
-text.
-
-See the [bunmsh repository](https://github.com/jjtseng93/bunmsh) for its full
-syntax, interactive controls, builtins, and current compatibility details.
-
 ### Showing images
 
 The Linux text console cannot draw pictures, so first start `bunterm`, the
@@ -591,7 +680,20 @@ aarch64 guest also needs a QEMU display; see
 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.
+Left-drag selects text only when the application has not enabled mouse reporting.
+Click the top-left **2×2 pixels** for **Copy / Paste**, **font − / +**, the VT
+list and a local command field (`font 16`, `copy`, `paste`, `vt 2`, `help`).
+Paste uses bracketed paste when the application requests it.
+`bunterm --no-clipboard` disables both OSC 52 and menu clipboard actions.
+
+See [Using bunterm](#using-bunterm) for the menu and Kitty keyboard support.
+
+In `buninu-browser`, a website's Copy button can write text through
+`navigator.clipboard.writeText()` after a user click or key press on HTTPS
+or localhost. The browser controller prefers `xclip -selection clipboard`,
+so copied text reaches the same clipboard used by bunterm and jsmdcui.
+If no clipboard provider is available, the operation reports failure.
+This is separate from selecting text and copying it with Casty's shortcuts.
 
 For Chinese input, run the pinyin input method
 [jspinyin](https://www.npmjs.com/package/@drxiaozhi/jspinyin) in a bunterm
@@ -607,6 +709,11 @@ jspinyin
   OSC 52, and `Ctrl-V` pastes it in jsmdcui or jspinyin, since jsmdcui reads
   from `xclip` first by default.
 
+jspinyin also has **Clear / Restore** buttons. Clear saves the current result
+before emptying it; Restore appends that saved text to the end of the result.
+Restoring keeps the saved text, so repeated clicks can append it repeatedly.
+The input panel's help link explains candidate selection and other controls.
+
 ### Playing YouTube with sound (experimental)
 
 [jspulse](https://github.com/jjtseng93/jspulse), now a built-in, is a
@@ -640,23 +747,47 @@ chroot shell on tty2. `bun x` needs network access; see
    bunterm 3
    ```
 
-3. **Set the volume, then test the speakers.** Setting a volume also unmutes
-   the output, so the 3-second test tone is guaranteed to be audible. Adjust
-   the percentage afterwards if it is too quiet or too loud:
+3. **Identify the sound card, set its volume, then test playback.** First
+   list the ALSA cards and their mixer controls:
+
+   ```sh
+   jspulse --audio-info
+   ```
+
+   For built-in speakers or headphones plugged into the computer's audio
+   jack, choose the **onboard analog audio** card. In the example with
+   card 0 **HDA Intel HDMI**, card 1 **HDA Intel PCH**, and card 2
+   **HDA NVIDIA**, try **card 1 (HDA Intel PCH)** first. Controls named
+   `Speaker Playback`, `Headphone Playback`, `PCM Playback`, or
+   `Master Playback` are useful clues for this output.
+
+   Choose an **HDMI/DisplayPort** card instead when you want sound from a
+   monitor or TV connected through that GPU. Intel HDMI and NVIDIA audio
+   do not normally feed the computer's analog headphone jack. A USB headset
+   or USB sound card should use its own USB audio card.
+
+   Card numbers vary by machine; replace `1` below with the card connected
+   to your intended output, then use the test tone to check it.
 
    ```sh
-   jspulse --volume 50
-   jspulse --play
+   jspulse --card 1 --volume 50
+   jspulse --card 1 --play
    ```
 
-4. **Start the sound server.** It keeps running in the foreground, so leave
-   this terminal as it is; `Ctrl+C` stops it:
+   Setting a supported playback volume also unmutes its corresponding switch.
+   HDMI cards may have no hardware playback volume control; in that case skip
+   `--volume` and adjust the connected monitor/TV volume. This does not by
+   itself mean HDMI playback is unavailable. The test tone checks the selected
+   output; adjust the volume as needed.
+
+4. **Start the sound server on the same card.** It keeps running in the
+   foreground, so leave this terminal as it is; `Ctrl+C` stops it:
 
    ```sh
-   jspulse --alsa
-   
+   jspulse --alsa --card 1
+
    # or start in the background
-   jspulse --alsa &
+   jspulse --alsa --card 1 &
    ```
 
 5. **Start casty with sound.** Press `Ctrl+Alt+F2` to return to the chroot
@@ -683,6 +814,45 @@ chroot shell on tty2. `bun x` needs network access; see
 If there is no sound, check step 4's terminal for errors, and make sure
 `PULSE_SERVER` was exported in the same shell that started casty.
 
+### Data and persistence
+
+Buninu Linux runs from an in-memory initramfs. Changes to the default home
+directory (`/buninu`), system configuration, and packages installed during a
+session disappear after reboot unless saved to a mounted disk. `/tmp` is also
+temporary. The boot image does not automatically save these changes back to
+itself, and creating a directory under `/mnt` alone does not make it persistent.
+
+To keep files, load storage drivers at the initial `bun-repl>` prompt, then
+enter the shell:
+
+```js
+cfg.disk
+start()
+```
+
+Mount an existing data partition (replace `/dev/sda1` with your partition),
+then save or copy files into it:
+
+```sh
+mount /dev/sda1 /mnt/data --mkdir
+mkdir -p /mnt/data/work
+cp /buninu/notes.md /mnt/data/work/notes.md
+cd /mnt/data/work
+```
+
+The copy example assumes you have already created `/buninu/notes.md`. Files
+written under `/mnt/data` while the partition is mounted remain on that disk.
+After reboot, mount the same partition again to access them. This does not
+automatically restore your home directory, installed packages, or system settings.
+
+Before unplugging the disk, close programs using it, leave its directories,
+and unmount it successfully:
+
+```sh
+cd /
+umount /mnt/data
+```
+
 ## Commands inside /bin
 
 | command | does | manual |
@@ -695,8 +865,12 @@ If there is no sound, check step 4's terminal for errors, and make sure
 | `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` |
+| `dhclient` | Reacquire DHCPv4 settings after expiry or when needed (`dhclient usb0`), then exit; also supports release | `dhclient --help` |
+| `ping` | IPv4 ICMP / IPv6 ICMPv6 echo via Bun FFI; count, interval, timeout, deadline, payload size, TTL and source selection | `ping --help` |
 | `ps` | composable process fields from `/proc`; also exports its snapshot and single-row formatter for other commands | `ps --help` |
 | `top` | periodically refreshes the process snapshot and rows supplied by `ps` | `top --help` |
+| `xdg-open` | open HTTP/HTTPS, `about:`, or an existing local file in buninu-browser on a new bunterm VT | `xdg-open --help` |
+| `chvt` | Switch Linux VTs (`chvt 1` / `chvt 2`), including switching away from and back to bunterm | `chvt --help` |
 | `poweroff` | sync pending writes and power off through the Linux reboot system call | `poweroff --help` |
 | `reboot` | sync pending writes and restart through the shared Linux reboot logic | `reboot --help` |
 | `tar` | create, extract, or list tar archives with gzip and zstd compression through `Bun.Archive` | `tar --help` |
@@ -717,6 +891,14 @@ above, implemented as Bun scripts or thin launchers for bundled packages.
 For Debian/Alpine rootfs and Chromium examples, see
 [Optional chroot and native binaries](#optional-chroot-and-native-binaries).
 
+`ping -c 4 127.0.0.1` checks IPv4 connectivity; `ping -6 -c 4 ::1` checks
+IPv6. `ping -c 10 -i 0.2 -W 1 HOST` adjusts count, interval and reply timeout.
+The command uses ICMP sockets directly, with a raw-socket fallback when needed.
+It supports Linux glibc/musl and native Android bionic through the shared libc
+loader; `BUNINU_LIBC` remains an explicit override. Run
+`bun test test/ping.test.js test/libc.test.js` to compare against the installed
+system ping. See `ping --help` for permission requirements and supported flags.
+
 ### Buninu Browser (early-stage, experimental)
 
 `buninu-browser` is still in an early stage. Websites may render incorrectly
@@ -739,6 +921,17 @@ REPL, then run `jspulse --alsa` in another terminal or use `jspulse --alsa &` to
 buninu-browser about:audio
 ```
 
+For a trusted test website with a self-signed HTTPS certificate, disable
+certificate verification for that invocation only:
+
+```sh
+env NODE_TLS_REJECT_UNAUTHORIZED=0 buninu-browser https://localhost:8443
+```
+
+This also disables verification for other requests made by that process and
+its inherited child processes. Avoid exporting it globally; verification
+remains enabled when this override is absent.
+
 ### Buninu Land (early-stage, experimental)
 
 Run `buninu-land` inside `bunterm` (or another Kitty-graphics terminal) to
@@ -749,6 +942,49 @@ requires no npm download.
 buninu-land
 ```
 
+The launcher enables Casty's `--no-shortcuts`: page keys go to Land and its
+clients instead of triggering Casty shortcuts. To quit the frontend, click
+**@** at the left of the address bar, type `q`, and press Enter. Clicking the
+address itself edits it; the bar displays the actual Wayland socket path.
+
+With the bundled Casty inside bunterm or a Kitty-keyboard-capable jsgotty,
+Super combinations and key releases are forwarded automatically:
+
+| Shortcut | Action |
+| --- | --- |
+| Super+Arrow | Focus a window in that direction |
+| Super+W / Super+Q | Ask the focused window to close |
+| Super+F | Toggle fullscreen |
+| Super+T | Toggle floating/tiling |
+| Super+Alt+F | Toggle maximization on Land's single output |
+| Super+Shift+Arrow | Swap with a tiled window in that direction |
+| Alt+Tab / Alt+Shift+Tab | Cycle forward/backward through windows |
+| Super+1–9 | Switch workspace |
+| Super+Shift+1–9 | Move the focused window to that workspace and follow it |
+| Super+- / Super+= | Shrink/grow horizontally; add Shift for vertically |
+
+Resize increments are 100 logical pixels; add Alt for 25 or Ctrl for 300.
+Tiled windows change the split ratio. These are the implemented window actions,
+not the complete Omarchy desktop. Legacy terminals cannot reliably send Super;
+Ctrl+Alt combinations now pass through to clients rather than acting as aliases.
+
+**Client GPU acceleration:** first run `cfg.gpu` in the initial REPL before
+opening bunterm (see [Optional client GPU acceleration](#optional-client-gpu-acceleration-cfggpu)).
+Then run Land in bunterm with the render node for the GPU you want to advertise:
+
+```sh
+buninu-land -- --gpu=/dev/dri/renderD128
+```
+
+Replace that example node with the actual one; numbering can change at boot.
+The client environment still needs working Mesa drivers and access to the same
+render node. Clients in a chroot also need access to Land's Wayland socket.
+The preset enables linear DMA-BUF import, deferred capture and 2 ms polling.
+Bare `--gpu` enables the preset without selecting a DRM device. Land itself
+still composites in software; only client rendering can use the GPU.
+Driver support is limited: the tested Intel path worked, but the tested Nouveau
+path produced blank/corrupt images. This does not guarantee NVIDIA support.
+
 The socket directory defaults to `$TMPDIR`, or the system temporary directory
 if `TMPDIR` is unset; an explicitly set `XDG_RUNTIME_DIR` takes precedence.
 No environment setup is needed to launch the compositor.
@@ -1108,7 +1344,7 @@ firmware console and waits; press any key to return to the firmware interface.
 
 `build-image.sh` is shared with [Section 2](#2-buninu-linux-bun-as-pid-1) — see [Disk layout](#disk-layout).
 
-### 2. Buninu Linux – Bun as PID 1
+### 2. Buninu Linux: Bun as PID 1
 
 An unsigned x64 Unified Kernel Image assembled from official Alpine packages,
 with Bun as the init process, replaces the hello-world application:
@@ -1179,7 +1415,7 @@ initramfs/                init.js, commands, userspace: the same for every archi
 native/<arch>/            musl and the GCC runtime (committed); bun and modules (fetched)
 ```
 
-The `--real` inputs are Alpine v3.24 `linux-lts-6.18.56-r0`, musl `1.2.6-r2`,
+The `--real` inputs are Alpine v3.24 `linux-lts-6.18.58-r0`, musl `1.2.6-r2`,
 `systemd-efistub-260.2-r0`, `libstdc++`/`libgcc` `15.2.0-r5`, and Bun 1.4.2
 `linux-x64-musl-baseline`. The aarch64 guest uses the same versions from
 Alpine's aarch64 repository and Bun's `linux-aarch64-musl`. There is no BusyBox
@@ -1193,15 +1429,11 @@ tampered with is fetched again and has to pass the same hash before a script
 extracts from it. Bumping a version changes both the file name and the hash, so
 it always refetches.
 
-The five application packages are pinned separately in
-`scripts/npm-packages.md`: `buninu-browser@0.2.3`, `buninu-land@0.1.3`,
-`@drxiaozhi/casty@1.3.7`, `@drxiaozhi/jspulse@0.2.1`, and
-`@drxiaozhi/jspinyin@0.1.1`. These were npm's `latest` versions when checked
-on 2026-10-11, with buninu-browser updated on 2026-10-12, and
-casty 1.3.7 and buninu-land 0.1.3 verified on 2026-10-16;
-fetch never resolves `latest` or a version range at runtime.
+The five application packages and their exact versions are pinned in
+[`scripts/npm-packages.md`](scripts/npm-packages.md), the authoritative list
+for this image. Fetch never resolves `latest` or a version range at runtime.
 Each registry tarball was checked against its published SHA-512 integrity
-before its SHA-256 was recorded in the shared pins file.
+before its SHA-256 was recorded in that shared pins file.
 
 The manifest uses fixed YAML-compatible blocks: a double-quoted
 `"package@version":` header, followed by two `  - ` lines containing the
@@ -1330,7 +1562,9 @@ LBA 2048..262110   ESP, FAT32 "EFIBOOT", type GUID C12A7328-F81F-11D2-BA4B-00A0C
 LBA 262111..       backup GPT
 ```
 
-128 MiB sparse, 1 MiB-aligned, with 34 sectors reserved at the end for the
+At least 128 MiB sparse, growing automatically with the EFI payload (64 MiB
+increments, with room for FAT metadata and free space), 1 MiB-aligned, with
+34 sectors reserved at the end for the
 backup GPT. `EFI/BOOT/BOOTX64.EFI` and `EFI/BOOT/BOOTAA64.EFI` are the
 architecture-specific removable-media fallback paths, so matching firmware
 runs the one present in the image without any NVRAM boot entry.
@@ -1343,7 +1577,7 @@ The physical boot chain is firmware → the UKI stub → its embedded
 and, with the currently pinned kernel, embeds this complete command line:
 
 ```text
-console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.56-0-lts rdinit=/bin/bun -- -e import('/init.js')
+console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.58-0-lts rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 Serial kernel logging is retained, while the final console makes
@@ -1367,7 +1601,7 @@ the same way). Build without `--real`; this selects Alpine `linux-virt`, omits t
 module set, and puts `ttyS0` last so serial stdio owns `/dev/console`:
 
 ```text
-console=tty0 console=ttyS0,115200 panic=0 PATH=/bin KERNEL_RELEASE=6.18.56-0-virt rdinit=/bin/bun -- -e import('/init.js')
+console=tty0 console=ttyS0,115200 panic=0 PATH=/bin KERNEL_RELEASE=6.18.58-0-virt rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 Build and boot it with:
@@ -1484,7 +1718,7 @@ The default `--real` image embeds this kernel command line (shown for the
 currently pinned LTS release):
 
 ```text
-console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.56-0-lts rdinit=/bin/bun -- -e import('/init.js')
+console=ttyS0,115200 console=tty0 REAL_MACHINE=1 panic=0 PATH=/bin KERNEL_RELEASE=6.18.58-0-lts rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 The physical display (`tty0`) is the final console and therefore owns PID 1's
@@ -1563,24 +1797,39 @@ custom `libinit.so` is needed.
 On a `--real` boot, init starts `/etc/resolv.conf` with `1.1.1.1` and
 `8.8.8.8`; these are initial public resolvers until the user replaces them
 with DNS appropriate for the local network. Hardware networking remains down
-until `cfg.net` loads the packaged drivers and the user assigns an address and
-route.
+until `cfg.net` loads the packaged drivers and attempts DHCP configuration.
+Manual address and route configuration with `ip` remains available.
+
+`cfg.net` starts DHCP in the background for every detected non-loopback interface.
+It returns immediately; failures and acquisition timeouts are logged without
+interrupting init. Each client exits after configuring its lease; no renewal process stays running.
+Repeated `cfg.net` calls do not launch duplicate active clients. Route metrics
+start at 100; only the first interface updates DNS, leaving the init fallback
+resolver available if it cannot acquire a lease.
+
+After a lease expires or when network settings need to be obtained again,
+run `dhclient usb0` (or `dhclient eth0`, depending on the interface name).
+This is not an extra step after successful automatic configuration by `cfg.net`.
+`dhclient` exits after configuration; `-timeout 20` limits acquisition to 20
+seconds. Leases do not renew automatically. For manual static configuration,
+see [Basic configuration](#basic-configuration).
 
 On a `--real` image the REPL also offers the getter-based `cfg` namespace:
-`cfg.net`, `cfg.disk`, `cfg.power`, `cfg.sound` and `cfg.all` run as soon as the property is read, without
+`cfg.net`, `cfg.disk`, `cfg.power`, `cfg.sound`, `cfg.gpu` 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
 `fetch-alpine.sh` kept in `modules.alias` and lists the interfaces. `cfg.disk`
 loads the packaged SATA/PATA/SCSI, NVMe/VMD and USB storage stacks so
 their disks and partitions appear in `/dev`, then lists `/sys/class/block`. `cfg.all`
-unconditionally attempts every packaged module and recursively loads its
+attempts every packaged module **except GPU modules** and recursively loads its
 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.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`
@@ -1594,6 +1843,68 @@ reports nothing registered). Nothing loads them at boot. PID 1 also installs
 the current process environment preserved, while overriding `PATH` and `HOME`
 for the userspace session.
 
+### Optional client GPU acceleration (`cfg.gpu`)
+
+To omit only the added GPU module requests and firmware when building:
+
+```sh
+bun index.js -b --real --no-gpu
+```
+
+The original simpledrm/fbcon/bunterm path, sound/network/storage modules, and
+any dependencies they require are retained. The setting applies to fetch/build
+and is forwarded into Docker. For direct shell scripts use
+`env BUNINU_NO_GPU=1 REAL_MACHINE=1 LINUX_FLAVOR=lts ./build-uki.sh`.
+Switching this option invalidates the module/firmware cache; omit the option
+(and unset `BUNINU_NO_GPU`) to restore the default GPU packaging. Cached APK
+downloads are retained but excluded from the image. This does not disable GPU
+support already compiled into the selected kernel.
+
+
+GPU drivers are packaged but are **not loaded by boot, `start()`, `cfg.all`, or
+`cfgMod`**. The existing simpledrm/framebuffer and software-rendered bunterm path
+stays the default. At the PID 1 REPL, before opening bunterm/fbdev, explicitly read:
+
+```js
+cfg.gpu
+```
+
+This is a one-shot PCI/virtio hardware probe, not a daemon. It matches available
+drivers, loads their module dependencies, and lists `/dev/dri/renderD*` and
+`/dev/fb*`. Individual driver failures are reported without stopping init. A
+missing render node is not reported as successful acceleration: inspect kernel
+firmware/driver messages; if probing is asynchronous, read `cfg.gpu` again later.
+If a process already holds an fd or mmap of `/dev/fb*`, it refuses to load GPU
+drivers. Exit that framebuffer client first; after GPU handoff, reopen it to
+discover the new framebuffer, resolution and pixel format. `fb0` is not guaranteed.
+
+The x86_64 LTS module set includes Intel `i915`/`xe`, AMD `amdgpu`/legacy `radeon`,
+NVIDIA **Nouveau**, and VMware `vmwgfx`; both architectures request `virtio_gpu`.
+Modules absent from a selected Alpine kernel are skipped with a build-time note.
+The five pinned Alpine `linux-firmware-{i915,xe,amdgpu,radeon,nvidia}` packages are
+included when PC GPU modules are present (about 151 MB of downloads). Firmware
+symlinks and directory aliases are preserved, and the kernel reads their `.zst`
+files directly. Firmware pins live in `scripts/gpu-firmware.json`; licenses and
+WHENCE are under `LICENSES/linux-firmware/`. Rebuild existing images to include
+the new modules and firmware; the build detects older fetch caches.
+
+Render nodes are set to `root:0`, mode `0660`, for this system's root clients.
+For non-root clients, set a numeric supplementary group before reading the getter:
+
+```js
+process.env.BUNINU_RENDER_GID = "107" // use the actual client render group ID
+cfg.gpu
+```
+
+The client must run with that numeric group and, inside a chroot/proot, see the
+real `/dev/dri` nodes and relevant `/sys`. Mesa, Vulkan loader/ICD and their
+dependencies belong in the **client's** environment; this change does not install
+them or accelerate CanvasKit/Land itself. A render node alone does not prove
+hardware rendering: verify `vulkaninfo`/the browser's renderer and visible output.
+QEMU additionally needs an accelerated host GPU backend (VirGL/Venus); a plain
+2D virtio GPU is not 3D acceleration. This does not include NVIDIA's proprietary
+driver, Android KGSL, or board-specific ARM GPU/DT/firmware enablement.
+
 ## Contents
 
 - [Quick start](#quick-start)
@@ -1609,16 +1920,18 @@ for the userspace session.
     + [Testing on a Linux host in Docker](#testing-on-a-linux-host-in-docker)
 - [Using Buninu Linux](#using-buninu-linux)
   * [Basic configuration](#basic-configuration)
+  * [Using bunterm](#using-bunterm)
+  * [Using Bun Modern Shell](#using-bun-modern-shell)
   * [Editor quick start](#editor-quick-start)
     + [jsmdcui](#jsmdcui)
   * [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)
   * [Playing YouTube with sound (experimental)](#playing-youtube-with-sound-experimental)
+  * [Data and persistence](#data-and-persistence)
 - [Commands inside /bin](#commands-inside-bin)
   * [Buninu Browser (early-stage, experimental)](#buninu-browser-early-stage-experimental)
   * [Buninu Land (early-stage, experimental)](#buninu-land-early-stage-experimental)
@@ -1637,7 +1950,7 @@ for the userspace session.
   * [Old build from a source checkout](#old-build-from-a-source-checkout)
 - [Implementation details](#implementation-details)
   * [1. Hello world](#1-hello-world)
-  * [2. Buninu Linux – Bun as PID 1](#2-buninu-linux-bun-as-pid-1)
+  * [2. Buninu Linux: Bun as PID 1](#2-buninu-linux-bun-as-pid-1)
     + [Build flags](#build-flags)
     + [Build pipeline](#build-pipeline)
       - [Pipeline inputs and outputs](#pipeline-inputs-and-outputs)
@@ -1650,13 +1963,14 @@ for the userspace session.
     + [Command implementation](#command-implementation)
     + [Reaching JavaScript with nothing mounted](#reaching-javascript-with-nothing-mounted)
     + [What init.js does](#what-initjs-does)
+  * [Optional client GPU acceleration (`cfg.gpu`)](#optional-client-gpu-acceleration-cfggpu)
 - [Authorship](#authorship)
 - [License](#license)
   * [Bundled component licenses](#bundled-component-licenses)
 
 ## Authorship
 
-Buninu Linux is written and maintained by Dr. John (醫者小智), the author of
+Buninu Linux is written and maintained by Dr. John, the author of
 [Buninu](https://github.com/jjtseng93/buninu), whose userspace it runs. The
 kernel, the C library, the GCC runtime, the UEFI stub and Bun itself are the
 work of their respective projects; [NOTICE.md](NOTICE.md) names each one with
@@ -1696,12 +2010,12 @@ when redistributing the image.
 | Linux kernels and networking, storage, xHCI, USB and HID modules | GPL-2.0-only with the Linux syscall note | image only |
 | systemd EFI stub | LGPL-2.1-or-later | image only |
 | Bun | MIT, plus the licenses of what it statically links | image only |
-| buninu-browser 0.2.3 | MIT for its own code; bundled components have their own licenses | npm download → image |
-| buninu-land 0.1.3 | MIT for its own code; bundled components retain their own licenses and notices | npm download → image |
+| buninu-browser | MIT for its own code; bundled components have their own licenses | npm download → image |
+| buninu-land | MIT for its own code; bundled components retain their own licenses and notices | npm download → image |
 | wasmpeg / FFmpeg (`@wasmpeg/cpu` 1.0.1, bundled in buninu-browser) | LGPL-2.1-or-later, plus component notices; source archive and rebuild documentation retained | browser package → image |
-| `@drxiaozhi/casty` 1.3.7 | MIT | npm download → image |
-| `@drxiaozhi/jspulse` 0.2.1 | LGPL-2.1-or-later, plus component notices | npm download → image |
-| `@drxiaozhi/jspinyin` 0.1.1 | MIT; hanzipinyin material under the Unlicense | npm download → image |
+| `@drxiaozhi/casty` | MIT | npm download → image |
+| `@drxiaozhi/jspulse` | LGPL-2.1-or-later, plus component notices | npm download → image |
+| `@drxiaozhi/jspinyin` | MIT; hanzipinyin material under the Unlicense | npm download → image |
 | CanvasKit 0.41.1 (`initramfs/lib/canvaskit/`, Skia compiled to WebAssembly) | BSD-3-Clause (`LICENSES/BSD-3-Clause-Skia.txt`) | committed |
 | xterm.js 6.0.0 headless core and unicode-graphemes addon (`initramfs/lib/xterm/`); box-drawing shape tables in `initramfs/lib/bunterm/glyphs.js` | MIT (`LICENSES/MIT-xterm.js.txt`) | committed |
 | DejaVu Sans Mono (`initramfs/usr/share/fonts/DejaVuSansMono*.ttf`) | Bitstream Vera (`LICENSES/Bitstream-Vera.txt`) | committed |