@datamoc/mw_games 0.19.0 → 0.20.0

package/dist/threads/index.d.ts

@@ -0,0 +1,3 @@
+export { spawn } from './spawn.ts';
+export type { SpawnOptions } from './spawn.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/threads/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/threads/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/threads/index.js

@@ -0,0 +1,2 @@
+export { spawn } from './spawn.js';
+//# sourceMappingURL=index.js.map

package/dist/threads/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/threads/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/threads/spawn.d.ts

@@ -0,0 +1,41 @@
+export interface SpawnOptions {
+    /** buffers posted to the task instead of copied: each is detached from this thread when spawn runs */
+    transfer?: Transferable[];
+    /** abandons the task after this many milliseconds; there is no default, because a render can legitimately take minutes */
+    timeout?: number;
+    /** aborting rejects the promise with the signal's reason and terminates the task's worker */
+    signal?: AbortSignal;
+}
+/**
+ * Runs `fn` on a worker thread and resolves with its value, keeping the caller's thread
+ * free: the one synchronous block a game can never get back is the frame it spends waiting.
+ *
+ * The task is serialized with `Function.prototype.toString` and rehydrated in the worker,
+ * so it must be **self-contained** - no closures over module scope, no imports, no bound or
+ * native functions. Everything it needs arrives as `args`, structured-cloned in; buffers
+ * listed in `options.transfer` are moved instead, detached from the caller's thread. The
+ * result comes back structured-cloned, with every ArrayBuffer inside it transferred rather
+ * than copied (the worker is finished with them). A task that throws, closes over
+ * something the worker cannot see, or exits its worker without answering rejects the
+ * promise - it never hangs - and `timeout` or `signal` abandon a task that never returns.
+ *
+ * One worker per task: construction costs a few milliseconds, which is nothing next to the
+ * work worth moving off the main thread (T161 measured break-even at roughly 10 ms per
+ * task in a batch, and far less against a dropped frame).
+ *
+ * @example
+ * ```ts
+ * import { spawn } from '@datamoc/mw_games/threads';
+ *
+ * const sum = await spawn((a: number, b: number) => a + b, [40, 2]);
+ * console.log(sum); // 42
+ *
+ * //a task that never returns is abandoned rather than hanging the caller
+ * const controller = new AbortController();
+ * const pending = spawn(() => new Promise(() => {}), [], { signal: controller.signal });
+ * controller.abort();
+ * pending.catch((error: Error) => console.log(error.name)); // 'AbortError'
+ * ```
+ */
+export declare function spawn<Args extends readonly unknown[], Result>(fn: (...args: Args) => Result, args?: Args, options?: SpawnOptions): Promise<Awaited<Result>>;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/threads/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../src/threads/spawn.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC5B,sGAAsG;IACtG,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B,0HAA0H;IAC1H,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAsED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAS,SAAS,OAAO,EAAE,EAAE,MAAM,EAC5D,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,EAC7B,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CA0D1B"}

package/dist/threads/spawn.js

