From ee55431fef3b17a8eb786d28f79c1c5b08ab7e34 Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sun, 8 Nov 2026 14:52:01 -0600
Subject: [PATCH 1/2] feat: put each JDK module but java.base in its own image
 file, so a host can leave out the ones its pages never load

---
 AGENTS.md               |  2 +-
 README.md               |  7 ++--
 docs/browser.md         | 22 ++++++-----
 docs/development.md     |  3 +-
 scripts/build-web.ts    | 81 +++++++++++++++++++++++++++++++++++------
 src/browser/http.ts     | 57 ++++++++++++++++++++++++++---
 src/image.ts            | 14 +++----
 src/jimage.ts           |  4 +-
 test/http-files.test.ts | 53 ++++++++++++++++++++++++++-
 test/image.test.ts      | 31 +++++++++++++++-
 10 files changed, 231 insertions(+), 43 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f954c84..edce841 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,7 +32,7 @@ Node, which is how the tests run.
   IndexedDB and one VM per about:blank iframe. Keep these working.
 - The release form is an npm package of the built files only
   (`java-web.js`, `java-web-worker.js`, `node.js` (the Node entry), `cli.js` (the
-  `java-web` command), `boot.pack`, `jdk/image.jar`,
+  `java-web` command), `boot.pack`, the `jdk/*.jar` image files,
   `jdk/javac.pack`, 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.
diff --git a/README.md b/README.md
index 64b36ba..95daa84 100644
--- a/README.md
+++ b/README.md
@@ -10,10 +10,9 @@ and its page API matches CheerpJ's, so existing pages can switch.
 pnpm add @project516/java-web
 ```
 
-Serve `node_modules/@project516/java-web/dist/` as static files (on GitHub
-Pages, deploy from Actions: a `gh-pages` branch cannot hold the 120 MB
-`jdk/image.jar`; on a project site, `/app/` is `user.github.io`, so files are
-under `/app/<repo>/`), then:
+Serve `node_modules/@project516/java-web/dist/` as static files (on a GitHub
+Pages project site, `/app/` is the site root `user.github.io`, so the page's
+files are under `/app/<repo>/`), then:
 
 ```html
 <script src="java-web.js"></script>
diff --git a/docs/browser.md b/docs/browser.md
index 855e21a..aa245bd 100644
--- a/docs/browser.md
+++ b/docs/browser.md
@@ -5,15 +5,19 @@ The npm package holds the built files: `java-web.js`, `java-web-worker.js`,
 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.
 
-- The server should answer range requests for `jdk/image.jar`, the whole JDK
-  image, so a page reads only the classes it needs. `boot.pack` holds what a
-  typical start reads, and `jdk/javac.pack` what javac adds. A host that
-  compresses ranged responses still works, at the cost of one full download of
-  `jdk/image.jar` (about 120 MB).
-- `jdk/image.jar` is over GitHub's 100 MB limit for a file in a git
-  repository, so a site published by pushing a `gh-pages` branch cannot hold
-  it. GitHub Pages deployed from Actions (`actions/upload-pages-artifact`)
-  serves it, Range requests included.
+- The server should answer range requests for the `jdk/*.jar` files, the JDK
+  image, so a page reads only the classes it needs. `jdk/image.jar` holds
+  `java.base` and the files around the classes, each other module is in
+  `jdk/<module>.jar`, and `jdk/ct.sym.jar` holds what `javac --release` reads.
+  `boot.pack` holds what a typical start reads, and `jdk/javac.pack` what javac
+  adds. A host that compresses ranged responses still works, at the cost of one
+  full download of each image file a page reads.
+- A host can leave out the `jdk/<module>.jar` of a module its pages never
+  load, and `jdk/ct.sym.jar` when nothing compiles with `--release`. A class of
+  a left-out module does not load (`NoClassDefFoundError`), and the console
+  names the missing file. Without `localeData` nothing reads
+  `jdk/jdk.localedata.jar` (26 MB); javac reads `jdk.compiler`,
+  `java.compiler` and `jdk.zipfs`.
 - The JIT compiles hot Java methods with `new Function`, so a page with a
   Content Security Policy needs `'unsafe-eval'` in `script-src`. Without it,
   Java still runs, only interpreted.
