buninu 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## 0.2.4 - 2026-08-19
+
+### Added
+
+- Add the `xdg-open` command (`apps/xdg-open`), which opens a file or URL
+  with whatever the platform considers its default handler: native-bridge's
+  `xdgOpen` on Android (the host resolves a path under Buninu's home and
+  hands it to another app through a read-only `content://` provider, since
+  that directory is otherwise private to the APK), `termux-open` when
+  running under plain Termux with no native bridge, `open` on macOS, `start`
+  on Windows, and the real system `xdg-open` on Linux. That last one skips
+  Buninu's own `bin` while searching `PATH`, since this script is itself
+  registered as `xdg-open` and would otherwise find and run itself.
+- Add `showimg`, a `bin/`-only shorthand for `jsgotty --viu` (no `apps/`
+  subfolder, since it has no logic of its own beyond forwarding args).
+- Add `rz`/`sz`, `bin/`-only companion scripts wrapping the existing
+  `apps/jsgotty/rz.js`/`sz.js` -- `rz` uploads a file over ZMODEM, `sz`
+  downloads one -- over the same terminal connection jsgotty renders in a
+  browser or WebView.
+
+- Add `apps/native-bridge`, a Bun module (`toast`, `clipboardRead`/`getcb`,
+  `clipboardWrite`/`setcb`, and the raw `call(func, args, envp)` it and the
+  CLI both sit on top of) that reaches minapk's Android native bridge over
+  `PKG_BRIDGE_SOCK` -- a Bun unix socket, filesystem-path or Linux
+  abstract-namespace depending on how that env var is encoded -- using
+  jsmdcui's `rpc.mjs` `switchBackend`. Only meaningful inside an APK built by
+  minapk with the native bridge wired in; elsewhere `available()` returns
+  `false` and calls throw a clear error instead of doing nothing silently.
+  Every call times out after 5s by default, so a stuck or unresponsive host
+  can never hang the caller. `bun apps/native-bridge/native-bridge.js [func]
+  [args...]` runs it directly; a bare invocation defaults `func` to
+  `_discover` and lists what the host implements.
+- Add the `xclip` command (`apps/xclip`), ported from the DroidScript-era
+  `../tmpk/bin/xclip.sh` to use native-bridge instead of `dsapi.pipe`.
+  `-selection primary` (the default) stays local-file-only, matching real X11
+  semantics where the primary selection is never the same thing as the
+  clipboard; `-selection clipboard`/`-clip` bridges to the real Android
+  clipboard through native-bridge. jsmdcui's own clipboard backend detection
+  already shells out to `xclip` on Linux-like platforms (`isLinuxLike()`
+  counts `process.platform === "android"`), so jsmdcui's middle-click paste,
+  selection auto-sync, and `PastePrimary` command all work inside an APK with
+  no further wiring once `xclip` is on `PATH`.
+- Add `speak`/`ttsStatus`/`tts` to native-bridge and the `tts` command
+  (`apps/tts`) built on them. Android's TextToSpeech completion signal is an
+  asynchronous callback with no way to push it to the far side over this
+  protocol, so `speak(text, speed, pitch, flush)` never blocks -- it returns
+  a handle immediately, and `ttsStatus(handle)`/`tts(handle)` (`"speaking"`,
+  `"done"`, `"error"`, or `"unknown"` once a terminal state has already been
+  consumed) is polled to find out when it finishes. `pitch`/`speed` both
+  default to `1.0` (normal), the same convention as `termux-tts-speak`'s
+  `-p`/`-r`; native-bridge passes them straight to `TextToSpeech.setPitch()`/
+  `setSpeechRate()` with no unit conversion. `tts <text>` wraps the polling
+  loop for the common case, blocking the calling process until speech
+  finishes -- the same as any other CLI tool that waits for the thing it
+  started, and, like real TTS tooling (espeak-ng has no timeout concept at
+  all; Windows SAPI's `WaitUntilDone` documents `-1`/infinite as the default),
+  waits as long as it takes with no wall-clock cap by default. Pass
+  `--timeout <ms>` to opt into a bounded wait instead, or `-a`/`--async` to
+  not wait at all. `--pitch`/`--speed` override the environment; without
+  them, `tts` reads `$TTS_PITCH`/`$TTS_SPEED` itself (falling back to `1` for
+  either that is unset), so jsmdcui's own `TTS_PITCH`/`TTS_SPEED` convention
+  (which it sets on `Bun.env` before spawning a TTS command, inherited here
+  like any other child process env var) is honored automatically -- jsmdcui's
+  own `detectTtsCmd()` already falls back to a bare `Bun.which("tts")` after
+  termux-tts-speak/espeak-ng/espeak, which this `tts` now satisfies, but that
+  particular fallback branch passes no `-p`/`-r`-equivalent flags at all, so
+  reading the env vars directly here is the only way `tts`'s pitch/speed
+  actually reaches Android's TTS engine through that path.
+- Give `xclip` and `tts` a real fallback on non-Android platforms too, since
+  Buninu is cross-OS, not Android-only. `xclip`'s `-selection clipboard`
+  register now also tries jsmdcui's own `ClipboardManager`
+  (`src/platform/clipboard.js`, imported directly rather than reimplemented)
+  on win32/darwin, then `wl-copy`/`wl-paste` on Linux; `tts` gains a
+  `detectTtsCmd()` copied verbatim from jsmdcui's `src/index.js` (same
+  pitch/speed/lang math and command construction, including the win32
+  PowerShell/SAPI SSML branch, copied rather than hand-retyped since that
+  quoting is easy to silently break and this had no Windows machine to
+  verify it on) covering termux-tts-speak/say/PowerShell/espeak-ng/espeak.
+  Both deliberately skip the one path that would reintroduce the exact
+  self-reference risk they otherwise avoid: `ClipboardManager`'s Linux-like
+  branch searches PATH for a binary named `xclip`, and jsmdcui's own
+  `detectTtsCmd()` ends with a `Bun.which("tts")` fallback -- since these two
+  commands are themselves registered as Buninu's `xclip`/`tts`, ahead of
+  anything else of the same name on PATH, using either the way jsmdcui does
+  from inside xclip.js/tts.js would just be each script invoking itself.
+- Add `bin/*.bat` launchers for the new commands (`native-bridge`, `xclip`,
+  `tts`, `showimg`, `rz`, `sz`, `xdg-open`). POSIX platforms get their
+  `bin/<name>` entries as symlinks rebuilt by `bin/init.js` on startup,
+  which Windows cannot use, so each command needs its own `.bat` there.
+
+### Changed
+
+- Update the bundled jsmdcui to 0.18.1, which adds `switchBackend()` to
+  `src/cui/rpc.mjs` so an RPC caller can point at something other than the
+  default `rpc` endpoint -- specifically a unix socket, which is what
+  `native-bridge` dials. Also picks up 0.18.1's fix for decoding a
+  percent-encoded socket path, needed because `new URL("unix:" + sock)`
+  turns a leading NUL (a Linux abstract-namespace socket) into `%00`.
+- `native-bridge`'s CLI now prints `_discover` one function per line instead
+  of as a single line of JSON, which makes the list greppable. The value
+  itself is untouched -- rpc.mjs dispatches every call against that object,
+  so it stays exactly what the host returned; only the CLI's own display of
+  it changed.
+
 ## 0.2.3 - 2026-08-18
 
 ### Added

