From 1ea8f333f75484f5f176805dc2a80b69bd510dab Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sat, 31 Oct 2026 15:29:52 -0500
Subject: [PATCH 1/5] Ship a Node entry in the package: dist/node.js exports
 runNode and is the java-web command, reading the packaged JDK image

---
 .github/workflows/release.yml |  2 +
 .github/workflows/test.yml    |  2 +
 AGENTS.md                     |  8 ++--
 README.md                     | 13 ++++++
 docs/browser.md               |  2 +-
 docs/node.md                  | 53 +++++++++++++++++++++++
 package.json                  |  5 +++
 scripts/build-web.ts          | 13 +++++-
 src/browser/http.ts           | 21 +++++----
 src/image.ts                  | 58 +++++++++++++++++++++++++
 src/node.ts                   | 12 ++++--
 test/image.test.ts            | 81 +++++++++++++++++++++++++++++++++++
 12 files changed, 253 insertions(+), 17 deletions(-)
 create mode 100644 docs/node.md
 create mode 100644 src/image.ts
 create mode 100644 test/image.test.ts

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 05889ca..dee22c4 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -37,4 +37,6 @@ jobs:
           git -C build/ref/jdk25u sparse-checkout set test/lib test/jdk/lib test/jdk/tools/lib $dirs
           node scripts/jtreg/run.ts build/ref/jdk25u --only-passing --jobs 4
       - run: pnpm build
+      - name: Node entry on the built dist/
+        run: node --expose-gc --test test/image.test.ts
       - run: npm publish
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 937e176..a48c45c 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -34,3 +34,5 @@ jobs:
       - run: pnpm typecheck
       - run: pnpm test
       - run: pnpm build
+      - name: Node entry on the built dist/
+        run: node --expose-gc --test test/image.test.ts
diff --git a/AGENTS.md b/AGENTS.md
index 3cbc11a..5358489 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,8 +30,9 @@ Node, which is how the tests run.
   (`natives`, `javaProperties`), `cheerpjRunMain`, `cheerpjRunLibrary`
   (static String calls), `cheerpOSAddStringFile`, `cjFileBlob`, `/files/` in
   IndexedDB and one VM per about:blank iframe. Keep these working.
