buninu 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 0.3.0 - 2026-08-21
+
+### Added
+
+- Add `openWebView`, `evalWebView`, `showWebView` and `currWebView` to
+  `apps/native-bridge` (short spellings `openwv`, `evalwv`, `showwv`,
+  `currwv`, both accepted over the wire and listed in the host's `_discover`,
+  the same arrangement `getcb`/`setcb` already had), plus the
+  `WEBVIEW_CURRENT`/`WEBVIEW_CONSOLE`/`WEBVIEW_APP` constants. The host app
+  has exactly two WebViews, alive from startup and never created or closed at
+  runtime: `0` is the console showing the jsgotty terminal, `1` is the app
+  WebView, which starts blank and behind. An id of `-1` means whichever is in
+  front. `openWebView` loads without bringing its target forward, 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, and
+  `showWebView(-1)` switches to the *next* WebView rather than being a no-op.
+  `evalWebView` resolves to the value the expression produced rather than a
+  string containing it, with `undefined`, functions and thrown exceptions all
+  arriving as `null` because WebView itself does not distinguish them.
+- `xdg-open` gained `MINAPK_WEBVIEW`, which names the WebView to open a URL
+  in (and brings it to the front) instead of handing the URL to the
+  platform's default handler. Read here rather than by the host app on
+  purpose: it is an environment variable of this process tree, so the host
+  could not see a value exported in the shell a moment ago, which is the
+  whole point of having it. Only URLs are redirected -- a filesystem path
+  still goes to the host, whose `content://` provider can actually serve it,
+  unlike a `file://` URL in a WebView. A value that is not a plain integer is
+  reported and ignored rather than guessed at, and a WebView the host does
+  not have falls back to the default handler after saying so.
+- Add `demo-server.js`: serves one fixed page on an OS-assigned port and
+  opens it in the app WebView through `MINAPK_WEBVIEW=1 xdg-open`, as the
+  smallest end-to-end exercise of the above.
+- Add `buninu.backToConsole` (default `true`), read by the minapk host app,
+  not by Buninu itself: it decides whether the Android back key, pressed on
+  the app WebView with no page of its own to go back to, switches to the
+  console WebView or takes the leave-the-app path. The host treats a missing,
+  unreadable or non-boolean value as `true`, so it cannot fail in a way that
+  leaves the back key broken. minapk's `--no-back-to-console` sets it for a
+  single build.
+
+## 0.2.5 - 2026-08-19
+
+- Fixed fish shell startup breaking buninu
+- Start fish after entering the shell please
+
 ## 0.2.4 - 2026-08-19
 
 ### Added

package/README.md

@@ -125,7 +125,7 @@ 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) over PKG_BRIDGE_SOCK
+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
@@ -150,10 +150,45 @@ 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, call, available } from
+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
+native-bridge openwv 1 https://example.com   # load it, screen unchanged
+native-bridge showwv 1                       # now bring it to the front
+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
@@ -178,6 +213,25 @@ 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
+MINAPK_WEBVIEW=1 xdg-open https://example.com   # in the app WebView, on screen
+export MINAPK_WEBVIEW=1                         # ...or for the whole session
+```
+
+`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.
+
 ## Export
 
 Export the current Buninu installation as a gzip-compressed tar archive:
@@ -349,6 +403,29 @@ from the directory containing `package.json`.
 
 Use `--shell <path-or-name>` for a one-time override.
 
+## Back key (Android, optional)
+
+Set `buninu.backToConsole` in `package.json` to decide what the Android host
+app's back key does while the app WebView (id `1`, see `native-bridge` above)
+is in front and has no page of its own left to go back to. It defaults to
+`true`: back switches to the console WebView, leaving the app WebView loaded
+and running behind it. Set it to `false` and back leaves the app instead.
+
+```json
+{
+  "buninu": {
+    "backToConsole": false
+  }
+}
+```
+
+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
+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.
+
 ## Process-list helpers
 
 The bundled `.bashrc` provides `pspa` (`ps -eo pid,args`) and `pspac`, which

package/apps/native-bridge/native-bridge.js

@@ -101,6 +101,51 @@ export const tts = ttsStatus
 // the receiving app on modern Android.
 export const xdgOpen = (target) => call("xdgOpen", [target])
 
