sandboxedjs 0.1.3 → 0.1.4

package/README.md

@@ -45,6 +45,7 @@ Node 18.17+. Everything is pure JavaScript and WebAssembly — no compilation st
 | **Coreutils** | 154 programs — `ls cat cp mv rm mkdir grep sed awk find head tail sort uniq wc cut tr tee xargs chmod chown ln du df ps tar gzip base64 sha256sum diff curl wget` and the rest — plus 54 shell builtins |
 | **Node.js** | Real Node semantics via Nodepod — `require`, npm packages, `http`, `fs`, streams, `worker_threads` |
 | **Python** | MicroPython on WebAssembly, mounted on the *same* filesystem |
+| **FFmpeg** | `ffmpeg` and `ffprobe` (FFmpeg 5.1) reading and writing container files directly — [optional install](#video-and-audio) |
 | **`/proc`** | Live and synthesised — `ps`, `top`, `free` and `uptime` all read the same source |
 | **Networking** | Virtual interfaces, `/etc/hosts` resolution, in-container HTTP servers, an optional bridge to a real host port |
 | **Users** | Real `/etc/passwd` and `/etc/group`; `useradd`, `su`, `sudo`, and permission checks that deny for real — for the shell and Python, [but not Node](#the-in-container-user-model-does-not-constrain-nodejs) |
@@ -587,15 +588,51 @@ Those three use dynamic imports, so they only fail if you call them.
 removed and the seam is there, but treat browser support as "should work, unproven" rather than
 a tested claim.
 
+## Video and audio
+
+`ffmpeg` and `ffprobe` are FFmpeg 5.1 compiled to WebAssembly, mounted on the container's own
+filesystem. The mount is the point: inputs and outputs are ordinary container files, so nothing
+is staged in or copied back and a pipeline can be built out of scripts and pipes as usual.
+
+The runtime is ~31MB of WebAssembly, which is a lot to force on someone who wants a shell, so it
+installs separately. Without it the commands report themselves as missing, exactly as a real
+system reports an uninstalled binary:
+
+```bash
+npm install @ffmpeg/core
+```
+
+```js
+const box = await createContainer({ cwd: "/media" });
+
+// Make a clip, then transcode it — both files are just container files.
+await box.exec("ffmpeg -f lavfi -i testsrc=size=640x480:rate=25:duration=5 -pix_fmt yuv420p clip.mp4");
+await box.exec("ffmpeg -i clip.mp4 -vf scale=320:-2 -frames:v 1 thumb.png");
+
+const thumbnail = await box.fs.readFile("/media/thumb.png");
+```
+
+Every FFmpeg invocation gets a fresh WebAssembly instance, because FFmpeg ends by calling
+`exit()` and tears its runtime down as it goes; the compiled module is cached, so only the cheap
+half is repeated. Runs are synchronous — a long transcode occupies the thread until it finishes.
+
+Two caveats worth knowing:
+
+- **`ffprobe` does not report an exit status.** Whenever it does real work this build leaves
+  through `exit()` without setting a return value, so success and failure are indistinguishable
+  to the caller. It is reported as success; branch on its *output*, not its exit code. `ffmpeg`
+  itself reports status correctly and can be relied on in `&&` chains.
+- **No hardware acceleration and no native codecs** beyond what the WebAssembly build ships.
+
 ## Known limits
 
 Honest list of what does not work:
 
-- **Vite's dev server** loads and reads its config, then stops when esbuild starts: Nodepod
-  initialises esbuild by importing it from a CDN over `https:`, which the Node ESM loader
-  refuses. Anything that needs esbuild — Vite, and tools built on it — is therefore unavailable
-  under Node. Express, Koa, Fastify-style apps and plain `http` servers work. See
-  `examples/react-app` for a React setup that runs.
+- **esbuild-based toolchains.** Nodepod boots esbuild by importing it from a CDN over `https:`,
+  which the Node ESM loader refuses, so anything routed through esbuild cannot start under Node.
+  This affects older toolchains — Vite 4 and its contemporaries. Current Vite ships its Rust
+  pipeline as WebAssembly and runs fine, dev server included, as do Express, Koa, Fastify-style
+  apps and plain `http` servers.
 - **Python is MicroPython**, so C extensions (`numpy`, `pandas`, `cryptography`) are unavailable.
 - **No real sockets.** HTTP servers work through the request proxy; raw TCP/UDP does not.
 - **No real processes.** Processes are cooperative async tasks: `kill -9` cannot interrupt a