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

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.0.0-alpha] - 2026-05-26
+
+### Breaking
+- CLI now requires JWT authentication via `--auth-token`
+- The package ships as a CLI-only right now
+
+### Added
+- **Job cache**: file-level cache that skips an entire transform when the same input + config was already processed
+- **Audio compression**: external audio references are re-encoded to Opus/OGG; supported input formats are WAV, FLAC, and AIFF (lossy formats pass through unchanged)
+- **PMREM standalone CLI command**: `needle-gltf pmrem <input>` converts EXR and Radiance HDR files to PMREM KTX2
+- **Multiple file inputs**: `transform` now accepts comma-separated paths (e.g. `needle-gltf transform a.glb,b.glb out/`)
+- Auth surfaces clean "token expired" message when the JWT `exp` claim is past
+
+### Fixed
+- Cache restore now also restores external files (KTX2, PMREM) alongside the main GLB
+- PMREM NaN generation that caused artifacts in certain EXR files
+- xxHash WASM init race condition, now resolved with `ensureHashReady` gate
+- LOD file detection no longer matches against directory names
+- toktx: probes `ktx` binary to match what the compression step actually runs
+- `getConfig` now returns a fresh copy instead of a shared mutable reference
+- `stats` tolerates undefined errors/warnings in `addFrom`
+- Material-only GLBs are no longer incorrectly pruned
+- `createOpaqueExtension` return type fixed, downstream casts removed
+- `stats` command exits with code 0
+
 ## [2.15.0] - 2026-03-20
 - add: EXR environment map compression (PMREM / FASTHDR) for Needle Engine, supporting both Unity and Blender exports
 - fix: cache hashing stability (circular reference handling)

package/README.md

@@ -26,6 +26,18 @@ To load progressively enhanced glTF files in Needle Engine or another three.js b
 ### Commands
 - `help` - use help to view options
 
+### Platform support
+
+The bundled `basisu` encoder (used for HDR / EXR → KTX2 HDR) supports:
+
+| OS      | Arch                  | Status |
+|---------|-----------------------|--------|
+| Linux   | x64                   | Supported |
+| Linux   | arm64                 | Not supported |
+| macOS   | arm64 (Apple Silicon) | Supported |
+| macOS   | x64 (Intel)           | Not supported |
+| Windows | x64                   | Supported |
+
 ### Configuration
 
 The pipeline reads an optional `needle.config.json` from the working directory (or any parent directory). Configure pipeline behaviour under the `gltf` key:
@@ -49,7 +61,7 @@ The `gltf` value may also be a string shorthand for `usecase` — `"gltf": "prod
 | `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.enabled` | `boolean` | `true` | Compress externally referenced lossless audio files (`.wav`, `.flac`, `.aiff`/`.aif`) 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. |