buninu 0.4.6 → 0.4.7

package/README.md

@@ -1,29 +1,45 @@
 # Buninu
 
+**BUNinu Is Not Unix** 🐮
+
+**幫你牛** 🐂 ・ **Bunに入魂** 🔥
+
 ![icon](https://raw.githubusercontent.com/jjtseng93/buninu/main/icon.png)
 
-> **Early development:** Buninu is still at an early stage of development.
-> Features, configuration, and command-line behavior may change between releases.
-> Linux, Android, and Windows can run the current early implementation, but
-> their support and portability behavior are still being tested and refined.
+Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun. One
+command gives you a working shell — in a browser tab, or straight in the
+terminal you are already in — on Android, Linux, Windows, and macOS, with
+nothing to compile and nothing installed system-wide.
 
-- Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun that runs across operating systems
+```sh
+npx buninu
+```
 
-- It starts a browser-accessible terminal through jsgotty. The architecture is
-  designed for Android, Linux, and Windows.
+> **Status:** Buninu is still under active development. The browser
+> terminal, the install-and-update flow, and the bundled commands are the
+> settled parts — Android and Linux first, with Windows working the same way
+> and macOS support newer. Still moving: `package.json` settings and
+> command-line flags can change between releases, and the local shell
+> (`--local`, bunmsh) has no job control yet, so use the browser terminal when
+> you need to background a job.
 
-- Name expansions:
-  * English: **BUNinu Is Not Unix** 🐮
-  * 中文：**幫你牛** 🐂
-  * 日本語：**Bunに入魂** 🔥
+- Source: [github.com/jjtseng93/buninu](https://github.com/jjtseng93/buninu)
 
 - Core components:
   * [jsgotty](https://github.com/jjtseng93/js-gotty): Remote shell from a Browser or Terminal
-  * [jsmdcui](https://github.com/jjtseng93/jsmdcui): Both a text editor and Markdown execution runtime (not static rendering) based on [bunmicro](https://github.com/jjtseng93/bunmicro)
-  * [bunmsh](https://github.com/jjtseng93/bunmsh): Bun Modern Shell. Not completed yet
-
-See [ARCHITECTURE.md](ARCHITECTURE.md) for the complete architecture, portability model,
-and self-bootstrapping design.
+  * [jsmdcui](https://github.com/jjtseng93/jsmdcui): Both a text editor and
+    Markdown execution runtime (not static rendering), based on
+    [bunmicro](https://github.com/jjtseng93/bunmicro)
+  * [bunmsh](https://github.com/jjtseng93/bunmsh): Bun Modern Shell — a
+    dependency-free, mksh-inspired command shell with a JavaScript mode, and
+    builtins that answer the same way on Windows as on POSIX systems
+
+- [Why Buninu exists](#why)
+- [Table of contents](#contents)
+- [ARCHITECTURE.md](ARCHITECTURE.md): the complete architecture, portability
+  model, and self-bootstrapping design
+- [Commands inside the shell](#commands-inside-the-shell): the reference for a
+  session you are already in
 
 ## Install Bun
 
@@ -95,6 +111,14 @@ Drops you straight into [bunmsh](apps/bunmsh/README.md) (Bun Modern Shell), a
 dependency-free, mksh-inspired command shell that runs on Bun, without going
 through the browser/jsgotty flow.
 
+It is marked experimental for one reason above the rest: bunmsh has no job
+control yet. There is no `jobs`, `bg` or `fg`, and no suspending a command
+that is already running — a foreground command holds the terminal until it
+finishes on its own. Everything else a session needs is there: pipelines and
+redirection, functions and compound commands, history, completion with ghost
+suggestions, and a JavaScript mode. Reach for the browser terminal when you
+need to park a job and come back to it.
+
 To try it:
 
 ```sh
@@ -124,8 +148,8 @@ Or run it from a source checkout:
 bun ./bin/init.js --local
 ```
 
-Buninu's own tools (`rz`, `sz`, `showimg`, `tts`, `xdg-open`, `native-bridge`,
-etc.) stay available inside this shell too, same as in the browser session.
+Buninu's own tools (`glow`, `jmi`, `xclip`, `tts`, `xdg-open`, etc.) stay
+available inside this shell too, same as in the browser session.
 
 Unlike the shells the browser terminal starts, **bunmsh does not read
 `.bashrc`**. It does not claim complete POSIX behavior yet, so a startup file
@@ -147,6 +171,391 @@ in a subshell before starting a fresh shell — so aliases and functions a
 startup command defines are gone by the time you reach a prompt either way.
 Until bunmsh reads a startup file of its own, sourcing it by hand is the way.
 
+## Security
+
+**Buninu (when starting a remote shell) binds its terminal server to `127.0.0.1`**, so out of the box it
+only accepts connections from the machine it runs on. It is not reachable from
+other devices on the network unless you explicitly opt in.
+
+Within that machine, the terminal is writable (`-w`) and unauthenticated by
+default: only the loopback binding and jsgotty's random URL path (`-r`) stand
+between a local process and a shell with Buninu's permissions.
+
+To listen on another interface, pass `--address <value>` (see
+[Start](#start)). Arguments you give on the command line override the defaults
+the package ships in its `scripts.start` entry, the loopback binding included,
+so **pass `--credential user:pass` at the same time** — a random port and URL
+path are not a substitute for authentication once the server is reachable from
+outside the machine.
+
+## Command-line usage
+
+These are flags to `bin/init.js` itself, resolved before Buninu starts.
+Everything else on the command line is forwarded to jsgotty.
+
+```text
+Init options:
+  --local
+    Start Buninu in this terminal
+      instead of a Remote Shell
+      reached from a browser
+      (via jsgotty, the default)
+
+  -h, --help
+    Show this help and exit
+  -V, --version
+    Show version & runtime info, then exit
+
+  --readme
+    Render README.md in the terminal and exit
+  --changelog
+    Render CHANGELOG.md in the terminal and exit
+
+  --readme-tui
+    Open README.md as a Terminal UI
+  --readme-wui
+    Serve README.md as a Web UI
+
+  --export [output.tgz]
+    Export this Buninu installation
+    (default: ./buninu.tgz)
+
+  --export-config [output.json]
+    Export Buninu's package.json
+    (default: ./buninu.json)
+
+Install options:
+  -i, --install [dir]
+    Install this package into <dir>/buninu
+    (default: .)
+
+  -si, --strip-install [dir]
+    Install into <dir> directly
+    Without a top-level directory of its own
+
+  (--install --help for full options)
+
+Remote Shell options:
+  --shell <path|name>
+    Override buninu.shell for this run
+  --command <command>
+    Override buninu.command for this run
+```
+
+`--local` is the one flag here that changes what Buninu starts rather than
+what it reports; [Start a local shell in a
+Terminal](#start-a-local-shell-in-a-terminal-experimental) covers what that
+session can and cannot do, and [Start](#start) covers the browser route it
+replaces.
+
+`--readme-tui` and `--readme-wui` hand README.md to jsmdcui, so its headings
+and its table of contents become links you can follow rather than text you
+scroll past — the first in this terminal, the second at a URL it prints for a
+browser. Opening a Markdown file that way makes jsmdcui write five generated
+files beside it, so Buninu copies README.md into a directory under `TMPDIR`
+first and runs it there: an installation stays yours, and nothing generated
+ends up in an `--export` or outliving an update.
+
+`--export` and `--export-config` are described under [Export](#export), which
+also covers what an archive made through `npx` contains and what one made from
+your own installation does instead.
+
+`--install --help` lists the install options in full, including `--force` and
+`--yes`; see [Install and update](#install-and-update) for what an update does
+with files you changed.
+
+`--shell` and `--command` override for one run what
+[Shell selection](#shell-selection-optional) and
+[Startup command](#startup-command-optional) set in `package.json`.
+
+### Launching a bundled app directly
+
+As the **first** argument, `--jsgotty`, `--jsmdcui`, `--bunmsh`, or `--musl-la`
+bypasses the shell and startup-command flow entirely: it spawns that app with
+every remaining argument forwarded to it, and exits with its exit code.
+
+```text
+  --jsgotty [args...]
+    Spawn jsgotty directly,
+      forwarding remaining arguments,
+      and exit with its exit code
+  (--jsgotty --help = jsgotty options)
+
+  --jsmdcui [args...]
+    Spawn jsmdcui directly,
+      same forwarding behavior
+
+  --bunmsh [args...]
+    Spawn bunmsh directly,
+      same forwarding behavior
+
+  --musl-la [args...]
+    Spawn musl-la directly,
+      same forwarding behavior
+```
+
+Use it to reach an app's own options, which Buninu would otherwise interpret
+as its own — `npx buninu --jsgotty --help` shows jsgotty's flag reference
+rather than this one.
+
+## Commands inside the shell
+
+Once you are inside a running Buninu shell, these are available (the
+validated source list is `apps/cmdlist`; see [Add a command](#add-a-command)
+for how it works):
+
+---
+
+- **Bun Modern Shell & its builtins**
+  * `bunmsh` — Bun Modern Shell supports multi-tabs cwd
+  * `catfancy` — Pretty print a file with JSON, YAML, TOML, Markdown and JS/TS colored
+  * `lsfancy` — List a directory with emoji, aware of the terminal width
+  * `serve` — Serve a directory over HTTP
+  * `curl` — Fetch an HTTP URL or download it to a file, built on Bun's `fetch`
+  * `pspa` / `pspac` — List processes, plain or colored as shell syntax
+  * `kill` — Signal a process, on Windows as well as POSIX
+
+  Everything below `bunmsh` is one of its builtins, so they are there once you
+  are inside a bunmsh session, and every one of them documents itself with
+  `--help`. From any other shell, reach them with
+  `bunmsh -cc builtin <name> argv1 argv2 ...`.
+
+---
+
+- **Markdown applications**
+  * `jsmdcui` — Run interactive Markdown applications in both TUI & WebUI
+  * `jsmdcui --demo-reader` — Text-to-speech ebook reader
+  * `jsmdcui --demo-imgtool` — Image processor with table-based UI based on `Bun.Image`
+  * `jsmdcui --demo-imgtool-zh` — The same processor in Traditional Chinese
+  * `jsmdcui --demo-maze` — Maze game
+  * `jsmdcui --cdp-maze` — The same maze game, started with a local Chrome DevTools
+    Protocol server and solved by the bundled solver three seconds later
+
+---
+
+- **Editing and viewing**
+  * `jmi` — Edit files in the js micro editor
+  * `glow` — View file contents with syntax highlighting
+
+---
+
+- **Terminal and file transfer**
+  * `jsgotty` — Run a browser-accessible terminal
+  * `showimg` — Show an image in the terminal
+  * `rz` — Upload a file over ZMODEM
+  * `sz` — Download a file over ZMODEM
+
+  These three work in the browser route, a minapk WebView included, but not
+  necessarily under `--local`: they speak the Kitty graphics protocol and
+  ZMODEM, which a plain terminal emulator need not support. They are
+  equivalent to `jsgotty --viu`, `--rz` and `--sz`.
+
+---
+
+- **System integration**
+  * `xclip` — X11-style clipboard tool; `-selection clipboard`/`-clip` bridges
+    to the system clipboard
+  * `tts` — Speak text and wait for it to finish (`-a` to not wait)
+  * `xdg-open` — Open a file or URL with the platform's default handler
+  * `native-bridge` — Call the Android host app (toast, clipboard, speak,
+    WebViews) over `PKG_BRIDGE_SOCK`
+
+---
+
+- **Running programs**
+  * `bun` — Run the bundled Bun, falling back to one already on `PATH`
+  * `bunx` — Globally install a package with bun, then exec its matching binary
+  * `musl-la` — Launch AArch64 ELF programs with the bundled musl loader
+
+---
+
+- **Help**
+  * `buninu-help` — Render README.md with glow, then show icon.png with `showimg`
+
+### Details for the above commands
+
+`rz [target-dir]` (upload into `target-dir`, default: cwd) and `sz <file>
+[more files...]` (download one or more files) are thin `bin/`-only wrappers
+around `apps/jsgotty/rz.js`/`sz.js`, transferring files over ZMODEM through
+the same terminal connection jsgotty already renders in a browser or WebView.
+
+---
+
+`xclip [-o] [-selection primary|clipboard] [-clip]` is a small X11-`xclip`-
+compatible clipboard tool. `-selection primary` (the default) never touches
+the system clipboard, matching real X11 semantics. `-selection
+clipboard`/`-clip` reaches the real system clipboard on Android, macOS,
+Windows, and Linux/Wayland. jsmdcui picks this up automatically once it's on
+`PATH`, so its middle-click paste and copy/paste commands just work.
+
+---
+
+`tts <text> [-f|--flush] [-a|--async] [--timeout <ms>] [--pitch <n>]
+[--speed <n>]` speaks text and, by default, blocks until it finishes — no
+timeout unless you pass `--timeout`. Works on Android, macOS, Windows, and
+Linux (via espeak-ng/espeak). `--pitch`/`--speed` fall back to
+`$TTS_PITCH`/`$TTS_SPEED` when not given explicitly, so jsmdcui's own
+pitch/speed setting is honored automatically.
+
+---
+
+`glow` and `jmi` are the same program under two names: both run the bundled
+jsmdcui, `glow` with its `--cat` mode, which renders a file to stdout and
+exits, and `jmi` with no mode of its own, which opens the editor because this
+jsmdcui is configured editor-first through `MDCUI_DEFAULT_EDIT`. Neither is
+the Go program called glow — `glow --help` and `jmi --help` both print
+jsmdcui's own reference, and jsmdcui's options are the ones that apply.
+
+---
+
+`bun` is the installation's own Bun rather than whatever the machine has. On
+Android it runs `androidNativeLibs/libbun.so` when an APK supplies one;
+otherwise it picks the binary for the machine — `bun-la`, `bun-lx`, or
+`bun-wx.exe` — and extracts it from `apps/bun/bunBin.tgz` first whenever that
+archive is newer than the binary already sitting there. Only when none of
+those is available does it fall back to a Bun on `PATH`, skipping its own
+directory on the way so the `bun` symlink beside it cannot call itself. This
+is what lets an installation carry the runtime it needs with it.
+
+---
+
+`bunx <package>[@version] [args...]` installs with `bun i -g` and runs the
+matching binary. On Android, the underlying `bun i -g` currently needs
+[oven-sh/bun#39084](https://github.com/oven-sh/bun/pull/39084) merged
+upstream — without it, install is killed by SIGSYS (Android's seccomp policy
+rejects a syscall bin-linking uses), so `bunx` can't install anything there yet.
+
+---
+
+`buninu-help` renders README.md with `jmi`'s `--cat` mode — the same rendering
+`glow` gives — and then shows `icon.png` with `showimg`. It is the command the
+default startup greeting points to.
+
+Reach that mode as `jmi --cat` or as plain `glow`, not as `jsmdcui --cat`. The
+`jsmdcui` launcher routes any `.md` argument into the Markdown UI, and opening
+a file that way writes five generated files beside it rather than only
+printing it.
+
+---
+
+`musl-la [-e] <program> [args...]` runs an AArch64 Linux ELF program through
+the bundled musl loader, which is what lets a binary built against musl run
+inside a Buninu session. It is AArch64-only, as its suffix says — see
+[Platform-specific binaries](#platform-specific-binaries) — and the loader it
+uses is the APK's `libld-musl.so` when one is present, or
+`apps/musl-la/ld-musl-aarch64.so.1` otherwise.
+
+The library path is assembled for you. `musl-la` scans its arguments for the
+first file whose leading four bytes are the ELF magic number, and puts that
+file's own directory on the search path along with `apps/musl-la/` and
+anything already in `LD_LIBRARY_PATH` — so a program with its shared objects
+beside it needs no setup. That path normally reaches the loader as
+`--library-path`; pass `-e` as the first argument to export it as
+`LD_LIBRARY_PATH` instead, which is what a program that goes on to exec
+something else of its own needs.
+
+---
+
+`xdg-open <file-or-url>` hands a file or URL to whatever the platform treats
+as its default handler: the host app through native-bridge on Android (or
+`termux-open` under plain Termux), `open` on macOS, `start` on Windows, and
+the real system `xdg-open` on Linux.
+
+Inside minapk's APK, `MINAPK_WEBVIEW` redirects that: set it to a WebView id
+and a URL is loaded into that WebView and brought to the front (`openWebView`
+then `showWebView`) instead of being handed to the system's default handler.
+
+```sh
+# In the app WebView, on screen
+MINAPK_WEBVIEW=1 xdg-open https://example.com
+
+# ...or for the whole session
+export MINAPK_WEBVIEW=1
+```
+
+`0` is the console, so it navigates the terminal page away — the back key
+returns to it and jsgotty reconnects, but it is not usually what you want.
+`-1` is whichever WebView is in front. Only URLs are redirected: a file path
+always goes to the host's own handler, since WebView cannot read a `file://`
+URL under Buninu's home (`setAllowFileAccess` is false from API 30 on) while
+the host serves that same file through its content:// provider. A value that
+is not a plain integer is reported on stderr and ignored rather than guessed
+at, an unset or empty value keeps the default behavior, and a WebView the host
+does not have falls back to the default handler after saying so.
+
+---
+
+`native-bridge [func] [args...]` calls into the Android host app that
+[minapk](https://github.com/jjtseng93/minapk) built the running
+APK with, over an abstract-namespace unix socket. A bare `native-bridge`
+lists what the host implements. Every call
+times out after 5 seconds instead of hanging; outside such an APK, every call
+fails with a clear error instead of doing nothing silently. `import { toast,
+clipboardRead, clipboardWrite, speak, ttsStatus, openWebView, evalWebView,
+showWebView, currWebView, call, available } from
+"apps/native-bridge/native-bridge.js"` gives the same functions as a library,
+for use from a `js back` block.
+
+`openWebView(id, url)`, `evalWebView(id, js)`, `showWebView(id)` and
+`currWebView()` (short: `openwv`, `evalwv`, `showwv`, `currwv`) drive the host
+app's WebViews. There are exactly two, both
+alive from startup and neither ever created nor closed at runtime: id `0` is
+the console — the jsgotty terminal this shell is rendered in — and id `1` is
+the app WebView, which starts out blank and behind. Anywhere an id is taken,
+`-1` means whichever WebView is in front right now.
+
+`openWebView` loads a URL *without* bringing that WebView to the front, so
+loading the app WebView while the user keeps looking at the terminal is one
+call. `showWebView` is the only thing that changes what is on screen; the
+host's on-screen key bar (Ctrl/Alt/Shift and friends), its volume-key menu and
+its back key all act on whichever WebView is in front, so they follow the
+switch. Back on the app WebView with no page of its own to go back to
+switches to the console rather than leaving the app, unless
+`buninu.backToConsole` says otherwise (see "Back key" below).
+`showWebView(-1)` switches to the next WebView instead of being a no-op --
+with two of them, a toggle. `evalWebView` resolves to the value the
+expression produced, not a string containing it; `undefined`, a function, and
+a thrown exception all arrive as `null`, since WebView itself does not
+distinguish them.
+
+All four also answer to a short `openwv`/`evalwv`/`showwv`/`currwv` spelling,
+the same way `clipboardRead`/`clipboardWrite` answer to `getcb`/`setcb`: the
+host accepts either and lists both in its `_discover` response, so either name
+works from the CLI, from `rpcraw`, and as an `import`.
+
+```sh
+# Load it, screen unchanged
+native-bridge openwv 1 https://example.com
+
+# Now bring it to the front
+native-bridge showwv 1
+
+native-bridge evalwv 1 document.title
+native-bridge currwv
+```
+
+## Differences from upstream
+
+The versions of jsmdcui and jsgotty bundled here differ from the ones their
+own projects ship.
+
+### The bundled jsmdcui
+
+  * Is configured editor-first by `MDCUI_DEFAULT_EDIT`
+  * The command `jmi` with a Markdown file opens the normal terminal editor
+    (js micro editor)
+  * The command `jsmdcui` preserves its original behavior:
+    `apps/jsmdcui/jsmdcui.sh`, which starts its `tui` entry point with
+    `--mdcui` when running Markdown apps, and forwards all command-line
+    arguments
+  * Adds the Buninu-only `# syntax: markdown` marker for Markdown highlighting
+    in extensionless files; upstreaming may be considered later
+
+### The bundled jsgotty
+
+  * No longer depends on or ships `node-pty`
+  * Its PTY is provided by Bun's terminal API
+
 ## Data & Persistence
 
 Running Buninu via `npx` works like a container: `npx` fetches the package into
@@ -280,209 +689,6 @@ A source checkout's own `.git` is never copied into an installation, so
 installing into a directory that is itself a repository leaves that repository
 alone.
 
-## Security
-
-`scripts.start` binds jsgotty to `127.0.0.1` by default, so the terminal
-server only accepts connections from the same machine. It is not reachable
-from other devices on the network unless you explicitly opt in.
-
-The terminal itself is writable (`-w`) and unauthenticated by default; only
-the loopback binding and jsgotty's random URL path (`-r`) stand between a
-local process and a shell with Buninu's permissions. To listen on another
-interface, forward `--address <value>` (see [Start](#start)); forwarded
-arguments override the flags baked into `scripts.start`. Also pass
-`--credential user:pass` when doing so, since the random port and URL path
-are not a substitute for authentication once the server is reachable from
-outside the machine.
-
-## Command-line usage
-
-These are flags to `bin/init.js` itself, resolved before Buninu starts.
-Everything else on the command line is forwarded to jsgotty.
-
-```text
--h, --help       Show command-line help
--V, --version    Show the Buninu, Bun, platform, and architecture versions
---readme         Render README.md in the terminal
---changelog      Render CHANGELOG.md in the terminal
---local          Start bunmsh in this terminal instead of a browser terminal
-
--i,  --install [dir]        Install into <dir>/buninu (default: .)
--si, --strip-install [dir]  Install into <dir> itself
---export [output.tgz]       Export this installation as a tarball
---export-config [out.json]  Export this package.json
-
---shell <path|name>   Override buninu.shell for this run
---command <command>   Override buninu.command for this run
-```
-
-`--install --help` lists the install options in full, including `--force` and
-`--yes`; see [Install and update](#install-and-update) for what an update does
-with files you changed. The other groups are covered by
-[Start](#start), [Export](#export), [Shell selection](#shell-selection-optional)
-and [Startup command](#startup-command-optional).
-
-### Launching a bundled app directly
-
-As the **first** argument, `--jsgotty`, `--jsmdcui`, or `--musl-la` bypasses the
-shell and startup-command flow entirely: it spawns that app with every
-remaining argument forwarded to it, and exits with its exit code.
-
-```text
---jsgotty [args...]  Spawn jsgotty directly and exit with its exit code
---jsmdcui [args...]  Spawn jsmdcui directly and exit with its exit code
---musl-la [args...]  Spawn musl-la directly and exit with its exit code
-```
-
-Use it to reach an app's own options, which Buninu would otherwise interpret
-as its own — `npx buninu --jsgotty --help` shows jsgotty's flag reference
-rather than this one.
-
-## Commands inside the shell
-
-Once you are inside a running Buninu shell, these are available (the
-validated source list is `apps/cmdlist`; see [Add a command](#add-a-command)
-for how it works):
-
-```text
-glow          Render files with jsmdcui syntax highlighting
-jmi           Open files in the js micro editor
-jsgotty       Run a browser-accessible terminal
-jsmdcui       Edit and run interactive Markdown applications
-musl-la       Launch AArch64 ELF programs with the bundled musl loader
-buninu-help   Render README.md with glow, then show icon.png with jsgotty --viu
-bunx          Globally install a package with bun, then exec its matching binary
-native-bridge Call the Android host app (toast, clipboard, speak, WebViews) over PKG_BRIDGE_SOCK
-xclip         X11-style clipboard tool; -selection clipboard/-clip bridges to the system clipboard
-tts           Speak text and wait for it to finish (-a to not wait)
-showimg       Shorthand for jsgotty --viu
-rz            Upload a file over ZMODEM
-sz            Download a file over ZMODEM
-xdg-open      Open a file or URL with the platform's default handler
-```
-
-`buninu-help` renders README.md with jsmdcui's `--cat` mode and then shows
-`icon.png` with jsgotty's `--viu`. It is the command the default startup
-greeting points to.
-
-`bunx <package>[@version] [args...]` installs with `bun i -g` and runs the
-matching binary. On Android, the underlying `bun i -g` currently needs
-[oven-sh/bun#39084](https://github.com/oven-sh/bun/pull/39084) merged
-upstream — without it, install is killed by SIGSYS (Android's seccomp policy
-rejects a syscall bin-linking uses), so `bunx` can't install anything there yet.
-
-`native-bridge [func] [args...]` calls into the Android host app that
-[minapk](https://www.npmjs.com/package/@drxiaozhi/minapk) built the running
-APK with, over an abstract-namespace unix socket. A bare `native-bridge`
-lists what the host implements. Every call
-times out after 5 seconds instead of hanging; outside such an APK, every call
-fails with a clear error instead of doing nothing silently. `import { toast,
-clipboardRead, clipboardWrite, speak, ttsStatus, openWebView, evalWebView,
-showWebView, currWebView, call, available } from
-"apps/native-bridge/native-bridge.js"` gives the same functions as a library,
-for use from a `js back` block.
-
-`openWebView(id, url)`, `evalWebView(id, js)`, `showWebView(id)` and
-`currWebView()` (short: `openwv`, `evalwv`, `showwv`, `currwv`) drive the host
-app's WebViews. There are exactly two, both
-alive from startup and neither ever created nor closed at runtime: id `0` is
-the console -- the jsgotty terminal this shell is rendered in -- and id `1` is
-the app WebView, which starts out blank and behind. Anywhere an id is taken,
-`-1` means whichever WebView is in front right now.
-
-`openWebView` loads a URL *without* bringing that WebView to the front, so
-loading the app WebView while the user keeps looking at the terminal is one
-call. `showWebView` is the only thing that changes what is on screen; the
-host's on-screen key bar (Ctrl/Alt/Shift and friends), its volume-key menu and
-its back key all act on whichever WebView is in front, so they follow the
-switch. Back on the app WebView with no page of its own to go back to
-switches to the console rather than leaving the app, unless
-`buninu.backToConsole` says otherwise (see "Back key" below).
-`showWebView(-1)` switches to the next WebView instead of being a no-op --
-with two of them, a toggle. `evalWebView` resolves to the value the
-expression produced, not a string containing it; `undefined`, a function, and
-a thrown exception all arrive as `null`, since WebView itself does not
-distinguish them.
-
-All four also answer to a short `openwv`/`evalwv`/`showwv`/`currwv` spelling,
-the same way `clipboardRead`/`clipboardWrite` answer to `getcb`/`setcb`: the
-host accepts either and lists both in its `_discover` response, so either name
-works from the CLI, from `rpcraw`, and as an `import`.
-
-```sh
-# Load it, screen unchanged
-native-bridge openwv 1 https://example.com
-
-# Now bring it to the front
-native-bridge showwv 1
-
-native-bridge evalwv 1 document.title
-native-bridge currwv
-```
-
-`xclip [-o] [-selection primary|clipboard] [-clip]` is a small X11-`xclip`-
-compatible clipboard tool. `-selection primary` (the default) never touches
-the system clipboard, matching real X11 semantics. `-selection
-clipboard`/`-clip` reaches the real system clipboard on Android, macOS,
-Windows, and Linux/Wayland. jsmdcui picks this up automatically once it's on
-`PATH`, so its middle-click paste and copy/paste commands just work.
-
-`tts <text> [-f|--flush] [-a|--async] [--timeout <ms>] [--pitch <n>]
-[--speed <n>]` speaks text and, by default, blocks until it finishes -- no
-timeout unless you pass `--timeout`. Works on Android, macOS, Windows, and
-Linux (via espeak-ng/espeak). `--pitch`/`--speed` fall back to
-`$TTS_PITCH`/`$TTS_SPEED` when not given explicitly, so jsmdcui's own
-pitch/speed setting is honored automatically.
-
-`rz [target-dir]` (upload into `target-dir`, default: cwd) and `sz <file>
-[more files...]` (download one or more files) are thin `bin/`-only wrappers
-around `apps/jsgotty/rz.js`/`sz.js`, transferring files over ZMODEM through
-the same terminal connection jsgotty already renders in a browser or WebView.
-
-`xdg-open <file-or-url>` hands a file or URL to whatever the platform treats
-as its default handler: the host app through native-bridge on Android (or
-`termux-open` under plain Termux), `open` on macOS, `start` on Windows, and
-the real system `xdg-open` on Linux.
-
-Inside minapk's APK, `MINAPK_WEBVIEW` redirects that: set it to a WebView id
-and a URL is loaded into that WebView and brought to the front (`openWebView`
-then `showWebView`) instead of being handed to the system's default handler.
-
-```sh
-# In the app WebView, on screen
-MINAPK_WEBVIEW=1 xdg-open https://example.com
-
-# ...or for the whole session
-export MINAPK_WEBVIEW=1
-```
-
-`0` is the console, so it navigates the terminal page away -- the back key
-returns to it and jsgotty reconnects, but it is not usually what you want.
-`-1` is whichever WebView is in front. Only URLs are redirected: a file path
-always goes to the host's own handler, since WebView cannot read a `file://`
-URL under Buninu's home (`setAllowFileAccess` is false from API 30 on) while
-the host serves that same file through its content:// provider. A value that
-is not a plain integer is reported on stderr and ignored rather than guessed
-at, an unset or empty value keeps the default behavior, and a WebView the host
-does not have falls back to the default handler after saying so.
-
-## Differences from upstream
-
-The versions of jsmdcui and jsgotty bundled here differ from the ones their
-own projects ship.
-
-### The bundled jsmdcui
-
-  * Is configured editor-first by MDCUI_DEFAULT_EDIT
-  * The command `jmi` with a Markdown file opens the normal terminal editor.(js micro editor)
-  * The command `jsmdcui` preserves its original behavior: `apps/jsmdcui/jsmdcui.sh`, which starts its `tui` entry point with `--mdcui` when running markdown Apps, and forwards all command-line arguments.
-  * Adds the Buninu-only `# syntax: markdown` marker for Markdown highlighting in extensionless files; upstreaming may be considered later.
-
-### The bundled jsgotty
-
-  * No longer depends on or ships `node-pty`. 
-  * Its PTY is provided by Bun's terminal API.
-
 ## Export
 
 Export a Buninu installation as a gzip-compressed tar archive. What gets
@@ -623,6 +829,29 @@ call "%~dp0bun.bat" "%~dp0..\apps\hello\hello.js" %*
 exit /b %ERRORLEVEL%
 ```
 
+### Platform-specific binaries
+
+A bundled binary that only runs on one platform and architecture carries a
+two-letter suffix: the platform first, then the architecture.
+
+| Suffix | Platform | Architecture |
+|---|---|---|
+| `la` | Linux | arm64 |
+| `lx` | Linux | x64 |
+| `aa` | Android | arm64 |
+| `wx` | Windows | x64 |
+| `ma` | macOS | arm64 |
+
+So `bin/bun.sh` picks `bun-la`, `bun-lx` or `bun-wx.exe` for the machine it
+finds itself on, and `musl-la` is the Linux/arm64 ELF loader — on any other
+platform there is nothing for it to load. A name without a suffix is
+portable: `hello.js` above runs wherever Bun does.
+
+One binary is deliberately outside the scheme. `bin/libsh-loader.so` is
+Android/arm64 and would otherwise be `-aa`, but Android extracts and executes
+only files named `lib*.so` from an APK's native library directory, so that
+name belongs to the platform rather than to this convention.
+
 ## Startup command (optional)
 
 Set `buninu.command.default` or a platform-specific value (`android`, `linux`,
@@ -749,7 +978,7 @@ and running behind it. Set it to `false` and back leaves the app instead.
 
 This one is read by the host app, not by Buninu itself, so it does nothing
 outside an APK built with
-[minapk](https://www.npmjs.com/package/@drxiaozhi/minapk) -- where it can also
+[minapk](https://github.com/jjtseng93/minapk) — where it can also
 be set for a single build with `--no-back-to-console`. The host treats a
 missing, unreadable, or non-boolean value as `true`, so nothing here can fail
 in a way that leaves the back key broken.
@@ -813,3 +1042,95 @@ words, and `pspac` is two commands joined by `;` with a redirection in the
 first, so it cannot be one — but the builtin of that name is already there, and
 an alias that fails to define leaves it reachable. See
 [Start a local shell in a Terminal](#start-a-local-shell-in-a-terminal-experimental).
+
+## Why
+
+- The usual way to get a Unix
+  environment onto a machine
+  * A system package manager
+  * A compiler
+  * On Android or Windows,
+    you install Linux first:
+    WSL, or a proot distro
+
+- Buninu's way: everything it
+  needs is JavaScript on Bun
+  * Nothing to build
+  * Nothing installed
+    system-wide
+  * The bundled jsgotty
+    dropped `node-pty` for
+    Bun's own terminal API
+  * So the same tree runs
+    unchanged on a phone, a
+    laptop and a server
+
+- Not a bare runtime either
+  * An editor and Markdown
+    runtime
+  * A clipboard tool
+  * Text-to-speech
+  * ZMODEM file transfer
+  * An `xdg-open` that knows
+    each platform's real
+    handler
+
+- An installation is one
+  directory
+  * Yours to edit
+  * Copy it to another machine
+    and your shell, the
+    commands you added and
+    your history go with it
+  * Your own `$HOME` is never
+    touched — a shell started
+    here still finds your SSH
+    keys and Git configuration
+
+## Contents
+
+- [Install Bun](#install-bun)
+- [Start](#start)
+  * [Start a remote shell in a Browser](#start-a-remote-shell-in-a-browser)
+  * [Start a local shell in a Terminal (experimental)](#start-a-local-shell-in-a-terminal-experimental)
+- [Security](#security)
+- [Command-line usage](#command-line-usage)
+  * [Launching a bundled app directly](#launching-a-bundled-app-directly)
+- [Commands inside the shell](#commands-inside-the-shell)
+- [Differences from upstream](#differences-from-upstream)
+- [Data & Persistence](#data--persistence)
+- [Install and update](#install-and-update)
+- [Export](#export)
+- [Environment](#environment)
+- [Add a command](#add-a-command)
+  * [Platform-specific binaries](#platform-specific-binaries)
+- [Startup command (optional)](#startup-command-optional)
+- [Shell selection (optional)](#shell-selection-optional)
+- [Data directory (optional)](#data-directory-optional)
+- [Back key (Android, optional)](#back-key-android-optional)
+- [Process-list helpers](#process-list-helpers)
+- [Why](#why)
+- [License](#license)
+
+## License
+
+Buninu's own code is MIT — see [LICENSE](LICENSE).
+
+The apps bundled under `apps/` are separate projects on their own terms, and
+each carries its licence with it:
+
+| App | Licence | Files under `apps/<app>/` |
+|---|---|---|
+| jsgotty | MIT; its bundled front-end libraries are MIT and Apache-2.0 | `LICENSE`, `NOTICE`, `LICENSES/`, `static/js/gotty.licenses.txt` |
+| jsmdcui | MIT | `LICENSE`, `runtime/syntax/LICENSE` |
+| bunmsh | MIT; mksh's own terms are not relicensed under it | `LICENSE`, `LICENSE-MKSH`, `LICENSE-MICRO` |
+| musl-la | MIT for musl itself, and see below | `LICENSE_musl.txt`, `NOTICE`, `LICENSES/` |
+
+One component is worth naming here rather than leaving in a file to be found:
+`apps/musl-la` ships `libgcc_s.so.1` and `libstdc++.so.6`, built from GCC
+14.2.0, under **GPL-3.0 with the GCC Runtime Library Exception**. That
+exception is what lets them be distributed alongside code under any licence,
+so nothing here changes Buninu's own MIT terms — but if your organisation
+screens for GPL, this is the component it will find. `apps/musl-la/NOTICE`
+records the exact build, its Corresponding Source, and SHA-256 sums for every
+binary in that directory.