package/README.md

@@ -118,13 +118,20 @@ 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
+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) 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
@@ -137,6 +144,40 @@ matching binary. On Android, the underlying `bun i -g` currently needs
 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, call, available } from
+"apps/native-bridge/native-bridge.js"` gives the same functions as a library,
+for use from a `js back` block.
+
+`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.
+
 ## Export
 
 Export the current Buninu installation as a gzip-compressed tar archive:
@@ -184,6 +225,8 @@ paths obtained from Android APIs:
 
 - `PKG_DDIR`: `/storage/emulated/<user-id>/Android/data/<package>`.
 - `PKG_MDIR`: `/storage/emulated/<user-id>/Android/media/<package>`.
+- `PKG_BRIDGE_SOCK`: the `native-bridge` unix socket, when the host app
+  wires one in; see `native-bridge` above.
 
 ## Add a command
 

package/apps/cmdlist

@@ -20,3 +20,24 @@ buninu-help
 
 ### bunx — Globally install a package with bun, then exec its matching binary
 bunx
+
+### native-bridge — Call the Android host app (toast, clipboard) over PKG_BRIDGE_SOCK; bare invocation lists what the host implements
+native-bridge
+
+### xclip — X11-style clipboard tool; -selection clipboard/-clip bridges to the real Android clipboard via native-bridge
+xclip
+
+### tts — Speak text through the Android host and wait for it to finish (-a to not wait)
+tts
+
+### showimg — Shorthand for jsgotty --viu
+showimg
+
+### rz — Upload a file over ZMODEM (bun apps/jsgotty/rz.js)
+rz
+
+### sz — Download a file over ZMODEM (bun apps/jsgotty/sz.js)
+sz
+
+### xdg-open — Open a file or URL with the platform's default handler (native bridge on Android, open/start/xdg-open elsewhere)
+xdg-open

package/apps/jsmdcui/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.18.0] - 2026-08-19
+
+### Added
+
+- Add `switchBackend(endpoint)` to `rpc.mjs`, repointing every `rpc.*` call
+  (including `_discover`) at a different endpoint instead of the default
+  `"rpc"`. Returns the previous endpoint so a caller can restore it.
+- Accept a Bun unix socket as that endpoint: pass `"unix:/path/to/sock"` (or
+  `"UNIX:/path/to/sock"`) to `switchBackend`, and every `rpc.*` fetch is
+  issued over that socket via Bun's `unix` fetch option instead of as an
+  http path. Dispatch is unaffected, since routing is by function name in
+  the request body rather than by HTTP path. Only meaningful when `rpc.mjs`
+  runs under Bun (the `unix` fetch option has no effect in a browser).
+
 ## [0.17.3] - 2026-08-12
 
 ### Fixed