diff --git a/docs/development.md b/docs/development.md
index accbffa..578c66f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -8,7 +8,8 @@ included, builds the same image, with the Linux class library whose natives
 java-web implements. The host JDK is the HotSpot reference the tests run, linked
 at `build/hotspot`. The build links the selected modules into `build/jdk/lib/modules`;
 `lib/packages.txt` indexes packages for the boot class loader. `pnpm build`
-puts it, with the files around it, in `dist/jdk/image.jar`, read by byte range.
+puts it, with the files around it, in `dist/jdk/image.jar` and, for each module
+but `java.base`, `dist/jdk/<module>.jar`, all read by byte range.
 It packs the byte ranges a typical start reads into `boot.pack`, and those javac
 adds into `jdk/javac.pack`. Without `localeData`, the VM leaves `jdk.localedata`
 out with `jdk.module.limitmods`, as `--limit-modules` does.
diff --git a/scripts/build-web.ts b/scripts/build-web.ts
index 0efe88f..164b73b 100644
--- a/scripts/build-web.ts
+++ b/scripts/build-web.ts
@@ -173,14 +173,56 @@ const rangeEntries = (ranges: Map<string, [number, number][]>, src: Recorder) =>
   [...ranges].flatMap(([p, spans]) => spans.map(([s, e]): [string, Uint8Array] => [`@${s}:${p}`, src.readRange(p, s, e - s)!]));
 const inJavacPack = new Set(javacFiles);
 
-// Every java.home file goes in one file, jdk/image.jar, read in ranges:
-// lib/modules (the jimage with every class) and the conf/ and lib/ files
-// around it. The index says where each file is, so the worker can stat and
-// list offline.
+// A jimage's resources as runs of one module's, [module, start, end) in image
+// order. Empty resources and module-info.class are left out: jlink puts the
+// latter with the index, and javac reads them all.
+function moduleRuns(image: Uint8Array): [string, number, number][] {
+  const v = new DataView(image.buffer, image.byteOffset, image.byteLength);
+  const count = v.getUint32(16, true);
+  const locations = 28 + count * 8, strings = locations + v.getUint32(20, true);
+  const resources = strings + v.getUint32(24, true);
+  const str = (off: number) => {
+    let s = "";
+    for (let i = strings + off; image[i]; i++) s += String.fromCharCode(image[i]);
+    return s;
+  };
+  const found: [string, number, number][] = [];
+  for (let i = 0; i < count; i++) {
+    let p = locations + v.getUint32(28 + count * 4 + i * 4, true);
+    const attrs = Array<number>(8).fill(0);
+    while (image[p] > 7) {
+      const b = image[p++];
+      let value = 0;
+      for (let n = (b & 7) + 1; n > 0; n--) value = value * 256 + image[p++];
+      attrs[b >> 3] = value;
+    }
+    const size = attrs[6] || attrs[7];
+    if (size && !(!attrs[2] && str(attrs[3]) === "module-info")) found.push([str(attrs[1]), resources + attrs[5], resources + attrs[5] + size]);
+  }
+  const runs: [string, number, number][] = [];
+  for (const [module, start, end] of found.sort((a, b) => a[1] - b[1])) {
+    const last = runs[runs.length - 1];
+    if (last?.[0] === module) last[2] = Math.max(last[2], end);
+    else runs.push([module, start, end]);
+  }
+  return runs;
+}
+
+// The java.home files go in jdk/image.jar, read in ranges, with the index
+// saying where each is, so the worker can stat and list offline. Parts a page
+// may never read go in their own files, which a host can leave out: each
+// module of lib/modules but java.base in jdk/<module>.jar, and lib/ct.sym
+// (javac --release) in jdk/ct.sym.jar.
+const linked = new Set(/^MODULES="(.*)"$/m.exec(readFileSync(join(jdk, "release"), "utf8"))![1].split(" "));
+const imageSizes = new Map<string, number>();
+// appends data to jdk/<name>.jar, returning where it starts there
+const put = (name: string, data: Uint8Array) => {
+  const at = imageSizes.get(name) ?? 0;
+  (at ? appendFileSync : writeFileSync)(join(dist, "jdk", `${name}.jar`), data);
+  imageSizes.set(name, at + data.length);
+  return at;
+};
 const lines: string[] = [];