+// The host has exactly two WebViews, both alive from startup and neither ever
+// created nor closed at runtime: WEBVIEW_CONSOLE (0) is the jsgotty terminal
+// this shell is being rendered in, WEBVIEW_APP (1) is the app WebView, which
+// simply starts out blank and behind. WEBVIEW_CURRENT (-1) means whichever
+// one is in front right now, and is the default wherever an id is optional.
+// All four functions also go by openwv/evalwv/showwv/currwv, both here and
+// over the wire (the Java dispatcher answers to either spelling and lists
+// both in _discover), on the same grounds as getcb/setcb above.
+export const WEBVIEW_CURRENT = -1
+export const WEBVIEW_CONSOLE = 0
+export const WEBVIEW_APP = 1
+
+// Loads url into a WebView *without* bringing it to the front, so
+// openWebView(WEBVIEW_APP, url) while the user is looking at the terminal is
+// a plain background load -- showWebView is the only thing that changes what
+// is on screen. Omitting url loads nothing and just reports the id back,
+// which is how -1 gets resolved to a real id. Returns the id loaded into.
+export const openWebView = (id = WEBVIEW_CURRENT, url = "") =>
+  call("openWebView", [id, url])
+export const openwv = openWebView
+
+// Resolves to the value the expression produced -- a real number/string/
+// object, not a string containing one -- because the host sends
+// evaluateJavascript's own JSON text straight back as the response body.
+// undefined, a function, and a thrown exception all arrive as null: WebView
+// itself does not distinguish them, so return something JSON can carry when
+// you need to tell them apart. A page that never answers is given up on by
+// the host (inside this module's own call timeout) and comes back as an
+// "error: ..." string rather than hanging.
+export const evalWebView = (id, js) => call("evalWebView", [id, js])
+export const evalwv = evalWebView
+
+// Brings a WebView to the front. The bottom key bar (Ctrl/Alt/Shift and
+// friends), the volume-key menu and the back key all act on whatever is in
+// front, so this is also what re-points them. An id of -1 -- the default --
+// switches to the next WebView rather than being a no-op, which with two of
+// them is simply a toggle. Returns the id now in front.
+export const showWebView = (id = WEBVIEW_CURRENT) => call("showWebView", [id])
+export const showwv = showWebView
+
+// The id of the WebView in front, for code that wants to put something back
+// the way it found it.
+export const currWebView = () => call("currWebView")
+export const currwv = currWebView
+
 // `bun native-bridge.js <func> [args...]`, dispatched straight to call(func,
 // args) -- not restricted to toast/clipboardRead/clipboardWrite, exactly like
 // calling rpcraw(func, args) would be. This is a raw RPC, equivalent to a

package/apps/xdg-open/xdg-open.js

@@ -7,9 +7,74 @@
 // the default handler" mechanism -- macOS/Windows are real OS
 // commands/APIs, but Linux's is conventionally *also* a command named
 // xdg-open, so this script has to be careful not to find itself on PATH.
-import { xdgOpen as bridgeOpen, available } from "../native-bridge/native-bridge.js"
+import {
+  xdgOpen as bridgeOpen, available, openWebView, showWebView,
+} from "../native-bridge/native-bridge.js"
 const fs = require("fs")
 