@@ -0,0 +1,143 @@
+import { nodeThreads, workerMain } from './worker.js';
+const browserWorker = (events) => {
+    if (typeof Worker === 'undefined' ||
+        typeof Blob === 'undefined' ||
+        typeof URL === 'undefined' ||
+        typeof URL.createObjectURL !== 'function') {
+        return null;
+    }
+    //a blob worker, because the shipped file:// page allows worker-src blob: and because a
+    //file:// module worker is blocked by CORS whatever the policy says
+    const url = URL.createObjectURL(new Blob([`(${workerMain.toString()})()`], { type: 'text/javascript' }));
+    let worker;
+    try {
+        worker = new Worker(url);
+    }
+    catch (error) {
+        URL.revokeObjectURL(url);
+        throw error;
+    }
+    worker.onmessage = (event) => events.reply(event.data);
+    worker.onerror = (event) => events.fail(new Error(event.message || 'the worker failed to run'));
+    worker.onmessageerror = () => events.fail(new Error('the worker sent a reply that could not be deserialized'));
+    return {
+        post: (message, transfer) => worker.postMessage(message, transfer),
+        terminate: () => {
+            worker.terminate();
+            URL.revokeObjectURL(url);
+        },
+    };
+};
+const nodeWorker = (events) => {
+    const threads = nodeThreads();
+    if (!threads)
+        return null;
+    //the same source string as the browser path, executed as CJS by Node's eval mode
+    const worker = new threads.Worker(`(${workerMain.toString()})()`, { eval: true });
+    worker.on('message', (reply) => events.reply(reply));
+    worker.on('error', (error) => events.fail(error instanceof Error ? error : new Error(String(error))));
+    worker.on('messageerror', () => events.fail(new Error('the worker sent a reply that could not be deserialized')));
+    //a task that kills its worker without answering must reject rather than hang forever -
+    //the failure the multithreading package's pool never reports (T161)
+    worker.on('exit', (code) => events.fail(new Error(`the worker exited with code ${code} before answering`)));
+    return {
+        post: (message, transfer) => worker.postMessage(message, transfer),
+        terminate: () => void worker.terminate(),
+    };
+};
+/** the error a failed reply carries, with the worker-side stack where there was one */
+function taskError(reply) {
+    const error = new Error(reply.message);
+    if (reply.stack)
+        error.stack = reply.stack;
+    return error;
+}
+/**
+ * Runs `fn` on a worker thread and resolves with its value, keeping the caller's thread
+ * free: the one synchronous block a game can never get back is the frame it spends waiting.
+ *
+ * The task is serialized with `Function.prototype.toString` and rehydrated in the worker,
+ * so it must be **self-contained** - no closures over module scope, no imports, no bound or
+ * native functions. Everything it needs arrives as `args`, structured-cloned in; buffers
+ * listed in `options.transfer` are moved instead, detached from the caller's thread. The
+ * result comes back structured-cloned, with every ArrayBuffer inside it transferred rather
+ * than copied (the worker is finished with them). A task that throws, closes over
+ * something the worker cannot see, or exits its worker without answering rejects the
+ * promise - it never hangs - and `timeout` or `signal` abandon a task that never returns.
+ *
+ * One worker per task: construction costs a few milliseconds, which is nothing next to the
+ * work worth moving off the main thread (T161 measured break-even at roughly 10 ms per
+ * task in a batch, and far less against a dropped frame).
+ *
+ * @example
+ * ```ts
+ * import { spawn } from '@datamoc/mw_games/threads';
+ *
+ * const sum = await spawn((a: number, b: number) => a + b, [40, 2]);
+ * console.log(sum); // 42
+ *
+ * //a task that never returns is abandoned rather than hanging the caller
+ * const controller = new AbortController();
+ * const pending = spawn(() => new Promise(() => {}), [], { signal: controller.signal });
+ * controller.abort();
+ * pending.catch((error: Error) => console.log(error.name)); // 'AbortError'
+ * ```
+ */
+export function spawn(fn, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        if (options.signal?.aborted) {
+            reject(options.signal.reason);
+            return;
+        }
+        let settled = false;
+        let timer;
+        let worker;
+        const settle = (finish) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+            //one worker per task: whatever settled it, the worker is done
+            worker?.terminate();
+            finish();
+        };
+        function onAbort() {
+            settle(() => reject(options.signal.reason));
+        }
+        const events = {
+            reply: (reply) => settle(() => {
+                if (reply.ok)
+                    resolve(reply.value);
+                else
+                    reject(taskError(reply));
+            }),
+            fail: (error) => settle(() => reject(error)),
+        };
+        try {
+            //each host returns null when its environment is absent, so they are tried in order
+            worker = browserWorker(events) ?? nodeWorker(events);
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        if (!worker) {
+            reject(new Error('spawn() needs Web Workers or node:worker_threads, and this environment offers neither'));
+            return;
+        }
+        if (options.timeout !== undefined && options.timeout > 0) {
+            timer = setTimeout(() => settle(() => reject(new Error(`the task did not answer within ${options.timeout} ms`))), options.timeout);
+        }
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            worker.post({ code: fn.toString(), args: args ?? [] }, options.transfer ?? []);
+        }
+        catch (error) {
+            //unclonable arguments, or a transfer list that does not match the message
+            settle(() => reject(error));
+        }
+    });
+}
+//# sourceMappingURL=spawn.js.map