-const imageFile = join(dist, "jdk", "image.jar");
-writeFileSync(imageFile, "");
-let imageSize = 0;
 const walk = (dir: string) => {
   for (const name of readdirSync(dir).sort()) {
     const p = join(dir, name);
@@ -190,10 +232,25 @@ const walk = (dir: string) => {
     if (st.isDirectory()) {
       lines.push(`d ${rel}`);
       walk(p);
+    } else if (rel === "/lib/modules") {
+      const data = readFileSync(p);
+      const parts: [number, string][] = [];
+      let pos = 0;
+      for (const [module, start, end] of moduleRuns(data)) {
+        if (module === "java.base" || !linked.has(module)) continue;
+        if (parts.some(([, m]) => m === module)) throw new Error(`lib/modules has ${module} in more than one place`);
+        if (start > pos) parts.push([pos, "image"]);
+        parts.push([start, module]);
+        pos = end;
+      }
+      if (pos < data.length) parts.push([pos, "image"]);
+      parts.forEach(([start, image], i) => {
+        const at = put(image, data.subarray(start, i + 1 < parts.length ? parts[i + 1][0] : data.length));
+        lines.push(start ? `p ${rel} ${start} ${image}:${at}` : `f ${rel} ${st.size} ${image}:${at}`);
+      });
     } else {
-      lines.push(`f ${rel} ${st.size} image:${imageSize}${inJavacPack.has(rel) ? " javac" : ""}`);
-      appendFileSync(imageFile, readFileSync(p));
-      imageSize += st.size;
+      const image = rel === "/lib/ct.sym" ? "ct.sym" : "image";
+      lines.push(`f ${rel} ${st.size} ${image}:${put(image, readFileSync(p))}${inJavacPack.has(rel) ? " javac" : ""}`);
     }
   }
 };
@@ -249,4 +306,6 @@ const javacPack = writePack(join(dist, "jdk", "javac.pack"), [
   ...javacFiles.map((p): [string, Uint8Array] => [p, javacRecorder.read(p)!]),
   ...rangeEntries(javacRanges, javacRecorder),
 ]);
-console.log(`dist/ ready: boot.pack ${boot}, jdk/javac.pack ${javacPack}, jdk/image.jar ${(imageSize / 2 ** 20).toFixed(0)} MB`);
+const mb = (n: number) => `${(n / 2 ** 20).toFixed(0)} MB`;
+const others = [...imageSizes].filter(([n]) => n !== "image").reduce((n, [, size]) => n + size, 0);
+console.log(`dist/ ready: boot.pack ${boot}, jdk/javac.pack ${javacPack}, jdk/image.jar ${mb(imageSizes.get("image")!)}, ${imageSizes.size - 1} more images ${mb(others)}`);
diff --git a/src/browser/http.ts b/src/browser/http.ts
index a60281b..33d6ed8 100644
--- a/src/browser/http.ts
+++ b/src/browser/http.ts
@@ -12,6 +12,9 @@ export interface Pack {
   lazy: Map<string, string>;
   // path -> the image file holding it and its offset there
   offsets: Map<string, { image: string; at: number }>;
+  // path -> where the bytes from each start on are, for a file split across
+  // image files, sorted by start; offsets has the first part
+  parts: Map<string, { start: number; image: string; at: number }[]>;
   // path -> parts of a file read in ranges (the JDK image), as [offset, bytes]
   // sorted by offset
   ranges: Map<string, [number, Uint8Array][]>;
@@ -25,8 +28,10 @@ const utf8 = new TextDecoder();
 // Pack layout: repeated [u16 path length][path][u32 size][bytes]. In the boot
 // pack, "/index.prefix" holds prefix-coded "d path" and "f path size
 // [image:offset] [pack]" lines. A file with an offset is read in ranges from
-// <image>.jar; a named pack is <name>.pack next to it and is
-// fetched whole the first time one of its files is read. An entry named
+// <image>.jar, and a "p path start image:offset" line after it says the
+// file's bytes from start on are in another image. A named pack is
+// <name>.pack next to it and is fetched whole the first time one of its files
+// is read. An entry named
 // "@<offset>:<path>" holds part of a file read in ranges, and one named
 // "@lazy:<pack>:<path>" lists, as u32 start and end pairs, the parts of it
 // that pack holds. Images are .jar
@@ -44,7 +49,7 @@ export function parsePack(buf: ArrayBuffer): Pack {
     files.set(path, u8.subarray(p + 4, p + 4 + size));
     p += 4 + size;
   }
-  const pack: Pack = { files, index: null, lazy: new Map(), offsets: new Map(), ranges: new Map(), lazyRanges: new Map() };
+  const pack: Pack = { files, index: null, lazy: new Map(), offsets: new Map(), parts: new Map(), ranges: new Map(), lazyRanges: new Map() };
   for (const [p, data] of files) {
     if (p[0] !== "@") continue;
     files.delete(p);
@@ -169,10 +174,34 @@ export function addIndex(pack: Pack, text: string, prefix = false) {
         b = c;
       }
       pack.lazy.set(path, line.slice(b + 1));
+    } else if (line[0] === "p") {
+      const b = line.indexOf(" ", a + 1), colon = line.lastIndexOf(":");
+      const name = line.slice(b + 1, colon);
+      let image = images.get(name);
+      if (image === undefined) images.set(name, (image = `/${name}.jar`));
+      let parts = pack.parts.get(path);
+      if (!parts) pack.parts.set(path, (parts = []));
+      parts.push({ start: +line.slice(a + 1, b), image, at: +line.slice(colon + 1) });
     }
   }
 }
 
