minidraco 0.1.0 → 0.2.0

package/README.md

@@ -21,10 +21,29 @@ gltfLoader.setDRACOLoader(new MiniDRACOLoader())
 gltfLoader.load('model.glb', gltf => scene.add(gltf.scene))
 ```
 
-`MiniDRACOLoader` is API-compatible with `THREE.DRACOLoader` (`setDecoderPath` and friends are
-no-ops). Decoding runs in a pool of module workers (default 4, `setWorkerLimit(n)` to change,
-`0` to force synchronous main-thread decoding). If workers can't be spawned (SSR, exotic
-bundlers), it falls back to synchronous decoding automatically.
+`MiniDRACOLoader` is a structural drop-in for `THREE.DRACOLoader`: it's assignable to it with no
+cast on any three version (`setDecoderPath` and friends are no-ops), so
+`gltfLoader.setDRACOLoader(new MiniDRACOLoader())` just type-checks.
+
+Decoding runs in a pool of module workers by default (parallel across primitives, main thread
+stays free). If workers can't be spawned (SSR, exotic bundlers), it falls back to synchronous
+decoding automatically. Configure it at construction or with fluent setters:
+
+```ts
+new MiniDRACOLoader({ workers: false }) // decode synchronously on the main thread
+new MiniDRACOLoader({ workerLimit: 8 }) // pool size (default 4)
+new MiniDRACOLoader(loadingManager) // a three.js LoadingManager, as usual
+
+const loader = new MiniDRACOLoader()
+loader.setWorkers(false) // ...or toggle later (same as setWorkerLimit(0))
+```
+
+**Serving JS from a CDN origin** (Next.js `assetPrefix`, etc.) works out of the box: browsers
+refuse to construct a Worker from a cross-origin script, so minidraco bootstraps the worker
+through a same-origin blob module that imports the hashed CDN asset (a CORS request — your CDN
+must send `Access-Control-Allow-Origin`, which it already does if you load models or fonts from
+it). If even that fails, decoding falls back to the main thread rather than erroring.
+`setWorkerUrl(url)` exists as a manual override for exotic setups.
 
 Or decode a raw Draco bitstream without Three.js:
 
@@ -48,24 +67,35 @@ const mesh = decodeDracoMesh(new Uint8Array(bytes))
 
 ## Performance
 
-Decoding the three production bundle GLBs in `example/public/models` (Apple Silicon, medians;
-`bun run bench` for the harness). Raw single-threaded decode, bun/JSC:
-
-| file (points / faces)                | minidraco | draco.js | draco3d wasm |
-| ------------------------------------ | --------- | -------- | ------------ |
-| canine (1.1k / 0.5k)                 | 0.6 ms    | 0.6 ms   | 0.4 ms       |
-| player (5.1k / 2.5k)                 | 1.9 ms    | 1.7 ms   | 1.2 ms       |
-| static (291k / 221k, 488 primitives) | **50 ms** | 55 ms    | 51 ms        |
+Full cross-decoder results — the production bundles plus the 17 sample models shipped with
+[mrdoob/draco.js](https://github.com/mrdoob/draco.js) — are in
+[BENCH.md](https://github.com/verekia/minidraco/blob/main/BENCH.md), regenerated by
+`bun run bench` (with machine-readable
+[BENCH.json](https://github.com/verekia/minidraco/blob/main/BENCH.json) alongside for diffing
+perf work). Highlights, decoding the production bundle GLBs in
+`example/public/models` (Apple Silicon, medians). Raw single-threaded decode, bun/JSC:
+
+| file (points / faces)                          | minidraco | draco.js | draco3d wasm |
+| ---------------------------------------------- | --------- | -------- | ------------ |
+| manablade-characters (5.1k / 2.5k)             | 1.9 ms    | 1.7 ms   | 1.2 ms       |
+| manablade-static (291k / 221k, 488 primitives) | **50 ms** | 55 ms    | 51 ms        |
+
+The `/bench` page of the example runs the same fair comparison in the browser (V8): a raw
+single-threaded mode where all three decoders decode on the main thread, over the bundles plus
+the draco.js sample models (synced locally by `bun dev`, never deployed). Browser runs — both
+the single-threaded mode and the multi-threaded GLTFLoader wall clock — are tracked in
+[BENCH.browser.json](https://github.com/verekia/minidraco/blob/main/BENCH.browser.json) via the
+page's "Save to BENCH.browser.json" button (local dev only).
 
 In the browser the worker pool changes the story for real scenes — wall-clock
-`GLTFLoader.parse` of the 488-primitive static bundle (Chromium, warm loaders, `/bench` page of
-the example):
+`GLTFLoader.parse` of the 488-primitive manablade-static bundle (Chromium, warm loaders, `/bench`
+page of the example):
 
-| decoder                  | static bundle | main thread |
-| ------------------------ | ------------- | ----------- |
-| minidraco (4 workers)    | ~51 ms        | free        |
-| draco.js (main thread)   | ~72 ms        | blocked     |
-| draco3d wasm (4 workers) | ~23 ms        | free        |
+| decoder                  | manablade-static | main thread |
+| ------------------------ | ---------------- | ----------- |
+| minidraco (4 workers)    | ~51 ms           | free        |
+| draco.js (main thread)   | ~72 ms           | blocked     |
+| draco3d wasm (4 workers) | ~23 ms           | free        |
 
 And unlike the wasm decoder there is nothing to host or fetch: the first decode doesn't pay the
 ~50–70 ms wasm download + compile + worker bootstrap, which typically makes minidraco the fastest
@@ -99,7 +129,7 @@ decode, while the JS decoders ship inside your existing bundle chunks.
 bun install
 bun dev        # library watch build + example dev server
 bun run all    # format check, lint, typecheck, warden, tests
-bun run bench  # decoder comparison benchmark (bun)
+bun run bench  # decoder comparison benchmark (bun) — rewrites BENCH.md
 ```
 
 The test suite decodes every Draco primitive of the bundle GLBs with minidraco and the official

package/dist/index.d.ts

@@ -25,6 +25,7 @@ declare class DecoderBuffer {
     decodeFloat32(): number | undefined;
     decodeUint64(): number | undefined;
     decodeBytes(size: number): Uint8Array | undefined;
+    decodeBytesView(size: number): Uint8Array | undefined;
     startBitDecoding(decodeSize: boolean): number | undefined;
     endBitDecoding(): void;
     decodeLeastSignificantBits32(nbits: number): number | undefined;
@@ -162,8 +163,6 @@ declare class Mesh extends PointCloud {
         elementType: number;
     }[];
     constructor();
-    _ensureFaceCapacity(numFaces: number): void;
-    addFace(face: ArrayLike<number>): void;
     setNumFaces(numFaces: number): void;
     numFaces(): number;
     face(faceId: number): number[];