package/apps/jsmdcui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.17.3",
+  "version": "0.18.0",
   "description": "Markdown as a Common UI for Terminals and Web Browsers",
   "type": "module",
   "main": "./src/index.js",

package/apps/jsmdcui/src/cui/rpc.mjs

@@ -7,6 +7,35 @@ const crlf="\r\n"
 
 let apilist = new Map()
 
+//  Endpoint every frontend rpc fetch posts to. Returns the previous one.
+let rpcBackend = "rpc"
+
+export function switchBackend( endpoint )
+{
+  const previous = rpcBackend ;
+
+  rpcBackend = ( endpoint || "rpc" ) + "" ;
+
+  return previous ;
+}
+
+//  rpcBackend starting with "unix"/"UNIX" (e.g. "unix:/path/to/sock") names a
+//  Bun unix socket instead of an http path. fetch() rejects the unix: scheme
+//  outright, so the request goes to a fixed dummy URL and the real path comes
+//  from fetch's `unix` option instead; routing here is by func name in the
+//  JSON body, not by HTTP path, so the dummy URL costs nothing.
+const rpcFetchUrl = () =>
+  ( rpcBackend.slice(0,4) === "unix" || rpcBackend.slice(0,4) === "UNIX" )
+    ? "http://unix/rpc" : rpcBackend ;
+
+// decodeURIComponent undoes new URL()'s percent-encoding of the path, which
+// otherwise turns a leading NUL byte (a Linux abstract-namespace socket name,
+// e.g. "unix:\0name") into the three literal characters "%00" instead of the
+// single byte 0x00 Bun's `unix` option needs to actually reach it.
+const rpcFetchOpt = () =>
+  ( rpcBackend.slice(0,4) === "unix" || rpcBackend.slice(0,4) === "UNIX" )
+    ? { unix: decodeURIComponent(new URL(rpcBackend).pathname) } : {} ;
+
 export const jss = JSON.stringify
 
 const webMdcuiIdSource = String.raw`[_\p{L}\p{N}][_\p{L}\p{M}\p{N}:-]*`;
@@ -309,7 +338,7 @@ function webComponentMarkdownHtml(markdown)
   const source = String(markdown ?? "");
   if (typeof Bun !== "undefined" && Bun?.markdown?.html)
     return renderWebComponentMarkdownOnServer(source);