+// Where byte off of a file read in ranges is: the image file, the offset
+// there, and how many bytes from off on that part of the file holds.
+export function imagePart(pack: Pack, path: string, off: number): { image: string; at: number; len: number } | undefined {
+  const first = pack.offsets.get(path);
+  if (!first) return undefined;
+  let { image, at } = first, start = 0, end = pack.index!.get(path)!;
+  for (const p of pack.parts.get(path) ?? []) {
+    if (p.start > off) {
+      end = p.start;
+      break;
+    }
+    ({ image, at, start } = p);
+  }
+  return { image, at: at + off - start, len: end - off };
+}
+
 const BLOCK = 64 << 10;
 
 function encodePath(path: string): string {
@@ -204,8 +233,10 @@ export class HttpBackend implements Backend {
   private fetchedPacks = new Set<string>();
   // 64 KB blocks of files read in parts, by path
   private blocks = new Map<string, Map<number, Uint8Array>>();
+  // files read in ranges that the server does not have
+  private missing = new Set<string>();
 
-  constructor(base: string, pack: Pack = { files: new Map(), index: null, lazy: new Map(), offsets: new Map(), ranges: new Map(), lazyRanges: new Map() }) {
+  constructor(base: string, pack: Pack = { files: new Map(), index: null, lazy: new Map(), offsets: new Map(), parts: new Map(), ranges: new Map(), lazyRanges: new Map() }) {
     this.base = base.endsWith("/") ? base.slice(0, -1) : base;
     this.pack = pack;
   }
@@ -290,8 +321,18 @@ export class HttpBackend implements Backend {
       return this.readRange(path, off, len);
     }
     // has() parses the path's module first; image files themselves are not indexed
-    const at = this.pack.index?.has(path) ? this.pack.offsets.get(path) : undefined;
-    if (at !== undefined) return this.readRange(at.image, at.at + off, len);
+    const at = this.pack.index?.has(path) ? imagePart(this.pack, path, off) : undefined;
+    if (at !== undefined) {
+      if (len <= at.len || at.len <= 0) return this.readRange(at.image, at.at, len);
+      const head = this.readRange(at.image, at.at, at.len);
+      const rest = head && this.readRange(path, off + at.len, len - at.len);
+      if (!head || !rest) return null;
+      const out = new Uint8Array(len);
+      out.set(head);
+      out.set(rest, head.length);
+      return out;
+    }
+    if (this.missing.has(path)) return null;
     let blocks = this.blocks.get(path);
     if (!blocks) this.blocks.set(path, (blocks = new Map()));
     const first = Math.floor(off / BLOCK), last = Math.floor((off + len - 1) / BLOCK);
@@ -315,6 +356,10 @@ export class HttpBackend implements Backend {
         this.blocks.delete(path);
         return data.subarray(off, off + len);
       }
+      if (xhr.status === 404) {
+        this.missing.add(path);
+        console.warn(`java-web: ${this.base}${path} is missing, so the classes in it do not load`);
+      }
       if (xhr.status !== 206) return null;
       if (!rangeOk(xhr, b * BLOCK, data.length)) return this.readWhole(path, off, len);
       for (let i = b; i <= end; i++) blocks.set(i, data.subarray((i - b) * BLOCK, (i - b + 1) * BLOCK));
diff --git a/src/image.ts b/src/image.ts
index 5f9cdec..79898bc 100644
--- a/src/image.ts
+++ b/src/image.ts
@@ -1,10 +1,10 @@
 // The JDK image as `pnpm build` packages it in dist/, read from disk under
 // Node: boot.pack holds the index and the files and image ranges a typical
-// start reads, and the rest is read at its offset in jdk/image.jar.
+// start reads, and the rest is read at its offset in the jdk/*.jar images.
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { listIndex, packedRange, parsePack } from "./browser/http.ts";
+import { imagePart, listIndex, packedRange, parsePack } from "./browser/http.ts";
 import type { Pack } from "./browser/http.ts";
 import type { Backend, Stat } from "./fs.ts";
 
@@ -55,15 +55,15 @@ export class ImageBackend implements Backend {
     if (packed) return packed.subarray(off, off + len);
     const part = packedRange(this.pack, p, off, len);
     if (part) return part;
-    const at = this.pack.offsets.get(p);
-    if (!at) return null;
+    if (!this.pack.offsets.has(p)) return null;
     const out = new Uint8Array(len);
     let n = 0;
     try {
-      let fd = this.fds.get(at.image);
-      if (fd === undefined) this.fds.set(at.image, (fd = imageFd(path.join(this.dir, "jdk", at.image))));
       while (n < len) {
-        const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
+        const at = imagePart(this.pack, p, off + n)!;
+        let fd = this.fds.get(at.image);
+        if (fd === undefined) this.fds.set(at.image, (fd = imageFd(path.join(this.dir, "jdk", at.image))));
+        const got = fs.readSync(fd, out, n, Math.min(len - n, at.len), at.at);
         if (got === 0) break;
         n += got;
       }
diff --git a/src/jimage.ts b/src/jimage.ts
index 81bc55e..ebaf927 100644
--- a/src/jimage.ts
+++ b/src/jimage.ts
@@ -63,7 +63,9 @@ export class JImage {
     if (actual !== full) return null;
     if (attrs[6]) throw new Error("compressed jimage resource");
     const data = this.fs.readRange(this.path, this.index.length + attrs[5], attrs[7]);
-    if (!data || data.length !== attrs[7]) throw new Error(`cannot read image resource: ${full}`);
+    // a host may leave out the image file of a module its pages never load
+    if (!data) return null;
+    if (data.length !== attrs[7]) throw new Error(`cannot read image resource: ${full}`);
     return data;
   }
 }
diff --git a/test/http-files.test.ts b/test/http-files.test.ts
index 4672100..df540f5 100644
--- a/test/http-files.test.ts
+++ b/test/http-files.test.ts
@@ -1,6 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { HttpBackend } from "../src/browser/http.ts";
+import { addIndex, HttpBackend, PackIndex } from "../src/browser/http.ts";
+import type { Pack } from "../src/browser/http.ts";
 
 test("HTTP file reads preserve reserved characters in filenames", (t) => {
   const files = new Map([
@@ -75,3 +76,53 @@ test("class metadata and contents use one request without Content-Length", (t) =
   assert.deepEqual(backend.stat("/folder"), { dir: true, size: 0, mtime: 0 });
   assert.deepEqual(calls, ["GET https://example.test/app/Found.class", "GET https://example.test/app/Missing.class", "HEAD https://example.test/app/folder"]);
 });
+
+test("a file split across image files reads each part by range, and a missing one warns once", (t) => {
+  // /lib/modules is "HEAD" "MOD" "TAIL", the middle in jdk.other.jar, which the server lacks at first
+  const files = new Map([["/jdk/image.jar", new TextEncoder().encode("xHEADTAIL")], ["/jdk/jdk.other.jar", new TextEncoder().encode("MOD")]]);
+  const calls: string[] = [];
+  class XHR {
+    status = 404;
+    response = new ArrayBuffer(0);
+    private url!: URL;
+    private range: [number, number] | null = null;
+    open(_method: string, url: string) { this.url = new URL(url); }
+    setRequestHeader(_name: string, value: string) {
+      const m = /^bytes=(\d+)-(\d+)$/.exec(value)!;
+      this.range = [+m[1], +m[2]];
+    }
+    getResponseHeader() { return null; }
+    send() {
+      calls.push(this.url.pathname);
+      const data = files.get(this.url.pathname);
+      if (!data || !this.range) return;
+      this.status = 206;
+      this.response = data.slice(this.range[0], this.range[1] + 1).buffer;
+    }
+  }
+  const original = Object.getOwnPropertyDescriptor(globalThis, "XMLHttpRequest");
+  Object.defineProperty(globalThis, "XMLHttpRequest", { configurable: true, value: XHR });
+  const warnings: string[] = [];
+  t.mock.method(console, "warn", (m: string) => warnings.push(m));
+  t.after(() => {
+    if (original) Object.defineProperty(globalThis, "XMLHttpRequest", original);
+    else Reflect.deleteProperty(globalThis, "XMLHttpRequest");
+  });
+  const pack = (): Pack => {
+    const p: Pack = { files: new Map(), index: new PackIndex(), lazy: new Map(), offsets: new Map(), parts: new Map(), ranges: new Map(), lazyRanges: new Map() };
+    addIndex(p, "d /lib\nf /lib/modules 11 image:1\np /lib/modules 4 jdk.other:0\np /lib/modules 7 image:5");
+    return p;
+  };
+  const text = (d: Uint8Array | null) => d && new TextDecoder().decode(d);
+  const b = new HttpBackend("https://example.test/jdk", pack());
+  assert.equal(text(b.readRange("/lib/modules", 0, 11)), "HEADMODTAIL");
+  assert.equal(text(b.readRange("/lib/modules", 5, 4)), "ODTA");
+  files.delete("/jdk/jdk.other.jar");
+  const left = new HttpBackend("https://example.test/jdk", pack());
+  assert.equal(text(left.readRange("/lib/modules", 7, 4)), "TAIL");
+  calls.length = 0;
+  assert.equal(left.readRange("/lib/modules", 4, 3), null);
+  assert.equal(left.readRange("/lib/modules", 5, 1), null);
+  assert.deepEqual(calls, ["/jdk/jdk.other.jar"]);
+  assert.deepEqual(warnings, ["java-web: https://example.test/jdk/jdk.other.jar is missing, so the classes in it do not load"]);
+});
diff --git a/test/image.test.ts b/test/image.test.ts
index c4e60ec..0c998ce 100644
--- a/test/image.test.ts
+++ b/test/image.test.ts
@@ -1,4 +1,4 @@
-// The Node backend over the packaged image (boot.pack and jdk/<module>.jar),
+// The Node backend over the packaged image (boot.pack and the jdk/*.jar images),
 // and dist/node.js, the Node entry `pnpm build` makes; those tests skip until
 // dist/ is built.
 
@@ -9,7 +9,7 @@ import { join } from "node:path";
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { ImageBackend } from "../src/image.ts";
-import { listIndex, packedRange, parsePack } from "../src/browser/http.ts";
+import { imagePart, listIndex, packedRange, parsePack } from "../src/browser/http.ts";
 import { hotspot } from "../scripts/hotspot.ts";
 
 const root = join(import.meta.dirname, "..");
@@ -65,6 +65,33 @@ test("ImageBackend reads the index, packed files and module images", () => {
   }
 });
 
+test("a file split across images reads from each part, and a left-out part reads as missing", () => {
+  const dir = mkdtempSync(join(tmpdir(), "jw-image-"));
+  try {
+    mkdirSync(join(dir, "jdk"));
+    // /lib/modules is "HEAD" "MOD" "TAIL": the middle in its own image
+    writeFileSync(join(dir, "jdk", "image.jar"), "xHEADTAIL");
+    writeFileSync(join(dir, "jdk", "jdk.other.jar"), "MOD");
+    const boot = pack([["/index.prefix", "0 d /lib\n0 f /lib/modules 11 image:1\n0 p /lib/modules 4 jdk.other:0\n15 7 image:5"]]);
+    writeFileSync(join(dir, "boot.pack"), boot);
+    const text = (d: Uint8Array | null) => d && new TextDecoder().decode(d);
+    const b = new ImageBackend(dir);
+    assert.equal(text(b.read("/lib/modules")), "HEADMODTAIL");
+    assert.equal(text(b.readRange("/lib/modules", 2, 4)), "ADMO");
+    assert.equal(text(b.readRange("/lib/modules", 5, 20)), "ODTAIL");
+    rmSync(join(dir, "jdk", "jdk.other.jar"));
+    const left = new ImageBackend(dir);
+    assert.equal(text(left.readRange("/lib/modules", 7, 4)), "TAIL");
+    assert.equal(left.readRange("/lib/modules", 4, 3), null);
+    const image = parsePack(boot.buffer as ArrayBuffer);
+    assert.deepEqual(imagePart(image, "/lib/modules", 0), { image: "/image.jar", at: 1, len: 4 });
+    assert.deepEqual(imagePart(image, "/lib/modules", 5), { image: "/jdk.other.jar", at: 1, len: 2 });
+    assert.deepEqual(imagePart(image, "/lib/modules", 8), { image: "/image.jar", at: 6, len: 3 });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("a VM keeps reading the image it started with when an upgrade replaces it", () => {
   const dir = mkdtempSync(join(tmpdir(), "jw-image-"));
   try {

From 870fc2b0b15b76d6842a941eba05a959fc686980 Mon Sep 17 00:00:00 2001
From: Project516 <138796702+Project516@users.noreply.github.com>
Date: Sun, 8 Nov 2026 15:09:21 -0600
Subject: [PATCH 2/2] fix: warn once when the Node image backend cannot read an
 image file, and warn about compressed ranges only once a whole read works

---
 src/browser/http.ts |  6 ++++--
 src/image.ts        | 22 +++++++++++++++-------
 test/image.test.ts  | 11 +++++++++--
 3 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/src/browser/http.ts b/src/browser/http.ts
index 33d6ed8..8222bb0 100644
--- a/src/browser/http.ts
+++ b/src/browser/http.ts
@@ -377,11 +377,13 @@ export class HttpBackend implements Backend {
   }
 
   // When ranges of a file come back wrong, reads all of it once: a whole
-  // response decodes correctly even from a host that compresses it.
+  // response decodes correctly even from a host that compresses it. A range
+  // that fails to decode throws as a network error does, so a failed read
+  // here is taken as the network's, and later reads try again.
   private readWhole(path: string, off: number, len: number): Uint8Array | null {
-    console.warn(`java-web: range reads of ${this.base}${path} came back compressed or wrong, so it is read whole. Serve it without compression (as .jar files are on GitHub Pages).`);
     const xhr = this.request("GET", path);
     if (!xhr) return null;
+    console.warn(`java-web: range reads of ${this.base}${path} came back compressed or wrong, so it is read whole. Serve it without compression (as .jar files are on GitHub Pages).`);
     const data = new Uint8Array(xhr.response as ArrayBuffer);
     this.cache.set(path, data);
     this.blocks.delete(path);
diff --git a/src/image.ts b/src/image.ts
index 79898bc..3ef90fc 100644
--- a/src/image.ts
+++ b/src/image.ts
@@ -20,6 +20,9 @@ export function imageFd(file: string): number {
   return fd;
 }
 
+// image files a read failed in, warned about once
+const unreadable = new Set<string>();
+
 export class ImageBackend implements Backend {
   readonly writable = false;
   // this VM's descriptor of each image file
@@ -57,21 +60,26 @@ export class ImageBackend implements Backend {
     if (part) return part;
     if (!this.pack.offsets.has(p)) return null;
     const out = new Uint8Array(len);
-    let n = 0;
+    let n = 0, image = "";
     try {
       while (n < len) {
         const at = imagePart(this.pack, p, off + n)!;
-        let fd = this.fds.get(at.image);
-        if (fd === undefined) this.fds.set(at.image, (fd = imageFd(path.join(this.dir, "jdk", at.image))));
+        image = at.image;
+        let fd = this.fds.get(image);
+        if (fd === undefined) this.fds.set(image, (fd = imageFd(path.join(this.dir, "jdk", image))));
         const got = fs.readSync(fd, out, n, Math.min(len - n, at.len), at.at);
         if (got === 0) break;
         n += got;
       }
-    } catch {
-      return null;
+    } catch {}
+    if (n === len) return out;
+    // a missing, short or unreadable image reads as missing rather than cut off
+    const file = path.join(this.dir, "jdk", image);
+    if (!unreadable.has(file)) {
+      unreadable.add(file);
+      console.warn(`java-web: cannot read ${file}, so the classes in it do not load`);
     }
-    // a short or unreadable image is damaged; the file reads as missing rather than cut off
-    return n === len ? out : null;
+    return null;
   }
 
   list(p: string): string[] | null {
diff --git a/test/image.test.ts b/test/image.test.ts
index 0c998ce..01695eb 100644
--- a/test/image.test.ts
+++ b/test/image.test.ts
@@ -26,7 +26,9 @@ function pack(entries: [string, string | Uint8Array][]): Uint8Array {
   return Uint8Array.from(parts);
 }
 
-test("ImageBackend reads the index, packed files and module images", () => {
+test("ImageBackend reads the index, packed files and module images", (t) => {
+  const warnings: string[] = [];
+  t.mock.method(console, "warn", (m: string) => warnings.push(m));
   const dir = mkdtempSync(join(tmpdir(), "jw-image-"));
   try {
     mkdirSync(join(dir, "jdk"));
@@ -58,6 +60,7 @@ test("ImageBackend reads the index, packed files and module images", () => {
     assert.equal(b.read("/lib"), null);
     // past the end of a damaged image
     assert.equal(b.read("/lib/cut"), null);
+    assert.deepEqual(warnings, [`java-web: cannot read ${join(dir, "jdk", "jdk.other.jar")}, so the classes in it do not load`]);
     rmSync(join(dir, "jdk", "image.jar"));
     assert.throws(() => new ImageBackend(dir), /no packaged JDK image/);
   } finally {
@@ -65,7 +68,9 @@ test("ImageBackend reads the index, packed files and module images", () => {
   }
 });
 
-test("a file split across images reads from each part, and a left-out part reads as missing", () => {
+test("a file split across images reads from each part, and a left-out part reads as missing", (t) => {
+  const warnings: string[] = [];
+  t.mock.method(console, "warn", (m: string) => warnings.push(m));
   const dir = mkdtempSync(join(tmpdir(), "jw-image-"));
   try {
     mkdirSync(join(dir, "jdk"));
@@ -83,6 +88,8 @@ test("a file split across images reads from each part, and a left-out part reads
     const left = new ImageBackend(dir);
     assert.equal(text(left.readRange("/lib/modules", 7, 4)), "TAIL");
     assert.equal(left.readRange("/lib/modules", 4, 3), null);
+    assert.equal(left.readRange("/lib/modules", 5, 1), null);
+    assert.deepEqual(warnings, [`java-web: cannot read ${join(dir, "jdk", "jdk.other.jar")}, so the classes in it do not load`]);
     const image = parsePack(boot.buffer as ArrayBuffer);
     assert.deepEqual(imagePart(image, "/lib/modules", 0), { image: "/image.jar", at: 1, len: 4 });
     assert.deepEqual(imagePart(image, "/lib/modules", 5), { image: "/jdk.other.jar", at: 1, len: 2 });