buninu-linux 0.3.1 → 0.4.0

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).

package/initramfs/bin/bunterm

@@ -0,0 +1,66 @@
+#!/bin/bun
+// bunterm — a graphical terminal emulator on the Linux framebuffer.
+
+import { showDocument } from "../lib/document.js";
+import { runTerminal } from "../lib/bunterm/terminal.js";
+
+const usage = () => {
+  console.error(`Usage:
+  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [-e command [argument...]]
+  bunterm -h | --help`);
+};
+
+const main = async () => {
+  const options = { argv: [] };
+  const arguments_ = process.argv.slice(2);
+  for (let index = 0; index < arguments_.length; index++) {
+    const argument = arguments_[index];
+    if (argument === "-h" || argument === "--help") {
+      await showDocument("bunterm");
+      return 0;
+    }
+    if (argument === "-e") {
+      if (index + 1 >= arguments_.length) {
+        usage();
+        throw new Error("-e needs a command");
+      }
+      options.command = arguments_[index + 1];
+      options.argv = arguments_.slice(index + 2);
+      break;
+    }
+    const valued = (name) => {
+      const value = argument.startsWith(`${name}=`) ? argument.slice(name.length + 1) : arguments_[++index];
+      if (value === undefined) {
+        usage();
+        throw new Error(`${name} needs a value`);
+      }
+      return value;
+    };
+    if (argument === "--font-size" || argument.startsWith("--font-size=")) {
+      options.fontSize = Number(valued("--font-size"));
+      if (!Number.isFinite(options.fontSize) || options.fontSize < 6) throw new Error("--font-size must be a number of at least 6");
+    } else if (argument === "--line-height" || argument.startsWith("--line-height=")) {
+      options.lineHeight = Number(valued("--line-height"));
+      if (!Number.isFinite(options.lineHeight) || options.lineHeight <= 0) throw new Error("--line-height must be a positive number");
+    } else if (argument === "--fb" || argument.startsWith("--fb=")) {
+      options.device = valued("--fb");
+    } else if (argument === "--no-blink") {
+      options.cursorBlink = false;
+    } else if (argument.startsWith("/dev/")) {
+      options.console = argument;
+    } else {
+      usage();
+      throw new Error(`unexpected argument: ${argument}`);
+    }
+  }
+  return runTerminal(options);
+};
+
+let status = 1;
+try {
+  status = await main();
+} catch (error) {
+  console.error(`bunterm: ${error?.message ?? error}`);
+}
+// A pending console read would otherwise keep the process alive.
+process.exit(status);

package/initramfs/buninu/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.4.15 - 2026-09-22
+
+### Changed
+
+- Sync jsgotty to 1.1.12
+  * Export `BunPtyBackend` from `gotty.js`, the PTY layer built on
+    `Bun.spawn({ terminal })`, so other programs can run a command on a
+    pseudo-terminal without their own FFI. Buninu Linux's `bunterm`, a
+    graphical terminal on the framebuffer, is its first user, together with
+    the already exported `KittyGraphicsParser`
+
+### Fixed
+
+- jsgotty: a chunked kitty graphics transfer whose first chunk names an
+  image id (`i=`) is now continued by later chunks that carry only `m=`, as
+  the protocol allows. Previously those chunks were treated as new anonymous
+  transfers, so the image never completed. jsgotty's own `showimg` repeats
+  the id in every chunk and was unaffected; `kitten icat`, timg, chafa and
+  similar clients were
+
+## 0.4.13 - 2026-09-22
+
+### Changed
+
+- Sync bunmsh to 0.3.9
+  * `Ctrl-U` removes and saves the text before the cursor; pressing it again
+    at the beginning of the line restores it. `Ctrl-K` independently toggles
+    the text after the cursor when at the end of the line
+  * Unquoted pathname patterns follow directory symbolic links used as
+    intermediate path components, as traditional shells do, so patterns such
+    as `/sys/class/net/*/device` pass through sysfs class links
+  * The fallback `ls`/`lsfancy` lists a glob's files as one listing instead
+    of one section per file, honors `--`, and follows a command-line symlink
+    to a directory
+- Sync jsmdcui to 0.19.2
+  * Pressing `Ctrl-W` twice quickly switches to the next tab like `Alt-T`
+    from either an editor or a terminal pane; at the rightmost tab, when every
+    tab holds only terminal panes, it opens a new editor tab instead of
+    cycling back
+
 ## 0.4.12 - 2026-09-20
 
 ### Fixed

package/initramfs/buninu/apps/jsgotty/gotty.js

@@ -1173,9 +1173,9 @@ class KittyGraphicsParser {
 
     if (control.m === "1") {
       this.transfers.set(key, existing);
-      if (!control.i && !control.I) {
-        this.implicitTransferKey = key;
-      }
+      //  Later chunks of a transfer only need m=; they continue the transfer
+      //  in progress whether or not its first chunk named an image id.
+      this.implicitTransferKey = key;
       return null;
     }
 
@@ -3314,6 +3314,7 @@ async function bootstrap() {
 
 module.exports.CursorStateTracker = CursorStateTracker;
 module.exports.KittyGraphicsParser = KittyGraphicsParser;
+module.exports.BunPtyBackend = BunPtyBackend;
 module.exports.webSocketOriginAllowed = webSocketOriginAllowed;
 
 if (require.main === module) {

package/initramfs/buninu/apps/jsgotty/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsgotty",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "description": "Share your terminal as a web application: A JavaScript rewrite of GoTTY",
   "license": "MIT",
   "bin": {

package/initramfs/buninu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun that runs across operating systems",
   "type": "module",
   "main": "./bin/init.js",

package/initramfs/init.js

@@ -341,6 +341,12 @@ const launchBunmsh = () => {
 
 const launchBuninu = () => {
 
+  console.log(`
+Type bunterm in bunmsh: Graphical Terminal
+  Shows Emojis, CJK chars
+  Supports Kitty Graphics Protocol
+`)
+
   const entry = `/buninu/bin/init.js`;
   console.log(`buninu: Starting ${entry} --local`);
   const shell = Bun.spawnSync([