-  return fetch("rpc", {
+  return fetch(rpcFetchUrl(), { ...rpcFetchOpt(),
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify(["_mdcui_render_markdown", [source]]),
@@ -1389,7 +1418,7 @@ export const rpcraw = async (func,argv,envp)=>{
   const apilistMod = await FrontendDiscoverApi()
   
   if(apilistMod[func])
-    return await fetch("rpc", {
+    return await fetch(rpcFetchUrl(), { ...rpcFetchOpt(),
       method: "POST",
       body: JSON.stringify([
         func,argv,envp
@@ -1463,7 +1492,7 @@ export function getfuncparams( func )
 export async function FrontendDiscoverApi()
 {
   if(!apilist.get(0))
-    apilist.set(0, await fetch("rpc", {
+    apilist.set(0, await fetch(rpcFetchUrl(), { ...rpcFetchOpt(),
       method: "POST",
       body: JSON.stringify(["_discover"])
     }).then(r=>r.json()).catch(e=>e) ) ;

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

@@ -0,0 +1,154 @@
+// Called from a jsmdcui `js back` block (a Bun process), never from `js front`:
+// the `unix` fetch option native-bridge relies on only works under Bun, not
+// inside the Android WebView that renders front code.
+// rpc.mjs's rpc.* Proxy exists so a caller can dial an RPC by a name it only
+// knows at runtime; every call here uses a fixed, known-in-advance name, so
+// there is nothing that sugar buys us. Going straight to rpcraw also gets us
+// a real envp slot -- rpc.foo(...) always sends envp as {} (it is fed by the
+// Proxy's own internal `this`, not anything a caller supplies).
+import { rpcraw, switchBackend } from "../jsmdcui/src/cui/rpc.mjs"
+
+// PKG_BRIDGE_SOCK carries whatever rpc.mjs's rpcFetchOpt() needs after
+// decodeURIComponent(new URL("unix:"+sock).pathname): percent-encoded
+// (e.g. "%00native-bridge") for a Linux abstract-namespace socket -- an env
+// var cannot carry a literal NUL byte, but it can carry the three ASCII
+// characters "%00" -- or a plain path for a real filesystem socket, which
+// has nothing that needs encoding and passes through unchanged. Either way,
+// native-bridge.js does not decide which; it forwards the value as-is.
+const sock = process.env.PKG_BRIDGE_SOCK
+
+if (sock) switchBackend(`unix:${sock}`)
+
+// rpc.mjs never throws for a call the far side does not implement; it
+// resolves to a string starting with "Unknown func" instead (evalBack/rpcraw
+// in rpc.mjs both use this exact prefix). Default here is the same silent
+// behavior; call nothrow(false) to make native-bridge throw in that case
+// instead, so a missing PKG_BRIDGE_SOCK or an unimplemented host method fails
+// loudly rather than being mistaken for a successful result. Any value other
+// than an explicit `false` (including calling nothrow() with no argument)
+// restores the default silent behavior.
+let noThrowUnknownFunc = true
+
+export function nothrow(bool)
+{
+  noThrowUnknownFunc = bool !== false
+}
+
+// fetch() never times out on its own: if the host never answers (main thread
+// wedged, bridge crashed mid-request, anything), the await below would hang
+// forever without this race. The abandoned rpcraw() call keeps running in
+// the background after the race settles -- Bun's event loop treats a
+// pending fetch as a reason to stay alive, so it is not enough for this
+// function to merely return; whatever ultimately calls call() must still
+// process.exit() once it is done, or the process itself will not exit even
+// though every await has resolved.
+const DEFAULT_TIMEOUT_MS = 5000
+
+export async function call(name, args = [], envp, timeoutMs = DEFAULT_TIMEOUT_MS)
+{
+  if (!sock)
+    throw new Error(`native-bridge: PKG_BRIDGE_SOCK is not set (not running inside minapk's APK)`)
+
+  const result = await Promise.race([
+    rpcraw(name, args, envp),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(
+        `native-bridge: "${name}" timed out after ${timeoutMs}ms`)), timeoutMs)),
+  ])
+
+  if (!noThrowUnknownFunc && typeof result === "string" && result.startsWith("Unknown func"))
+    throw new Error(`native-bridge: host does not implement "${name}"`)
+
+  return result
+}
+
+export const available = () => !!sock
+
+// clipboardRead/clipboardWrite are long enough to want a short alias; toast
+// already is one. The Java dispatcher accepts either spelling over the wire
+// and lists both in its _discover response, so calling the alias directly
+// (e.g. from the CLI below, or another rpcraw caller) works too, not just
+// through these.
+export const toast = (text, long = false) => call("toast", [text, long])
+
+export const clipboardRead = () => call("clipboardRead")
+export const getcb = clipboardRead
+
+export const clipboardWrite = (text) => call("clipboardWrite", [text])
+export const setcb = clipboardWrite
+
+// TTS has no push/callback path over this protocol -- speak() only waits for
+// the host to accept the utterance, not for it to finish speaking, and
+// returns a handle immediately. Poll ttsStatus(handle) yourself ("speaking",
+// "done", "error", or "unknown" once a terminal state has already been
+// consumed) until it leaves "speaking"; apps/tts wraps that loop for the
+// common case instead of every caller writing its own.
+// Only text is required. 1.0 is normal for both speed and pitch, same
+// convention as termux-tts-speak's -p/-r; native-bridge does not assume any
+// particular caller's own default (jsmdcui's TTS_PITCH/TTS_SPEED, for
+// instance, default to 1/1.5 -- that is jsmdcui's own choice, read
+// TTS_PITCH/TTS_SPEED yourself if you want to honor it).
+export const speak = (text, speed = 1, pitch = 1, flush = false) =>
+  call("speak", [text, speed, pitch, flush])
+
+export const ttsStatus = (handle) => call("ttsStatus", [handle])
+export const tts = ttsStatus
+
+// target is either a URL (any scheme:// prefix, opened via ACTION_VIEW same
+// as a WebView link tap) or a path under Buninu's home -- served back out
+// through a read-only content:// provider, since the home directory is
+// otherwise private to this app and a raw file:// Uri would be rejected by
+// the receiving app on modern Android.
+export const xdgOpen = (target) => call("xdgOpen", [target])
+
+// `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
+// native function call on the host side: the result can be any JSON value
+// (string, number, boolean, null, array, object), not just a plain object,
+// so it is printed as-is rather than assumed to have any particular shape.
+// Each arg is JSON.parse'd when it parses cleanly (so `42`, `true`, `[1,2]`,
+// `{"a":1}` arrive as their real types) and kept as a plain string otherwise
+// (so `hi` stays "hi" rather than failing to parse as JSON). No func given at
+// all defaults to `_discover`, so a bare `bun native-bridge.js` lists what
+// the far side implements instead of erroring.
+export async function main()
+{
+  const [name = "_discover", ...rawArgs] = process.argv.slice(2)
+
+  const args = rawArgs.map(arg => {
+    try { return JSON.parse(arg) } catch { return arg }
+  })
+
+  try
+  {
+    const result = await call(name, args)
+
+    // Display-only: _discover's real value (an object, relied on as-is by
+    // rpc.mjs's own dispatch gate -- see FrontendDiscoverApi/rpcraw) is
+    // never touched. This only changes what gets printed here, one
+    // function per line instead of JSON.stringify's single-line output, so
+    // the list is easy to grep.
+    if (name === "_discover" && result && typeof result === "object")
+    {
+      const lines = Object.entries(result).map(([k, v]) => `"${k}":${JSON.stringify(v)}`)
+      console.log("{\n" + lines.join(",\n") + "\n}")
+    }
+    else
+    {
+      console.log(JSON.stringify(result))
+    }
+  }
+  catch (e)
+  {
+    console.error(e.message)
+    process.exit(1)
+  }
+
+  // Explicit exit even on success: see the note above call()'s timeout race
+  // -- an abandoned rpcraw() from a prior timeout can keep the process alive
+  // on its own otherwise.
+  process.exit(0)
+}
+
+if (import.meta.main) main()

package/apps/native-bridge/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "native-bridge",
+  "version": "0.1.0",
+  "description": "Call the Android host app (toast, clipboard, ...) from a Buninu Bun back script, over the unix socket minapk exposes as PKG_BRIDGE_SOCK",
+  "type": "module",
+  "main": "./native-bridge.js",
+  "license": "MIT"
+}

package/apps/tts/tts.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+
+// Wraps native-bridge's raw speak()/ttsStatus() -- which never block, since
+// TextToSpeech's completion signal is a callback the far side has no way to
+// push to us over this protocol -- in the polling loop most callers actually
+// want. Invoked as a subprocess this necessarily blocks the caller until
+// speech finishes (or --async is given): that is expected, the same as any
+// other CLI tool that waits for the thing it started.
+import { speak, ttsStatus, available } from "../native-bridge/native-bridge.js"
+
+// Buninu is cross-OS, not just Android: when native-bridge isn't available,
+// fall back to a locally-spawned platform TTS command instead of just
+// failing. This block is copied verbatim from jsmdcui's own
+// src/index.js detectTtsCmd() (same pitch/speed/lang math, same command
+// construction) rather than reimplemented, since the PowerShell quoting in
+// the win32 branch is exactly the kind of thing that is easy to silently
+// break by hand-retyping and hard to verify without a real Windows machine.
+//
+// One deliberate omission from the original: it ends with an
+// `if (Bun.which("tts")) return {cmd:['tts'],via:'arg'}` fallback. Calling
+// that from inside this exact script (also registered as Buninu's "tts"
+// command, ahead of anything else named "tts" on PATH) would just be this
+// script invoking itself -- the same self-reference risk xclip.js avoids
+// around ClipboardManager's own "xclip" search, so it is left out here.
+function detectTtsCmd(speed, pitch) {
+  const platform = process.platform;
+
+  const lang = process.env.TTS_LANG || 'zh-TW'
+  process.env.TTS_LANG = lang ;
+
+  if (platform === "android") {
+    if (Bun.which("termux-tts-speak"))
+      return { cmd: ["termux-tts-speak", "-p", String(pitch), "-r", String(speed)], via: "arg" };
+  }
+
+  if (platform === "darwin") {
+    // say -r <wpm>; pitch via [[pbas n]] embedded TTS command (0-127, 48 = normal)
+    const rate = Math.round(175 * speed);
+    const pitchN = Math.max(0, Math.min(127, Math.round(48 * pitch)));
+    return {
+      cmd: ["say", "-r", String(rate)],
+      via: "arg",
+      textTransform: pitchN !== 48 ? (t) => `[[pbas ${pitchN}]] ${t}` : null,
+    };
+  }
+
+  if (platform === "win32") {
+    // Rate property: -10 to 10 (0 = normal); pitch via SSML <prosody>
+    const rate = Math.max(-10, Math.min(10, Math.round((speed - 1) * 10)));
+    const pitchPct = Math.round((pitch - 1) * 100);
+    const pitchAttr = (pitchPct >= 0 ? "+" : "") + pitchPct + "%";
+    for (const shell of ["pwsh.exe", "powershell.exe"]) {
+      if (Bun.which(shell)) {
+        const psCmd =
+          "Add-Type -AssemblyName System.Speech; " +
+          `$s = New-Object System.Speech.Synthesis.SpeechSynthesizer; $s.Rate = ${rate}; ` +
+          `$t = [Console]::In.ReadToEnd(); ` +
+          `$x = [System.Security.SecurityElement]::Escape($t); ` +
+          `$s.SpeakSsml('<speak xml:lang="${lang}" version="1.0" xmlns="http://www.w3.org/2001/10/synthesis"><prosody pitch="${pitchAttr}">' + $x + '</prosody></speak>')`;
+        return { cmd: [shell, "-NoProfile", "-Command", psCmd], via: "stdin" };
+      }
+    }
+  }
+
+  // Linux / Android fallback: espeak-ng / espeak
+  // Speed: -s <wpm> (175 = normal), Pitch: -p <n> (0-99, 50 = normal)
+  for (const bin of ["espeak-ng", "espeak"]) {
+    if (Bun.which(bin)) {
+      const spd = Math.round(175 * speed);
+      const pit = Math.max(0, Math.min(99, Math.round(50 * pitch)));
+      return { cmd: [bin, '-s', spd, '-p', pit], via: "arg" };
+    }
+  }
+
+  return null;
+}
+
+// Also copied verbatim (as the spawn side of the same jsmdcui code path,
+// runTts) other than operating on the whole text at once instead of
+// per-sentence, since a CLI invocation has no buffer/cursor to highlight
+// against sentence by sentence the way the jsmdcui TUI does.
+async function speakViaPlatformCommand(text, cmd) {
+  const spawnOpts = { stdout: "ignore", stderr: "ignore", env: process.env };
+  spawnOpts.stdin = cmd.via === "stdin" ? new Blob([text]) : "ignore";
+
+  if (cmd.via === "arg") {
+    text = (text + "")
+      .replace(/^-+/, "")
+      .replaceAll("`", "")
+      .replaceAll("$", "");
+    if (cmd.textTransform) text = cmd.textTransform(text);
+  }
+  const args = cmd.via === "arg" ? [...cmd.cmd, text] : cmd.cmd;
+  const proc = Bun.spawn(args, spawnOpts);
+  return await proc.exited;
+}
+
+// Not too short: each tick is a full unix-socket round trip, and TTS
+// utterances run several seconds at minimum, so polling faster just burns
+// cycles without getting the answer any sooner.
+const POLL_MS = 500
+
+// No wall-clock cap by default. Real TTS tooling doesn't invent one: espeak-ng
+// has no timeout concept at all (its man page documents speed/pitch/gaps but
+// nothing about how long it may block), and Windows SAPI's WaitUntilDone
+// treats -1 ("wait forever") as the documented default -- a fixed cap here
+// would just mean this tool gives up early on long text, which has nothing
+// to do with the host actually being broken. The loop below still can't hang
+// on a genuinely dead host: each poll has call()'s own 5s timeout (throws,
+// caught below), and the loop condition itself already exits the moment
+// status leaves "speaking" -- "unknown"/"error" are the real failure signal,
+// not a timer. Pass --timeout to opt into a bounded wait instead.
+const argv = process.argv.slice(2)
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(`
+ Usage: tts <text>
+  tts "hello world"
+  tts -f "interrupt and say this instead"
+  tts -a "say this, don't wait for it to finish"
+  tts --timeout 30000 "give up after 30s if still speaking"
+  tts --pitch 1.2 --speed 0.8 "slower and higher-pitched"
+
+ -f, --flush       interrupt whatever is currently speaking
+ -a, --async       print the handle and exit immediately instead of polling
+ --timeout <ms>    give up and exit non-zero after this long (default: none,
+                    wait as long as it takes -- matches espeak-ng/SAPI)
+ --pitch <n>       1.0 is normal (default: $TTS_PITCH, or 1 if unset)
+ --speed <n>       1.0 is normal (default: $TTS_SPEED, or 1 if unset)
+`)
+  process.exit(0)
+}
+
+const flush = argv.includes("-f") || argv.includes("--flush")
+const isAsync = argv.includes("-a") || argv.includes("--async")
+
+const optValue = (flag, envFallback) => {
+  const i = argv.indexOf(flag)
+  const raw = i !== -1 ? argv[i + 1] : process.env[envFallback]
+  const n = Number(raw)
+  return Number.isFinite(n) ? n : 1
+}
+const timeoutIdx = argv.indexOf("--timeout")
+const maxWaitMs = timeoutIdx !== -1 ? Number(argv[timeoutIdx + 1]) : null
+const pitch = optValue("--pitch", "TTS_PITCH")
+const speed = optValue("--speed", "TTS_SPEED")
+
+const valueFlags = new Set(["--timeout", "--pitch", "--speed"])
+const text = argv.find((a, i) => !a.startsWith("-") && !valueFlags.has(argv[i - 1])) ?? ""
+
+if (!available()) {
+  // No Android native bridge -- fall back to a local platform TTS command
+  // (see detectTtsCmd() above). flush/polling/handles are all native-bridge
+  // concepts specific to Android's async TextToSpeech callback; there is no
+  // equivalent "interrupt what's currently speaking" here, so -f/--flush is
+  // silently a no-op on this path.
+  const cmd = detectTtsCmd(speed, pitch)
+  if (!cmd) {
+    console.error("no TTS backend found: no native bridge, and no termux-tts-speak/say/PowerShell/espeak-ng/espeak on PATH")
+    process.exit(1)
+  }
+
+  if (isAsync) {
+    speakViaPlatformCommand(text, cmd)
+    process.exit(0)
+  }
+
+  const code = await speakViaPlatformCommand(text, cmd)
+  process.exit(code === 0 ? 0 : 1)
+}
+
+let handle
+try {
+  handle = await speak(text, speed, pitch, flush)
+} catch (e) {
+  console.error(`speak failed: ${e.message}`)
+  process.exit(1)
+}
+
+if (isAsync) {
+  console.log(handle)
+  process.exit(0)
+}
+
+const start = Date.now()
+let status = "speaking"
+
+while (status === "speaking") {
+  if (maxWaitMs != null && Date.now() - start > maxWaitMs) {
+    console.error(`tts: gave up waiting for "${handle}" after ${maxWaitMs}ms`)
+    process.exit(1)
+  }
+
+  await new Promise(resolve => setTimeout(resolve, POLL_MS))
+
+  try {
+    status = await ttsStatus(handle)
+  } catch (e) {
+    console.error(`ttsStatus failed: ${e.message}`)
+    process.exit(1)
+  }
+}
+
+if (status === "error") {
+  console.error(`tts: "${handle}" reported an error`)
+  process.exit(1)
+}
+
+if (status === "unknown") {
+  console.error(`tts: "${handle}" went unknown before finishing`)
+  process.exit(1)
+}
+
+process.exit(0)

package/apps/xclip/xclip.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env bun
+
+// Ported from ../tmpk/bin/xclip.sh (the DroidScript-era xclip). That version
+// bridged to native only through DroidScript's dsapi.pipe; this one uses
+// native-bridge instead. The core semantics are unchanged: "primary" is
+// local-file-only (matches X11's mouse-selection clipboard, which xclip also
+// keeps separate from the real clipboard), and only "-selection clipboard"
+// (or its "-clip"/"-clipboard" shorthand) touches the real system clipboard.
+import { getcb, setcb, available } from "../native-bridge/native-bridge.js"
+import { ClipboardManager } from "../jsmdcui/src/platform/clipboard.js"
+
+// Buninu is cross-OS, not just Android, so the "clipboard" register falls
+// back through: native-bridge (Android) -> jsmdcui's own ClipboardManager
+// (win32/darwin only, see below) -> wl-copy/wl-paste (Linux, Wayland).
+//
+// ClipboardManager is deliberately NOT used on Linux-like platforms
+// (including Android): its own backend detection searches PATH for a binary
+// literally named "xclip" there, and this script is itself registered as
+// Buninu's "xclip" command, ahead of any real system xclip on PATH -- using
+// it here would make this script shell out to itself. Its win32/darwin
+// branches never search for "xclip" at all, so those two are safe.
+let desktopClipboard = null
+function getDesktopClipboard() {
+  if (process.platform !== "win32" && process.platform !== "darwin") return null
+  if (!desktopClipboard) desktopClipboard = new ClipboardManager()
+  return desktopClipboard
+}
+
+const wlAvailable = () => !!(Bun.which("wl-copy") && Bun.which("wl-paste"))
+const wlRead = () => {
+  const proc = Bun.spawnSync(["wl-paste", "--no-newline"])
+  return proc.success ? new TextDecoder().decode(proc.stdout) : null
+}
+const wlWrite = (text) => Bun.spawnSync(["wl-copy"], { stdin: Buffer.from(text) }).success
+
+const argv = process.argv.slice(2)
+
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(`
+ Usage: Paste/Copy
+  xclip -o [-selection clipboard]
+  xclip -o [-clip]
+  echo hello | xclip [-selection clipboard]
+  echo hello | xclip [-clip]
+
+ Uses primary by default(mouse selection)
+`)
+  process.exit(0)
+}
+
+const selMatch = argv.join(" ").match(/-selection\s+(\S+)/)
+const cb = selMatch ? selMatch[1]
+  : argv.some(a => a.includes("-clip")) ? "clipboard"
+  : "primary"
+
+process.stderr.write(`\x1b[35mClipboard 剪貼板📋 ： ${cb} \n\x1b[0m`)
+
+const cbf = `${process.env.HOME}/.xclip.${cb}`
+const useNative = cb !== "primary"
+const desktop = useNative ? getDesktopClipboard() : null
+
+if (useNative && !available() && !desktop && !wlAvailable())
+  process.stderr.write(`no system clipboard found (no native bridge, no ClipboardManager backend, no wl-copy/wl-paste)\nNo native clipboard now!\n`)
+
+const isPaste = argv.some(a => a.toLowerCase() === "-o")
+
+if (isPaste) {
+  process.stderr.write(`\x1b[33mPaste 貼上 📋 \n\x1b[0m`)
+
+  if (useNative) {
+    if (available()) {
+      try {
+        await Bun.write(cbf, (await getcb()) ?? "")
+      } catch (e) {
+        process.stderr.write(`getcb failed: ${e.message}\n`)
+      }
+    } else if (desktop) {
+      try {
+        await Bun.write(cbf, desktop.read("clipboard") ?? "")
+      } catch (e) {
+        process.stderr.write(`clipboard read failed: ${e.message}\n`)
+      }
+    } else if (wlAvailable()) {
+      const text = wlRead()
+      if (text != null) await Bun.write(cbf, text)
+    }
+  }
+
+  const file = Bun.file(cbf)
+  if (await file.exists()) process.stdout.write(new Uint8Array(await file.arrayBuffer()))
+} else {
+  process.stderr.write(`\x1b[33mCopy 複製 ✂️ \n\x1b[0m`)
+
+  const input = await Bun.stdin.arrayBuffer()
+  await Bun.write(cbf, input)
+
+  if (useNative) {
+    if (available()) {
+      try {
+        await setcb(new TextDecoder().decode(input))
+      } catch (e) {
+        process.stderr.write(`setcb failed: ${e.message}\n`)
+      }
+    } else if (desktop) {
+      try {
+        desktop.write(new TextDecoder().decode(input), "clipboard")
+      } catch (e) {
+        process.stderr.write(`clipboard write failed: ${e.message}\n`)
+      }
+    } else if (wlAvailable()) {
+      wlWrite(new TextDecoder().decode(input))
+    }
+  }
+}
+
+// Explicit exit: call()'s own timeout race means every await above is
+// guaranteed to settle, but a getcb()/setcb() that hit that timeout leaves
+// an abandoned fetch running, which keeps Bun's event loop alive on its own.
+// Without this, xclip could still hang after printing everything it needs
+// to -- the shell would just never get its prompt back.
+process.exit(0)

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env bun
+
+// Android goes through native-bridge's xdgOpen (MainActivity.java validates
+// the path stays under Buninu's home and serves it back out through a
+// read-only content:// provider; a bare URL just goes to ACTION_VIEW). The
+// other platforms each have their own "open with whatever the OS thinks is
+// 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"
+const fs = require("fs")
+
+// 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
+// would just find this file. Skip Buninu's own bin dir and keep looking
+// further down PATH for wherever a real xdg-open actually lives.
+function findSystemXdgOpen() {
+  const ownBinDir = process.env.BUNINU_HOME ? `${process.env.BUNINU_HOME}/bin` : null
+  for (const dir of (process.env.PATH || "").split(":").filter(Boolean)) {
+    if (dir === ownBinDir) continue
+    const candidate = `${dir}/xdg-open`
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK)
+      return candidate
+    } catch {}
+  }
+  return null
+}
+
+async function runCommand(args) {
+  const proc = Bun.spawn(args, { stdout: "ignore", stderr: "ignore" })
+  return (await proc.exited) === 0
+}
+
+const argv = process.argv.slice(2)
+
+if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+  console.log("usage: xdg-open <file-or-url>")
+  process.exit(argv.length === 0 ? 1 : 0)
+}
+
+const target = argv[0]
+let ok = false
+
+try {
+  if (process.platform === "android") {
+    if (available()) {
+      ok = 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
+      // ACTION_VIEW-based open, same fallback relationship as tts.js's
+      // termux-tts-speak branch when native-bridge isn't available.
+      ok = await runCommand(["termux-open", target])
+    } else {
+      throw new Error("no native bridge and no termux-open (install termux-api, or run inside minapk's APK)")
+    }
+  } else if (process.platform === "darwin") {
+    ok = await runCommand(["open", target])
+  } else if (process.platform === "win32") {
+    // start is a cmd builtin, not a real executable, and needs an empty ""
+    // title argument first or it treats a quoted target as the title.
+    ok = await runCommand(["cmd", "/c", "start", "", target])
+  } else {
+    const real = findSystemXdgOpen()
+    if (!real) throw new Error("no system xdg-open found on PATH")
+    ok = await runCommand([real, target])
+  }
+} catch (e) {
+  process.stderr.write(`xdg-open: ${e.message}\n`)
+  process.exit(1)
+}
+
+// Explicit exit: bridgeOpen() goes through native-bridge's call(), whose own
+// timeout race leaves an abandoned fetch running the event loop on a
+// timeout -- without this, xdg-open could hang after printing everything it
+// needs to.
+process.exit(ok ? 0 : 1)

package/bin/native-bridge.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\native-bridge\native-bridge.js" %*
+exit /b %ERRORLEVEL%

package/bin/rz.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\jsgotty\rz.js" %*
+exit /b %ERRORLEVEL%

package/bin/rz.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+sd=$(dirname "$(realpath "$0")")
+
+exec bun "$sd"/../apps/jsgotty/rz.js "$@"

package/bin/showimg.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\jsgotty\gotty.js" --viu %*
+exit /b %ERRORLEVEL%

package/bin/showimg.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+sd=$(dirname "$(realpath "$0")")
+
+exec bun "$sd"/../apps/jsgotty/gotty.js --viu "$@"

package/bin/sz.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\jsgotty\sz.js" %*
+exit /b %ERRORLEVEL%

package/bin/sz.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+sd=$(dirname "$(realpath "$0")")
+
+exec bun "$sd"/../apps/jsgotty/sz.js "$@"

package/bin/tts.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\tts\tts.js" %*
+exit /b %ERRORLEVEL%

package/bin/xclip.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\xclip\xclip.js" %*
+exit /b %ERRORLEVEL%

package/bin/xdg-open.bat

@@ -0,0 +1,3 @@
+@echo off
+call "%~dp0bun.bat" "%~dp0..\apps\xdg-open\xdg-open.js" %*
+exit /b %ERRORLEVEL%

package/package.json

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