buninu-linux 0.3.0 → 0.4.0

package/README.md

@@ -25,14 +25,18 @@
 
 ---
 
+- [Table of contents](#contents)
+- .
 - 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 drivers
+  * `cfg.net` loads common wired NIC and Android USB-tethering drivers
+  * Android phone USB tethering over RNDIS has been tested successfully, allowing Buninu Linux to access the Internet through an Android phone
   * IP addresses and routes are configured manually because the image does not yet include a DHCP client.
-  * The bundled `jmi` editor, `jsmdcui` app runtime, and local JavaScript execution also work.
+  * The bundled `jmi` editor, jsmdcui editor/terminal multitasking, and local JavaScript execution also work.
+  * The graphical terminal `bunterm` draws on the framebuffer with CJK, colour emoji and kitty images; see [Showing images](#showing-images)
 
 ---
 
@@ -130,20 +134,20 @@ whitespace-only line prints the welcome and current `cfg.*` getter list again.
 Load only the subsystem needed, then enter the Buninu shell:
 
 ```js
-cfg.net       // wired NIC drivers
+cfg.net       // wired NIC and Android USB-tethering drivers
 cfg.disk      // SATA/NVMe/USB storage drivers and detected block devices
 cfg.power     // battery, AC, button and thermal drivers
 start()
 ```
 
 There is no DHCP client yet; configure a detected wired interface with `ip` as
-described under [Real hardware](#real-hardware). Run `poweroff` for a synced
+described under [Basic configuration](#basic-configuration). Run `poweroff` for a synced
 shutdown. After editing the initramfs, `bun ./index.js -b --real --export` rebuilds the
 image; `-h` lists all flags.
 
-## Running
+## Using Buninu Linux
 
-### Real hardware
+### Basic configuration
 
 Real hardware is the primary target. Boot the USB drive with Secure Boot
 disabled unless you have signed the UKI yourself. The physical display and USB
@@ -157,7 +161,7 @@ cfg.disk
 cfg.power
 ```
 
-`cfg.net` loads the packaged wired-network drivers and prints detected
+`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()`:
 
@@ -178,6 +182,8 @@ mount -fv /dev/sda1 /mnt
 
 Run `poweroff` for a synced shutdown.
 
+### Editor quick start
+
 The bundled `jmi` terminal editor works without a network connection:
 
 ```sh
@@ -203,19 +209,140 @@ After leaving the editor with `Ctrl-Q`, run it locally:
 bun hlw.js
 ```
 
-- Sometimes `Enters` in some scenarios don't directly work; if that's the case, try `Ctrl-J` or `Ctrl-M`
+If `Enter` is not recognized in a particular terminal, try `Ctrl-J` or
+`Ctrl-M`.
+
+### Panes, terminals, and tabs
+
+`jmi` and jsmdcui can keep editors and terminal sessions open together. Press
+`Ctrl-E`, type `term`, and press `Enter` to open the default Buninu shell in a
+terminal pane. `term COMMAND` starts a specific command instead. Use `vsplit`,
+`hsplit`, or `tab` from the same `Ctrl-E` command prompt to create another
+editor pane or tab; each command optionally accepts a filename. From an editor
+pane, `Ctrl-T` is the direct shortcut for a new empty tab.
+
+#### Pane and tab controls
+
+| Input | Result |
+| --- | --- |
+| Click a pane | Focus that editor or terminal pane. |
+| `Ctrl-T` in an editor pane | Open a new empty tab. |
+| `Ctrl-W` once | Move to the next pane in the current tab, from either an editor or terminal pane. |
+| `Alt-T` | Move to the next tab. |
+| **`Ctrl-W` twice quickly** | **Important escape hatch:** move to the next tab like `Alt-T`, or create an editor tab when needed. See the detailed explanation below. |
+| `Esc` in a terminal pane | Close that terminal pane and return to its previous editor buffer |
+| `Ctrl-Q` or `Alt-Q` in an editor pane | Close the current editor UI. |
+
+**Why this escape hatch is important:** A terminal pane must forward almost every key combination unchanged to the
+shell or application running inside it. `Ctrl-W` is therefore the one
+multitasking escape key that jsmdcui intercepts: it lets you leave the active
+terminal without terminating the work inside it. Press it once to move to the
+next pane in the current tab. Press it twice quickly to move to the next tab.
+
+The double press is especially important in an all-terminal workspace. When
+the current tab is the rightmost tab and every existing tab contains only
+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:
 
-## Commands inside /bin
+```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
+graphical terminal on the framebuffer, and run the image commands inside it:
+
+```sh
+# Start the graphical terminal on this virtual console (or name one: bunterm /dev/tty1)
+bunterm
+
+# Show an image with the kitty graphics protocol (jsgotty --viu)
+showimg /buninu/icon.png
 
-Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes four commands
-implemented as Bun scripts:
+# Render README.md with glow, then show icon.png
+buninu-help
+
+# Markdown view with its images in place
+# cfg.net first to show that GitHub image
+jsmdcui --allow-url README.md
+```
+
+`bunterm` draws with Skia (CanvasKit) and understands the kitty graphics
+protocol, so anything that speaks it — `showimg`, `jsmdcui`, `kitten icat`,
+`timg` — shows images, alongside CJK text and colour emoji. The cursor moves
+below a shown image, and images scroll with the text. When the program you
+started exits, the console returns to text mode. `bunterm --help` has the
+options; [graphics.md](graphics.md) describes how it is built. The image
+needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
+(the default `linux-virt` builds one only as modules the image omits).
+
+## Commands inside /bin
 
 | command | does | manual |
 | --- | --- | --- |
 | `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` |
+| `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` |
 | `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` |
+| `bunterm` | a graphical terminal on the framebuffer: Skia (CanvasKit) text with CJK, colour emoji, seamless box drawing, kitty graphics images; xterm.js's emulator core over Bun's built-in PTY | `bunterm --help` |
+
+Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes nine commands
+implemented as Bun scripts.
+
+The small `tar` follows the current `Bun.Archive` boundary: extraction
+restores directories and symbolic links, while hard links are skipped by Bun
+1.4.3. Creation stores regular files but not Unix metadata, links, or empty
+directories, and listing reports regular files only. It supports gzip and
+Bun's built-in zstd, not xz or bzip2.
 
 `--help` renders each Markdown manual in the terminal. Common examples:
 
@@ -224,6 +351,8 @@ mount /dev/sda1 /mnt --mkdir
 mount -fv /dev/sda1 /mnt
 mount -t tmpfs -o size=64M tmpfs /tmp/x
 mount -t ntfs3 -o force /dev/sda3 /mnt/windows
+umount /mnt
+umount -R /mnt
 
 ip link set eth0 up
 ip addr add 192.168.1.50/24 dev eth0
@@ -233,9 +362,32 @@ 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 a virtual console: a graphical terminal with CJK, emoji and images
+bunterm
+bunterm /dev/tty1 --font-size 20 -e bun /buninu/apps/jsmdcui/src/index.js --demo
 ```
 
+The graphics stack behind `bunterm` — the framebuffer module, CanvasKit,
+the fonts and the terminal — is described in [graphics.md](graphics.md).
+
 ## Environment and dependencies
 
 ### Build environment
@@ -340,6 +492,8 @@ bun ./index.js -fb --real --export
 `index.js` is the single entry point (`npm run fetch` and `npm run pack` call
 it too). Its physical-image stages run as fetch → build:
 
+#### Build flags
+
 | flag | runs | use it when |
 | --- | --- | --- |
 | `-f`, `--fetch` | `fetch-alpine.sh`, `fetch-bun.sh` | first clone, or after bumping a pinned version |
@@ -356,8 +510,8 @@ bun x buninu-linux -fb --real --export
 
 `--linux-lts` selects Alpine's general-purpose LTS kernel. `--real` implies
 `--linux-lts` and builds for physical hardware: it makes `tty0` the primary
-console and includes xHCI/USB HID, common wired network, storage and ACPI power
-modules needed by typical laptops and desktops.
+console and includes xHCI/USB HID, common wired NIC, Android USB-tethering,
+storage and ACPI power modules needed by typical laptops and desktops.
 
 For real hardware, `-fb --real` is the complete image pipeline and
 `-b --real` is the edit-and-rebuild loop. Before starting, `index.js` checks
@@ -396,6 +550,8 @@ The primary `bun ./index.js -fb --real` pipeline runs the steps below in order;
 each writes files the next one reads. When selected, `--export` runs afterward
 and copies the final `vda.img` to the invocation directory.
 
+##### Pipeline inputs and outputs
+
 | script | reads | writes |
 | --- | --- | --- |
 | `fetch-alpine.sh` | Alpine CDN | `kernel/vmlinuz-lts`, `kernel/linuxx64.efi.stub`, musl, and the selected network, storage, input, power and filesystem modules with trimmed module indexes |
@@ -423,6 +579,8 @@ boot.
 `build-uki.sh` appends sections to systemd's `linuxx64.efi.stub` with
 `objcopy`, at hand-picked VMAs because `objcopy` will not lay them out for you:
 
+##### UKI sections
+
 | section | offset from image base | contents | size |
 | --- | --- | --- | --- |
 | `.text` | +0x0 | the stub itself | 66 KB |
@@ -589,7 +747,7 @@ Which modules the image carries is the list in `fetch-alpine.sh`; the
 `select_module` helper there pulls in dependencies from Alpine's
 `modules.dep`, and `--real` adds common storage paths (`sd_mod`, `ahci`,
 `ata_generic`, `pata_acpi`, `nvme`, Intel `vmd`, `usb-storage` and `uas`),
-the wired NICs and the ACPI power drivers. Alpine's
+the wired NICs, Android USB-tethering drivers and the ACPI power drivers. Alpine's
 kernels build all of these as modules; a self-built kernel with them `=y`
 works the same way, the loaders just find nothing to load.
 
@@ -685,8 +843,10 @@ 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
 declared dependencies. `--real` ships Intel `e1000`/`e1000e`/`igb`/`igc`,
-Realtek `r8169`, Atheros `alx`, Broadcom `tg3` and the `r8152`/`ax88179_178a`/
-`cdc_ether` USB dongles. `cfg.power` loads the ACPI
+Realtek `r8169`, Atheros `alx`, Broadcom `tg3`, common USB dongles, and
+`rndis_host`/`cdc_ether`/`cdc_ncm`/`cdc_eem`/`cdc_subset`/`zaurus` for Android
+USB tethering. `cfg.net` unconditionally attempts all of these packaged
+network modules. `cfg.power` loads the ACPI
 `battery`, `ac`, `button` and `thermal` modules through `/lib/modprobe.js`
 and lists `/sys/class/power_supply` (a desktop without a battery simply
 reports nothing registered). Nothing loads them at boot. PID 1 also installs
@@ -694,12 +854,49 @@ reports nothing registered). Nothing loads them at boot. PID 1 also installs
 `Promise.reject()` at the prompt makes Bun exit, which is a kernel panic
 (`Attempted to kill init!`).
 
-The REPL exposes a global `bunmsh()` function. Calling it creates
-`/tmp/bunmsh-runtime`, installs the pinned `bunmsh@0.3.6` package there, and
-directly runs its `src/main.js` with a small explicit environment. The calls
-are synchronous so bunmsh exclusively owns the terminal until `exit` returns
-to the Bun REPL. `start()` launches Buninu with the current process environment
-preserved, while overriding `PATH` and `HOME` for the userspace session.
+`start()` launches the bundled Buninu userspace and its bunmsh (Bun Modern Shell) with
+the current process environment preserved, while overriding `PATH` and `HOME`
+for the userspace session.
+
+## Contents
+
+- [Quick start](#quick-start)
+  * [Steps](#steps)
+    + [Build directly with bun x](#build-directly-with-bun-x)
+    + [Or build from a source checkout](#or-build-from-a-source-checkout)
+    + [Write the image to a USB drive](#write-the-image-to-a-usb-drive)
+    + [Booting from the USB drive](#booting-from-the-usb-drive)
+- [Using Buninu Linux](#using-buninu-linux)
+  * [Basic configuration](#basic-configuration)
+  * [Editor quick start](#editor-quick-start)
+  * [Panes, terminals, and tabs](#panes-terminals-and-tabs)
+    + [Pane and tab controls](#pane-and-tab-controls)
+  * [Using Bun Modern Shell](#using-bun-modern-shell)
+  * [Showing images](#showing-images)
+- [Commands inside /bin](#commands-inside-bin)
+- [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)
+- [Implementation details](#implementation-details)
+  * [1. Hello world](#1-hello-world)
+  * [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)
+    + [UKI layout](#uki-layout)
+      - [UKI sections](#uki-sections)
+    + [Disk layout](#disk-layout)
+    + [Real-hardware boot details](#real-hardware-boot-details)
+    + [QEMU development](#qemu-development)
+      - [QEMU networking](#qemu-networking)
+    + [Command implementation](#command-implementation)
+    + [Reaching JavaScript with nothing mounted](#reaching-javascript-with-nothing-mounted)
+    + [What init.js does](#what-initjs-does)
+- [Authorship](#authorship)
+- [License](#license)
+  * [Bundled component licenses](#bundled-component-licenses)
 
 ## Authorship
 
@@ -721,6 +918,8 @@ The repository also commits four third-party platform binaries under
 `initramfs/lib/`, and the built image redistributes several more. Each stays
 under its own terms, with the full texts in [`LICENSES/`](LICENSES/):
 
+### Bundled component licenses
+
 | Component | License | Where |
 |---|---|---|
 | musl (`ld-musl-x86_64.so.1`, `libc.musl-x86_64.so.1`) | MIT | committed |
@@ -728,6 +927,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 |
+| 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 |
+| Noto Sans CJK, Noto Color Emoji (+ Flags), Noto Sans Symbols (`initramfs/usr/share/fonts/Noto*`) | SIL OFL 1.1 (`LICENSES/OFL-1.1.txt`) | committed |
+| Roboto (`initramfs/usr/share/fonts/Roboto-Regular.ttf`) | Apache-2.0 (`LICENSES/Apache-2.0.txt`) | committed |
 
 One component is worth naming here rather than leaving to be found: the two
 GCC runtime libraries are **GPL-3.0 with the GCC Runtime Library Exception**

package/fetch-alpine.sh

@@ -79,10 +79,15 @@ if [ "${REAL_MACHINE:-}" = 1 ]; then
         select_module "$module"
     done
     # Wired NICs: Intel (e1000/e1000e/igb/igc), Realtek (r8169 plus its PHY
-    # driver), Qualcomm Atheros (alx), Broadcom (tg3), and USB dongles
-    # (Realtek r8152, ASIX ax88179, CDC Ethernet). cfg.net in init.js
-    # matches them to hardware through the pci:/usb: lines of modules.alias.
-    for module in e1000 e1000e igb igc r8169 realtek alx tg3 r8152 ax88179_178a cdc_ether; do
+    # driver), Qualcomm Atheros (alx), Broadcom (tg3), and USB dongles.
+    # Android USB tethering commonly presents RNDIS, CDC ECM/NCM/EEM, or an
+    # older CDC subset/zaurus-compatible gadget. Selecting the leaf drivers
+    # recursively includes usbnet, mii, usbcore and usb-common from
+    # modules.dep. cfg.net unconditionally attempts every packaged
+    # kernel/drivers/net module, then matches USB and PCI modaliases.
+    for module in e1000 e1000e igb igc r8169 realtek alx tg3 \
+                  r8152 ax88179_178a cdc_ether rndis_host cdc_ncm cdc_eem \
+                  cdc_subset zaurus; do
         select_module "$module"
     done
 fi

package/graphics.md

@@ -0,0 +1,213 @@
+# The Buninu Linux graphics stack
+
+Buninu Linux draws on the screen without X11, Wayland, a GPU or any native
+graphics library: the Linux framebuffer is mapped into Bun, Skia (compiled to
+WebAssembly as CanvasKit) rasterizes into it, and `bunterm` puts an
+xterm-compatible terminal on top. Everything is JavaScript or WebAssembly
+except the kernel's `/dev/fb0`, reached through a few `ioctl`s and one `mmap`
+via Bun FFI.
+
+```
+ ┌──────────────────────────────────────────────────────────────────────┐
+ │ programs on a PTY:  bunmsh, jsmdcui, bun scripts, kitten icat …      │
+ └───────────────▲───────────────────────────────┬──────────────────────┘
+        keyboard │ (raw console bytes)            │ output bytes + kitty APC
+ ┌───────────────┴───────────────────────────────▼──────────────────────┐
+ │ /bin/bunterm  →  /lib/bunterm/terminal.js                             │
+ │   BunPtyBackend (jsgotty) ─ Bun.spawn({ terminal })    ← Bun's PTY    │
+ │   KittyGraphicsParser (jsgotty) ─ splits ESC _ G … ESC \ packets      │
+ │   @xterm/headless Terminal ─ VT parser, screen buffer, attributes     │
+ │   images.js ─ kitty placements as Skia images anchored to lines       │
+ │   input.js ─ /dev/ttyN raw mode, console→xterm key sequences          │
+ │   renderer.js ─ cells → glyphs (fonts) or vectors (glyphs.js)         │
+ └───────────────────────────────────────────────┬──────────────────────┘
+                                                 │ Skia draw calls
+ ┌───────────────────────────────────────────────▼──────────────────────┐
+ │ /lib/canvas.js  ─ CanvasKit 0.41.1 (Skia in wasm, /lib/canvaskit/)    │
+ │   openCanvas(): MakeRasterDirectSurface in the framebuffer's own      │
+ │   pixel format (BGRA_8888 / RGBA_8888 / RGB_565) inside the wasm heap │
+ │   loadFontSet(): /usr/share/fonts/fonts.json → Typefaces + FontMgr    │
+ └───────────────────────────────────────────────┬──────────────────────┘
+                                                 │ one memcpy per frame
+ ┌───────────────────────────────────────────────▼──────────────────────┐
+ │ /lib/fbdev.js  ─ Framebuffer: FBIOGET_*SCREENINFO, mmap, KDSETMODE    │
+ │   runGraphics(): graphics mode + restore on exit/signal               │
+ │   JS drawing (drawLine, fillPolygon …) and blitImageData() fallback   │
+ └───────────────────────────────────────────────┬──────────────────────┘
+                                                 │ ioctl / mmap (bun:ffi, /lib/dlopen.js)
+ ┌───────────────────────────────────────────────▼──────────────────────┐
+ │ Linux: /dev/fb0 (efifb / simpledrm from the UEFI GOP), /dev/ttyN      │
+ └──────────────────────────────────────────────────────────────────────┘
+```
+
+## Layers
+
+### 1. Framebuffer — `/lib/fbdev.js`
+
+`Framebuffer` opens `/dev/fb0`, reads the variable and fixed screen info
+(size, stride, bits per pixel, the red/green/blue bit offsets) and `mmap`s
+the device. Drawing goes to a JavaScript back buffer laid out exactly like
+the device; `flush()` copies it row by row into the mapping. Nothing draws
+straight into the mapping: on efifb the memory is write-combining, reads are
+very slow, and drawing there would tear.
+
+`runGraphics(draw)` wraps a graphical program: it switches the virtual
+console to `KD_GRAPHICS` (otherwise the kernel's text console keeps
+overwriting the screen), runs `draw`, and restores `KD_TEXT` whether the
+call returns, throws, exits, or is killed by a catchable signal. Given a
+specific `/dev/ttyN`, it `VT_ACTIVATE`s that console first and switches
+back to the previous one at the end; while drawing it takes `VT_PROCESS`
+mode, so Ctrl-Alt-Fn still switches consoles and `onAcquire` lets the
+program repaint when its console returns.
+
+Manual: `fbdev --help` / `initramfs/usr/share/doc/buninu-linux/fbdev.md`.
+
+### 2. Skia — `/lib/canvas.js` and `/lib/canvaskit/`
+
+CanvasKit is Google's Skia compiled to WebAssembly (the same npm package the
+browser uses). WebAssembly can only write its own linear memory, so Skia
+cannot draw into the `mmap` directly. Instead `openCanvas()` allocates a
+buffer in the wasm heap and creates a `MakeRasterDirectSurface` on it in the
+framebuffer's native pixel layout (`pickColorType()` maps the kernel's
+bitfields to `BGRA_8888` for the usual XRGB8888, or `RGBA_8888` /
+`RGB_565`). The `Framebuffer`'s `pixels` view is pointed at that buffer, so
+`flush()` is the same single `memcpy` as before and the JavaScript drawing
+functions keep working on the same frame. A 24-bit or paletted device falls
+back to CanvasKit's HTML-canvas emulation plus `blitImageData()`, which
+converts per pixel.
+
+Skia is CPU-only here (no GPU, no WebGL); the whole 1080p frame is a few
+milliseconds to copy and cells are cached by Skia's glyph cache. The wasm
+heap starts at 128 MiB and grows as fonts are loaded into it, which is why
+QEMU is now started with `-m 1G`.
+
+`loadFontSet()` reads `/usr/share/fonts/fonts.json` and builds the typefaces
+and a `FontMgr` for a named set (`terminal`, `ui`). Noto Sans CJK is a
+collection; the manager registers all five faces and the set's preferred
+face (`Noto Sans CJK TC`) is the one handed out, so Taiwanese glyph forms
+are used without relying on `locl`.
+
+Manual: `initramfs/usr/share/doc/buninu-linux/canvas.md`.
+
+### 3. Fonts — `/usr/share/fonts/`
+
+| File | Role | License |
+|---|---|---|
+| `DejaVuSansMono.ttf`, `-Bold.ttf` | terminal grid font: 0.6 em wide, 1.16 em tall, box drawing, arrows, `☐☒✓`, Braille-free but everything jsmdcui draws | Bitstream Vera |
+| `NotoSansCJK-Regular.ttc` | 32 MiB variable collection: JP/KR/SC/TC/HK faces, ~21 000 unified ideographs, ext. A, part of ext. B, kana, bopomofo, hangul, full-width forms | OFL 1.1 |
+| `NotoColorEmoji.ttf`, `NotoColorEmojiFlags.ttf` | CBDT bitmap colour emoji; Skia's FreeType port renders them in colour | OFL 1.1 |
+| `NotoSansSymbols-Regular-Subsetted.ttf`, `-Subsetted2.ttf` | arrows, math, geometric shapes, dingbats, Braille, musical symbols, cards | OFL 1.1 |
+| `Roboto-Regular.ttf` | variable Latin/Greek/Cyrillic for non-terminal UI (`ui` set) | Apache 2.0 |
+
+The Noto and Roboto files are the ones Android ships; DejaVu comes from
+Debian. Each license text sits next to the fonts and in `LICENSES/`.
+
+### 4. Terminal — `/bin/bunterm` and `/lib/bunterm/`
+
+`bunterm` reuses three finished components instead of writing a terminal
+from scratch:
+
+- **PTY**: jsgotty's `BunPtyBackend`, which is `Bun.spawn(cmd, { terminal:
+  { cols, rows, data, exit } })` — Bun's built-in pseudo-terminal, no
+  node-pty, no FFI. jsgotty now exports the class for this.
+- **Emulation**: `@xterm/headless`, the xterm.js core (VT parser, screen
+  and scrollback buffers, SGR attributes, terminal replies, markers) with
+  its DOM renderer removed. `@xterm/addon-unicode-graphemes` makes 🇹🇼,
+  ZWJ sequences and combining marks occupy one cell.
+- **Images**: jsgotty's `KittyGraphicsParser`, which splits the kitty
+  graphics APC packets out of the byte stream, reassembles chunked
+  transfers, inflates `o=z`, and produces placement / delete / query events
+  and the replies to send back. (Two small changes to the vendored jsgotty:
+  the export, and later chunks of a transfer whose first chunk named `i=`
+  now continue that transfer, as the protocol allows — to be carried back
+  to the jsgotty repository.)
+
+Around those, `/lib/bunterm/` adds:
+
+| File | Does |
+|---|---|
+| `renderer.js` | Paints `term.buffer` cell by cell. Cell size comes from DejaVu Sans Mono; every glyph is looked up in the regular font, then the fallbacks (colour emoji first for emoji-presentation code points, monochrome symbols first otherwise) and centred in its one or two cells; oversized fallback glyphs are scaled to fit. Multi-code-point graphemes are shaped by Skia's `Paragraph` and cached. Only rows whose content hash changed since the last frame, the cursor rows, and rows under moved images are repainted. 16/256/24-bit colour, bold (with bright base colours), italic, dim, underline, strikethrough, inverse, invisible. |
+| `glyphs.js` | Box drawing (U+2500–257F incl. double, dashed, rounded, mixed-weight), block elements and shades (U+2580–259F), Powerline (U+E0A0–E0BF) and legacy computing (U+1FB70–1FB97) drawn as Skia paths, so they meet seamlessly at any size. The shape tables are xterm.js's `CustomGlyphs.ts` (MIT); coordinates snap to pixel centres for crisp 1-px lines. |
+| `images.js` | Kitty placements: decodes PNG (`f=100`) with Skia or raw RGB/RGBA (`f=24/32`), with `Bun.Image` as a transcoder for other encodings; anchors each placement to an xterm marker so it scrolls with its line and disappears with it (on the alternate screen, where xterm.js issues no markers, to a fixed row that is dropped when that screen ends); sizes in cells (`c,r`) or from pixel size; crops (`x,y,w,h`), cell offsets (`X,Y`), `p=` placement ids, `a=d` deletion scopes, and the cursor move after a placement. |
+| `input.js` | Raw mode on the console (`TCGETS`/`TCSETS` through the shared libc binding) and translation of the kernel's "linux" key sequences to xterm's, honouring DECCKM. |
+| `terminal.js` | `createSession()` wires PTY → parser → emulator → renderer with a coalesced ~60 Hz frame timer and a serialized output queue, so a kitty packet always sees the cursor position left by the text before it. `runTerminal()` adds `runGraphics()` and the keyboard. |
+
+Manual: `bunterm --help` / `initramfs/usr/share/doc/buninu-linux/bunterm.md`.
+
+## Data flow of one frame
+
+1. The program writes to the PTY; Bun delivers the bytes to `BunPtyBackend`'s
+   `data` callback.
+2. `KittyGraphicsParser.consume()` returns plain-text runs and kitty packets
+   in order. Plain runs go to `term.write()` (awaited, so the buffer is
+   current); each packet is parsed with the cursor position at that point,
+   handed to `ImageStore`, and acknowledged back to the PTY if the client
+   asked.
+3. A frame is requested. Sixteen milliseconds later `Renderer.render()`
+   hashes each visible row, repaints the changed ones (background rect,
+   glyph or vector, underline), draws the cursor block, and re-draws the
+   parts of image placements that intersect the repainted rows.
+4. `screen.flush()` finishes Skia's work and copies the wasm-heap frame into
+   the `/dev/fb0` mapping.
+
+Keyboard bytes travel the other way: console → `input.js` → PTY. Terminal
+replies (cursor position, device attributes, kitty acks) go from the
+emulator straight to the PTY.
+
+## Sizes
+
+| Component | Raw | In the gzip initramfs |
+|---|---|---|
+| CanvasKit wasm + js | 7.3 MB | ~2.7 MB |
+| xterm headless + graphemes addon | 0.2 MB | ~0.05 MB |
+| Fonts | 39.9 MB | ~24 MB |
+| Total added | ~47 MB | ~27 MB |
+
+The initramfs grew from 44.7 MB to 71.8 MB compressed; the UKI is 84.5 MB and
+the 127 MB EFI system partition keeps 46 MB free. The initramfs is unpacked
+into RAM, and CanvasKit copies the fonts it uses into its heap, so the guest
+needs about 1 GB.
+
+## Trying it
+
+The framebuffer needs a kernel that provides one. Alpine's `linux-lts` has
+`CONFIG_FB`, `CONFIG_FB_EFI` and `CONFIG_DRM_SIMPLEDRM` built in; the default
+`linux-virt` builds them as modules, and the image ships only the network,
+storage, USB and HID modules, so there `/dev/fb0` never appears. Build with
+`./index.js -b --linux-lts` (or `--real`); under QEMU the lts kernel gets a
+1280×800 `simpledrm` framebuffer from the UEFI GOP even with `-display none`,
+and the monitor's `screendump` shows it. From a virtual console in the guest:
+
+```sh
+bunterm                                  # /bin/sh on this console
+bunterm /dev/tty1 --font-size 20         # from a serial console, use VT 1
+bunterm -e bun /buninu/apps/jsmdcui/src/index.js --demo
+bun /lib/fbdev.js                        # the plain-framebuffer triangle
+```
+
+To render off-screen on the build host (no framebuffer), give `openCanvas()`
+a plain object with `width`, `height`, `stride`, `bitsPerPixel`, `fields` and
+a `pixels` `Uint8Array`, replace `screen.flush`, and snapshot the surface —
+that is how the renderer and the kitty pipeline were tested during
+development (`BUNINU_LIBC=/lib/aarch64-linux-gnu/libc.so.6` lets `dlopen.js`
+load the host libc).
+
+Verified in QEMU (lts kernel, `-vga std`, 1 GB): the attribute/CJK/emoji
+sample, a kitty PNG placement, an interactive bunmsh with keys sent through
+the console, and the jsmdcui editor demo all render as on the host;
+`bunterm /dev/tty2` from the serial REPL switches the display to tty2 and
+back to tty1 on exit, and Ctrl-Alt-F2 / Ctrl-Alt-F1 during a session
+switch away and repaint on return. On the
+host, `jsmdcui --tui` on a Markdown file with a JPEG (bunterm sets
+`JSMDCUI_KITTY_MODE=extended` for the program it runs) places the image
+through its transmit / `a=p` / `a=d` sequence exactly as in the browser.
+
+## Not done yet
+
+- Mouse, selection and scrollback viewing in `bunterm`.
+- Kitty `z < 0` (images behind text), animation frames, Unicode
+  placeholders, and shared-memory transmission.
+- Text run shaping with ligatures for single-code-point cells (each cell is
+  one glyph; Paragraph shaping is only used for grapheme clusters).
+- Non-terminal UI on `canvas.js` (the `ui` font set and Roboto are there for
+  it).