package/dist/threads/spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.js","sourceRoot":"","sources":["../../src/threads/spawn.ts"],"names":[],"mappings":"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"}

package/dist/threads/worker.d.ts

@@ -0,0 +1,51 @@
+/** what the main thread posts to a fresh worker: the task's source and its arguments */
+export interface WorkerRequest {
+    /** the stringified task function, rehydrated in the worker with `new Function` */
+    code: string;
+    args: readonly unknown[];
+}
+/** what the worker posts back: the value, or the failure that stopped it */
+export type WorkerReply = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+    stack?: string;
+};
+/**
+ * The slice of `node:worker_threads` this module uses, described structurally: `src/`
+ * compiles in a browser-only config (the `@example` fence compiler runs with `types: []`),
+ * so nothing here may name `process` or a `node:` type directly.
+ */
+export interface NodeThreads {
+    parentPort: {
+        on(event: 'message', listener: (request: WorkerRequest) => void): void;
+        postMessage(message: WorkerReply, transfer?: ArrayBuffer[]): void;
+    } | null;
+    Worker: new (code: string, options: {
+        eval: true;
+    }) => {
+        on(event: 'message', listener: (reply: WorkerReply) => void): void;
+        on(event: 'error', listener: (error: unknown) => void): void;
+        on(event: 'messageerror', listener: () => void): void;
+        on(event: 'exit', listener: (code: number) => void): void;
+        postMessage(message: WorkerRequest, transfer?: readonly unknown[]): void;
+        terminate(): Promise<number> | void;
+    };
+}
+/** `node:worker_threads` reached through `globalThis`, so nothing here needs @types/node */
+export declare function nodeThreads(): NodeThreads | undefined;
+/**
+ * The worker half of `threads.spawn`: receives one task, runs it, replies, and goes no
+ * further (spawn terminates it as soon as the reply settles).
+ *
+ * **This function must stay self-contained.** `spawn` ships it to a worker with
+ * `workerMain.toString()`, so it may not reference imports, module-scope helpers or any
+ * outer binding - everything it needs is either a language global or nested inside it.
+ * The same body runs in both transports: a classic blob worker in the browser (where the
+ * shipped `file://` CSP allows only `worker-src blob:` and `new Function`, per the T161
+ * probe) and an eval'd `node:worker_threads` worker in Node, which has no `self`.
+ */
+export declare function workerMain(): void;
+//# sourceMappingURL=worker.d.ts.map

package/dist/threads/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../src/threads/worker.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC7B,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CACzB;AAED,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExG;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,UAAU,EAAE;QACX,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAC;QACvE,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;KAClE,GAAG,IAAI,CAAC;IACT,MAAM,EAAE,KACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,KACnB;QACJ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAC;QACnE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;QAC7D,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;QACtD,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;QAC1D,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;QACzE,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;KACpC,CAAC;CACF;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,IAAI,WAAW,GAAG,SAAS,CAMrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAoEjC"}

package/dist/threads/worker.js

