@needle-tools/gltf-build-pipeline 2.16.0-alpha.bc3af72 → 2.16.0-alpha.eb5a640

package/README.md

@@ -14,10 +14,10 @@ Includes support for generating LOD quality level for textures and meshes. Use w
 In general all files that have been processed by this package are valid glTF/GLB files.    
 The glTF Build Pipeline package is meant to be used as a last step before delivery.   
 That means:
-- files are meant to be loaded e.g. in a web runtime like three.js 
+- files are meant to be loaded by [Needle Engine](https://needle.tools) (and other three.js based runtimes)
 - files are not to be opened in Blender again to be further edited    
 
-To load progressively enhanced glTF files in any three.js based engine see examples at [@needle-tools/gltf-progressive](https://www.npmjs.com/package/@needle-tools/gltf-progressive)
+To load progressively enhanced glTF files in Needle Engine or another three.js based runtime, see examples at [@needle-tools/gltf-progressive](https://www.npmjs.com/package/@needle-tools/gltf-progressive)
 
 ### Installation
 
@@ -26,6 +26,33 @@ To load progressively enhanced glTF files in any three.js based engine see examp
 ### Commands
 - `help` - use help to view options
 
+### Configuration
+
+The pipeline reads an optional `needle.config.json` from the working directory (or any parent directory). Configure pipeline behaviour under the `gltf` key:
+
+```json
+{
+  "gltf": {
+    "usecase": "product",
+    "textures": { "lods": true },
+    "meshes":   { "lods": true },
+    "audio":    { "enabled": true, "bitrate": 64 },
+    "exr":      { "enabled": true }
+  }
+}
+```
+
+The `gltf` value may also be a string shorthand for `usecase` — `"gltf": "product"` is equivalent to `"gltf": { "usecase": "product" }`.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `usecase` | `"default" \| "product" \| "world"` | `"default"` | High-level optimisation profile. |
+| `textures.lods` | `boolean` | `true` | Generate progressive texture LODs. |
+| `meshes.lods` | `boolean` | `true` | Generate progressive mesh LODs. |
+| `audio.enabled` | `boolean` | `true` | Compress externally referenced `.wav` audio files to Opus in an `.ogg` container, rewriting the URIs in the glTF. Lossy formats (`.mp3`, `.ogg`, `.m4a`, `.aac`) pass through unchanged to avoid compounding compression artifacts. Requires `ffmpeg` with `libopus` on `PATH`; when missing the build logs a warning and leaves the audio files untouched. |
+| `audio.bitrate` | `number` (kbps) | `128` | Opus encoding bitrate. 96 is near-transparent for most music; 128 matches YouTube's music tier and is the safe "won't sound bad" default. Drop to 48–64 for known mono/UI-only assets. |
+| `exr.enabled` | `boolean` | `true` | Convert EXR textures to KTX2 HDR via PMREM. When `false`, EXR textures (bundled and externally referenced) are left as-is so a downstream step can handle them. |
+
 # Contact
 
 For licensing questions please contact us.

package/dist/cache/cache.d.ts

@@ -2,6 +2,7 @@
 /// <reference types="node" resolution-mode="require"/>
 import { ExtensibleProperty } from "@gltf-transform/core";
 import { Logger } from "@donmccurdy/caporal";
+export declare function ensureHashReady(): Promise<void>;
 /**
  * Clear the cache.
  * This will remove all files in the cache directory.

package/dist/cache/cache.js

@@ -6,9 +6,16 @@ import { getVersion } from "../utils/version.js";
 // import * as CHECKDISCSPACE from 'check-disk-space'
 import xxhash from "xxhash-wasm";
 let xxHashModule = null;
-xxhash().then(module => {
-    xxHashModule = module;
-}).catch(() => { });
+// Single shared promise that resolves once the WASM module is loaded (or has failed).
+// Callers should `await ensureHashReady()` once before any synchronous hash call to
+// avoid a race where early calls use the JS fallback and later calls use WASM —
+// producing different cache keys for the same input within one process.
+const xxHashReady = xxhash()
+    .then(module => { xxHashModule = module; })
+    .catch(() => { });
+export function ensureHashReady() {
+    return xxHashReady;
+}
 /**
  * Get the available space on the cache directory in bytes.
  */
@@ -179,6 +186,17 @@ export function getKeyWithHash(property) {
     const key = `${prefix}-${hash}`;
     return { key, hash };
 }
+/**
+ * Combine two 32-bit hashes with mixing. Plain `a + b` is commutative and
+ * has poor diffusion — swapping two attribute buffers collides. This uses a
+ * boost::hash_combine-style mix: xor in the new bits, then bit-shift mix so
+ * order matters and unrelated changes don't cancel out.
+ */
+function combineHash(seed, value) {
+    // 0x9e3779b9 = golden-ratio constant used by boost / fnv variants
+    seed = (seed ^ (value + 0x9e3779b9 + ((seed << 6) | 0) + (seed >>> 2))) | 0;
+    return seed;
+}
 /**
  * Get the hash for a property or an object.
  * @param property The property to get the hash for.
@@ -186,27 +204,26 @@ export function getKeyWithHash(property) {
  * @returns The hash as a number.
  */
 export function getHash(property, level = 0) {
-    let hashStr = "";
     let hash = 0;
     if (property instanceof ExtensibleProperty) {
         const extensions = property.listExtensions();
         const extras = property.getExtras();
-        hash += hashObject({
+        hash = combineHash(hash, hashObject({
             extensions,
             extras,
-        });
+        }));
         if (property instanceof Texture) {
             const image = property.getImage();
             const bytes = image?.buffer;
             if (bytes)
-                hash += hashBuffer(bytes, image.byteOffset, image.byteLength);
+                hash = combineHash(hash, hashBuffer(bytes, image.byteOffset, image.byteLength));
         }
         else if (property instanceof Mesh) {
             const weights = property.getWeights();
-            hash += hashObject(weights);
+            hash = combineHash(hash, hashObject(weights));
             const primitives = property.listPrimitives();
             for (const prim of primitives) {
-                hash += hashString(getHash(prim, level + 1));
+                hash = combineHash(hash, hashString(getHash(prim, level + 1)));
             }
         }
         else if (property instanceof Primitive) {
@@ -220,32 +237,35 @@ export function getHash(property, level = 0) {
                     name: s,
                 };
             });
-            hash += hashObject({
+            hash = combineHash(hash, hashObject({
                 indices,
                 attributes,
                 targets,
                 semantics: semanticsNames
-            });
+            }));
             if (indices) {
                 const indexBuffer = indices.getArray();
                 if (indexBuffer) {
-                    hash += hashBuffer(indexBuffer.buffer, indexBuffer.byteOffset, indexBuffer.byteLength);
+                    hash = combineHash(hash, hashBuffer(indexBuffer.buffer, indexBuffer.byteOffset, indexBuffer.byteLength));
                 }
             }
             // We can not pass the whole buffer into hashObject since very large meshes will cause errors when trying to stringify
             // See https://linear.app/needle/issue/NE-6414
+            // Mix the semantic name into each attribute hash so swapping two attributes (e.g. POSITION ↔ NORMAL)
+            // doesn't collide — without this, the commutative combine would erase attribute identity.
             for (const sem of semantics) {
                 const arr = property.getAttribute(sem)?.getArray();
                 if (arr) {
-                    hash += hashBuffer(arr.buffer, arr.byteOffset, arr.byteLength);
+                    hash = combineHash(hash, hashString(sem));
+                    hash = combineHash(hash, hashBuffer(arr.buffer, arr.byteOffset, arr.byteLength));
                 }
             }
         }
     }
     else {
-        hash += hashObject(property);
+        hash = combineHash(hash, hashObject(property));
     }
-    return hashStr + hash;
+    return String(hash);
 }
 const cleanBuildPipelineVersion = getVersion(false).replace(/[^a-zA-Z0-9]/g, "_");
 function getCacheDirectory(root) {

package/dist/cli/index.js

@@ -5,7 +5,7 @@ import { printStats, writeFileStatsToFile } from '../utils/stats.js';
 import { getVersion } from '../utils/version.js';
 import { UsecaseOptions, createConfig, getConfig } from '../config/index.js';
 import { isLOD, make_progressive } from '../transforms/needle_progressive.js';
-import { cacheSizeLimit, clearCache, limitCacheSize } from '../cache/cache.js';
+import { cacheSizeLimit, clearCache, ensureHashReady, limitCacheSize } from '../cache/cache.js';
 import { computeJobKey, saveJobResult, tryRestoreJobResult } from '../cache/job-cache.js';
 import { existsSync, statSync } from 'fs';
 import { ensureIsDirectory, foreachGLTF, isDirectory } from '../utils/fileutils.js';
@@ -14,6 +14,16 @@ import { ERROR_CODES } from '../constants.js';
 import { trackPipelineStart, trackPipelineEnd, trackError } from '../utils/analytics.js';
 // For testing / dev you can run `npm link` in the package directory
 // For removing the link run `npm rm --global @needle-tools/gltf-build-pipeline`
+// Disable caporal's autoCast for positional arguments.
+//
+// caporal's autoCast uses /^true|false$/ (precedence bug — should be /^(true|false)$/),
+// which matches any string ending with "false" or starting with "true". An <output>
+// path like ".../out-shellfalse" gets coerced to the boolean false, then stringified
+// to "false", and the pipeline writes to "<inputDir>/false" instead of the requested
+// directory. Same shape applies to paths ending with "on" or starting with "yes"/"1".
+// Disabling autoCast at the program level forces positionals through String(...);
+// options with explicit BOOLEAN/STRING validators are unaffected.
+program.cast(false);
 program
     .command("version", "Print current version")
     .action(async ({ logger }) => {
@@ -35,6 +45,9 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
     .option("--verbose", "Enable verbose output", { validator: program.BOOLEAN, default: false })
     .action(async ({ logger, args, options }) => {
     logger.level = options.verbose ? "debug" : "info";
+    // Wait for the xxHash WASM module so any hashing inside calculateStats sees the
+    // same hash function on every call (otherwise the first calls use the JS fallback).
+    await ensureHashReady();
     logger.info("Calculating stats for \"" + args.input + "\"");
     const input = args.input.toString();
     const filestats = new Array();
@@ -60,8 +73,14 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
 This will produce multiple versions of the input file, each with a different level of optimization.   
 Each version will be compressed and written to the output directory.
 `)
-    .argument('<input>', "The input glTF, GLB or VRM file that should be compressed OR a directory that contains files to be compressed")
-    .argument('<output>', "The output file or directory. It can be an absolute path or a relative path to the input file. If not provided, the input file will be overwritten.", { default: null })
+    // Explicit STRING validators prevent caporal's autoCast() from silently coercing
+    // a path that ends with "false" / "on" (or starts with "true" / "yes" / "1") into
+    // a boolean — caporal's autoCast regex is missing parentheses and matches as
+    // /^true | false$/ rather than /^(true|false)$/. Without these validators, an
+    // output path like "out-shellfalse" gets cast to the boolean false → stringified
+    // → file written to "<inputDir>/false" instead of the named directory.
+    .argument('<input>', "The input glTF, GLB or VRM file that should be compressed OR a directory that contains files to be compressed", { validator: program.STRING })
+    .argument('<output>', "The output file or directory. It can be an absolute path or a relative path to the input file. If not provided, the input file will be overwritten.", { default: null, validator: program.STRING })
     .option("--compress", `When enabled files will be compressed`, { validator: program.BOOLEAN, default: true })
     .option("--progressive", `When enabled files will processed to be progressively loaded`, { validator: program.BOOLEAN, default: true })
     .option("--usecase <usecase>", `The usecase for the compression. This will set the compression settings. Possible options: [${UsecaseOptions.join(", ")}]`, { validator: program.STRING })
@@ -76,6 +95,10 @@ Each version will be compressed and written to the output directory.
         logger.error(`[Needle Build Pipeline] v${getVersion()} You need to enable at least one of the options: --compress or --progressive`);
         return;
     }
+    // Wait for the xxHash WASM module before any hashing happens. Without this the
+    // first hash calls in a process use the JS fallback while later ones use WASM,
+    // producing different cache keys for the same input within a single run.
+    await ensureHashReady();
     logger.info(`[Needle Build Pipeline] v${getVersion()} — Transform '${args.input}'`);
     const pipelineMode = [options.progressive && 'progressive', options.compress && 'compress'].filter(Boolean).join('+');
     trackPipelineStart({ mode: pipelineMode, usecase: options.usecase?.toString() });
@@ -164,7 +187,7 @@ Each version will be compressed and written to the output directory.
                         stats.totalFileSizeInMBBefore += inputFileSize;
                     }
                 }
-                logger.info(`→ [CACHE] Restored ${restored.length} file(s)for job ${jobKey}`);
+                logger.info(`→ [CACHE] Restored ${restored.length} file(s) for job ${jobKey}`);
                 return;
             }
         }

package/dist/config/index.d.ts

@@ -13,6 +13,17 @@ export type Config = {
     meshes?: {
         lods: boolean;
     };
+    audio?: {
+        /** Enable Opus/Ogg compression of externally referenced audio files. Default: true. */
+        enabled?: boolean;
+        /** Opus encoding bitrate in kbps. Default: 64. */
+        bitrate?: number;
+    };
+    exr?: {
+        /** Enable EXR -> KTX2 HDR conversion via PMREM. When false, EXR textures (bundled or
+         *  externally referenced) are left untouched. Default: true. */
+        enabled?: boolean;
+    };
 };
 /**
  * Create a config object with the given usecase.

package/dist/config/index.js

@@ -70,8 +70,11 @@ export function getConfig(configPath, fallbackSearchDirectory, opts) {
             throw new Error(`Failed parsing config at \"${configPath}\"`);
         }
     }
+    // Always return a fresh shallow copy. Callers (notably the CLI) mutate the
+    // returned object (`config.usecase = ...`); returning the cache by reference
+    // would let those mutations poison subsequent getConfig() calls.
     if (_cachedConfig !== undefined) {
-        return _cachedConfig;
+        return { ..._cachedConfig };
     }
     // Resolve the config once and cache it
     // Check if a needle.config.json exists in the directory from which the script is run (or any parent directory)
@@ -82,12 +85,14 @@ export function getConfig(configPath, fallbackSearchDirectory, opts) {
             logger.info(`Using config with usecase: ${_cachedConfig.usecase}`);
         }
     }
-    // If no config was found, use the default config
+    // If no config was found, use the default config. Store a copy in the cache
+    // so we never alias defaultConfig directly — that way even if a downstream
+    // bug ever returned the cache by reference, defaultConfig itself stays clean.
     if (!_cachedConfig) {
         logger.debug("No config found. Using default config.");
-        _cachedConfig = defaultConfig;
+        _cachedConfig = { ...defaultConfig };
     }
-    return _cachedConfig;
+    return { ..._cachedConfig };
 }
 let _cachedConfig = undefined;
 export function searchConfig(directory, logger) {

package/dist/extensions/NEEDLE_opaque/NEEDLE_opaque.d.ts

@@ -1,4 +1,4 @@
-import { WriterContext, PropertyType } from '@gltf-transform/core';
+import { Extension, WriterContext, PropertyType } from '@gltf-transform/core';
 declare interface IExtensibleProperty {
 }
 type DebugBreakPoint = boolean | "pointer:read";
@@ -23,5 +23,5 @@ export interface IExtensionWriter {
     write(context: WriterContext, prop: IExtensibleProperty): void;
 }
 export declare let currentGenerator: string;
-export declare function createOpaqueExtension(name: string, types: PropertyType | PropertyType[], opts?: Options): IOpaqueExtension;
+export declare function createOpaqueExtension(name: string, types: PropertyType | PropertyType[], opts?: Options): typeof Extension;
 export {};

package/dist/extensions/NEEDLE_opaque/NEEDLE_opaque.js

@@ -5,6 +5,7 @@ import { NEEDLE_progressive_texture_settings } from '../NEEDLE_progressive_textu
 import { testAssert } from '../../utils/test-assert.js';
 import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
+import { isAudioUri, isRelativeAudioUri, listAudioRefs, registerAudioRef } from '../../transforms/needle_audio_registry.js';
 const ALL_PROPERTY_TYPES = [];
 for (const key in PropertyType) {
     ALL_PROPERTY_TYPES.push(PropertyType[key]);
@@ -627,6 +628,25 @@ class JsonPointerHandler {
                         else
                             console.warn("WARN: failed registering pointer", fullPath, value);
                     }
+                    // External audio reference (e.g. "click.wav" or "music.mp3" on a NEEDLE_components AudioSource).
+                    // Audio is never embedded in the GLB — it stays as a sidecar file. We register the
+                    // (obj, key) location so `needle_audio_transform` can compress the file and so the
+                    // write-time pass can rewrite the JSON string to the new URI.
+                    if (!isTexturePointer && isAudioUri(value) && isRelativeAudioUri(value)) {
+                        const inputDir = getExtensionInputFile() ? dirname(getExtensionInputFile()) : '';
+                        const audioPath = inputDir ? join(inputDir, value) : '';
+                        if (audioPath && existsSync(audioPath)) {
+                            registerAudioRef({ obj, key, sourcePath: audioPath, sourceUri: value });
+                            if (this.debug)
+                                console.log(`Registered external audio "${value}" at ${fullPath}`);
+                        }
+                        else if (audioPath) {
+                            // Non-fatal: leave the URI untouched and warn. Mirrors EXR error path
+                            // but uses warn instead of testAssert since missing audio shouldn't
+                            // hard-fail the build.
+                            this.document.getLogger().warn(`NEEDLE_opaque: external audio not found: ${audioPath}`);
+                        }
+                    }
                     // External EXR file reference (e.g. "StudioHDRI_ferndale_studio_04_1k.exr" in a ReflectionProbe)
                     // Inject the file into the document as a Texture so PMREM can process it
                     if (!isTexturePointer && value.match(/\.exr$/i)) {
@@ -816,6 +836,16 @@ class JsonPointerHandler {
             if (ptr.resolve(context, step))
                 ptr.write();
         });
+        // Resolve external audio pointers: rewrite the JSON string from the original URI
+        // (e.g. "click.wav") to the compressed URI (e.g. "click.opus.ogg"). Refs whose
+        // `newUri` was never set (ffmpeg missing, compression skipped) are left untouched.
+        for (const ref of listAudioRefs()) {
+            if (ref.newUri && ref.obj[ref.key] === ref.sourceUri) {
+                if (this.debug)
+                    console.log(`< Resolved external audio: ${ref.sourceUri} → ${ref.newUri}`);
+                ref.obj[ref.key] = ref.newUri;
+            }
+        }
         // Resolve external EXR pointers: update component data with the texture's current URI
         for (const { obj, key, texture } of this.externalExrPointers) {
             const uri = texture.getURI() || texture.getName() || '';

package/dist/extensions/NEEDLE_opaque/index.d.ts

@@ -1,3 +1,2 @@
-import { Extension } from "@gltf-transform/core";
 export * from "./NEEDLE_opaque.js";
-export declare const ALL_EXTENSIONS: (typeof Extension)[];
+export declare const ALL_EXTENSIONS: typeof import("@gltf-transform/core").Extension[];

package/dist/scripts/pack-gltf.js

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer';
 import { dedup, metalRough, prune, resample } from '@gltf-transform/functions';
 import { ALL_EXTENSIONS as NEEDLE_EXTENSIONS, NEEDLE_compression_texture, NEEDLE_mesh_compression, NEEDLE_pmrem, NEEDLE_lightmaps_ext, setExtensionInputFile } from '../extensions/index.js';
-import { isLOD, isMeshLOD, needle_animation_transform, needle_asset, needle_mesh_transform, needle_texture_transform, } from '../transforms/index.js';
+import { clearAudioRegistry, isLOD, isMeshLOD, listAudioRefs, needle_animation_transform, needle_asset, needle_audio_transform, needle_mesh_transform, needle_texture_transform, } from '../transforms/index.js';
 import { copyExternalResources, getOutputPath, getVersion, isMaterialOnlyGLB, ioTryReadWithMissingResources, writeNodeIO } from "../utils/index.js";
 import { addToCache, getHash, tryGetFromCache, } from "../cache/index.js";
 import { TestAssertionError } from '../utils/test-assert.js';
@@ -70,6 +70,7 @@ export async function packGLTF(inputFile, outputFile, options) {
         // Use sourceFile when available (e.g. when inputFile is a progressive output copy)
         const assetSourceFile = options.sourceFile ?? inputFile;
         setExtensionInputFile(assetSourceFile);
+        clearAudioRegistry();
         const document = await ioTryReadWithMissingResources(io, inputFile);
         if (options.logger) {
             document.setLogger(options.logger);
@@ -96,6 +97,7 @@ export async function packGLTF(inputFile, outputFile, options) {
                 config,
             }),
             needle_mesh_transform({ file: inputFile, config }),
+            needle_audio_transform({ outfile: outputFile, useCache, config }),
             needle_animation_transform({}),
             resample({
                 tolerance: 1e-6, // NOTE: lowered from 1e-4 to 1e-6 to fix https://linear.app/needle/issue/NE-6872
@@ -148,6 +150,13 @@ export async function packGLTF(inputFile, outputFile, options) {
                     }
                 }
             }
+            for (const ref of listAudioRefs()) {
+                const uri = ref.newUri ?? ref.sourceUri;
+                const absPath = path.resolve(outDir, uri);
+                if (existsSync(absPath)) {
+                    options.externalFiles.push(absPath);
+                }
+            }
         }
         logger.debug(`← Writing to ${outputFile}`);
         await writeNodeIO(io, outputFile, document);

package/dist/transforms/index.d.ts

@@ -7,3 +7,6 @@ export * from "./needle_mesh_transform.js";
 export * from "./needle_common.js";
 export * from "./needle_texture_transform.js";
 export * from "./needle_animation_transform.js";
+export * from "./needle_audio.js";
+export * from "./needle_audio_registry.js";
+export * from "./needle_audio_ffmpeg.js";

package/dist/transforms/index.js

@@ -7,3 +7,6 @@ export * from "./needle_mesh_transform.js";
 export * from "./needle_common.js";
 export * from "./needle_texture_transform.js";
 export * from "./needle_animation_transform.js";
+export * from "./needle_audio.js";
+export * from "./needle_audio_registry.js";
+export * from "./needle_audio_ffmpeg.js";

package/dist/transforms/needle_audio.d.ts

@@ -0,0 +1,12 @@
+import { Transform } from '@gltf-transform/core';
+import { Config } from '../config/index.js';
+export type AudioTransformOptions = {
+    /** The path the GLB will be written to. Audio sidecars are placed alongside. */
+    outfile: string;
+    /** Disk cache toggle */
+    useCache: boolean;
+    config: Config;
+};
+export declare function needle_audio_transform(options: AudioTransformOptions): Transform;
+/** "click.wav" → "click.opus.ogg". Preserves the basename casing. */
+export declare function computeOpusOggUri(sourceUri: string): string;

package/dist/transforms/needle_audio.js

@@ -0,0 +1,104 @@
+import { createTransform } from '@gltf-transform/functions';
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname, extname, join } from 'path';
+import { v4 as uuid } from 'uuid';
+import tmp from 'tmp';
+import { addToCache, tryGetFromCache } from '../cache/index.js';
+import { safeRmDir } from '../utils/fileutils.js';
+import { encodeOpusOgg, findFfmpeg } from './needle_audio_ffmpeg.js';
+import { listAudioRefs } from './needle_audio_registry.js';
+const DEFAULT_BITRATE_KBPS = 128;
+export function needle_audio_transform(options) {
+    return createTransform('needle_audio_transform', async (document) => {
+        const refs = listAudioRefs();
+        if (refs.length === 0)
+            return;
+        const logger = document.getLogger();
+        const audioCfg = options.config.audio ?? {};
+        if (audioCfg.enabled === false) {
+            logger.debug(`audio: disabled in config — ${refs.length} external audio reference(s) left untouched`);
+            return;
+        }
+        const bitrate = audioCfg.bitrate ?? DEFAULT_BITRATE_KBPS;
+        const ffmpeg = await findFfmpeg();
+        if (!ffmpeg) {
+            logger.warn(`audio: ffmpeg not found on PATH — ${refs.length} audio file(s) will pass through uncompressed`);
+            return;
+        }
+        if (!ffmpeg.hasLibopus) {
+            logger.warn(`audio: ffmpeg is installed but libopus codec is missing — ${refs.length} audio file(s) will pass through uncompressed`);
+            return;
+        }
+        const outDir = dirname(options.outfile);
+        const bySource = new Map();
+        for (const ref of refs) {
+            const list = bySource.get(ref.sourcePath) ?? [];
+            list.push(ref);
+            bySource.set(ref.sourcePath, list);
+        }
+        const tmpDir = join(tmp.tmpdir, 'needle-audio', uuid());
+        mkdirSync(tmpDir, { recursive: true });
+        try {
+            for (const [sourcePath, refsForSource] of bySource) {
+                if (!existsSync(sourcePath)) {
+                    logger.warn(`audio: source not found at write time, skipping: ${sourcePath}`);
+                    continue;
+                }
+                const sourceUri = refsForSource[0].sourceUri;
+                const newUri = computeOpusOggUri(sourceUri);
+                const sourceBytes = readFileSync(sourcePath);
+                const contentHash = createHash('md5').update(sourceBytes).digest('hex');
+                const cacheKey = `audio-opus-${contentHash}-${bitrate}k`;
+                let oggBytes = null;
+                if (options.useCache) {
+                    const cached = tryGetFromCache(cacheKey);
+                    if (cached && cached.length > 0) {
+                        logger.debug(`audio: cache hit for ${sourceUri} (${cacheKey})`);
+                        oggBytes = cached;
+                    }
+                }
+                if (!oggBytes) {
+                    const tmpOgg = join(tmpDir, `${uuid()}.ogg`);
+                    const t0 = Date.now();
+                    await encodeOpusOgg(ffmpeg.path, sourcePath, tmpOgg, bitrate);
+                    if (!existsSync(tmpOgg)) {
+                        logger.error(`audio: ffmpeg did not produce output for ${sourceUri}`);
+                        continue;
+                    }
+                    oggBytes = new Uint8Array(readFileSync(tmpOgg));
+                    const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+                    const srcKb = sourceBytes.length / 1024;
+                    const dstKb = oggBytes.length / 1024;
+                    logger.info(`audio: ${sourceUri} (${srcKb.toFixed(0)} KB) → ${newUri} (${dstKb.toFixed(0)} KB) in ${elapsed}s`);
+                    if (options.useCache)
+                        addToCache(cacheKey, oggBytes);
+                }
+                const outPath = join(outDir, newUri);
+                mkdirSync(dirname(outPath), { recursive: true });
+                writeFileSync(outPath, oggBytes);
+                // Remove the source audio file from the output dir (mirrors PMREM at needle_pmrem.ts:161-164).
+                // The source bytes have already been read into memory above, so this is safe even in
+                // in-place mode (input dir == output dir).
+                const sourceInOutDir = join(outDir, sourceUri);
+                if (existsSync(sourceInOutDir)) {
+                    rmSync(sourceInOutDir);
+                }
+                for (const ref of refsForSource) {
+                    ref.newUri = newUri;
+                }
+            }
+        }
+        finally {
+            await safeRmDir(tmpDir);
+        }
+    });
+}
+/** "click.wav" → "click.opus.ogg". Preserves the basename casing. */
+export function computeOpusOggUri(sourceUri) {
+    const dir = dirname(sourceUri);
+    const ext = extname(sourceUri);
+    const stem = basename(sourceUri, ext);
+    const newName = `${stem}.opus.ogg`;
+    return dir === '.' || dir === '' ? newName : join(dir, newName);
+}

package/dist/transforms/needle_audio_ffmpeg.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Soft-dependency probe for system `ffmpeg` with `libopus` encoder.
+ *
+ * Returns `{ path, hasLibopus }` if ffmpeg is on PATH, else `null`. Cached for the
+ * process lifetime — `findFfmpeg()` only spawns the probe once. Test code can
+ * reset the cache via `__resetFfmpegProbeForTests()`.
+ */
+export type FfmpegInfo = {
+    path: string;
+    hasLibopus: boolean;
+};
+export declare function findFfmpeg(): Promise<FfmpegInfo | null>;
+export declare function __resetFfmpegProbeForTests(): void;
+export declare function encodeOpusOgg(ffmpegPath: string, inputPath: string, outputPath: string, bitrateKbps: number): Promise<void>;

package/dist/transforms/needle_audio_ffmpeg.js

@@ -0,0 +1,51 @@
+/**
+ * Soft-dependency probe for system `ffmpeg` with `libopus` encoder.
+ *
+ * Returns `{ path, hasLibopus }` if ffmpeg is on PATH, else `null`. Cached for the
+ * process lifetime — `findFfmpeg()` only spawns the probe once. Test code can
+ * reset the cache via `__resetFfmpegProbeForTests()`.
+ */
+import { execFile } from 'child_process';
+let _probe;
+export function findFfmpeg() {
+    if (_probe === undefined) {
+        _probe = probe();
+    }
+    return _probe;
+}
+export function __resetFfmpegProbeForTests() {
+    _probe = undefined;
+}
+function probe() {
+    return new Promise(resolve => {
+        execFile('ffmpeg', ['-hide_banner', '-codecs'], { timeout: 5000, windowsHide: true }, (err, stdout) => {
+            if (err) {
+                resolve(null);
+                return;
+            }
+            const hasLibopus = /libopus/i.test(stdout) && /opus/i.test(stdout);
+            resolve({ path: 'ffmpeg', hasLibopus });
+        });
+    });
+}
+export function encodeOpusOgg(ffmpegPath, inputPath, outputPath, bitrateKbps) {
+    return new Promise((resolve, reject) => {
+        const args = [
+            '-hide_banner',
+            '-loglevel', 'error',
+            '-y',
+            '-i', inputPath,
+            '-vn',
+            '-c:a', 'libopus',
+            '-b:a', `${bitrateKbps}k`,
+            outputPath,
+        ];
+        execFile(ffmpegPath, args, { windowsHide: true }, (err, _stdout, stderr) => {
+            if (err) {
+                reject(new Error(`ffmpeg failed (exit ${err.code}):\n${stderr || err.message}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}

package/dist/transforms/needle_audio_registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Module-global registry for external audio file references discovered during glTF read.
+ *
+ * Mirrors the `_extensionInputFile` module-global pattern used elsewhere in the codebase.
+ * The CLI processes files sequentially, so the registry is reset at the start of every
+ * `packGLTF` call via `clearAudioRegistry()`.
+ *
+ * Population happens in `JsonPointerHandler.read` when it encounters a string ending
+ * in a known audio extension. Consumption happens in two places:
+ *   1. `needle_audio_transform` — reads `listAudioRefs()`, compresses each unique
+ *      source file, fills in `newUri` on every ref pointing at that source.
+ *   2. `JsonPointerHandler.resolveAndWrite` — overwrites `ref.obj[ref.key]` with
+ *      `ref.newUri` so the JSON output points at the compressed file.
+ */
+export type AudioRef = {
+    /** The component-data object whose `[key]` field holds the audio path */
+    obj: object;
+    /** Key on `obj` that holds the original audio URI string */
+    key: string;
+    /** Absolute path to the source audio file on disk */
+    sourcePath: string;
+    /** Original URI as it appeared in the JSON (relative path) */
+    sourceUri: string;
+    /** Set by `needle_audio_transform` after compression. If unset, the JSON ref
+     *  is left untouched (e.g. ffmpeg missing, compression skipped). */
+    newUri?: string;
+};
+export declare function registerAudioRef(ref: AudioRef): void;
+export declare function listAudioRefs(): AudioRef[];
+export declare function clearAudioRegistry(): void;
+/** Audio extensions the compression transform will re-encode. Lossless only —
+ *  re-encoding lossy formats (mp3/m4a/aac/ogg) would compound artifacts. Those
+ *  paths are still valid in source glTFs; they are simply passed through. */
+export declare const AUDIO_EXTENSIONS: readonly [".wav"];
+export declare function isAudioUri(value: string): boolean;
+/** Returns true if the URI is a relative path we should attempt to resolve+compress.
+ *  Absolute URLs (http(s), data, file, blob, leading slash, drive letter) are passed through unchanged. */
+export declare function isRelativeAudioUri(value: string): boolean;

package/dist/transforms/needle_audio_registry.js

@@ -0,0 +1,47 @@
+/**
+ * Module-global registry for external audio file references discovered during glTF read.
+ *
+ * Mirrors the `_extensionInputFile` module-global pattern used elsewhere in the codebase.
+ * The CLI processes files sequentially, so the registry is reset at the start of every
+ * `packGLTF` call via `clearAudioRegistry()`.
+ *
+ * Population happens in `JsonPointerHandler.read` when it encounters a string ending
+ * in a known audio extension. Consumption happens in two places:
+ *   1. `needle_audio_transform` — reads `listAudioRefs()`, compresses each unique
+ *      source file, fills in `newUri` on every ref pointing at that source.
+ *   2. `JsonPointerHandler.resolveAndWrite` — overwrites `ref.obj[ref.key]` with
+ *      `ref.newUri` so the JSON output points at the compressed file.
+ */
+let _refs = [];
+export function registerAudioRef(ref) {
+    _refs.push(ref);
+}
+export function listAudioRefs() {
+    return _refs;
+}
+export function clearAudioRegistry() {
+    _refs = [];
+}
+/** Audio extensions the compression transform will re-encode. Lossless only —
+ *  re-encoding lossy formats (mp3/m4a/aac/ogg) would compound artifacts. Those
+ *  paths are still valid in source glTFs; they are simply passed through. */
+export const AUDIO_EXTENSIONS = ['.wav'];
+const _audioRegex = new RegExp(`(${AUDIO_EXTENSIONS.map(e => '\\' + e).join('|')})$`, 'i');
+export function isAudioUri(value) {
+    return _audioRegex.test(value);
+}
+/** Returns true if the URI is a relative path we should attempt to resolve+compress.
+ *  Absolute URLs (http(s), data, file, blob, leading slash, drive letter) are passed through unchanged. */
+export function isRelativeAudioUri(value) {
+    if (!value)
+        return false;
+    if (/^[a-z]+:/i.test(value))
+        return false; // http:, https:, data:, file:, blob:, etc.
+    if (value.startsWith('//'))
+        return false; // protocol-relative
+    if (value.startsWith('/'))
+        return false; // POSIX absolute
+    if (/^[a-z]:[\\/]/i.test(value))
+        return false; // Windows drive (C:\ or C:/)
+    return true;
+}

package/dist/transforms/needle_progressive.d.ts

@@ -1,4 +1,4 @@
-import { ILogger, Texture, Transform, vec2 } from '@gltf-transform/core';
+import { ILogger, Primitive, Texture, Transform, TypedArray, vec2 } from '@gltf-transform/core';
 import { Config } from '../config/index.js';
 declare interface ProgressiveOptions {
     path: string | Array<string>;
@@ -39,6 +39,14 @@ export declare enum TextureResizeFilter {
 export declare const TEXTURE_RESIZE_DEFAULTS: TextureResizeOptions;
 export declare function resizeTextureToMax(texture: Texture, maxSize: number, logger: ILogger): Promise<void>;
 export declare function make_progressive_meshes(filePath: string, _options: any, opts?: ProgressiveOptions): Transform;
+export declare type PrimitiveData = {
+    indices: TypedArray;
+    attributes: {
+        [key: string]: TypedArray;
+    };
+};
+export declare function clonePrimitiveData(prim: Primitive, logger: ILogger): PrimitiveData | null;
+export declare function setPrimitiveData(prim: Primitive, data: PrimitiveData): void;
 export declare function isMeshLOD(filepath: string): boolean;
 export declare function isImageLOD(filepath: string): boolean;
 export declare function isLOD(filepath: string): boolean;

package/dist/transforms/needle_progressive.js

@@ -304,10 +304,11 @@ export function make_progressive_textures(filePath, _options = TEXTURE_RESIZE_DE
             // If any texture LOD was generated we can resize the texture here
             // E.g. for specular/glossiness textures we might not generate any LODs and then we don't want to downsize the texture
             if (results?.length) {
-                options.size[0] = settings.maxSize;
-                options.size[1] = settings.maxSize;
-                logger.debug(`[${NAME}] Resizing embedded texture[${index}] to ${options.size[0]}x${options.size[1]}`);
-                await resizeTexture(options, texture, logger, uri || name, slots);
+                // Build a per-iteration resize options object — never mutate the shared `options`,
+                // otherwise the next texture's size check (line ~238) would see the previous texture's maxSize.
+                const resizeOpts = { ...options, size: [settings.maxSize, settings.maxSize] };
+                logger.debug(`[${NAME}] Resizing embedded texture[${index}] to ${resizeOpts.size[0]}x${resizeOpts.size[1]}`);
+                await resizeTexture(resizeOpts, texture, logger, uri || name, slots);
                 if (opts?.useCache === false) {
                 }
                 else
@@ -453,7 +454,7 @@ async function createTextureLod(args, opts) {
         mkdirSync(basePath, { recursive: true });
     }
     logger.info(`[${NAME}] Write texture LOD ${level} to \"${filename}\"`);
-    newIo.write(outName, newDoc);
+    await newIo.write(outName, newDoc);
     logger.info(`[${NAME}] Generate hash for texture LOD ${level}`);
     const hash = getHash(newTexture);
     return {
@@ -830,24 +831,30 @@ export function make_progressive_meshes(filePath, _options, opts) {
 function deleteFile(filePath, _context) {
     rmSync(filePath);
 }
-function clonePrimitiveData(prim, logger) {
+// Clone a TypedArray preserving its concrete type (Uint16Array stays Uint16Array etc.).
+// Coercing to Float32Array breaks integer attributes (JOINTS, FEATURE_ID, indices) and changes
+// the accessor's componentType when written back via setArray.
+function cloneTypedArray(src) {
+    return src.slice();
+}
+export function clonePrimitiveData(prim, logger) {
     const semantics = prim.listSemantics();
     if (semantics.some(s => s.includes("JOINTS"))) {
         return null;
     }
-    const prevIndices = prim.getIndices();
-    const indices = !prevIndices ? new Uint32Array() : new Uint32Array(prevIndices.getArray());
+    const prevIndicesArray = prim.getIndices()?.getArray();
+    const indices = prevIndicesArray ? cloneTypedArray(prevIndicesArray) : new Uint32Array();
     const attributes = {};
     for (const attr of semantics) {
         logger.info(`[${NAME}] Clone attribute ${attr}`);
-        const accessor = prim.getAttribute(attr);
-        if (accessor) {
-            attributes[attr] = new Float32Array(accessor.getArray());
+        const src = prim.getAttribute(attr)?.getArray();
+        if (src) {
+            attributes[attr] = cloneTypedArray(src);
         }
     }
     return { indices, attributes };
 }
-function setPrimitiveData(prim, data) {
+export function setPrimitiveData(prim, data) {
     const indices = prim.getIndices();
     if (indices) {
         indices.setArray(data.indices);
@@ -1090,11 +1097,20 @@ async function simplifyMesh(doc, mesh, prim, index, lodinfo) {
     };
     return compressPrimitive(doc, mesh, prim, index, weldOptions, simplifyOptions);
 }
+// Match only files this pipeline emits: <basename>_<level>_<uuid>.glb
+// (uuid is generated via generateGuid → uuid v5, 36 chars with hyphens).
+// Anchoring against the basename + UUID format prevents false positives from
+// user assets like "image_hero.glb" or "/path/mesh_lod_test.glb", which the
+// previous substring check (filepath.includes(...)) misclassified as LODs,
+// causing the pipeline to silently skip them.
+const UUID_RE_SRC = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const IMAGE_LOD_RE = new RegExp(`(?:^|[\\\\/])image_\\d+_${UUID_RE_SRC}\\.glb$`, 'i');
+const MESH_LOD_RE = new RegExp(`(?:^|[\\\\/])mesh_lod_\\d+_${UUID_RE_SRC}\\.glb$`, 'i');
 export function isMeshLOD(filepath) {
-    return filepath.includes("mesh_lod_");
+    return MESH_LOD_RE.test(filepath);
 }
 export function isImageLOD(filepath) {
-    return filepath.includes("image_");
+    return IMAGE_LOD_RE.test(filepath);
 }
 export function isLOD(filepath) {
     return isMeshLOD(filepath) || isImageLOD(filepath);

package/dist/transforms/needle_texture_transform.js

@@ -96,6 +96,10 @@ async function processTexture(texture, index, document, logger, context) {
     const originalMimeType = texture.getMimeType();
     // Handle EXR textures via PMREM → KTX2 HDR
     if (originalMimeType === "image/exr") {
+        if (context.config.exr?.enabled === false) {
+            logger.debug(`→ Skipping EXR -> KTX2 HDR for ${texture.getName()} [${index}] (config.exr.enabled = false)`);
+            return;
+        }
         await context.pmremContext.process(index, texture, null, context);
         return;
     }

package/dist/transforms/toktx.js

@@ -4,8 +4,7 @@ import os from 'os';
 import semver from 'semver';
 import tmp from 'tmp';
 import { TextureChannel } from '@gltf-transform/core';
-import { execSync } from 'child_process';
-import { spawn, commandExists, waitExit, MICROMATCH_OPTIONS } from './util.js';
+import { spawn, waitExit, MICROMATCH_OPTIONS } from './util.js';
 import { TextureResizeFilter, getTextureColorSpace } from '@gltf-transform/functions';
 import { ETC1S_DEFAULTS, UASTC_DEFAULTS } from './toktx_types.js';
 tmp.setGracefulCleanup();
@@ -143,53 +142,41 @@ export function createParams(texture, slots, channels, size, logger, numTextures
     }
     return params;
 }
-let didLogToktxVersion = false;
+let didLogKtxVersion = false;
 export async function checkKTXSoftware(logger, env) {
-    let failedFindingToktx = false;
-    const proc = spawn('toktx', ['--version'], { env: env });
+    // Probe the `ktx` binary because that's what the compression step actually runs
+    // (see needle_toktx.ts: spawn('ktx', params, ...)). Probing `toktx` would let a
+    // partial install pass the prerequisite check and then fail mid-compression
+    // when `ktx create` is invoked. `ktx` ships with KTX-Software 4.3+ alongside
+    // `toktx`, so this matches our KTX_SOFTWARE_VERSION_MIN.
+    let failedFindingKtx = false;
+    const proc = spawn('ktx', ['--version'], { env: env });
     proc.on('error', (err) => {
         if (err.message.endsWith("ENOENT")) {
-            failedFindingToktx = true;
+            failedFindingKtx = true;
         }
     });
     const [status, stdout, stderr] = await waitExit(proc);
-    if (failedFindingToktx) {
-        console.log(`WARN: Unable to find "toktx". Confirm KTX-Software is installed from: https://github.com/KhronosGroup/KTX-Software.`);
+    if (failedFindingKtx) {
+        console.log(`WARN: Unable to find "ktx". Confirm KTX-Software is installed from: https://github.com/KhronosGroup/KTX-Software.`);
         return null;
     }
-    const version = (stdout || stderr)
-        .replace(/toktx\s+/, '')
-        .replace(/~\d+/, '')
-        .trim();
-    if (status !== 0 || !semver.valid(semver.clean(version))) {
-        throw new Error('Unable to find "toktx" version. Confirm KTX-Software is installed from:\n\nhttps://github.com/KhronosGroup/KTX-Software.');
+    // Extract the X.Y.Z from outputs like "ktx version: v4.3.2~6" or "toktx v4.3.0~28".
+    const versionMatch = (stdout || stderr).match(/v?(\d+\.\d+\.\d+)/);
+    const version = versionMatch ? versionMatch[1] : null;
+    if (status !== 0 || !version || !semver.valid(version)) {
+        throw new Error('Unable to find "ktx" version. Confirm KTX-Software is installed from:\n\nhttps://github.com/KhronosGroup/KTX-Software.');
     }
-    else if (semver.lt(semver.clean(version), KTX_SOFTWARE_VERSION_MIN)) {
-        logger.warn(`toktx: Expected KTX-Software >= v${KTX_SOFTWARE_VERSION_MIN}, found ${version}.`);
+    else if (semver.lt(version, KTX_SOFTWARE_VERSION_MIN)) {
+        logger.warn(`ktx: Expected KTX-Software >= v${KTX_SOFTWARE_VERSION_MIN}, found ${version}.`);
         return null;
     }
     else {
-        if (!didLogToktxVersion)
-            logger.debug(`toktx: Found KTX-Software ${version}.`);
-        didLogToktxVersion = true;
+        if (!didLogKtxVersion)
+            logger.debug(`ktx: Found KTX-Software ${version}.`);
+        didLogKtxVersion = true;
     }
-    return semver.clean(version);
-}
-async function toktxCommandExistsSync(env) {
-    if (env) {
-        // if env is defined use that to check if toktx is installed
-        try {
-            execSync('toktx --version', { encoding: 'utf-8', env: env });
-            return true;
-        }
-        catch (error) {
-            return false;
-        }
-    }
-    else if (!await commandExists('toktx')) {
-        return false;
-    }
-    return true;
+    return version;
 }
 function isPowerOfTwo(value) {
     if (value <= 2)

package/dist/utils/index.d.ts

@@ -6,5 +6,4 @@ export * from "./texture.js";
 export * from "./guid.js";
 export * from "./nodeio.js";
 export * from "./stats.js";
-export * from "./merge.js";
 export * from "./validate.js";

package/dist/utils/index.js

@@ -6,5 +6,4 @@ export * from "./texture.js";
 export * from "./guid.js";
 export * from "./nodeio.js";
 export * from "./stats.js";
-export * from "./merge.js";
 export * from "./validate.js";

package/dist/utils/stats.js

@@ -88,6 +88,14 @@ export class FileStats extends Stats {
         this.isLOD = isLOD(this.filename);
     }
 }
+// Union the two arrays, tolerating undefined on either side. `new Set(undefined)`
+// throws, which is what the prior implementation would do whenever `this.errors`
+// was undefined but `other.errors` was non-empty.
+function mergeUnique(a, b) {
+    if (!a && !b)
+        return undefined;
+    return Array.from(new Set([...(a ?? []), ...(b ?? [])]));
+}
 export class MeshInfo {
     count = 0;
     primitives = 0;
@@ -104,8 +112,8 @@ export class MeshInfo {
         this.triangles += other.triangles;
         this.memory += other.memory;
         this.formats = Array.from(new Set(this.formats.concat(other.formats)));
-        this.errors = Array.from(new Set(this.errors?.concat(other.errors)));
-        this.warnings = Array.from(new Set(this.warnings?.concat(other.warnings)));
+        this.errors = mergeUnique(this.errors, other.errors);
+        this.warnings = mergeUnique(this.warnings, other.warnings);
     }
 }
 export class TextureInfo {
@@ -120,8 +128,8 @@ export class TextureInfo {
         this.memory += other.memory;
         this.gpu_memory += other.gpu_memory;
         this.formats = Array.from(new Set(this.formats.concat(other.formats)));
-        this.errors = Array.from(new Set(this.errors?.concat(other.errors)));
-        this.warnings = Array.from(new Set(this.warnings?.concat(other.warnings)));
+        this.errors = mergeUnique(this.errors, other.errors);
+        this.warnings = mergeUnique(this.warnings, other.warnings);
     }
 }
 export class AnimationInfo {

package/dist/utils/version.gen.d.ts

@@ -1 +1 @@
-export declare const version = "2.16.0-alpha.bc3af72";
+export declare const version = "2.16.0-alpha.eb5a640";

package/dist/utils/version.gen.js

@@ -1 +1 @@
-export const version = "2.16.0-alpha.bc3af72";
+export const version = "2.16.0-alpha.eb5a640";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/gltf-build-pipeline",
-  "version": "2.16.0-alpha.bc3af72",
+  "version": "2.16.0-alpha.eb5a640",
   "description": "Pipeline and tools for optimizing gltf files using gltf-transform and compression settings within glTF extensions",
   "main": "dist/index.js",
   "type": "module",

package/dist/utils/merge.d.ts

@@ -1,12 +0,0 @@
-/**
- * Simple object check.
- * @param item
- * @returns {boolean}
- */
-export declare function isObject(item: object): boolean;
-/**
- * Deep merge two objects.
- * @param target
- * @param ...sources
- */
-export declare function mergeDeep(target: any, ...sources: any[]): any;

package/dist/utils/merge.js

@@ -1,31 +0,0 @@
-/**
- * Simple object check.
- * @param item
- * @returns {boolean}
- */
-export function isObject(item) {
-    return (item && typeof item === 'object' && !Array.isArray(item));
-}
-/**
- * Deep merge two objects.
- * @param target
- * @param ...sources
- */
-export function mergeDeep(target, ...sources) {
-    if (!sources.length)
-        return target;
-    const source = sources.shift();
-    if (isObject(target) && isObject(source)) {
-        for (const key in source) {
-            if (isObject(source[key])) {
-                if (!target[key])
-                    Object.assign(target, { [key]: {} });
-                mergeDeep(target[key], source[key]);
-            }
-            else {
-                Object.assign(target, { [key]: source[key] });
-            }
-        }
-    }
-    return mergeDeep(target, ...sources);
-}