buninu-linux 0.7.5 → 0.8.55

package/README.md

@@ -44,10 +44,9 @@
     + See [Multitasking modes](#multitasking-modes)
   * The graphical terminal `bunterm` draws on the framebuffer with CJK, colour emoji and kitty images; see [Showing images](#showing-images)
     + Also has mouse click, wheel, and cursor drawing
-    + Simplified browser works: @sanohiro/casty in chroot debian
-    + (Use at your own risk: We haven't fully examined its code)
+    + Simplified browser works: buninu-browser natively or casty in chroot debian
     + Playing YouTube with sound (experimental); see [Playing YouTube with sound](#playing-youtube-with-sound-experimental)
-    + See [Commands inside `/bin`](#commands-inside-bin) for browser usage instructions
+    + See [Buninu Browser](#buninu-browser-early-stage-experimental) for the built-in browser, or [Debian and Chromium with casty](#debian-and-chromium-with-casty) for the optional chroot setup
 
 ---
 
@@ -61,58 +60,40 @@
 > test either an x86_64 or aarch64 guest with `qemu-system` instead, see
 > [Build and test with QEMU on macOS or Linux](#build-and-test-with-qemu-on-macos-or-linux).
 
+You can build the image on an Android phone, but the `--real` image below
+boots an x86-64 UEFI computer. It does not install Buninu Linux onto the phone.
+
 - This guide builds a bootable `buninu-linux-<version>.img`
-- The documented build environment is Debian 13 under Termux PRoot
-- A regular Debian installation works as well.
-  * Experimental Alpine support now!
-- For a source checkout, clone into the Termux home so native Termux and PRoot
-  can share it; `~` differs between them, but the absolute path is the same.
+- Fetch and build use JS tools by default and need host Bun, not the native
+  build toolchain or Docker. There is no need to enter PRoot just to build.
 
 ### Steps
 
-- Before anything, install Bun in Debian/Alpine first:
-
-```sh
-# Debian/Ubuntu
-apt update
-apt install curl unzip
-
-# Alpine
-apk update
-apk add curl unzip bash libgcc libstdc++
+- Install bun first:
+  * Android: run these commands in Termux:
 
-curl -fsSL https://bun.sh/install | bash
-```
+    ```sh
+    pkg update && pkg upgrade
+    pkg i npm
+    npm i -g bun
+    ```
 
-- Small tip: The below `apt install` command shows in the terminal when you run -b without the needed tools
+  * Others: Follow the official guide: <https://bun.com>
+- With Bun installed and on `PATH`, choose either build method below.
+  * Check by `bun --version`
+- Leave `BUNINU_JS_TOOLS` unset (or set it to `1`); `0`, `off` or `false`
+  selects the [old shell build](#old-build-shell-tools) instead.
 
 #### Build directly with bun x
 
-Install the build tools, enter a directory where
-you want to keep the finished image, then run the published package:
+Enter a directory where you want to keep the finished image, then run the
+published package directly. No `apt install`/`apk add` build tools are needed:
 
 ```sh
-# Debian/Ubuntu
-apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
-
-# Alpine
-apk add bash coreutils tar curl unzip parted dosfstools mtools libgcc libstdc++
-
-mkdir -p /data/data/com.termux/files/home/buninu-build
-cd /data/data/com.termux/files/home/buninu-build
-
-export PATH=$HOME/.bun/bin:$PATH
-
+mkdir -p buninu-build
+cd buninu-build
 bun x buninu-linux --version
-
-# Debian/Ubuntu
 bun x buninu-linux -fb --real --export
-
-# Alpine
-export BUNINU_JS_CPIO=1
-export BUNINU_JS_UKI=1
-bun x buninu-linux -fb --real --export
-
 ```
 
 `--export` copies the completed `vda.img` out of bunx's package directory and
@@ -122,35 +103,86 @@ command when writing the USB drive.
 
 #### Or build from a source checkout
 
-In native Termux:
-
-- git clone https://github.com/jjtseng93/buninu-linux.git ~/buninu-linux
+With Git and Bun available:
 
-In Debian 13 under PRoot:
+```sh
+git clone https://github.com/jjtseng93/buninu-linux.git buninu-linux
+cd buninu-linux
+bun ./index.js -fb --real --export
+```
 
-- apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
-- cd /data/data/com.termux/files/home/buninu-linux
-- bun ./index.js -fb --real --export
-  * Fetches from Alpine/Bun
-  * Selects the physical-hardware modules
-  * Builds `vda.img`
-  * Exports it to `buninu-linux-<version>.img`
+This fetches the pinned Alpine/Bun/npm inputs, selects the physical-hardware
+modules, builds `vda.img`, and exports `buninu-linux-<version>.img`.
 
 #### Write the image to a USB drive
 
-Write the complete exported image (or `vda.img` when not using `--export`), not
-the FAT partition inside it, to a USB drive. The source filename below is an
-example; replace it with the exact name printed by the build. The destination
-is also only an example: identify the correct whole-disk device first, because
-this overwrites it completely.
+The recommended method is **Ventoy**: install it on the USB drive once using
+a Windows or Linux computer, then copy image files onto it from Android,
+Linux, macOS or Windows. For later builds, simply copy the new `.img` file
+onto the same drive; there is no need to flash or reformat it each time.
+You can keep multiple images and choose one from Ventoy's boot menu.
+
+On Android, first make the exported image accessible to your file manager.
+Run `termux-setup-storage` and accept the storage permission prompt, or allow
+Termux to manage all files in Android's app settings if that option is
+available. From the directory containing the exported image, copy it to
+Download:
+
+```sh
+termux-setup-storage
+cp buninu-linux-*.img /sdcard/Download/
+```
+
+Use the complete exported `.img` (or `vda.img` when not using `--export`),
+not the FAT partition inside it. Replace the example filename below with the
+exact name printed by the build.
+
+**Android / Termux: copy to a prepared Ventoy drive.** Ordinary non-root
+Android/Termux cannot directly access a USB block device with `dd`; PRoot
+does not grant that access either. One option is to install
+[Ventoy on the USB drive using a Windows or Linux computer](https://www.ventoy.net/en/doc_start.html)
+first, then connect it to Android via USB OTG and use a file manager to copy
+the `.img` onto Ventoy's data partition. Safely eject it, boot the target PC from the USB
+drive, and select the image in Ventoy's menu. Ventoy supports `.img` files;
+no extraction or renaming to `.iso` is needed.
+
+---
+
+Installing Ventoy initially erases the selected USB drive. Later copying an
+image file onto it does not require reformatting. Do not use `dd` or Rufus
+on that drive if you want to preserve its Ventoy installation.
+
+Choose either Ventoy or direct image writing, not both. If you used Ventoy,
+skip the Linux/macOS/Windows direct-write methods below and continue to
+[Booting from the USB drive](#booting-from-the-usb-drive).
+
+**Linux: write directly with `dd`.** Identify the USB drive with `lsblk` and
+unmount its mounted partitions first. `/dev/sdX` below means the whole disk,
+not a partition such as `/dev/sdX1`. This overwrites the destination disk,
+including its partition table and existing files; check the device carefully.
 
 ```sh
 sudo dd if='buninu-linux-<version>.img' of=/dev/sdX bs=4M conv=fsync status=progress
 ```
 
-Alternatively, copy the exported `.img` file to a
-[Ventoy](https://www.ventoy.net/en/index.html) USB drive and select it from
-Ventoy's boot menu.
+**macOS: write directly with `dd`.** Use `diskutil list` to identify the USB
+drive, then substitute its actual disk number for `N` below. The same
+whole-disk overwrite warning applies. Use macOS's `bs=4m` spelling; press
+`Ctrl-T` during the copy to request progress.
+
+```sh
+diskutil list
+diskutil unmountDisk /dev/diskN
+sudo dd if='buninu-linux-<version>.img' of=/dev/rdiskN bs=4m
+sync
+diskutil eject /dev/diskN
+```
+
+**Windows: write with [Rufus](https://rufus.ie/).** Rufus supports raw `.img`
+disk images, not just ISO files (see its [official FAQ](https://github.com/pbatard/rufus/wiki/FAQ#openbsd)).
+Select the correct USB device, select the exported `.img` as the boot image,
+and start writing. Use DD/raw-image mode if prompted. This overwrites the
+selected USB drive; no conversion to `.iso` is needed.
 
 #### Booting from the USB drive
 
@@ -181,6 +213,17 @@ cfg.sound     // all packaged ALSA sound modules and detected sound devices
 start()
 ```
 
+Once `start()` opens the Buninu shell, run:
+
+```sh
+bunterm 2
+```
+
+This opens the graphical terminal on virtual console 2 and switches to it.
+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
 shutdown. After editing the initramfs, `bun ./index.js -b --real --export` rebuilds the
@@ -193,6 +236,11 @@ image; `-h` lists all flags.
 > an image for real x86-64 UEFI hardware, follow [Quick start](#quick-start)
 > above and use `-fb --real --export`.
 
+The commands in this section assume you have cloned the source and changed
+into its directory, as in [Or build from a source checkout](#or-build-from-a-source-checkout).
+You do not need to run that section's `--real` build first. Bun must be on
+`PATH`; install QEMU as shown below.
+
 The same `index.js` builds and boots Buninu Linux in QEMU on a Mac or Linux
 host. `--arch` picks the guest:
 
@@ -208,15 +256,15 @@ host. `--arch` picks the guest:
 
 #### macOS
 
-This project does not currently support a native macOS build toolchain (GNU
-cpio and tar, `fakeroot`, `parted`, PE-aware binutils), so on a Mac `index.js`
-always runs the fetch and build stages in a Debian 13 container built from
+The default JS tools build directly on macOS with host Bun, without Docker.
+If you opt out with `BUNINU_JS_TOOLS=0`, `index.js` runs the shell fetch and
+build stages in a Debian-based `oven/bun:1.4.2` container built from
 [`Dockerfile`](Dockerfile), with the checkout bind-mounted. The image is built
 on first use and tagged with a hash of the Dockerfile. Only the run stage uses
-the Mac itself:
+the Mac itself in that shell-tools mode:
 
 ```sh
-# Docker Desktop (running) for -f/-b, QEMU and its UEFI firmware for -r
+# Host Bun for -f/-b; QEMU and its UEFI firmware for -r
 brew install qemu
 
 # Apple Silicon: Hypervisor.framework accelerates the aarch64 guest
@@ -234,19 +282,20 @@ To run `bunterm` in a QEMU window on the aarch64 guest, see
 
 #### amd64 Linux
 
-On Debian or Ubuntu the build runs on the host exactly as in PRoot, and QEMU
-uses KVM for the x86_64 guest when the user can open `/dev/kvm`:
+On Debian or Ubuntu, the default JS build needs host Bun, not the native
+build toolchain. QEMU uses KVM for the x86_64 guest when the user can open
+`/dev/kvm`. Install QEMU and its firmware, then build and boot:
 
 ```sh
-apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
-apt install qemu-system-x86 ovmf
+sudo apt install qemu-system-x86 ovmf
 bun ./index.js -fbr
 ```
 
-Pass `--docker` to build in the same container as macOS instead of installing
-the build packages; the aarch64 guest additionally needs
-`binutils-aarch64-linux-gnu` for a host build and `qemu-system-arm
-qemu-efi-aarch64` to run.
+To run an aarch64 guest, additionally install `qemu-system-arm` and
+`qemu-efi-aarch64`. Cross-binutils are not needed for the default JS build.
+For the optional [old shell build](#old-build-shell-tools), install its native
+toolchain (including `binutils-aarch64-linux-gnu` for aarch64), or set
+`BUNINU_JS_TOOLS=0` and pass `--docker` to use the build container instead.
 
 #### What differs on aarch64
 
@@ -290,9 +339,9 @@ qemu-efi-aarch64` to run.
 #### Testing on a Linux host in Docker
 
 `test/host/host-test.sh` checks the Linux-host path from any machine with
-Docker: it starts a fresh Debian 13 container of the chosen CPU with the
+Docker: it starts a fresh `oven/bun:1.4.2` container of the chosen CPU with the
 build packages above and QEMU, clones the committed `HEAD` of this checkout,
-builds both guests with that toolchain (not `--docker`) and boots each one,
+builds both guests with Bun and the default JS tools (not nested `--docker`) and boots each one,
 driving the serial console through `test/host/boot-test.exp`:
 
 ```sh
@@ -546,25 +595,25 @@ For Chinese input, run the pinyin input method
 that is not inside a chroot, so it uses Buninu's `xclip`:
 
 ```sh
-bun x @drxiaozhi/jspinyin
+jspinyin
 ```
 
 - jspinyin → casty: press `Ctrl-C` in jspinyin to copy its result box, then
-  `Ctrl-V` in casty pastes it through OSC 52.
+  `Ctrl-V` or `Ctrl-E paste` in casty pastes it through OSC 52.
 - casty → jsmdcui / jspinyin: `Alt-C` in casty copies the selection through
   OSC 52, and `Ctrl-V` pastes it in jsmdcui or jspinyin, since jsmdcui reads
   from `xclip` first by default.
 
 ### Playing YouTube with sound (experimental)
 
-[jspulse](https://www.npmjs.com/package/@drxiaozhi/jspulse) is a
+[jspulse](https://github.com/jjtseng93/jspulse), now a built-in, is a
 PulseAudio-compatible sound server written for Bun. It runs natively in
 Buninu, outside any chroot, and plays through ALSA. Chromium-based programs
 such as `casty` inside the Debian chroot connect to it over `127.0.0.1`,
 because a chroot shares Buninu's network. Several programs can play at once.
 
 This assumes the Debian chroot and `casty` from
-[Commands inside /bin](#commands-inside-bin) are already set up, with the
+[Debian and Chromium with casty](#debian-and-chromium-with-casty) are already set up, with the
 chroot shell on tty2. `bun x` needs network access; see
 [Basic configuration](#basic-configuration).
 
@@ -593,15 +642,18 @@ chroot shell on tty2. `bun x` needs network access; see
    the percentage afterwards if it is too quiet or too loud:
 
    ```sh
-   bun x @drxiaozhi/jspulse --volume 50
-   bun x @drxiaozhi/jspulse --play
+   jspulse --volume 50
+   jspulse --play
    ```
 
 4. **Start the sound server.** It keeps running in the foreground, so leave
    this terminal as it is; `Ctrl+C` stops it:
 
    ```sh
-   bun x @drxiaozhi/jspulse --alsa
+   jspulse --alsa
+   
+   # or start in the background
+   jspulse --alsa &
    ```
 
 5. **Start casty with sound.** Press `Ctrl+Alt+F2` to return to the chroot
@@ -613,6 +665,18 @@ chroot shell on tty2. `bun x` needs network access; see
    bun casty.js https://www.youtube.com
    ```
 
+   Alternatively, the built-in `buninu-browser` runs directly in a native
+   Buninu `bunterm`, outside the chroot, and uses the same running jspulse
+   server. It is still in an early experimental stage, but can play an
+   individual video, for example:
+
+   ```sh
+   buninu-browser https://youtu.be/jf-pn0a-Twk
+   ```
+
+   Playback may still fail or be unstable; this does not imply full YouTube
+   compatibility.
+
 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.
 
@@ -621,6 +685,9 @@ If there is no sound, check step 4's terminal for errors, and make sure
 | command | does | manual |
 | --- | --- | --- |
 | `buninu-linux-help` | render this buninu-linux README from `/usr/share/doc/buninu-linux/README.md` | `buninu-linux-help` |
+| `buninu-browser` | early-stage, experimental JavaScript/WASM browser with the bundled casty terminal frontend; not yet a general-purpose browser replacement | `buninu-browser --help` |
+| `jspulse` | PulseAudio-compatible audio server and ALSA mixer controls; use `--alsa` on Buninu Linux | `jspulse --help` |
+| `jspinyin` | Chinese pinyin input panel, opened with the system jsmdcui in TUI mode; not a system-wide input method | — |
 | `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` |
@@ -629,12 +696,46 @@ If there is no sound, check step 4's terminal for errors, and make sure
 | `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` |
+| `gzip`, `gunzip`, `zcat` | compress or decompress gzip files, including decompression to stdout | `gzip --help` |
+| `unzip` | list or extract ZIP archives, or write a member to stdout with `-p` | `unzip --help` |
+| `truncate` | resize files, including sparse files | `truncate --help` |
+| `dd` | copy blocks between files with offsets, size limits and sparse-output support | `dd --help` |
+| `mkfs.fat` | format a FAT32 filesystem in a disk image | `mkfs.fat --help` |
+| `mmd`, `mcopy`, `mdir` | create directories, copy files and list contents in a FAT image without mounting it; use `-i IMAGE` and `::/path` | — |
+| `parted` | create and inspect GPT partitions in a disk image; script-mode subset | `parted --help` |
 | `stripansi` | remove ANSI escape sequences from stdin, `-`, or one or more files and concatenate the results | — |
 | `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 twelve commands
-implemented as Bun scripts.
+Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes the commands
+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).
+
+### Buninu Browser (early-stage, experimental)
+
+`buninu-browser` is still in an early stage. Websites may render incorrectly
+or fail to load or play media; it is not yet a general-purpose browser
+replacement. Run it inside `bunterm` (or another Kitty-graphics terminal).
+The browser and casty are bundled; these commands do not install them from npm.
+
+```sh
+# Open the Buninu website (requires network access)
+buninu-browser buninu.org
+
+# Open the browser's built-in audio test page
+buninu-browser about:audio
+```
+
+For audio output, first load sound drivers with `cfg.sound` at the PID 1
+REPL, then run `jspulse --alsa` in another terminal or use `jspulse --alsa &` to run in the background. In the browser terminal:
+
+```sh
+buninu-browser about:audio
+```
+
+### Archive tools and other examples
 
 The small `tar` reads the archive's own headers for links and listing, so
 extraction restores directories, hard links and every symbolic link —
@@ -644,7 +745,7 @@ only regular files. Creation still follows the `Bun.Archive` boundary: it
 stores regular files but not Unix metadata, links, or empty directories. It
 supports gzip and Bun's built-in zstd, not xz or bzip2.
 
-- `--help` renders each Markdown manual in the terminal.
+- Where provided, `--help` shows the command's help or renders its Markdown manual.
 - The `bun x` examples below require network access: 
   * `bun x` downloads the requested program from the npm registry and runs it without installing it permanently. 
   * If they fail the 1st time, try `bun pm cache rm`
@@ -668,6 +769,57 @@ bun x bunproot --git --readme | stripansi | jmi
 
 
 
+ip link set eth0 up
+ip addr add 192.168.1.50/24 dev eth0
+ip route add default via 192.168.1.1
+
+ip -br addr && ip route
+ip addr replace 192.168.1.50/24 dev eth0
+ip route replace default via 192.168.1.1
+
+ps -eo pid,args
+ps -ef
+ps aux
+pspac
+top
+top -b -n 1
+
+poweroff
+reboot
+
+tar cvf /tmp/buninu.tar README.md package.json
+tar tvf /tmp/buninu.tar
+mkdir -p /tmp/buninu-copy
+tar xvf /tmp/buninu.tar -C /tmp/buninu-copy
+
+# Add z to create a gzip-compressed archive
+tar czvf /tmp/buninu.tar.gz README.md package.json
+
+# On another virtual console: a graphical terminal with CJK, emoji and images
+bunterm 2
+bunterm /dev/tty3 --font-size 13 -e bun /buninu/apps/jsmdcui/src/index.js --demo
+```
+
+The graphics stack behind `bunterm` — the framebuffer module, CanvasKit,
+the fonts and the terminal — is described in [graphics.md](graphics.md).
+
+## Optional chroot and native binaries
+
+These optional examples download and run native Linux binaries, including
+Debian/Alpine utilities and Chromium. They are outside Buninu Linux's
+JS/WASM userspace-tooling approach and are not part of its default bundled
+applications. Skip this section if you want to use only the JS/WASM tools.
+The built-in `chroot` command itself is a Bun script; programs run inside
+the selected root filesystem need not be JavaScript or WebAssembly.
+
+A chroot shares the host kernel and is not a security sandbox. Use trusted
+root filesystems and software. Downloads require network access. The
+Debian and Alpine examples below target x86-64; chroot does not emulate
+another CPU architecture.
+
+### Debian and Chromium with casty
+
+```sh
 # Download and enter an x64 Debian rootfs
 # Make sure you have run this already:
 #   bunterm 2 --font-size 13
@@ -681,29 +833,25 @@ apt update
 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
+# The original casty is
+#   @sanohiro/casty
 # below is a fork of mine
-# fixing some issues
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
-# !!!Use at your own risk!!!
+# fixing some issues and adding functions
 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
+
 bun casty.js buninu.org
 # For sound in casty (YouTube), start jspulse first:
 # see "Playing YouTube with sound (experimental)" under "Using Buninu Linux"
+```
+
+For audio setup, see
+[Playing YouTube with sound (experimental)](#playing-youtube-with-sound-experimental).
 
+### Alpine minirootfs
 
+```sh
 # Download and enter an x64 Alpine minirootfs
 bun x bunproot --download-alpine-x64
 mkdir alpine
@@ -712,52 +860,24 @@ tar xvf ../alpine-minirootfs-*-x86_64.tar.gz
 cp $(which bun) bin
 chroot .
 apk add libgcc libstdc++
+```
 
+### An existing root filesystem
 
+```sh
 # Enter a root filesystem on a disk. /proc, /sys, /dev, /dev/pts, /run, /tmp
 # and /etc/resolv.conf are mounted for you and removed again on exit
 chroot /mnt
 chroot /mnt /bin/bun --version
 chroot -n /mnt /bin/sh        # traditional: mount nothing
-
-
-
-ip link set eth0 up
-ip addr add 192.168.1.50/24 dev eth0
-ip route add default via 192.168.1.1
-
-ip -br addr && ip route
-ip addr replace 192.168.1.50/24 dev eth0
-ip route replace default via 192.168.1.1
-
-ps -eo pid,args
-ps -ef
-ps aux
-pspac
-top
-top -b -n 1
-
-poweroff
-reboot
-
-tar cvf /tmp/buninu.tar README.md package.json
-tar tvf /tmp/buninu.tar
-mkdir -p /tmp/buninu-copy
-tar xvf /tmp/buninu.tar -C /tmp/buninu-copy
-
-# Add z to create a gzip-compressed archive
-tar czvf /tmp/buninu.tar.gz README.md package.json
-
-# On another virtual console: a graphical terminal with CJK, emoji and images
-bunterm 2
-bunterm /dev/tty3 --font-size 13 -e bun /buninu/apps/jsmdcui/src/index.js --demo
 ```
 
-The graphics stack behind `bunterm` — the framebuffer module, CanvasKit,
-the fonts and the terminal — is described in [graphics.md](graphics.md).
-
 ## Environment and dependencies
 
+The default JS build uses host Bun. The native build-tool dependencies below
+apply to the [old shell build](#old-build-shell-tools), the optional Docker
+shell toolchain, and the separate native hello-world example.
+
 ### Build environment
 
 The baseline is the stock Debian 13 (trixie) OCI image, which is also what this
@@ -825,6 +945,82 @@ The retired `test/build-init-bootstrap.sh` also needs `clang lld`. It compiles
 the historical freestanding x86-64 `/init`; the current Buninu Linux path does
 not use or compile it.
 
+## Old build (shell tools)
+
+These are the previous native-toolchain build instructions, retained as an
+optional alternative to the default JS tools. Set `BUNINU_JS_TOOLS=0`
+explicitly to use them. The documented environment is Debian 13 under Termux
+PRoot or a regular Debian/Ubuntu installation; the Alpine route is experimental.
+Missing shell build tools are reported before the selected stages run.
+
+- For a source checkout, clone into the Termux home so native Termux and PRoot
+  can share it; `~` differs between them, but the absolute path is the same.
+- Before anything, install Bun in Debian/Alpine first:
+
+```sh
+# Debian/Ubuntu
+apt update
+apt install curl unzip
+
+# Alpine
+apk update
+apk add curl unzip bash libgcc libstdc++
+
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Old build directly with bun x
+
+Install the build tools, enter a directory where you want to keep the
+finished image, then run the published package:
+
+```sh
+# Debian/Ubuntu
+apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
+
+# Alpine
+apk add bash coreutils tar curl unzip parted dosfstools mtools libgcc libstdc++
+
+mkdir -p /data/data/com.termux/files/home/buninu-build
+cd /data/data/com.termux/files/home/buninu-build
+
+export PATH=$HOME/.bun/bin:$PATH
+export BUNINU_JS_TOOLS=0
+
+bun x buninu-linux --version
+
+# Debian/Ubuntu
+bun x buninu-linux -fb --real --export
+
+# Alpine: use JS for cpio and UKI assembly within the shell pipeline
+export BUNINU_JS_CPIO=1
+export BUNINU_JS_UKI=1
+bun x buninu-linux -fb --real --export
+```
+
+`--export` copies the completed `vda.img` out of bunx's package directory into
+the invocation directory as `buninu-linux-<version>.img`.
+
+### Old build from a source checkout
+
+In native Termux:
+
+```sh
+git clone https://github.com/jjtseng93/buninu-linux.git ~/buninu-linux
+```
+
+In Debian 13 under PRoot:
+
+```sh
+apt install binutils-mingw-w64-x86-64 cpio curl dosfstools fakeroot mtools parted unzip
+cd /data/data/com.termux/files/home/buninu-linux
+BUNINU_JS_TOOLS=0 bun ./index.js -fb --real --export
+```
+
+This fetches the pinned inputs, selects the physical-hardware modules, builds
+`vda.img`, and exports `buninu-linux-<version>.img`. Continue with
+[Write the image to a USB drive](#write-the-image-to-a-usb-drive).
+
 ## Implementation details
 
 ### 1. Hello world
@@ -862,12 +1058,19 @@ it too). Its physical-image stages run as fetch → build:
 
 #### Build flags
 
+Fetch and build default to JS tools. Host Bun is required for npm extraction.
+Only `BUNINU_JS_TOOLS=0`, `off` or `false` disables this route (case-insensitive,
+with surrounding whitespace ignored); unset or empty values keep it enabled.
+JS tools bypass Docker, even with `--docker`. To use the container toolchain,
+run `BUNINU_JS_TOOLS=0 bun index.js -fb --docker`. The run stage still uses
+`run-qemu.sh` and host QEMU.
+
 | flag | runs | use it when |
 | --- | --- | --- |
-| `-f`, `--fetch` | `fetch-alpine.sh`, `fetch-bun.sh` | first clone, or after bumping a pinned version |
-| `-b`, `--build` | `build-uki.sh`, `build-image.sh` | after editing `initramfs/init.js` or the kernel command line |
+| `-f`, `--fetch` | `scripts/fetch.js` by default; shell route: `fetch-alpine.sh`, `fetch-bun.sh`, `fetch-npm.sh` | first clone, or after bumping a pinned version |
+| `-b`, `--build` | `scripts/build.js` by default; shell route: `build-uki.sh`, `build-image.sh` | after editing `initramfs/init.js` or the kernel command line |
 | `--arch ARCH` | explicitly selects `x86_64` (default for fetch/build) or `aarch64`; a bare `-r` detects the last built UKI | building or running a particular guest architecture |
-| `--docker` | `-f`/`-b` inside the container from `Dockerfile` (always on macOS) | no Debian toolchain on the host |
+| `--docker` | with JS tools disabled, `-f`/`-b` inside the container from `Dockerfile` (automatic on macOS in shell mode) | use the shell toolchain without installing it on the host |
 
 `--export` is a post-build option: after `-b` finishes, it copies `vda.img` to
 the directory where the command was invoked as
@@ -892,9 +1095,10 @@ its own.
 
 ```text
 index.js                  entry point: -f / -b / -r / --arch / --docker / --export / --linux-lts / --real
-Dockerfile                the Debian 13 build toolchain for --docker (and macOS)
+Dockerfile                Debian-based oven/bun:1.4.2 plus the shell build toolchain
 fetch-alpine.sh           [fetch]  kernel, EFI stub, musl, network/input/display modules
 fetch-bun.sh              [fetch]  Bun, libstdc++, libgcc
+fetch-npm.sh              [fetch]  pinned browser, casty, jspulse and jspinyin tarballs (download only)
 build-uki.sh              [build]  UKI; calls scripts/pack-initramfs.sh
 build-image.sh            [build]  GPT disk image; shared with the hello-world EFI
 run-qemu.sh               [run]    QEMU q35 (x86_64) or virt (aarch64), KVM/HVF/TCG
@@ -908,7 +1112,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.54-r0`, musl `1.2.6-r2`,
+The `--real` inputs are Alpine v3.24 `linux-lts-6.18.55-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
@@ -922,6 +1126,70 @@ 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 four application packages are pinned separately in
+`scripts/npm-packages.md`: `buninu-browser@0.2.2`,
+`@drxiaozhi/casty@1.3.4`, `@drxiaozhi/jspulse@0.2.1`, and
+`@drxiaozhi/jspinyin@0.1.1`. These were npm's `latest` versions when checked
+on 2026-10-11; 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.
+
+The manifest uses fixed YAML-compatible blocks: a double-quoted
+`"package@version":` header, followed by two `  - ` lines containing the
+registry URL and `sha256:HEX`. Blank lines and `#` comments are allowed.
+The `.md` extension lets `bun scripts/npm-packages.md` display the list.
+Bun parses it with `Bun.YAML.parse`; Node and shell also support the same
+strict format without installing a YAML parser. Cache filenames are derived
+from the package name and version, preserving the existing cache names.
+
+Both fetch routes download them directly from `registry.npmjs.org` into
+`downloads/npm/`, shared by x86_64 and aarch64, and verify the pinned SHA-256
+on cache hits as well as downloads. No npm/Bun package installation,
+lifecycle scripts or dependency resolution runs during fetch.
+
+At pack time, `scripts/stage-npm.js` (JS tools) or `scripts/stage-npm.sh`
+(shell tools) rechecks SHA-256 and extracts each archive with one leading
+component removed into the staging tree's `/usr/lib/node_modules/<package>`.
+Scoped names retain their `@scope/name` directories. No install scripts or
+dependency resolution run. JS extraction uses the initramfs JS `tar` and
+requires a host Bun; shell/Docker extraction uses the host `tar`, without Bun.
+The source `initramfs/` and project `package.json` are not modified by packing.
+
+The image gets `/usr/lib/package.json` with the four exact dependencies and
+standard `node_modules/.bin` links. This reserves a normal package-manager
+layout for later `cd /usr/lib` and `bun i --backend=copyfile`; no lockfile is
+fabricated. `bun i` alone retains the pinned versions, not newer releases.
+Persistence across boots and a package-update command are not implemented here.
+
+Only `buninu-browser` excludes `package/usr/lib/canvaskit` and
+`package/usr/share/fonts` when unpacked; `usr/README.md` and other contents
+are retained. The distribution's
+`/bin/buninu-browser` launcher creates missing resource directories and relative
+links on startup: package `usr/lib/canvaskit` points to `/lib/canvaskit`, and
+package `usr/share/fonts` points to `/usr/share/fonts`. Existing resources are
+left untouched, including resources restored by a later npm installation.
+The launcher runs the packaged casty directly, without `bunx`/`npx` downloads;
+other frontends/options are delegated to the package launcher. Use this
+distribution command for resource setup; calling the npm entry directly
+bypasses the hook. The extracted packages are otherwise unmodified, including
+their license/source files. This step does not start services or integrate
+jspinyin into the terminal.
+
+`/bin/jspulse` directly imports its installed package entry from
+`/usr/lib/node_modules`. `/bin/jspinyin` instead starts the system jsmdcui
+at `/buninu/apps/jsmdcui/src/index.js` with `--tui`, passing the user's arguments followed
+by `/usr/lib/node_modules/@drxiaozhi/jspinyin/im.md`. It bypasses the upstream
+`bun x jsmdcui` launcher, so launching this command does not download jsmdcui.
+Both are small, executable JavaScript files, with no shell wrapper.
+Run `jspulse --alsa` or `jspinyin` from the terminal.
+
+To fetch only these application archives:
+
+```sh
+bun scripts/fetch-npm.js     # built-in fetch; also works with Node.js
+./fetch-npm.sh              # curl + sha256sum, including inside Docker
+```
+
 #### Build pipeline
 
 The primary `bun ./index.js -fb --real` pipeline runs the steps below in order;
@@ -934,6 +1202,7 @@ and copies the final `vda.img` to the invocation directory.
 | --- | --- | --- |
 | `fetch-alpine.sh` | Alpine CDN | `kernel/<arch>/vmlinuz-<flavor>`, `kernel/<arch>/linuxx64.efi.stub` (`linuxaa64.efi.stub`), `native/<arch>/lib/ld-musl-<arch>.so.1`, and the selected network, storage, input, power and filesystem modules under `native/<arch>/lib/modules/` with trimmed module indexes |
 | `fetch-bun.sh` | GitHub, Alpine CDN | `native/<arch>/bin/bun`, `native/<arch>/lib/{libc.musl-<arch>.so.1,libstdc++.so.6,libgcc_s.so.1}` |
+| `fetch-npm.sh` / `scripts/fetch-npm.js` | npm registry, fixed URLs and SHA-256 in `scripts/npm-packages.md` | `downloads/npm/*.tgz`; pack later extracts into `/usr/lib/node_modules` |
 | `scripts/pack-initramfs.sh` | `initramfs/`, then `native/<arch>/` over it | `build/initramfs.cpio.gz` |
 | `build-uki.sh` | that archive, kernel, stub | `build/cmdline`, `build/os-release`, `vda/EFI/BOOT/BOOTX64.EFI` (`BOOTAA64.EFI`) |
 | `build-image.sh` | `vda/EFI/BOOT/BOOTX64.EFI` (`BOOTAA64.EFI`) | `vda.img` |
@@ -1005,7 +1274,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.54-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.55-0-lts rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 Serial kernel logging is retained, while the final console makes
@@ -1029,7 +1298,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.54-0-virt rdinit=/bin/bun -- -e import('/init.js')
+console=tty0 console=ttyS0,115200 panic=0 PATH=/bin KERNEL_RELEASE=6.18.55-0-virt rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 Build and boot it with:
@@ -1146,7 +1415,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.54-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.55-0-lts rdinit=/bin/bun -- -e import('/init.js')
 ```
 
 The physical display (`tty0`) is the final console and therefore owns PID 1's
@@ -1282,11 +1551,20 @@ for the userspace session.
   * [Clipboard](#clipboard)
   * [Playing YouTube with sound (experimental)](#playing-youtube-with-sound-experimental)
 - [Commands inside /bin](#commands-inside-bin)
+  * [Buninu Browser (early-stage, experimental)](#buninu-browser-early-stage-experimental)
+  * [Archive tools and other examples](#archive-tools-and-other-examples)
+- [Optional chroot and native binaries](#optional-chroot-and-native-binaries)
+  * [Debian and Chromium with casty](#debian-and-chromium-with-casty)
+  * [Alpine minirootfs](#alpine-minirootfs)
+  * [An existing root filesystem](#an-existing-root-filesystem)
 - [Environment and dependencies](#environment-and-dependencies)
   * [Build environment](#build-environment)
   * [Buninu Linux (Section 2)](#buninu-linux-section-2)
   * [Hello world (Section 1)](#hello-world-section-1)
   * [Retired native bootstrap](#retired-native-bootstrap)
+- [Old build (shell tools)](#old-build-shell-tools)
+  * [Old build directly with bun x](#old-build-directly-with-bun-x)
+  * [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)
@@ -1325,7 +1603,19 @@ own third-party notices, listed at the end of [NOTICE.md](NOTICE.md).
 The repository also commits four third-party platform binaries per guest
 architecture under `native/<arch>/lib/`, and the built image redistributes
 several more. Each stays
-under its own terms, with the full texts in [`LICENSES/`](LICENSES/):
+under its own terms, with platform license texts in [`LICENSES/`](LICENSES/).
+
+The build also fetches four SHA-256-pinned npm releases and redistributes
+them under `/usr/lib/node_modules`: `buninu-browser`, `@drxiaozhi/casty`,
+`@drxiaozhi/jspulse` and `@drxiaozhi/jspinyin`. Their license and notice files
+remain inside their package directories. Exact download URLs and hashes are
+in [`scripts/npm-packages.md`](scripts/npm-packages.md); versions, upstream
+sources and installed notice/source locations are recorded in
+[NOTICE.md](NOTICE.md#npm-applications-fetched-and-redistributed-in-the-image).
+The project's MIT license does not replace those packages' licenses.
+In particular, jspulse and the browser's bundled wasmpeg/FFmpeg code carry
+LGPL obligations; retain their licenses and supplied source/rebuild material
+when redistributing the image.
 
 ### Bundled component licenses
 
@@ -1336,6 +1626,11 @@ under its own terms, with the full texts in [`LICENSES/`](LICENSES/):
 | 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.2 | MIT for its own code; bundled components have their own licenses | 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.4 | 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 |
 | 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 |