+// MINAPK_WEBVIEW names *which* of the host app's WebViews to open into (0 is
+// the console, 1 the app WebView, -1 whichever is in front); unset means the
+// unchanged behavior of handing the target to the system's default handler.
+// It is read here rather than being detected by the host, because it is an
+// environment variable of this Bun process tree -- the host app's own process
+// cannot see a value exported in this shell a moment ago, and the whole point
+// of the variable is that it can be.
+//
+// Deliberately never Number()/parseInt(): Number("") is 0, and 0 is a
+// perfectly valid WebView id, so an exported-but-empty MINAPK_WEBVIEW= (the
+// usual way to switch something off) would come out meaning "open in the
+// console" -- i.e. navigate the terminal away. parseInt would likewise turn
+// "1x" into 1. Only a bare optionally-signed integer counts; anything else is
+// reported and treated as unset.
+function webViewIdFromEnv() {
+  const raw = (process.env.MINAPK_WEBVIEW ?? "").trim()
+  if (raw === "") return null
+  if (!/^-?\d+$/.test(raw)) {
+    process.stderr.write(
+      `xdg-open: ignoring MINAPK_WEBVIEW=${raw} (not an integer WebView id)\n`)
+    return null
+  }
+  return Number(raw)
+}
+
+// Only URLs. A filesystem path stays on the bridgeOpen path even when
+// MINAPK_WEBVIEW is set: WebView's setAllowFileAccess defaults to false from
+// API 30 on, so a file:// URL under Buninu's home would load as a blank page,
+// whereas the host's xdgOpen already serves that file properly through its
+// read-only content:// provider.
+const isUrl = (target) => /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(target)
+
+// The host answers with the id it actually used -- a JSON number -- and with
+// a string when something went wrong: "error: no such WebView: 9" from the
+// dispatcher, or rpc.mjs's own "Unknown func ..." when the APK is older than
+// these functions and does not list them in _discover. rpc.mjs also *resolves*
+// to an Error object instead of throwing when the fetch itself fails. So
+// success is checked as "is genuinely a number", never by parsing the result:
+// see webViewIdFromEnv above for why a coercing parse is dangerous here.
+//
+// showWebView(-1) means "switch to the next one", not "the one just loaded",
+// so the switch uses the id openWebView resolved and handed back, not the id
+// that was asked for.
+async function openInWebView(id, url) {
+  const opened = await openWebView(id, url)
+  if (typeof opened !== "number" || !Number.isInteger(opened)) {
+    process.stderr.write(
+      `xdg-open: MINAPK_WEBVIEW=${id}: ${opened?.message ?? opened}\n`)
+    return false
+  }
+
+  const shown = await showWebView(opened)
+  if (typeof shown !== "number" || !Number.isInteger(shown)) {
+    // Loaded but not brought to the front: say so rather than reporting
+    // success for something the user cannot see, but do not fall back to the
+    // system handler either -- the page really is loaded in that WebView.
+    process.stderr.write(
+      `xdg-open: loaded in WebView ${opened} but could not switch to it: ` +
+      `${shown?.message ?? shown}\n`)
+  }
+  return true
+}
+
 // Buninu's own bin/ is prepended to PATH ahead of any real system binary of
 // the same name (same concern as xclip.js/tts.js), and this script is
 // itself registered as Buninu's "xdg-open" command -- a naive PATH search
