minidraco 0.2.0 → 0.3.0

package/README.md

@@ -1,51 +1,29 @@
-# minidraco
+# 🐲 minidraco
 
 A fast, pure-TypeScript [Draco](https://google.github.io/draco/) mesh decoder with a drop-in
-`DRACOLoader` replacement for [Three.js](https://threejs.org/) — no wasm files to host, no
-external decoder to fetch and compile, and a built-in worker pool so decoding never blocks the
-main thread.
-
-minidraco started as a TypeScript port of [mrdoob/draco.js](https://github.com/mrdoob/draco.js)
-(MIT), then restructured and optimized (rANS table pooling, seam-list corner tables, allocation
-elimination in the entropy decoders, specialized attribute extraction) to close the gap with the
-official [draco3d](https://www.npmjs.com/package/draco3d) wasm decoder.
+`DRACOLoader` for [Three.js](https://threejs.org/) — no wasm to host or fetch, and a worker pool
+so decoding never blocks the main thread.
 
 ## Usage
 
 ```ts
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
-import { MiniDRACOLoader } from 'minidraco/three'
+import { MinidracoLoader } from 'minidraco/three'
 
 const gltfLoader = new GLTFLoader()
-gltfLoader.setDRACOLoader(new MiniDRACOLoader())
+gltfLoader.setDRACOLoader(new MinidracoLoader())
 gltfLoader.load('model.glb', gltf => scene.add(gltf.scene))
 ```
 
-`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:
+A drop-in for `THREE.DRACOLoader`, no cast needed. Decoding runs in a worker pool by default, with
+a main-thread fallback. Options:
 
 ```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))
+new MinidracoLoader({ workers: false }) // decode on the main thread
+new MinidracoLoader({ workerLimit: 8 }) // pool size (default 4)
 ```
 
-**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:
+Or decode a raw bitstream without Three.js:
 
 ```ts
 import { decodeDracoMesh } from 'minidraco'
@@ -53,90 +31,50 @@ import { decodeDracoMesh } from 'minidraco'
 const mesh = decodeDracoMesh(new Uint8Array(bytes))
 ```
 
-## Feature support
+## Features
 
-- Triangular meshes: edgebreaker (standard + valence) and sequential encodings, all bitstream
-  prediction schemes (delta, parallelogram, multi-parallelogram, constrained multi-parallelogram,
-  portable tex-coords, geometric octahedron normals)
-- Quantized, integer, and octahedron-normal attributes
-- Custom / generic attributes (glTF `_*` semantics), skinning attributes (`JOINTS_0` /
-  `WEIGHTS_0`), vertex colors, multiple UV sets
-- Output is verified bit-identical to the official wasm decoder (≤ 1 ulp on dequantized floats)
-  in the test suite, on both real production GLBs and Draco's own test corpus
-- Point clouds are not supported (glTF `KHR_draco_mesh_compression` only ever contains meshes)
+- Every Draco triangle mesh — all encodings, prediction schemes, and attribute types.
+- Bit-identical to the official wasm decoder, verified in the tests.
+- No point clouds (glTF Draco is always meshes).
 
 ## Performance
 
-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 manablade-static bundle (Chromium, warm loaders, `/bench`
-page of the example):
-
-| 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
-option for the first model on screen.
+Median across a 19-model corpus vs [draco.js](https://github.com/mrdoob/draco.js) and the official
+[draco3d](https://www.npmjs.com/package/draco3d) wasm decoder (full results in
+[BENCH.md](https://github.com/verekia/minidraco/blob/main/BENCH.md)):
 
-## Download size
+| benchmark                                     | vs draco.js     | vs draco3d wasm |
+| --------------------------------------------- | --------------- | --------------- |
+| single-threaded decode — bun (JSC)            | ⚪ even         | 🟢 1.13× faster |
+| single-threaded decode — Chrome (V8)          | ⚪ even         | 🟢 1.50× faster |
+| `GLTFLoader.parse`, worker pool — Chrome (V8) | 🟢 1.23× faster | 🔴 1.10× slower |
+
+On par with draco.js, faster than the wasm decoder single-threaded, and competitive in a real
+`GLTFLoader.parse` with the main thread left free.
 
-What the browser actually downloads per decoder (minified with esbuild, `three` external since
-it's shared; gzip -9 / brotli -q 11):
+🟢 **Cold start is the real win, and no warm benchmark shows it:** there's no `draco_decoder.wasm`
+to fetch and compile before the first decode, so the first model on screen appears sooner.
 
-| payload                                               | plain  | gzip    | brotli  |
-| ----------------------------------------------------- | ------ | ------- | ------- |
-| minidraco — `minidraco/three` in the app bundle       | 102 KB | 26.6 KB | 23.1 KB |
-| minidraco — `worker.js` chunk (fetched on 1st decode) | 99 KB  | 25.5 KB | 22.1 KB |
-| draco.js — loader + decoder in the app bundle         | 96 KB  | 24.8 KB | 21.5 KB |
-| draco3d — `draco_wasm_wrapper.js` (runtime fetch)     | 78 KB  | 13.1 KB | 11.0 KB |
-| draco3d — `draco_decoder.wasm` (runtime fetch)        | 279 KB | 86.1 KB | 64.6 KB |
+## Download size
 
-Totals over the wire (brotli): **minidraco ~45 KB** (23 KB in the app bundle + 22 KB worker
-chunk, or just 23 KB with `setWorkerLimit(0)`), **draco.js ~22 KB**, **draco3d wasm ~76 KB** —
-and the wasm files are separate runtime fetches you must host, on the critical path of the first
-decode, while the JS decoders ship inside your existing bundle chunks.
+Over the wire (brotli): **~23 KB** ships in your app bundle. With the worker pool on (default) the
+browser also fetches a **~22 KB** worker chunk on the first decode — **~45 KB** total; `workers: false`
+skips that fetch. **draco.js ~22 KB**, **draco3d wasm ~76 KB** — the wasm is a separate file you
+must host, while the JS decoders ship inside your bundle.
 
 ## Monorepo
 
 - `library/` — the `minidraco` package
-- `example/` — Next.js + React Three Fiber demo (model/decoder switcher, per-mesh filter,
-  animation playback, in-browser benchmark at `/bench`)
+- `example/` — Next.js + React Three Fiber demo with an in-browser benchmark at `/bench`
 
 ```sh
 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) — rewrites BENCH.md
+bun dev        # watch build + demo
+bun run all    # format, lint, typecheck, tests
+bun run bench  # cross-decoder benchmark
 ```
 
-The test suite decodes every Draco primitive of the bundle GLBs with minidraco and the official
-draco3d wasm decoder and compares indices and every attribute value, plus 13 raw `.drc` fixtures
-from Draco's test corpus covering the encodings the bundles don't hit.
-
 ## License
 
-MIT — includes code derived from [mrdoob/draco.js](https://github.com/mrdoob/draco.js) (MIT),
-implementing Google's [Draco](https://github.com/google/draco) bitstream (Apache-2.0).
+MIT — derived from [mrdoob/draco.js](https://github.com/mrdoob/draco.js) (MIT), implementing
+Google's [Draco](https://github.com/google/draco) bitstream (Apache-2.0).

package/dist/index.d.ts

@@ -1,46 +1,3 @@
-declare class BitDecoder {
-    _bitBuffer: Uint8Array | null;
-    _bitOffset: number;
-    _byteLength: number;
-    constructor();
-    reset(uint8Array: Uint8Array, byteLength: number): void;
-    bitsDecoded(): number;
-    getBits(nbits: number): number | undefined;
-}
-declare class DecoderBuffer {
-    _data: Uint8Array | null;
-    _dataView: DataView | null;
-    _dataSize: number;
-    _pos: number;
-    _bitDecoder: BitDecoder;
-    _bitMode: boolean;
-    _bitstreamVersion: number;
-    constructor();
-    init(data: ArrayBuffer | Uint8Array | ArrayLike<number>, dataSize?: number, version?: number): void;
-    decodeUint8(): number | undefined;
-    decodeInt8(): number | undefined;
-    decodeUint16(): number | undefined;
-    decodeUint32(): number | undefined;
-    decodeInt32(): number | undefined;
-    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;
-    decodeVarintUint32(): number | undefined;
-    decodeVarintUint64(): number | undefined;
-    advance(bytes: number): void;
-    get bitstreamVersion(): number;
-    set bitstreamVersion(v: number);
-    get data(): Uint8Array;
-    get dataHead(): Uint8Array;
-    get remainingSize(): number;
-    get decodedSize(): number;
-    get bitDecoderActive(): boolean;
-}
-
 declare class DataBuffer {
     _data: Uint8Array;
     constructor();
@@ -169,60 +126,6 @@ declare class Mesh extends PointCloud {
     setAttribute(attId: number, pa: PointAttribute): void;
 }
 
-declare class DracoOptions {
-    _globalOptions: Map<string, unknown>;
-    _attributeOptions: Map<number, Map<string, unknown>>;
-    constructor();
-    getGlobalBool(name: string, defaultVal: boolean): boolean;
-    findAttributeOptions(attKey: number): Map<string, unknown> | null;
-    getAttributeBool(attKey: number, name: string, defaultVal: boolean): boolean;
-}
-
-declare class DecoderOptions extends DracoOptions {
-    constructor();
-}
-
-declare class Decoder {
-    options_: DecoderOptions;
-    constructor();
-    static getEncodedGeometryType(inBuffer: DecoderBuffer): number;
-    decodeMeshFromBuffer(inBuffer: DecoderBuffer): {
-        mesh: Mesh | null;
-        ok: boolean;
-        message: string;
-    };
-    decodeBufferToMesh(inBuffer: DecoderBuffer, outGeometry: Mesh): {
-        ok: boolean;
-        message: string;
-    };
-    options(): DecoderOptions;
-}
-
-declare const DataType: {
-    readonly INVALID: 0;
-    readonly INT8: 1;
-    readonly UINT8: 2;
-    readonly INT16: 3;
-    readonly UINT16: 4;
-    readonly INT32: 5;
-    readonly UINT32: 6;
-    readonly INT64: 7;
-    readonly UINT64: 8;
-    readonly FLOAT32: 9;
-    readonly FLOAT64: 10;
-    readonly BOOL: 11;
-    readonly TYPES_COUNT: 12;
-};
-type DataType = (typeof DataType)[keyof typeof DataType];
-
-declare const EncodedGeometryType: {
-    readonly INVALID_GEOMETRY_TYPE: -1;
-    readonly POINT_CLOUD: 0;
-    readonly TRIANGULAR_MESH: 1;
-    readonly NUM_ENCODED_GEOMETRY_TYPES: 2;
-};
-type EncodedGeometryType = (typeof EncodedGeometryType)[keyof typeof EncodedGeometryType];
-
 declare const decodeDracoMesh: (data: Uint8Array) => Mesh;
 
-export { DataType, Decoder, DecoderBuffer, EncodedGeometryType, Type as GeometryAttributeType, Mesh, PointAttribute, decodeDracoMesh };
+export { Type as GeometryAttributeType, Mesh, PointAttribute, decodeDracoMesh };