@@ -0,0 +1,84 @@
+/** `node:worker_threads` reached through `globalThis`, so nothing here needs @types/node */
+export function nodeThreads() {
+    return globalThis.process?.getBuiltinModule?.('node:worker_threads');
+}
+/**
+ * The worker half of `threads.spawn`: receives one task, runs it, replies, and goes no
+ * further (spawn terminates it as soon as the reply settles).
+ *
+ * **This function must stay self-contained.** `spawn` ships it to a worker with
+ * `workerMain.toString()`, so it may not reference imports, module-scope helpers or any
+ * outer binding - everything it needs is either a language global or nested inside it.
+ * The same body runs in both transports: a classic blob worker in the browser (where the
+ * shipped `file://` CSP allows only `worker-src blob:` and `new Function`, per the T161
+ * probe) and an eval'd `node:worker_threads` worker in Node, which has no `self`.
+ */
+export function workerMain() {
+    //the same chain as nodeThreads(), inlined because workerMain is stringified into the
+    //worker and may not call anything module-scoped; the cast is a type, erased before then
+    const nodePort = globalThis.process?.getBuiltinModule?.('node:worker_threads')?.parentPort ?? null;
+    const scope = globalThis;
+    /** every ArrayBuffer reachable through plain objects and arrays, listed once each */
+    const transferablesOf = (value) => {
+        const out = [];
+        const seen = new Set();
+        const visit = (item) => {
+            if (item === null || typeof item !== 'object')
+                return;
+            if (seen.has(item))
+                return;
+            seen.add(item);
+            if (ArrayBuffer.isView(item)) {
+                //a view transfers its whole buffer; a SharedArrayBuffer cannot transfer, so it
+                //stays a copy (and does not exist in the shipped file:// target at all)
+                const buffer = item.buffer;
+                if (buffer instanceof ArrayBuffer && !out.includes(buffer))
+                    out.push(buffer);
+                return;
+            }
+            if (item instanceof ArrayBuffer) {
+                if (!out.includes(item))
+                    out.push(item);
+                return;
+            }
+            if (Array.isArray(item)) {
+                for (const entry of item)
+                    visit(entry);
+                return;
+            }
+            const prototype = Object.getPrototypeOf(item);
+            if (prototype === Object.prototype || prototype === null) {
+                for (const entry of Object.values(item))
+                    visit(entry);
+            }
+        };
+        visit(value);
+        return out;
+    };
+    const reply = (message, transfer = []) => {
+        if (nodePort)
+            nodePort.postMessage(message, transfer);
+        else
+            scope.postMessage(message, transfer);
+    };
+    const onRequest = async (request) => {
+        try {
+            const task = new Function(`return (${request.code});`)();
+            const value = await task(...request.args);
+            reply({ ok: true, value }, transferablesOf(value));
+        }
+        catch (error) {
+            const failure = error;
+            reply({
+                ok: false,
+                message: String(failure?.message ?? error),
+                stack: typeof failure?.stack === 'string' ? failure.stack : undefined,
+            });
+        }
+    };
+    if (nodePort)
+        nodePort.on('message', (request) => void onRequest(request));
+    else
+        scope.onmessage = (event) => void onRequest(event.data);
+}
+//# sourceMappingURL=worker.js.map

package/dist/threads/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/threads/worker.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export declare const version = "0.19.0";
+export declare const version = "0.20.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -9,5 +9,5 @@
  * this from `package.json` automatically, chosen because this project's own build already
  * has no step before `tsc`/`vite` that this would need to run ahead of.
  */
-export const version = '0.19.0';
+export const version = '0.20.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@datamoc/mw_games",
-	"version": "0.19.0",
+	"version": "0.20.0",
 	"description": "A local-file game framework: renderer-free game logic, drawn through PixiJS in 2D or Babylon.js in 3D, with mobile and desktop packaging.",
 	"license": "MPL-2.0",
 	"repository": {
@@ -178,6 +178,10 @@
 			"types": "./dist/testing/index.d.ts",
 			"import": "./dist/testing/index.js"
 		},
+		"./threads": {
+			"types": "./dist/threads/index.d.ts",
+			"import": "./dist/threads/index.js"
+		},
 		"./tools/benchmark-browser": "./tools/benchmark-browser.mjs",
 		"./tools/benchmark-history": "./tools/benchmark-history.mjs",
 		"./tools/browser-smoke": "./tools/browser-smoke.mjs",
@@ -361,6 +365,7 @@
 		"@capacitor/ios": "^7.4.4",
 		"@types/node": "^26.4.1",
 		"@types/ws": "^8.18.1",
+		"multithreading": "^0.3.52",
 		"pixi.js": "^8.20.1",
 		"playwright-core": "^1.62.1",
 		"prettier": "^3.9.6",

package/sbom.cdx.json

@@ -1,7 +1,7 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:316ac220-52bf-5102-b492-e3d49b6d5244",
+  "serialNumber": "urn:uuid:224ae83a-9a61-53bd-ab61-d8f83739153f",
   "version": 1,
   "metadata": {
     "tools": {
@@ -10,16 +10,16 @@
           "type": "application",
           "group": "datamoc",
           "name": "tools/sbom.mjs",
-          "version": "0.19.0"
+          "version": "0.20.0"
         }
       ]
     },
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/%40datamoc/mw_games@0.19.0",
+      "bom-ref": "pkg:npm/%40datamoc/mw_games@0.20.0",
       "name": "@datamoc/mw_games",
