perf(export): replace jszip with client-zip - 302 -> 211 kB bundle

The Download ZIP button bundles three short text files (the two Factorio
JSON documents plus the exchange string) for the headless CLI route. It
was costing 97 kB of the shipped bundle to do it.

`jszip`'s `browser` field resolves `./lib/index` to `dist/jszip.min.js`, a
97.6 kB pre-minified **browserify** bundle. That is an opaque IIFE with its
own module registry, so it cannot be tree-shaken, and the pako 1.0.11 baked
inside it cannot dedupe against the app's pako 3.0.1. The app was shipping
two pako majors plus `readable-stream`, `setimmediate` and eight more Node
shims in order to write three text files.

Measured, by building both ways:

| | raw | gzip |
| --- | --- | --- |
| before (jszip) | 302.07 kB | 99.81 kB |
| after (client-zip) | 211.44 kB | 73.11 kB |
| delta | **-90.63 kB (-30%)** | **-26.70 kB (-27%)** |

Isolating the libraries: a build with the zip feature stubbed out entirely
is 204.95 kB, so `client-zip` costs **6.49 kB** where `jszip` cost 97.1 kB
- about 15x smaller for this use.

Confirmed gone from the bundle rather than assumed: `JSZip`, `jszip`,
`setImmediate`, `readable-stream` and `_tr_stored_block` markers all drop
to zero, and pako's `incorrect header check` string goes from 2 occurrences
to 1 - the codec's pako 3.0.1 remains, the duplicate is gone. `vp build`
still prints no warnings at all, which is the standing invariant.

**The output is materially unchanged, and the reason is worth recording:
jszip was not compressing either.** Both writers emit `Stored` entries at
0% - `generateAsync` without an explicit `compression` option does not
deflate. So the whole pako 1.x payload was dead weight for this path. The
downloaded archive goes 7888 -> 7936 bytes (+48 bytes, +0.6%), which is the
central-directory layout differing slightly, not a compression regression.

`jszip` moves to devDependencies and stays the **reader** in
`test/zipExport.spec.ts`. That is deliberate: checking a client-zip archive
with client-zip would prove self-consistency, not correctness. Validated
against a third implementation too - `unzip -t` (Info-ZIP) reports "No
errors detected" and lists all three entries with correct names, sizes and
CRCs.

Note `pnpm add -D` will not relocate a package whose installed version
already satisfies the range - it prints "Already up to date" and leaves it
where it was - so the dependencies -> devDependencies move was made by
editing `package.json` directly and re-running `pnpm install`.

The spec gains two cases, because changing the *writer* means entry
presence is no longer a sufficient assertion: one parses both JSON entries
back and checks real fields, and asserts the exchange string survives
verbatim against the fixture; one covers preset-name-derived entry naming
and the exact entry set. 1249 -> 1251 tests.

Not adopted for currency: `client-zip`'s last human commit is 2025-03-14
(the newer repo push is a Dependabot branch). This swap buys bundle size
and API fit, not fresher maintenance. What it does improve is backlog - 8
open issues against jszip's 412 and 40 unanswered PRs.

Gate: `pnpm run verify` exit 0 - 314 files formatted, 301 clean, app 1251
passed / 3 skipped, worker 12, container 3.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GjMSePtN9aTgr8EtZp66k1

Author: wormeyman

package.json

@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@vue/devtools-api": "^8.2.1",
-    "jszip": "^3.10.1",
+    "client-zip": "^2.5.0",
     "pako": "^3.0.1",
     "pinia": "^4.0.2",
     "vue": "^3.5.40"
@@ -35,6 +35,7 @@
     "@vue/test-utils": "^2.4.11",
     "concurrently": "^10.0.4",
     "happy-dom": "^20.11.1",
+    "jszip": "^3.10.1",
     "typescript": "^6.0.3",
     "vite-plus": "^0.2.6",
     "vue-tsc": "^3.3.8"

pnpm-lock.yaml

@@ -1,4 +1,4 @@
-import JSZip from "jszip";
+import { downloadZip } from "client-zip";
 import { encodeExchangeString } from "../codec/mapExchangeString";
 import { presetToEncodable } from "../model/convert";
 import type { Preset } from "../model/types";