@@ -46,7 +111,14 @@ let ok = false
 try {
   if (process.platform === "android") {
     if (available()) {
-      ok = await bridgeOpen(target)
+      const webViewId = webViewIdFromEnv()
+      // A failed WebView open falls back to the system handler rather than
+      // failing outright: the request was "open this", and MINAPK_WEBVIEW
+      // only says where it would be preferred. openInWebView has already
+      // explained on stderr why it could not.
+      ok = webViewId !== null && isUrl(target)
+        ? (await openInWebView(webViewId, target)) || (await bridgeOpen(target))
+        : await bridgeOpen(target)
     } else if (Bun.which("termux-open")) {
       // Plain Termux (no minapk) still reports platform "android" but has
       // no PKG_BRIDGE_SOCK -- termux-open (Termux:API) does the same

package/bin/init.js

@@ -258,7 +258,7 @@ async function detectEnvironment() {
     return {
       name: "linux",
       shell:
-        await findCommand(process.env.SHELL) ||
+        // await findCommand(process.env.SHELL) ||
         Bun.which("bash") ||
         Bun.which("sh") ||
         "/bin/sh",
@@ -269,10 +269,11 @@ async function detectEnvironment() {
     return {
       name: "android",
       shell:
-        await findCommand(process.env.SHELL) ||
+        // await findCommand(process.env.SHELL) ||
         (await pathExists("/system/bin/sh") ? "/system/bin/sh" : null) ||
+        Bun.which("bash") ||
         Bun.which("sh") ||
-        "sh",
+        "/bin/sh",
     };
   }
 
@@ -280,7 +281,7 @@ async function detectEnvironment() {
     return {
       name: "macos",
       shell:
-        await findCommand(process.env.SHELL) ||
+        // await findCommand(process.env.SHELL) ||
         Bun.which("zsh") ||
         Bun.which("bash") ||
         Bun.which("sh") ||
@@ -292,7 +293,7 @@ async function detectEnvironment() {
     return {
       name: "linux",
       shell:
-        await findCommand(process.env.SHELL) ||
+        // await findCommand(process.env.SHELL) ||
         Bun.which("bash") ||
         Bun.which("sh") ||
         "/bin/sh",
@@ -302,7 +303,7 @@ async function detectEnvironment() {
   return {
     name: `unix:${process.platform}`,
     shell:
-      await findCommand(process.env.SHELL) ||
+      // await findCommand(process.env.SHELL) ||
       Bun.which("bash") ||
       Bun.which("sh") ||
       "/bin/sh",

package/demo-server.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+
+// Smallest end-to-end demo of the WebView bridge: serve one fixed page on a
+// port nobody picked in advance, then have xdg-open put it in the host app's
+// app WebView and switch to it. Run it from a Buninu shell inside minapk's
+// APK:
+//
+//   bun demo-server.js
+//
+// Outside such an APK it still runs and still serves; xdg-open just falls
+// back to whatever that platform's default handler is (see apps/xdg-open).
+
+const BODY = "Hello 你好 こんにちは"
+
+// port: 0 asks the OS for a free port instead of guessing one and racing
+// whatever already has it -- Buninu's own launcher picks jsgotty's port the
+// same way. The real number is only knowable after the listener exists, so
+// the URL is built from server.port, never from a constant.
+// hostname stays on loopback: this is a demo page for the WebView on this
+// device, not something other machines on the network should reach.
+const server = Bun.serve({
+  hostname: "127.0.0.1",
+  port: 0,
+  fetch() {
+    // charset is not optional here: without it the WebView guesses an
+    // encoding for the response, and the CJK half of BODY is what shows up
+    // as mojibake when it guesses wrong.
+    return new Response(BODY, {
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    })
+  },
+})
+
+// 127.0.0.1 rather than localhost: the listener is bound to the v4 loopback
+// address specifically, while "localhost" can resolve to ::1 first and give
+// the WebView a connection refused before it ever tries v4.
+const url = `http://127.0.0.1:${server.port}`
+console.log(`demo-server: serving ${JSON.stringify(BODY)} at ${url}`)
+
+// Buninu puts its own bin/ on PATH, so "xdg-open" normally resolves to
+// apps/xdg-open through the shloader. Fall back to running the script
+// directly for the case where this file is run outside a Buninu shell (a bare
+// `bun demo-server.js` in a checkout), where that PATH entry is not there.
+const xdgOpen = Bun.which("xdg-open")
+const command = xdgOpen
+  ? [xdgOpen, url]
+  : [process.execPath, `${import.meta.dir}/apps/xdg-open/xdg-open.js`, url]
+
+// MINAPK_WEBVIEW is read by xdg-open itself, not by the host app -- it names
+// which WebView to load into (1 is the app WebView) and brings it to the
+// front. Passed to this one child rather than exported, so it changes nothing
+// for the rest of the session.
+const child = Bun.spawn(command, {
+  env: { ...process.env, MINAPK_WEBVIEW: "1" },
+  stdout: "inherit",
+  stderr: "inherit",
+})
+
+if (await child.exited !== 0)
+  console.error(`demo-server: ${command[0]} exited with ${child.exitCode}; page is still served at ${url}`)
+
+// The server has to outlive the open: the WebView fetches the page after
+// xdg-open has already returned. Ctrl-C to stop.
+console.log("demo-server: Ctrl-C to stop")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Buninu is a portable, self-bootstrapping Unix-like userspace built on Bun that runs across operating systems",
   "type": "module",
   "main": "./bin/init.js",
@@ -23,7 +23,8 @@
       "macos": null,
       "windows": null
     },
-    "exitAfterCmd": false
+    "exitAfterCmd": false,
+    "backToConsole": true
   },
   "scripts": {
     "start": "bun ./apps/jsgotty/gotty.js --reconnect -r -w --webgl -a 127.0.0.1",