-      "version": "0.19.0",
-      "purl": "pkg:npm/%40datamoc/mw_games@0.19.0",
+      "version": "0.20.0",
+      "purl": "pkg:npm/%40datamoc/mw_games@0.20.0",
       "description": "A local-file game framework: renderer-free game logic, drawn through PixiJS in 2D or Babylon.js in 3D, with mobile and desktop packaging.",
       "licenses": [
         {
@@ -33,15 +33,15 @@
   "components": [
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40babylonjs/core@9.26.0",
+      "bom-ref": "pkg:npm/%40babylonjs/core@9.27.1",
       "name": "@babylonjs/core",
-      "version": "9.26.0",
-      "purl": "pkg:npm/%40babylonjs/core@9.26.0",
+      "version": "9.27.1",
+      "purl": "pkg:npm/%40babylonjs/core@9.27.1",
       "scope": "excluded",
       "hashes": [
         {
           "alg": "SHA-512",
-          "content": "6097bb661f6f8fa5a0f0d6b0268032728185161bb35bd28b67290d9b69ef94daecd8fe371d332fdd2be06dfc072a40e91dc81ae1caddc9536549fd39e4b2e45e"
+          "content": "6dc1de07b60dad84620fea448598c47f39bcb53fcde1d0bca1886510d1556bd7e73ff5e21c46e6b7b87653a12cfefb3cc7f023bbef6f829726ab6aa72effb71f"
         }
       ],
       "licenses": [
@@ -54,15 +54,15 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40babylonjs/loaders@9.26.0",
+      "bom-ref": "pkg:npm/%40babylonjs/loaders@9.27.1",
       "name": "@babylonjs/loaders",
-      "version": "9.26.0",
-      "purl": "pkg:npm/%40babylonjs/loaders@9.26.0",
+      "version": "9.27.1",
+      "purl": "pkg:npm/%40babylonjs/loaders@9.27.1",
       "scope": "excluded",
       "hashes": [
         {
           "alg": "SHA-512",
-          "content": "2207e634db293eeec2c421b40bcbef377d8cd1f737c1eda697047360c758ad380d1454113be09d3f71c5ebcb1295a6743f9855f604b8d87057fb79145c001fad"
+          "content": "042b671f83ae0a2abb5cf34436c38fc8d05118e0519556e5778f58c0c21a95b3638e070030cb64fb0c7c933135ff2c0a1771dfae3af5edb30b4f7aa0989678da"
         }
       ],
       "licenses": [
@@ -1356,15 +1356,15 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40types/node@26.5.1",
+      "bom-ref": "pkg:npm/%40types/node@26.6.2",
       "name": "@types/node",
-      "version": "26.5.1",
-      "purl": "pkg:npm/%40types/node@26.5.1",
+      "version": "26.6.2",
+      "purl": "pkg:npm/%40types/node@26.6.2",
       "scope": "excluded",
       "hashes": [
         {
           "alg": "SHA-512",
-          "content": "0b3366d857b35b8551fcb8c6eb251d88480b13fac043d4a58f9802bbf0b656b75c5bb2346a1359f0345b1d3ef3399eabdce36077f6ec4087926a80c6addd42ea"
+          "content": "5f53f6d6c70cbf8cc628b62a8dd1a368a6bb08e6b444a55861964dfcd7ef2d0d497a0c4585d869646fcbca7f005f1e820d46af280775d6fe81bdfa640c1c8af2"
         }
       ],
       "licenses": [
@@ -3202,6 +3202,27 @@
         }
       ]
     },
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/multithreading@0.3.52",
+      "name": "multithreading",
+      "version": "0.3.52",
+      "purl": "pkg:npm/multithreading@0.3.52",
+      "scope": "excluded",
+      "hashes": [
+        {
+          "alg": "SHA-512",
+          "content": "5e0fd81f59393ee63e41659f3c215ec39c6c529945f5cf9726a6343df95239f0186f5b96b876339b6cf328f920de2e406caf8e254b20cd7ef0b41f6081d9b4c6"
+        }
+      ],
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/nanoid@3.3.19",
@@ -4402,13 +4423,13 @@
   ],
   "dependencies": [
     {
-      "ref": "pkg:npm/%40babylonjs/core@9.26.0",
+      "ref": "pkg:npm/%40babylonjs/core@9.27.1",
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/%40babylonjs/loaders@9.26.0",
+      "ref": "pkg:npm/%40babylonjs/loaders@9.27.1",
       "dependsOn": [
-        "pkg:npm/%40babylonjs/core@9.26.0",
+        "pkg:npm/%40babylonjs/core@9.27.1",
         "pkg:npm/babylonjs-gltf2interface@9.26.0"
       ]
     },
@@ -4453,18 +4474,19 @@
       ]
     },
     {
-      "ref": "pkg:npm/%40datamoc/mw_games@0.19.0",
+      "ref": "pkg:npm/%40datamoc/mw_games@0.20.0",
       "dependsOn": [
-        "pkg:npm/%40babylonjs/core@9.26.0",
-        "pkg:npm/%40babylonjs/loaders@9.26.0",
+        "pkg:npm/%40babylonjs/core@9.27.1",
+        "pkg:npm/%40babylonjs/loaders@9.27.1",
         "pkg:npm/%40capacitor/android@7.6.9",
         "pkg:npm/%40capacitor/cli@7.6.9",
         "pkg:npm/%40capacitor/core@7.6.9",
         "pkg:npm/%40capacitor/ios@7.6.9",
-        "pkg:npm/%40types/node@26.5.1",
+        "pkg:npm/%40types/node@26.6.2",
         "pkg:npm/%40types/ws@8.18.1",
         "pkg:npm/fengari@0.1.5",
         "pkg:npm/json5@2.2.3",
+        "pkg:npm/multithreading@0.3.52",
         "pkg:npm/pixi.js@8.20.1",
         "pkg:npm/playwright-core@1.63.0",
         "pkg:npm/prettier@3.9.6",
@@ -4776,11 +4798,11 @@
     {
       "ref": "pkg:npm/%40types/fs-extra@8.1.5",
       "dependsOn": [
-        "pkg:npm/%40types/node@26.5.1"
+        "pkg:npm/%40types/node@26.6.2"
       ]
     },
     {
-      "ref": "pkg:npm/%40types/node@26.5.1",
+      "ref": "pkg:npm/%40types/node@26.6.2",
       "dependsOn": [
         "pkg:npm/undici-types@8.9.0"
       ]
@@ -4792,7 +4814,7 @@
     {
       "ref": "pkg:npm/%40types/ws@8.18.1",
       "dependsOn": [
-        "pkg:npm/%40types/node@26.5.1"
+        "pkg:npm/%40types/node@26.6.2"
       ]
     },
     {
@@ -5196,6 +5218,10 @@
       "ref": "pkg:npm/ms@2.1.3",
       "dependsOn": []
     },
+    {
+      "ref": "pkg:npm/multithreading@0.3.52",
+      "dependsOn": []
+    },
     {
       "ref": "pkg:npm/nanoid@3.3.19",
       "dependsOn": []
@@ -5532,7 +5558,7 @@
     {
       "ref": "pkg:npm/vite@8.3.0",
       "dependsOn": [
-        "pkg:npm/%40types/node@26.5.1",
+        "pkg:npm/%40types/node@26.6.2",
         "pkg:npm/fsevents@2.3.3",
         "pkg:npm/lightningcss@1.33.0",
         "pkg:npm/picomatch@4.0.7",

package/tools/compress-dist.d.mts

@@ -6,6 +6,8 @@ export interface CompressOptions {
 	brotli?: boolean;
 	/** Also write `.xz` siblings where smaller (default false, needs the system `xz`). */
 	xz?: boolean;
+	/** Files to compress at once (default `compressJobs()`). */
+	jobs?: number;
 }
 
 /**
@@ -25,6 +27,12 @@ export interface CompressRow {
 /** True when the system `xz` binary (LZMA2) is available for the opt-in archive pass. */
 export function hasXz(): boolean;
 
+/**
+ * How many files `compressDist` works on at once: `MWG_COMPRESS_JOBS` when it names
+ * a positive integer, else the machine's own thread count, else 4.
+ */
+export function compressJobs(): number;
+
 /**
  * Writes compressed siblings for the large files in `dir`, *into that same folder*: the
  * originals are left untouched, and each `<file>` gains `<file>.gz`, `<file>.br` and, when