-- The release form is an npm package of the built browser files only
-  (`java-web.js`, `java-web-worker.js`, `boot.pack`, `jdk/<module>.jar`,
+- The release form is an npm package of the built files only
+  (`java-web.js`, `java-web-worker.js`, `node.js` (the Node entry and the
+  `java-web` command), `boot.pack`, `jdk/<module>.jar`,
   `jdk/javac.pack`, `jdk/jdk.localedata.txt`, and OpenJDK's notices in `jdk/legal/`), versioned, with
   nothing built at install. A GitHub Actions workflow triggered by a release
   publishes it to npm; never publish by hand.
@@ -50,7 +51,8 @@ Node, which is how the tests run.
   `font*.ts` are the font natives (scaler, fontconfig, layout) over one TrueType font
 - `src/sockets.ts` sockets (`Sock`, POSIX readiness) and the in-VM loopback backend;
   `src/net-node.ts` host sockets, DNS and interfaces for Node
-- `src/node.ts` Node entry; `scripts/build-jdk.sh` builds `build/jdk`
+- `src/node.ts` Node entry, over `build/jdk` or, built as `dist/node.js`, the
+  packaged image (`src/image.ts`); `scripts/build-jdk.sh` builds `build/jdk`
 - `src/http-proxy.ts` the browser's virtual HTTP proxy (`fetch`); `scripts/tls/` the
   `javaweb.tls` pass-through TLS provider it relies on for `https:`
 
diff --git a/README.md b/README.md
index 44e41d7..35699b7 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,19 @@ Serve `node_modules/java-web/dist/` as static files, then:
 `cheerpjRunMain`, `cheerpjRunLibrary` (call Java from JS), JS natives and
 `/files/` storage work too. See [docs/browser.md](docs/browser.md).
 
+## Use it under Node
+
+```sh
+npx java-web -cp classes Main          # or: npx java-web -jar app.jar
+```
+
+```js
+import { runNode } from "java-web";
+const code = await runNode({ classpath: ["classes"], mainClass: "Main" });
+```
+
+See [docs/node.md](docs/node.md).
+
 ## What runs
 
 - Console apps, libraries and javac: every Java SE module, plus `jdk.compiler`,
diff --git a/docs/browser.md b/docs/browser.md
index 22ead88..61eb173 100644
--- a/docs/browser.md
+++ b/docs/browser.md
@@ -1,7 +1,7 @@
 # Using java-web in a page
 
 The npm package holds the built files: `java-web.js`, `java-web-worker.js`,
-`boot.pack` and `jdk/`. Serve `node_modules/java-web/dist/` as static files
+`boot.pack` and `jdk/` for pages, and `node.js` for Node ([node.md](node.md)). Serve `node_modules/java-web/dist/` as static files
 and load `java-web.js` with a classic `<script>` tag. It finds the other files
 next to itself, or where `cheerpjInit({ runtime: "/path/to/dist/" })` says.
 
diff --git a/docs/node.md b/docs/node.md
new file mode 100644
index 0000000..c212a82
--- /dev/null
+++ b/docs/node.md
@@ -0,0 +1,53 @@
+# Using java-web under Node
+
+The package's Node entry runs Java on Node 23.6 or newer, against the same
+packaged JDK image (`dist/boot.pack`, `dist/jdk/`) that pages use. The host file
+system is the VFS root, and Java sees the host's environment.
+
+## Command
+
+```sh
+npx java-web [options] Main [args]
+npx java-web [options] -jar app.jar [args]
+```
+
+| Option | Meaning |
+|---|---|
+| `-cp`, `-classpath`, `--class-path` | class path, `:`-separated (default `.`) |
+| `-Dkey=value` | a system property |
+| `-ea`, `-da`, `-esa` and the rest | assertions, as with `java` |
+| `--enable-preview` | preview features |
+| `--add-exports`, `--add-opens`, `--add-reads`, `--add-modules`, `--module-path`, `-p` | module options, as with `java` |
+| `--locale-data` | locales other than English (see [support.md](support.md#locales)) |
+| `--max-rss MB` | exit when resident memory passes this (default 2048) |
+| `--jdk DIR` | an exploded JDK image instead of the packaged one |
+| `--debug` | log VM events |
+
+Other `-X` and HotSpot-only options are ignored.
+
+## From JS
+
+```js
+import { runNode } from "java-web";
+
+const out = [];
+const code = await runNode({
+  classpath: ["classes"],
+  mainClass: "Main",        // or jar: "app.jar"
+  args: ["a", "b"],
+  stdout: (bytes) => out.push(bytes),
+});
+```
+
+`runNode` resolves to the exit code. Its options:
+
+- `classpath`, `mainClass` or `jar`, `args`, `props` (system properties)
+- `stdout`, `stderr` (byte callbacks; default the process's), `input` (fixed stdin bytes)
+- `env` (what `System.getenv()` returns; default the host's environment)
+- `natives`: Java `native` methods in JS, as in the browser ([browser.md](browser.md))
+- `assertions` (the flags, for example `["-ea"]`), `enablePreview`, `localeData`
+- `hostName` (what `InetAddress.getLocalHost()` reports), `maxRssMb`, `jdk`, `debug`
+
+`startLibrary(options)` starts a VM in library mode, and `libraryOf(vm)` is its
+`lib`, used as `cheerpjRunLibrary`'s result is in the browser. `vm.halt(0)`
+stops it.
diff --git a/package.json b/package.json
index 5582192..8be6649 100644
--- a/package.json
+++ b/package.json
@@ -19,11 +19,16 @@
   "license": "AGPL-3.0-only",
   "type": "module",
   "exports": {
+    ".": "./dist/node.js",
     "./dist/*": "./dist/*"
   },
+  "bin": {
+    "java-web": "dist/node.js"
+  },
   "files": [
     "dist/java-web.js",
     "dist/java-web-worker.js",
+    "dist/node.js",
     "dist/boot.pack",
     "dist/jdk/*.jar",
     "dist/jdk/javac.pack",
diff --git a/scripts/build-web.ts b/scripts/build-web.ts
index 09eae8f..a2e74f8 100644
--- a/scripts/build-web.ts
+++ b/scripts/build-web.ts
@@ -1,4 +1,4 @@
-// Builds dist/: the browser runtime (java-web.js + worker), the JDK image,
+// Builds dist/: the browser runtime (java-web.js + worker), the Node entry, the JDK image,
 // a boot pack with the JDK files a typical start needs, a javac pack the
 // worker fetches the first time javac runs, and the demo page.
 // Run `pnpm jdk` first.
@@ -33,6 +33,17 @@ for (const [entry, out] of [["api.ts", "java-web.js"], ["worker.ts", "java-web-w
   });
 }
 
+// the Node entry (runNode and the java-web command), over the packaged image next to it
+await build({
+  entryPoints: [join(root, "src", "node.ts")],
+  outfile: join(dist, "node.js"),
+  bundle: true,
+  platform: "node",
+  format: "esm",
+  target: "node23",
+  banner: { js: "#!/usr/bin/env node" },
+});
+
 mkdirSync(join(dist, "jdk"), { recursive: true });
 
 const samples = join(root, "web", "samples");
diff --git a/src/browser/http.ts b/src/browser/http.ts
index 853aaa3..f3dccb3 100644
--- a/src/browser/http.ts
+++ b/src/browser/http.ts
@@ -214,14 +214,17 @@ export class HttpBackend implements Backend {
   }
 
   list(path: string): string[] | null {
-    const idx = this.pack.index;
-    if (!idx) return null;
-    if (idx.get(path) !== -1) return null;
-    const prefix = path === "/" ? "/" : path + "/";
-    const out: string[] = [];
-    for (const p of idx.keys()) {
-      if (p.startsWith(prefix) && p.length > prefix.length && !p.slice(prefix.length).includes("/")) out.push(p.slice(prefix.length));
-    }
-    return out;
+    return this.pack.index ? listIndex(this.pack.index, path) : null;
+  }
+}
+
+// The names in a directory of a pack index, or null if path is not one.
+export function listIndex(idx: Map<string, number>, path: string): string[] | null {
+  if (idx.get(path) !== -1) return null;
+  const prefix = path === "/" ? "/" : path + "/";
+  const out: string[] = [];
+  for (const p of idx.keys()) {
+    if (p.startsWith(prefix) && p.length > prefix.length && !p.slice(prefix.length).includes("/")) out.push(p.slice(prefix.length));
   }
+  return out;
 }
diff --git a/src/image.ts b/src/image.ts
new file mode 100644
index 0000000..7b97572
--- /dev/null
+++ b/src/image.ts
@@ -0,0 +1,58 @@
+// The JDK image as `pnpm build` packages it in dist/, read from disk under
+// Node: boot.pack holds the index and the files a typical start reads, and
+// every other file is read at its offset in jdk/<module>.jar.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { addIndex, listIndex, parsePack } from "./browser/http.ts";
+import type { Pack } from "./browser/http.ts";
+import type { Backend, Stat } from "./fs.ts";
+
+// open module images by host path, shared by every VM in the process
+const images = new Map<string, number>();
+
+export class ImageBackend implements Backend {
+  readonly writable = false;
+  private readonly dir: string;
+  private readonly pack: Pack;
+
+  // dir holds boot.pack and jdk/; localeData adds jdk.localedata's files
+  constructor(dir: string, localeData = false) {
+    this.dir = path.resolve(dir);
+    const buf = fs.readFileSync(path.join(this.dir, "boot.pack"));
+    this.pack = parsePack(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+    if (localeData) addIndex(this.pack, fs.readFileSync(path.join(this.dir, "jdk", "jdk.localedata.txt"), "utf8"));
+  }
+
+  stat(p: string): Stat | null {
+    const size = this.pack.index!.get(p);
+    return size === undefined ? null : { dir: size < 0, size: Math.max(size, 0), mtime: 0 };
+  }
+
+  read(p: string): Uint8Array | null {
+    const size = this.pack.index!.get(p);
+    return size === undefined || size < 0 ? null : this.readRange(p, 0, size);
+  }
+
+  readRange(p: string, off: number, len: number): Uint8Array | null {
+    const packed = this.pack.files.get(p);
+    if (packed) return packed.subarray(off, off + len);
+    const at = this.pack.offsets.get(p);
+    if (!at) return null;
+    const file = path.join(this.dir, "jdk", at.image);
+    let fd = images.get(file);
+    if (fd === undefined) images.set(file, (fd = fs.openSync(file, "r")));
+    const out = new Uint8Array(len);
+    let n = 0;
+    while (n < len) {
+      const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
+      if (got === 0) break;
+      n += got;
+    }
+    return n === len ? out : out.subarray(0, n);
+  }
+
+  list(p: string): string[] | null {
+    return listIndex(this.pack.index!, p);
+  }
+}
diff --git a/src/node.ts b/src/node.ts
index ab8d804..9051bfd 100644
--- a/src/node.ts
+++ b/src/node.ts
@@ -10,6 +10,7 @@ import type { Backend, Stat } from "./fs.ts";
 import { Bridge, nativeTable } from "./bridge.ts";
 import { JVM, LM_CLASS, LM_JAR } from "./jvm.ts";
 import { hostNatives } from "./hostnatives.ts";
+import { ImageBackend } from "./image.ts";
 import { NodeNet } from "./net-node.ts";
 import type { NetBackend } from "./sockets.ts";
 
@@ -116,7 +117,8 @@ export class NodeBackend implements Backend {
   }
 }
 
-export const defaultJdk = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "build", "jdk");
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const defaultJdk = path.join(here, "..", "build", "jdk");
 
 export interface NodeRunOptions {
   classpath: string[];
@@ -124,6 +126,7 @@ export interface NodeRunOptions {
   jar?: string;
   args?: string[];
   props?: Record<string, string>;
+  // an exploded JDK image instead of build/jdk (or, for dist/node.js, the packaged one)
   jdk?: string;
   debug?: boolean;
   stdout?: (b: Uint8Array) => void;
@@ -164,7 +167,9 @@ const bridges = new WeakMap<JVM, Bridge>();
 function nodeVm(o: NodeRunOptions): JVM {
   const vfs = new VFS();
   vfs.mount("/", new NodeBackend("/", true));
-  vfs.mount("/jdk", new NodeBackend(o.jdk ?? defaultJdk));
+  // built as dist/node.js, it reads the packaged image next to it
+  const packaged = !o.jdk && fs.existsSync(path.join(here, "boot.pack"));
+  vfs.mount("/jdk", packaged ? new ImageBackend(here, o.localeData) : new NodeBackend(o.jdk ?? defaultJdk));
   if (!o.localeData) vfs.hide("/jdk/modules/jdk.localedata");
   const toVfs = (p: string) => path.resolve(p);
   const classpath = o.jar ? [toVfs(o.jar)] : o.classpath.map(toVfs);
@@ -288,4 +293,5 @@ function main(argv: string[]) {
   runNode(o).then((code) => process.exit(code));
 }
 
-if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+// run as a script, also through the symlink npm puts in node_modules/.bin
+if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) main(process.argv.slice(2));
diff --git a/test/image.test.ts b/test/image.test.ts
new file mode 100644
index 0000000..0e90221
--- /dev/null
+++ b/test/image.test.ts
@@ -0,0 +1,81 @@
+// The Node backend over the packaged image (boot.pack and jdk/<module>.jar),
+// and dist/node.js, the Node entry `pnpm build` makes; those tests skip until
+// dist/ is built.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ImageBackend } from "../src/image.ts";
+import { hotspot } from "../scripts/hotspot.ts";
+
+const root = join(import.meta.dirname, "..");
+const enc = new TextEncoder();
+
+// the boot.pack layout: [u16 path length][path][u32 size][bytes], repeated
+function pack(entries: [string, string][]): Uint8Array {
+  const parts: number[] = [];
+  for (const [p, d] of entries) {
+    const name = enc.encode(p), data = enc.encode(d);
+    parts.push(name.length >> 8, name.length & 255, ...name);
+    parts.push(data.length >>> 24, (data.length >> 16) & 255, (data.length >> 8) & 255, data.length & 255, ...data);
+  }
+  return Uint8Array.from(parts);
+}
+
+test("ImageBackend reads the index, packed files and module images", () => {
+  const dir = mkdtempSync(join(tmpdir(), "jw-image-"));
+  try {
+    mkdirSync(join(dir, "jdk"));
+    // java.base.jar holds "BOOTabcdef", the other image "XYZ"
+    writeFileSync(join(dir, "jdk", "java.base.jar"), "BOOTabcdef");
+    writeFileSync(join(dir, "jdk", "jdk.other.jar"), "XYZ");
+    writeFileSync(join(dir, "jdk", "jdk.localedata.txt"), "d /modules/jdk.localedata\nf /modules/jdk.localedata/L 3 jdk.other:0");
+    writeFileSync(join(dir, "boot.pack"), pack([
+      ["/index.txt", "d /lib\nf /lib/boot 4 java.base:0\nf /lib/rest 6 java.base:4\nd /modules\nd /modules/jdk.other\nf /modules/jdk.other/x 3 jdk.other:0"],
+      ["/lib/boot", "BOOT"],
+    ]));
+    const b = new ImageBackend(dir);
+    assert.deepEqual(b.stat("/lib"), { dir: true, size: 0, mtime: 0 });
+    assert.deepEqual(b.stat("/lib/rest"), { dir: false, size: 6, mtime: 0 });
+    assert.equal(b.stat("/lib/none"), null);
+    assert.deepEqual(b.list("/lib"), ["boot", "rest"]);
+    assert.deepEqual(b.list("/"), ["lib", "modules"]);
+    assert.equal(b.list("/lib/boot"), null);
+    const text = (d: Uint8Array | null) => d && new TextDecoder().decode(d);
+    assert.equal(text(b.read("/lib/boot")), "BOOT");
+    assert.equal(text(b.read("/lib/rest")), "abcdef");
+    assert.equal(text(b.readRange("/lib/rest", 2, 3)), "cde");
+    assert.equal(text(b.read("/modules/jdk.other/x")), "XYZ");
+    assert.equal(b.read("/lib"), null);
+    assert.equal(b.stat("/modules/jdk.localedata"), null);
+    assert.equal(text(new ImageBackend(dir, true).read("/modules/jdk.localedata/L")), "XYZ");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const node = join(root, "dist", "node.js");
+const skip = existsSync(node) ? false : "run `pnpm build` first";
+const out = join(root, "build", "test-image");
+
+test("dist/node.js runs a program as HotSpot does", { skip }, () => {
+  mkdirSync(out, { recursive: true });
+  spawnSync(hotspot("javac"), ["-d", out, join(root, "test", "java", "Collections.java")], { stdio: "inherit" });
+  const ref = spawnSync(hotspot("java"), ["-cp", out, "Collections"], { encoding: "utf8" });
+  const got = spawnSync(process.execPath, [node, "-cp", out, "Collections"], { encoding: "utf8" });
+  assert.deepEqual({ stdout: got.stdout, stderr: got.stderr, code: got.status }, { stdout: ref.stdout, stderr: ref.stderr, code: ref.status });
+});
+
+test("dist/node.js exports runNode, and javac runs on the packaged image", { skip }, async () => {
+  mkdirSync(out, { recursive: true });
+  spawnSync(hotspot("javac"), ["-d", out, join(root, "test", "java", "Javac.java")], { stdio: "inherit" });
+  const ref = spawnSync(hotspot("java"), ["-cp", out, "Javac"], { encoding: "utf8" });
+  const { runNode } = await import(node);
+  const stdout: Uint8Array[] = [];
+  const code = await runNode({ classpath: [out], mainClass: "Javac", stdout: (b: Uint8Array) => stdout.push(b) });
+  assert.equal(Buffer.concat(stdout).toString("utf8"), ref.stdout);
+  assert.equal(code, ref.status);
+});

From 23534b007cb57b166f836406c64115bf60f7a19b Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sat, 31 Oct 2026 15:35:00 -0500
Subject: [PATCH 2/5] Read a damaged image's file as missing, and report a
 missing JDK image clearly

---
 src/image.ts       |  3 ++-
 src/node.ts        | 13 +++++++++++--
 test/image.test.ts |  6 ++++--
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/src/image.ts b/src/image.ts
index 7b97572..1f1018b 100644
--- a/src/image.ts
+++ b/src/image.ts
@@ -49,7 +49,8 @@ export class ImageBackend implements Backend {
       if (got === 0) break;
       n += got;
     }
-    return n === len ? out : out.subarray(0, n);
+    // a short image is damaged; the file reads as missing rather than cut off
+    return n === len ? out : null;
   }
 
   list(p: string): string[] | null {
diff --git a/src/node.ts b/src/node.ts
index 9051bfd..238e81e 100644
--- a/src/node.ts
+++ b/src/node.ts
@@ -169,7 +169,11 @@ function nodeVm(o: NodeRunOptions): JVM {
   vfs.mount("/", new NodeBackend("/", true));
   // built as dist/node.js, it reads the packaged image next to it
   const packaged = !o.jdk && fs.existsSync(path.join(here, "boot.pack"));
-  vfs.mount("/jdk", packaged ? new ImageBackend(here, o.localeData) : new NodeBackend(o.jdk ?? defaultJdk));
+  const jdk = o.jdk ?? defaultJdk;
+  if (!packaged && !fs.existsSync(path.join(jdk, "lib", "packages.txt"))) {
+    throw new Error(`no JDK image at ${jdk}: run \`pnpm jdk\` in a checkout, or keep dist/node.js next to boot.pack and jdk/`);
+  }
+  vfs.mount("/jdk", packaged ? new ImageBackend(here, o.localeData) : new NodeBackend(jdk));
   if (!o.localeData) vfs.hide("/jdk/modules/jdk.localedata");
   const toVfs = (p: string) => path.resolve(p);
   const classpath = o.jar ? [toVfs(o.jar)] : o.classpath.map(toVfs);
@@ -290,7 +294,12 @@ function main(argv: string[]) {
     console.error("usage: java-web [-cp path] [-Dkey=value] Main [args] | -jar app.jar [args]");
     process.exit(2);
   }
-  runNode(o).then((code) => process.exit(code));
+  try {
+    runNode(o).then((code) => process.exit(code));
+  } catch (e) {
+    console.error(`java-web: ${(e as Error).message}`);
+    process.exit(1);
+  }
 }
 
 // run as a script, also through the symlink npm puts in node_modules/.bin
diff --git a/test/image.test.ts b/test/image.test.ts
index 0e90221..952c2a9 100644
--- a/test/image.test.ts
+++ b/test/image.test.ts
@@ -34,14 +34,14 @@ test("ImageBackend reads the index, packed files and module images", () => {
     writeFileSync(join(dir, "jdk", "jdk.other.jar"), "XYZ");
     writeFileSync(join(dir, "jdk", "jdk.localedata.txt"), "d /modules/jdk.localedata\nf /modules/jdk.localedata/L 3 jdk.other:0");
     writeFileSync(join(dir, "boot.pack"), pack([
-      ["/index.txt", "d /lib\nf /lib/boot 4 java.base:0\nf /lib/rest 6 java.base:4\nd /modules\nd /modules/jdk.other\nf /modules/jdk.other/x 3 jdk.other:0"],
+      ["/index.txt", "d /lib\nf /lib/boot 4 java.base:0\nf /lib/rest 6 java.base:4\nf /lib/cut 6 jdk.other:1\nd /modules\nd /modules/jdk.other\nf /modules/jdk.other/x 3 jdk.other:0"],
       ["/lib/boot", "BOOT"],
     ]));
     const b = new ImageBackend(dir);
     assert.deepEqual(b.stat("/lib"), { dir: true, size: 0, mtime: 0 });
     assert.deepEqual(b.stat("/lib/rest"), { dir: false, size: 6, mtime: 0 });
     assert.equal(b.stat("/lib/none"), null);
-    assert.deepEqual(b.list("/lib"), ["boot", "rest"]);
+    assert.deepEqual(b.list("/lib"), ["boot", "rest", "cut"]);
     assert.deepEqual(b.list("/"), ["lib", "modules"]);
     assert.equal(b.list("/lib/boot"), null);
     const text = (d: Uint8Array | null) => d && new TextDecoder().decode(d);
@@ -50,6 +50,8 @@ test("ImageBackend reads the index, packed files and module images", () => {
     assert.equal(text(b.readRange("/lib/rest", 2, 3)), "cde");
     assert.equal(text(b.read("/modules/jdk.other/x")), "XYZ");
     assert.equal(b.read("/lib"), null);
+    // past the end of a damaged image
+    assert.equal(b.read("/lib/cut"), null);
     assert.equal(b.stat("/modules/jdk.localedata"), null);
     assert.equal(text(new ImageBackend(dir, true).read("/modules/jdk.localedata/L")), "XYZ");
   } finally {

From b59c74f2573097c3d4797cc2462f8a7d68253592 Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sat, 31 Oct 2026 15:36:25 -0500
Subject: [PATCH 3/5] Open a module image for each read instead of keeping its
 descriptor

---
 src/image.ts | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)

diff --git a/src/image.ts b/src/image.ts
index 1f1018b..87053b6 100644
--- a/src/image.ts
+++ b/src/image.ts
@@ -8,9 +8,6 @@ import { addIndex, listIndex, parsePack } from "./browser/http.ts";
 import type { Pack } from "./browser/http.ts";
 import type { Backend, Stat } from "./fs.ts";
 
-// open module images by host path, shared by every VM in the process
-const images = new Map<string, number>();
-
 export class ImageBackend implements Backend {
   readonly writable = false;
   private readonly dir: string;
@@ -39,15 +36,17 @@ export class ImageBackend implements Backend {
     if (packed) return packed.subarray(off, off + len);
     const at = this.pack.offsets.get(p);
     if (!at) return null;
-    const file = path.join(this.dir, "jdk", at.image);
-    let fd = images.get(file);
-    if (fd === undefined) images.set(file, (fd = fs.openSync(file, "r")));
     const out = new Uint8Array(len);
     let n = 0;
-    while (n < len) {
-      const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
-      if (got === 0) break;
-      n += got;
+    const fd = fs.openSync(path.join(this.dir, "jdk", at.image), "r");
+    try {
+      while (n < len) {
+        const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
+        if (got === 0) break;
+        n += got;
+      }
+    } finally {
+      fs.closeSync(fd);
     }
     // a short image is damaged; the file reads as missing rather than cut off
     return n === len ? out : null;

From 80b6b8f8a31a5f4ec3f529bb1fd85528e648070f Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sat, 31 Oct 2026 15:40:16 -0500
Subject: [PATCH 4/5] Cut image reads at the file's end, read an unreadable
 image's file as missing, and report a packaged image without jdk/ and a
 failed run clearly

---
 src/image.ts       | 26 ++++++++++++++++++--------
 src/node.ts        |  6 ++----
 test/image.test.ts |  5 +++++
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/src/image.ts b/src/image.ts
index 87053b6..7a1c3b7 100644
--- a/src/image.ts
+++ b/src/image.ts
@@ -16,6 +16,9 @@ export class ImageBackend implements Backend {
   // dir holds boot.pack and jdk/; localeData adds jdk.localedata's files
   constructor(dir: string, localeData = false) {
     this.dir = path.resolve(dir);
+    if (!fs.existsSync(path.join(this.dir, "jdk", "java.base.jar"))) {
+      throw new Error(`no packaged JDK image in ${this.dir}: boot.pack needs jdk/ next to it`);
+    }
     const buf = fs.readFileSync(path.join(this.dir, "boot.pack"));
     this.pack = parsePack(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
     if (localeData) addIndex(this.pack, fs.readFileSync(path.join(this.dir, "jdk", "jdk.localedata.txt"), "utf8"));
@@ -32,23 +35,30 @@ export class ImageBackend implements Backend {
   }
 
   readRange(p: string, off: number, len: number): Uint8Array | null {
+    const size = this.pack.index!.get(p);
+    if (size === undefined || size < 0) return null;
+    len = Math.max(0, Math.min(len, size - off));
     const packed = this.pack.files.get(p);
     if (packed) return packed.subarray(off, off + len);
     const at = this.pack.offsets.get(p);
     if (!at) return null;
     const out = new Uint8Array(len);
     let n = 0;
-    const fd = fs.openSync(path.join(this.dir, "jdk", at.image), "r");
     try {
-      while (n < len) {
-        const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
-        if (got === 0) break;
-        n += got;
+      const fd = fs.openSync(path.join(this.dir, "jdk", at.image), "r");
+      try {
+        while (n < len) {
+          const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
+          if (got === 0) break;
+          n += got;
+        }
+      } finally {
+        fs.closeSync(fd);
       }
-    } finally {
-      fs.closeSync(fd);
+    } catch {
+      return null;
     }
-    // a short image is damaged; the file reads as missing rather than cut off
+    // a short or unreadable image is damaged; the file reads as missing rather than cut off
     return n === len ? out : null;
   }
 
diff --git a/src/node.ts b/src/node.ts
index 238e81e..a1c43aa 100644
--- a/src/node.ts
+++ b/src/node.ts
@@ -294,12 +294,10 @@ function main(argv: string[]) {
     console.error("usage: java-web [-cp path] [-Dkey=value] Main [args] | -jar app.jar [args]");
     process.exit(2);
   }
-  try {
-    runNode(o).then((code) => process.exit(code));
-  } catch (e) {
+  Promise.resolve().then(() => runNode(o)).then((code) => process.exit(code), (e) => {
     console.error(`java-web: ${(e as Error).message}`);
     process.exit(1);
-  }
+  });
 }
 
 // run as a script, also through the symlink npm puts in node_modules/.bin
diff --git a/test/image.test.ts b/test/image.test.ts
index 952c2a9..51472a9 100644
--- a/test/image.test.ts
+++ b/test/image.test.ts
@@ -48,12 +48,17 @@ test("ImageBackend reads the index, packed files and module images", () => {
     assert.equal(text(b.read("/lib/boot")), "BOOT");
     assert.equal(text(b.read("/lib/rest")), "abcdef");
     assert.equal(text(b.readRange("/lib/rest", 2, 3)), "cde");
+    // a range is cut at the file's end, not read into the next file
+    assert.equal(text(b.readRange("/lib/boot", 2, 10)), "OT");
+    assert.equal(text(b.readRange("/lib/rest", 4, 10)), "ef");
     assert.equal(text(b.read("/modules/jdk.other/x")), "XYZ");
     assert.equal(b.read("/lib"), null);
     // past the end of a damaged image
     assert.equal(b.read("/lib/cut"), null);
     assert.equal(b.stat("/modules/jdk.localedata"), null);
     assert.equal(text(new ImageBackend(dir, true).read("/modules/jdk.localedata/L")), "XYZ");
+    rmSync(join(dir, "jdk", "java.base.jar"));
+    assert.throws(() => new ImageBackend(dir), /no packaged JDK image/);
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }

From 86775e802d70d9a373f44c56eec0a29550b3efd6 Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sat, 31 Oct 2026 15:43:46 -0500
Subject: [PATCH 5/5] Ship TypeScript declarations for the Node entry, checked
 against src/node.ts by pnpm typecheck

---
 docs/node.md         |  4 +++-
 package.json         |  6 +++++-
 scripts/build-web.ts |  1 +
 src/node.ts          |  4 ++--
 test/node-types.ts   | 16 +++++++++++++++
 tsconfig.json        |  2 +-
 types/node.d.ts      | 49 ++++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 77 insertions(+), 5 deletions(-)
 create mode 100644 test/node-types.ts
 create mode 100644 types/node.d.ts

diff --git a/docs/node.md b/docs/node.md
index c212a82..338aa45 100644
--- a/docs/node.md
+++ b/docs/node.md
@@ -39,7 +39,8 @@ const code = await runNode({
 });
 ```
 
-`runNode` resolves to the exit code. Its options:
+The package ships TypeScript declarations (`dist/node.d.ts`). `runNode`
+resolves to the exit code. Its options:
 
 - `classpath`, `mainClass` or `jar`, `args`, `props` (system properties)
 - `stdout`, `stderr` (byte callbacks; default the process's), `input` (fixed stdin bytes)
@@ -47,6 +48,7 @@ const code = await runNode({
 - `natives`: Java `native` methods in JS, as in the browser ([browser.md](browser.md))
 - `assertions` (the flags, for example `["-ea"]`), `enablePreview`, `localeData`
 - `hostName` (what `InetAddress.getLocalHost()` reports), `maxRssMb`, `jdk`, `debug`
+- `fetch`: sockets stay inside the VM, and `http:` requests go to this `fetch`, as in the browser
 
 `startLibrary(options)` starts a VM in library mode, and `libraryOf(vm)` is its
 `lib`, used as `cheerpjRunLibrary`'s result is in the browser. `vm.halt(0)`
diff --git a/package.json b/package.json
index 8be6649..b5557c8 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,10 @@
   "license": "AGPL-3.0-only",
   "type": "module",
   "exports": {
-    ".": "./dist/node.js",
+    ".": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
     "./dist/*": "./dist/*"
   },
   "bin": {
@@ -29,6 +32,7 @@
     "dist/java-web.js",
     "dist/java-web-worker.js",
     "dist/node.js",
+    "dist/node.d.ts",
     "dist/boot.pack",
     "dist/jdk/*.jar",
     "dist/jdk/javac.pack",
diff --git a/scripts/build-web.ts b/scripts/build-web.ts
index a2e74f8..399990e 100644
--- a/scripts/build-web.ts
+++ b/scripts/build-web.ts
@@ -43,6 +43,7 @@ await build({
   target: "node23",
   banner: { js: "#!/usr/bin/env node" },
 });
+cpSync(join(root, "types", "node.d.ts"), join(dist, "node.d.ts"));
 
 mkdirSync(join(dist, "jdk"), { recursive: true });
 
diff --git a/src/node.ts b/src/node.ts
index a1c43aa..8105894 100644
--- a/src/node.ts
+++ b/src/node.ts
@@ -161,7 +161,7 @@ function fixedInput(data: Uint8Array) {
   };
 }
 
-const bridges = new WeakMap<JVM, Bridge>();
+const bridges = new WeakMap<object, Bridge>();
 
 // The host file system is the VFS root, with the JDK image mounted at /jdk.
 function nodeVm(o: NodeRunOptions): JVM {
@@ -239,7 +239,7 @@ export async function startLibrary(o: NodeRunOptions): Promise<JVM> {
   return vm;
 }
 
-export function libraryOf(vm: JVM): any {
+export function libraryOf(vm: object): any {
   return bridges.get(vm)!.root(0);
 }
 
diff --git a/test/node-types.ts b/test/node-types.ts
new file mode 100644
index 0000000..d67d086
--- /dev/null
+++ b/test/node-types.ts
@@ -0,0 +1,16 @@
+// Type-only check, run by `pnpm typecheck`: types/node.d.ts matches src/node.ts.
+
+import type * as declared from "../types/node.d.ts";
+import type * as real from "../src/node.ts";
+
+type Never<T extends never> = T;
+
+// the declared options are the real ones, less the internal socket backend
+export type Extra = Never<Exclude<keyof declared.NodeRunOptions, keyof real.NodeRunOptions>>;
+export type Undeclared = Never<Exclude<keyof real.NodeRunOptions, keyof declared.NodeRunOptions | "net">>;
+export const options = (o: declared.NodeRunOptions): real.NodeRunOptions => o;
+
+// each declared function accepts what the real one does and returns what it does
+export const run: typeof declared.runNode = null! as typeof real.runNode;
+export const start: typeof declared.startLibrary = null! as typeof real.startLibrary;
+export const lib: typeof declared.libraryOf = null! as typeof real.libraryOf;
diff --git a/tsconfig.json b/tsconfig.json
index 4c5e720..d7460fd 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,5 +13,5 @@
     "types": ["node"],
     "skipLibCheck": true
   },
-  "include": ["src", "test", "scripts"]
+  "include": ["src", "test", "scripts", "types"]
 }
diff --git a/types/node.d.ts b/types/node.d.ts
new file mode 100644
index 0000000..0ab884d
--- /dev/null
+++ b/types/node.d.ts
@@ -0,0 +1,49 @@
+// Types of the package's Node entry, dist/node.js. test/node-types.ts checks
+// them against src/node.ts, so `pnpm typecheck` fails when they drift.
+
+export interface NodeRunOptions {
+  classpath: string[];
+  mainClass?: string;
+  jar?: string;
+  args?: string[];
+  // system properties
+  props?: Record<string, string>;
+  // an exploded JDK image instead of the packaged one
+  jdk?: string;
+  debug?: boolean;
+  stdout?: (bytes: Uint8Array) => void;
+  stderr?: (bytes: Uint8Array) => void;
+  // fixed stdin contents instead of the process stdin
+  input?: Uint8Array;
+  // native methods in JS as in CheerpJ: Java_pkg_Class_method(lib, ...args)
+  natives?: Record<string, (lib: any, ...args: any[]) => unknown>;
+  // -ea, -da:pkg..., -esa and the like
+  assertions?: string[];
+  // the process exits when its resident memory goes past this
+  maxRssMb?: number;
+  enablePreview?: boolean;
+  // what InetAddress.getLocalHost() reports instead of the host's name
+  hostName?: string;
+  // what System.getenv() returns instead of the host's environment
+  env?: Record<string, string>;
+  // load jdk.localedata, the formats and names of locales other than English
+  localeData?: boolean;
+  // loopback sockets whose http: requests go to this fetch, instead of host sockets
+  fetch?: typeof fetch;
+}
+
+// A running VM, as startLibrary returns it.
+export interface JavaVM {
+  // resolves to the exit code
+  readonly exited: Promise<number>;
+  halt(code: number): void;
+}
+
+// Runs a main class or jar; resolves to the exit code.
+export function runNode(options: NodeRunOptions): Promise<number>;
+
+// Starts a VM in library mode.
+export function startLibrary(options: NodeRunOptions): Promise<JavaVM>;
+
+// A library-mode VM's `lib`, as cheerpjRunLibrary returns it in the browser.
+export function libraryOf(vm: JavaVM): any;