@@ -7,11 +7,42 @@ import { toMapGenSettingsJson, toMapSettingsJson } from "./jsonExport";
 /**
  * Bundle a preset's two Factorio JSON documents plus its map-exchange string
  * into a single downloadable ZIP `Blob`.
+ *
+ * The two JSON files are what the game's own CLI consumes - `factorio --create
+ * <save> --map-gen-settings <file> --map-settings <file>` - so this is the
+ * headless/dedicated-server route for a preset. The `.txt` carries the exchange
+ * string for the in-game map-generator dialog.
+ *
+ * Backed by `client-zip` rather than `jszip`, which is a bundle-size decision:
+ * jszip's `browser` field resolves to a 97.6 kB pre-minified *browserify*
+ * bundle - an opaque IIFE that cannot be tree-shaken and that carries its own
+ * copy of pako 1.x, so the app shipped two pako majors plus readable-stream and
+ * setimmediate shims in order to write three short text files. `client-zip` is
+ * zero-dependency browser-native ESM.
+ *
+ * `jszip` remains a devDependency and is *deliberately* still the reader in
+ * `test/zipExport.spec.ts`. Checking our own writer with our own reader would
+ * be self-consistent rather than correct; an independent, battle-tested reader
+ * is the whole point of that test.
+ *
+ * Entry timestamps default to "now", which is what jszip did too, so the
+ * archive is not byte-reproducible across runs. That is fine and always was:
+ * byte-exactness is the *exchange string's* invariant, enforced in
+ * `src/codec/`. A ZIP is read by whatever unzip tool opens it.
  */
 export async function buildZip(preset: Preset): Promise<Blob> {
-  const zip = new JSZip();
-  zip.file("map-gen-settings.json", JSON.stringify(toMapGenSettingsJson(preset), null, 2));
-  zip.file("map-settings.json", JSON.stringify(toMapSettingsJson(preset), null, 2));
-  zip.file(`${preset.name}.txt`, encodeExchangeString(presetToEncodable(preset)));
-  return zip.generateAsync({ type: "blob" });
+  return downloadZip([
+    {
+      name: "map-gen-settings.json",
+      input: JSON.stringify(toMapGenSettingsJson(preset), null, 2),
+    },
+    {
+      name: "map-settings.json",
+      input: JSON.stringify(toMapSettingsJson(preset), null, 2),
+    },
+    {
+      name: `${preset.name}.txt`,
+      input: encodeExchangeString(presetToEncodable(preset)),
+    },
+  ]).blob();
 }

src/io/zipExport.ts

@@ -7,18 +7,54 @@ import fixtures from "./fixtures/builtin-presets.json";
 
 const presets = fixtures.presets as Record<string, string>;
 
+function defaultPreset() {
+  return presetFromDecoded("Default", decodeExchangeString(presets["Default"] as string), true);
+}
+
 describe("buildZip", () => {
+  // `buildZip` writes with `client-zip`; this reads with `jszip`, which is a
+  // devDependency kept for exactly this purpose. Reading our own archive with
+  // our own writer's library would only prove self-consistency.
   it("bundles the two JSON files and the exchange string", async () => {
-    const preset = presetFromDecoded(
-      "Default",
-      decodeExchangeString(presets["Default"] as string),
-      true,
-    );
-    const blob = await buildZip(preset);
+    const blob = await buildZip(defaultPreset());
     const zip = await JSZip.loadAsync(blob);
     expect(zip.file("map-gen-settings.json")).not.toBeNull();
     expect(zip.file("map-settings.json")).not.toBeNull();
     const txt = await zip.file("Default.txt")?.async("string");
     expect(txt?.startsWith(">>>")).toBe(true);
   });
+
+  it("round-trips each entry's bytes intact, not merely its name", async () => {
+    const preset = defaultPreset();
+    const zip = await JSZip.loadAsync(await buildZip(preset));
+
+    // Entry presence says nothing about whether the payload survived the
+    // writer. Parse it back and check real fields.
+    const gen = JSON.parse((await zip.file("map-gen-settings.json")!.async("string")) as string);
+    expect(gen.width).toBe(preset.width);
+    expect(gen.height).toBe(preset.height);
+    expect(gen.autoplace_controls).toBeTypeOf("object");
+    expect(Object.keys(gen.autoplace_controls).length).toBeGreaterThan(0);
+
+    const map = JSON.parse((await zip.file("map-settings.json")!.async("string")) as string);
+    expect(map.pollution).toBeTypeOf("object");
+    expect(map.enemy_evolution).toBeTypeOf("object");
+
+    // The exchange string must survive verbatim - it is the one artifact in
+    // the archive with a byte-exactness invariant behind it.
+    const txt = (await zip.file("Default.txt")!.async("string")) as string;
+    expect(txt).toBe(presets["Default"]);
+  });
+
+  it("names the text entry after the preset", async () => {
+    const preset = defaultPreset();
+    preset.name = "My Custom Preset";
+    const zip = await JSZip.loadAsync(await buildZip(preset));
+    expect(zip.file("My Custom Preset.txt")).not.toBeNull();
+    expect(Object.keys(zip.files).sort()).toEqual([
+      "My Custom Preset.txt",
+      "map-gen-settings.json",
+      "map-settings.json",
+    ]);
+  });
 });