ldr 0.4.0 → 0.5.0

package/README.md

@@ -1,11 +1,14 @@
 # ldr
 
-High-performance LEGO® (LDraw) rendering for [three.js](https://threejs.org). Renders 100k-brick models at interactive frame rates by precompiling parts into a compact binary **parts pack** and drawing them with instancing, hidden-stud/tube culling, low-detail studs, single-sided faces and indexed edge lines.
+**Render 100,000-brick LEGO® (LDraw) models in three.js at interactive frame rates.**
 
-- Spec-compliant LDraw reader: `.ldr`, `.mpd` (submodels), `.dat`; BFC, `STEP`, `ROTSTEP`, `BUFEXCHG`, direct colours, `~Moved to` aliases.
-- `createLdrObject()` gives you a `THREE.Group` to drop into any scene, plus a build-steps API.
-- `ldr pack` CLI builds parts packs from your LDraw library (zstd/gzip compressed for serving).
-- ESM, TypeScript types, tree-shakeable (`sideEffects: false`); `three` is a peer dependency.
+`ldr` compiles the parts a model uses into a compact binary **parts pack** ahead of time. At runtime it draws them with GPU instancing, hidden-stud and underside culling, distance LOD (simplified meshes, sub-pixel studs dropped, per-cluster frustum culling), single-sided (BFC) faces and indexed edge lines. On an Apple M4 Pro that takes Datsville (392,514 bricks) from 410 ms to 27 ms per frame, and its load time from 24.7 s to 1.6 s.
+
+[![npm](https://img.shields.io/npm/v/ldr.svg)](https://www.npmjs.com/package/ldr) · MIT · ESM + TypeScript · `three` is a peer dependency
+- **Spec-compliant LDraw reader:** `.ldr`, `.mpd` and `.dat`, including MPD-embedded parts, geometry drawn directly in models, BFC, `STEP`/`ROTSTEP`, `!TEXMAP` and `!DATA`.
+- **`createLdrObject()`** returns a `THREE.Group` you can drop into any scene, plus a build-steps API.
+- **`ldr pack` CLI and `buildPack()`** build parts packs from your LDraw library, compressed with zstd or gzip for serving.
+- **Tree-shakeable** (`sideEffects: false`). The browser entry is `ldr`; the filesystem tools are in `ldr/node`.
 
 ## Install
 
@@ -13,15 +16,41 @@ High-performance LEGO® (LDraw) rendering for [three.js](https://threejs.org). R
 bun add ldr three        # or: npm i ldr three
 ```
 
+You also need the LDraw parts library, which is not bundled, to *build* packs. Download `complete.zip` from <https://library.ldraw.org> and unzip it to an `ldraw/` folder containing `LDConfig.ldr`, `parts/` and `p/`. Apps only need the pack at runtime, not the library.
+
 ## Quickstart
 
-1. **Build a parts pack** for your model(s) (one-time, at build time):
+### 1. Build a parts pack (CLI, once at build time)
 
 ```bash
 bunx ldr pack --ldraw ./ldraw -o public/car.pack.zst models/car.ldr
 ```
 
-2. **Render it:**
+```
+ldr pack --ldraw <dir> -o <out.bin|.zst|.gz> [model.ldr ...] [--part 3001.dat ...] [--all-parts]
+         [--studs low|full] [--prims full|low] [--no-weld] [--no-colors]
+         [--cond] [--textures] [--no-loose-geometry] [--no-lod] [--reorder]
+```
+
+The pack holds only the parts your models reference, plus the LDConfig colour table. A `.zst` or `.gz` extension compresses the output.
+
+### 2. …or build it from code (Node / Bun)
+
+```ts
+import { buildPack } from "ldr/node";
+
+const { data, parts, missing } = buildPack({
+  ldrawRoot: "./ldraw",
+  models: ["models/car.ldr"],   // paths, or { name, text }
+  studs: "low",                 // default
+  cond: false,                  // conditional lines (opt-in)
+  textures: false,              // printed/sticker parts (opt-in)
+});
+await Bun.write("public/car.pack.bin", data); // raw; compress with zstd/gzip for serving
+console.log(`${parts} parts`, missing.length ? `missing: ${missing}` : "");
+```
+
+### 3. Render it (browser)
 
 ```ts
 import * as THREE from "three";
@@ -29,97 +58,156 @@ import { parseModel, loadPack, createLdrObject } from "ldr";
 
 const [text, pack] = await Promise.all([
   fetch("/car.ldr").then((r) => r.text()),
-  loadPack("/car.pack.zst"),            // .zst / .gz / .br / raw .bin
+  loadPack("/car.pack.zst"),               // .zst / .gz / .br / raw .bin
 ]);
+
 const model = createLdrObject(parseModel(text, "car.ldr"), pack, {
   edges: true, cullStuds: true, cullUndersides: true, side: "front", material: "plastic",
 });
-scene.add(model.object);                 // +Y up, 1 unit = 1 LDU (scale option available)
-
-// build steps
-model.setStep(0);                        // show step 0 only … model.stepCount steps total
-model.setStep(null);                     // show everything
-```
-
-Add lights (or `scene.environment`) as for any `MeshStandardMaterial`/`MeshPhysicalMaterial`.
-
-## Getting parts
-
-The LDraw parts library is **not bundled** in this package. Download it from <https://library.ldraw.org> (`complete.zip`, ~90 MB unzipped to an `ldraw/` folder containing `LDConfig.ldr`, `parts/`, `p/`).
-The LDraw library is licensed **CC BY 2.0** — if you ship packs built from it, credit "LDraw.org Parts Library" (CC BY 2.0) in your app.
+scene.add(model.object);                    // +Y up, 1 unit = 1 LDU (see `scale`)
 
-Packs contain only the parts you ask for, so they're small: a 10k-brick Datsville section with 80 unique parts and the 100k section with 290 unique parts are 0.27 MB and 1.1 MB with zstd (1.3 / 3.3 MB gzip).
-
-```bash
-ldr pack --ldraw <dir> -o <out.bin|.zst|.gz> [model.ldr ...] [--part 3001.dat ...] [--all-parts]
-         [--studs low|full] [--prims full|low] [--no-weld] [--no-colors] [--cond] [--textures] [--no-loose-geometry]
-```
-
-Or from code (Node/Bun):
-
-```ts
-import { buildPack } from "ldr/node";
-const { data, parts, missing } = buildPack({ ldrawRoot: "./ldraw", models: ["car.ldr"], studs: "low" });
-await Bun.write("car.pack.bin", data);
+// Build steps
+model.setStep(0);                           // show step 0 … model.stepCount - 1
+model.setStep(null);                        // show everything
+const view = model.stepViews[3];            // ROTSTEP view for step 3 (or null)
 ```
 
-The pack embeds the LDConfig colour table by default, so no extra colour file is needed at runtime.
+Light the scene (or set `scene.environment`) as you would for any `MeshStandardMaterial` or `MeshPhysicalMaterial`.
 
-## API
+## API reference
 
 ### `ldr` (browser-safe)
 
+**Parsing and model**
+
 | export | description |
 |---|---|
-| `parse(text, name?) → Doc` | Parse LDraw text into files/commands (MPD-aware). |
-| `flatten(doc, { resolveModel?, looseGeometry?, textures? }) → PartInstance[]` | Expand submodels into placed parts with `color`, 12-number matrix `m`, `step`, nested `steps`, `path`. MPD-embedded parts (e.g. Studio/OMR unofficial parts) are emitted as parts (`embedded: true`, see `fileKind`); a model file's own type 2-5 lines become synthetic parts `<file>#<step>` (`looseGeometry`, default `true`); with `textures: true`, parts wrapped by a model-level `!TEXMAP` get `texPart` (a synthetic textured part, `texWrapper`). Instances carry their step's ROTSTEP `view`. |
-| `parseModel(text, name?, opts?)` | `parse` + `flatten`. |
-| `sequenceSteps(instances)` | Global build-step index per instance (nested submodel steps sequenced), plus `views`: the ROTSTEP view per global step. |
-| `fileKind(doc, name)` / `looseSource` / `loosePartName` / `texWrapper` / `fileStepViews` / `rotStepMatrix` / `stepViewMatrix` | Spec helpers: part vs model rule for MPD files (header type; else own geometry), the text of a model's loose geometry per step, model-level TEXMAP wrapper parts, ROTSTEP views (MLCad: `REL`/`ADD`/`ABS`/`END`, ROTSTEP ends the step). |
-| `parseLDConfig(text)` | `!COLOUR` table → `Map<code, {name, hex, edge, alpha}>`. |
-| `loadPack(url) → Promise<Pack>` | Fetch + decompress (by extension) + decode a pack. |
-| `decompressPack(bytes)` / `decodePack(buffer)` | Same, from bytes you already have (zstd/gzip auto-detected). |
-| `createLdrObject(instances, pack, options?) → LdrObject` | High-level three.js object. |
-| `createInstancedEdges(pos, instancedMesh, material?)` | Welded, indexed edge lines sharing an InstancedMesh's matrices (for custom batching). |
-| `conditionalLines(pack, entry, which?)` / `createInstancedConditionalEdges(cond, instancedMesh, material?)` | Type-5 conditional lines from a `--cond` pack (stride 12: p0, p1, c0, c1), drawn by a vertex shader only where the control points fall on the same side of the projected line. |
-| `makeTexturedMaterial(side, texture, wrapU?)` / `packTexture(pack, i)` / `texmapUV` / `texmapTriangleUV` | Printed / sticker parts from a `--textures` pack: a `!TEXMAP` UV material (image alpha blends over the part colour, untextured outside [0,1]) and the decoded embedded PNG. UV conventions follow LDView (v = 0 is the image's top row). |
-| `buildLdrScene`, `computeCulling`, `makeMaterial` | Low-level renderer used by the benchmarks. |
+| `parse(text, name?, { geometryText? }) → Doc` | Parses LDraw text into files and commands. MPD-aware: `0 FILE`/`0 NOFILE` and `0 !DATA` blocks. |
+| `flatten(doc, options?) → PartInstance[]` | Expands submodels into placed parts. Each instance has `part`, `color`, a 12-number matrix `m`, `step`, nested `steps`, `path` and the ROTSTEP `view` of its step. |
+| `parseModel(text, name?, options?)` | `parse` followed by `flatten`. |
+| `sequenceSteps(instances) → { count, stepOf, views }` | Gives each instance a global build-step index, sequencing nested submodel steps. `views` holds the ROTSTEP view per global step. |
+| `parseLDConfig(text) → Map<code, LDrawColor>` | Reads a `!COLOUR` table into `{ code, name, hex, edge, alpha }` entries. |
+| `fileKind(doc, name)` | Decides whether an MPD file is a part or a model: by its header type, otherwise by whether it has its own geometry. |
+| `looseSteps` / `looseFile` / `looseSource` / `loosePartName` | A model's own type 2–5 geometry, per step, as synthetic parts named `<file>#<step>`. |
+| `rotStepMatrix` / `stepViewMatrix` / `fileStepViews` | ROTSTEP views, following MLCad: `REL`, `ADD`, `ABS`, `END`. A ROTSTEP ends its step. |
+| `parseTexMap` / `texmapUV` / `texmapTriangleUV` / `transformTexMap` / `resolveTexture` / `texWrapper` | `!TEXMAP` support (`PLANAR`, `CYLINDRICAL`, `SPHERICAL`). UV conventions follow LDView: v = 0 is the image's top row. |
+| `parseColor`, `isDirectColor`, `colorToken`, `mul`, `invert`, `IDENTITY`, `norm`, `smoothNormals`, `hash32` | Low-level helpers. |
+
+`FlattenOptions`:
+
+| option | default | description |
+|---|---|---|
+| `looseGeometry` | `true` | Emits a model file's own type 2–5 lines as synthetic parts `<file>#<step>`. LDraw allows geometry in any file. |
+| `textures` | `false` | TEXMAP-aware view of the model. References wrapped by a model-level `!TEXMAP` get a `texPart`, and `!TEXMAP FALLBACK` references are skipped. Use with `textures: true` packs. |
+| `resolveModel(name)` | – | Resolves an external reference to a `Doc`, such as a model loaded separately. Return `null` to treat it as a part. |
+| `maxDepth` | `64` | Submodel nesting limit (cycle guard). |
+
+MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part instances (`embedded: true`) and override library parts of the same name.
+
+**Packs and rendering**
 
-`LdrObjectOptions`: `edges` (default `true`), `cullStuds` (`true`), `cullUndersides` (`true`), `side` (`"front"` \| `"double"`, default `"front"`), `material` (`"plastic"` \| `"standard"`), `colors` (Map / record / function override), `fallbackColor`, `ldrawSpace` (keep -Y up), `scale`, `step`, `conditionalLines` (default `true`; only has an effect with packs built with `--cond`), `conditionalStudLines` (default `true`; `false` skips stud silhouettes, ~half the conditional-line GPU cost but most of their visible effect on stud-heavy scenes), `textures` (default `true`; only has an effect with packs built with `--textures`; `object.texturesReady` resolves when images are decoded).
+| export | description |
+|---|---|
+| `loadPack(url) → Promise<Pack>` | Fetches, decompresses and decodes a pack. zstd and gzip are detected automatically. |
+| `decompressPack(bytes)` / `decodePack(buffer)` | Same, from bytes you already have. |
+| `createLdrObject(instances, pack, options?) → LdrObject` | High-level three.js object (see below). |
+| `createInstancedEdges(pos, instancedMesh, material?)` | Welded, indexed edge lines that share an `InstancedMesh`'s instance matrices. |
+| `conditionalLines(pack, entry, which?)` / `createInstancedConditionalEdges(cond, instancedMesh, material?)` / `conditionalLineVisible` | Type-5 conditional lines from a `cond` pack. A vertex shader keeps a segment only where both control points project to the same side of the line. |
+| `makeTexturedMaterial(side, texture, wrapU?)` / `packTexture(pack, i)` | Printed and sticker parts from a `textures` pack: a UV material and the decoded embedded PNG. |
+| `buildLdrScene`, `computeCulling`, `cullCore`, `makeMaterial` | Low-level renderer used by the benchmarks. `cullCore(instances, header, steps?)` is the typed-array culling core (with `steps`, also the step at which each stud and underside becomes hidden). |
+
+`LdrObjectOptions`:
+
+| option | default | description |
+|---|---|---|
+| `edges` | `true` | LDraw type-2 edge lines, indexed and sharing each part's instance matrices. |
+| `cullStuds` | `true` | Hides studs fully covered by a part above. |
+| `cullUndersides` | `true` | Hides undersides (tubes) sitting fully on studs below. |
+| `side` | `"front"` | `"front"` draws single-sided BFC faces; `"double"` draws both sides. Uncertified parts are always double-sided. |
+| `material` | `"plastic"` | `"plastic"` is `MeshPhysicalMaterial` with clearcoat; `"standard"` is `MeshStandardMaterial`, the cheapest option. |
+| `conditionalLines` | `true` | Conditional (silhouette) lines. Only takes effect with `cond` packs, and follows `edges`. |
+| `conditionalStudLines` | `true` | Conditional lines on studs. `false` roughly halves the conditional-line cost on large scenes. |
+| `textures` | `true` | Renders `!TEXMAP` images from `textures` packs; `false` draws the FALLBACK geometry. `object.texturesReady` resolves once the images are decoded. |
+| `colors` | pack table | Colour override: a `Map`, a record, or `(code) => color`. |
+| `fallbackColor` | `#A0A5A9` | Colour used for unknown codes. |
+| `ldrawSpace` | `false` | `true` keeps native LDraw space (-Y up). |
+| `scale` | `1` | Uniform scale (1 = 1 LDU; 1 stud = 20 LDU). |
+| `step` | all | Initial build step (inclusive, 0-based). |
+| `lod` | `true` | Distance LOD, re-selected for each camera you render with. Batches are split into spatial clusters (off-screen ones are frustum-culled). Each cluster draws the coarsest simplified mesh (from `lod` packs) whose error stays under `lodPx`, drops studs whose 12-LDU disc is under `lodPx`, and hides edges where a stud spans less than `lodEdgePx`. |
+| `lodPx` | `0.5` | LOD: maximum screen-space error in pixels. |
+| `lodEdgePx` | `0.5` | LOD: draw edge and conditional lines only where one stud (20 LDU) spans at least this many pixels. `0` = always. |
+
+`LdrObject`: `object`, `stats` (`instances`, `drawn`, `missing[]`, `studsHidden/Total`, `undersHidden/Total`, `buildMs`, `condBatches`, `texBatches`, `textures`, `clusters`), `stepCount`, `stepViews`, `texturesReady`, `setStep(n | null)`, `setEdges(on)`, `setConditionalLines(on)`, `setCulling(studs, undersides)`, `setSide(side)`, `setLod(on)`, `getBox(target?)`, `dispose()`.
+
+`setStep` doesn't rebuild anything: it compacts instance buffers, and culling is step-aware (a stud covered only by a later step's part stays visible). `stats` reflect the shown step.
+
+### `ldr/node` (Node / Bun only)
+
+Everything above, plus:
 
-`LdrObject`: `object`, `stats` (`instances`, `drawn`, `missing[]`, `studsHidden/Total`, `undersHidden/Total`, `buildMs`), `stepCount`, `stepViews` (ROTSTEP view per step, or `null`), `setStep(n | null)`, `setEdges(on)`, `setCulling(studs, undersides)`, `setSide(side)`, `getBox()`, `dispose()`.
+| export | description |
+|---|---|
+| `buildPack(options) → { data, parts, studKinds, missing, warnings? }` | Builds a pack. Options: `ldrawRoot`, `models`, `parts`, `allParts`, `studs` (`"low"` \| `"full"`), `primitives` (`"full"` \| `"low"`), `weld` (`true`), `cond` (`false`), `textures` (`false`), `looseGeometry` (`true`), `colors` (`true`), `lod` (`true`: meshoptimizer-simplified LOD meshes, pack feature `lod`), `reorder` (`false`: vertex-cache order), `onProgress`. |
+| `Library(root, unofficialRoot?)` | Filesystem LDraw resolver: `where`, `flatten`, `mesh`, `colors`, `texture`, `register`. Handles case-insensitive lookup and `~Moved to` aliases. |
+| `Compiler`, `encodePack`, `writePack`, `loadColors` | Lower-level pack compiler. |
+| `ResolverLibrary`, `splitModel`, `flattenWithLibrary`, `collectDeps` | The resolver that `buildPack` uses. |
 
-### `ldr/node` (Node/Bun only)
+## Benchmarks
 
-Everything above, plus `buildPack(options)`, `Library` (filesystem LDraw resolver: `where`, `flatten`, `mesh`, `colors`), `Compiler`, `encodePack`, `writePack`.
+All numbers below were measured with the harness in [`bench/`](https://github.com/EvanBacon/ldr/tree/main/bench/) and are taken from the result files there.
 
-## Performance
+- **Hardware and browser:** Apple **M4 Pro** MacBook Pro, Chrome with native GL (ANGLE → Metal), Bun 1.3.
+- **Frame time:** the **median synced frame time** (`gl.finish` per frame) while orbiting the camera.
+- **Load:** from fetch to the first rendered frame.
+- **Baseline:** three.js geometry from `LDrawLoader` merged per part and drawn with `InstancedMesh`, which is the fastest stock approach. Stock `LDrawLoader` scenes crash the tab (OOM) at 50k bricks and above, and already on Datsville 10k.
+- **ldr settings:** the defaults: LOD pack, distance LOD, low-detail studs, stud and underside culling, single-sided faces, no edges.
 
-Measured with the benchmark harness in [`bench/`](https://github.com/EvanBacon/ldr/tree/main/bench) (Chrome, synced frame time while orbiting). Apple M4 Pro, native GL (Metal via ANGLE):
+Sources: `bench/results/latest-perf.md` (the regression gate, `bench/baselines/darwin-apple-m4-pro.json`), `latest-mac-ablation.md`, and `research.md` §7 and Round 19.
 
-| model | renderer | load | frame | tris/frame | draw calls |
+| model | bricks | baseline frame | **ldr frame** | baseline load | **ldr load** |
 |---|---|---|---|---|---|
-| Datsville 100k bricks | three.js `LDrawLoader`-geometry instancing | 19.5 s | 105.7 ms (9 fps) | 142.7M | 290 |
-| Datsville 100k bricks | **ldr** (low studs, culling, single-sided) | **2.2 s** | **30.1 ms (33 fps)** | 59.1M | 506 |
-| Datsville 10k bricks | three.js instancing | 13.5 s | 45.9 ms | 60.5M | 80 |
-| Datsville 10k bricks | **ldr** (same) | **1.0 s** | **10.9 ms (92 fps)** | 21.0M | 131 |
-| 100k-brick grid | **ldr** + edges | 0.67 s | 15.7 ms (64 fps) | 4.0M | 24 |
-| 10k-brick grid | `LDrawLoader` | 6.6 s | 61.5 ms | 2.6M | 29,671 |
-| 10k-brick grid | **ldr** + edges | 0.15 s | 2.2 ms | 0.4M | 24 |
-
-**Demo app** (`demo/`, rAF fps on the M4 Pro with big-model defaults — shadows/AO/edges off above 50k bricks): Datsville 100k at **43.5 fps** (1.8 s load), full Datsville (392k bricks) at **9.9 fps**.
-
-Visual-diff studies show culling and single-sided faces are lossless (≤0.009% pixels); low-detail studs change only stud silhouettes. Stud culling hides ~39–51% of studs on real models.
-
-## Notes & limitations
-
-- Transparent colours render opaque. Conditional (type-5) lines are drawn only from packs built with `--cond` (pack v2, opt-in: +8–14% zstd size on Datsville); default packs carry type-2 edges only. Printed parts show their `!TEXMAP` images only from packs built with `--textures` (pack v2, opt-in; the PNGs dominate the size); default packs draw the parts' FALLBACK geometry. Model-level `!TEXMAP` around part references renders from `--textures` packs (one synthetic part per distinct map). Parts embedded in an MPD (unofficial/custom parts, stickers) render as parts and override library parts of the same name; geometry drawn directly in a model file is packed as synthetic parts (`--no-loose-geometry` to skip it).
-- ROTSTEP is reported (`stepViews`, `instance.view`), not applied: rotating the camera per step is up to the app.
-- `setStep` rebuilds batches (fast for instruction-sized models; culling is recomputed for the partial build).
-- Coordinates: LDraw units (1 stud = 20 LDU); the object is rotated to +Y up unless `ldrawSpace: true`.
-
-LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project.
-
-## License
-
-MIT (code). Parts data you build from the LDraw library is CC BY 2.0 (LDraw.org).
+| synthetic grid | 100,021 | 24.4 ms | **2.7 ms** | 0.2 s | 0.3 s |
+| Datsville 10k | 10,000 | 45.9 ms | **2.2 ms** | 13.5 s | **0.34 s** |
+| Datsville 100k | 100,000 | 105.7 ms | **6.2 ms** | 19.5 s | **0.79 s** |
+| Datsville (full) | 392,514 | 409.6 ms | **27.2 ms** | 24.7 s | **1.6 s** |
+
+How much each optimization contributes on Datsville 100k, in ms per frame: welding 108.1 → 64.6, stud culling → 50.8, underside culling → 41.7, low-detail studs → 31.0, single-sided faces → 30.1. Triangles per frame drop from 142.7M to 59.1M. Distance LOD (Round 19) then takes it to 6.2 ms and 6.6M triangles; ≤ 1.6% of pixels differ from full detail (mostly sub-pixel stud moiré).
+
+- **Pack size:** Datsville 100k (290 unique parts) is 25.8 MB raw, 3.98 MB gzip and **1.49 MB zstd** with LOD meshes (22.4 MB / 1.08 MB zstd with `lod: false`). Decoding a zstd pack in the browser (fzstd) takes about **60 ms**.
+- **Stock `LDrawLoader`:** loading the scene directly crashes the renderer (OOM) on the 50k, 100k and 250k grids and on Datsville 10k. The 10k grid loads in 6.6 s and draws at 61.5 ms per frame (29,671 draw calls), against 0.15 s and 2.2 ms with ldr + edges.
+- **Demo app** (`demo/`; rAF frame median at 2880×1800 on the M4 Pro):
+  - These comparisons are between demo settings. "Before" has every effect on (shadows, AO, screen-space edges, PBR/IBL); "after" is the demo's big-model defaults, which turn those effects off above 50k bricks.
+  - Full Datsville: **1.7 → 9.9 fps**.
+  - Datsville 100k: **8 → 43.5 fps**.
+- **Conditional lines** (opt-in `cond` packs) cost **+12–14 %** frame time on Datsville 10k and 100k (M4 Pro), and add 7–14 % to the zstd pack size.
+- **Edges:** with LOD, edges cost Datsville 100k 6.2 → 9.2 ms and full Datsville nothing measurable (27.2 ms), because edges are hidden where bricks are sub-pixel (`lodEdgePx`). Without edge LOD they cost 35 ms (100k) and 153 ms (full).
+- **Build steps:** `setStep` takes 66 ms on Datsville 100k and 29 ms on 10k (it was a full rebuild: 752 / 347 ms).
+- **Visual fidelity:** pixel diffs show culling and single-sided faces are lossless (≤ 0.009 % of pixels differ). Low-detail studs only change stud silhouettes.
+
+Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun run bench` (see [`bench/README.md`](https://github.com/EvanBacon/ldr/blob/main/bench/README.md)).
+
+## LDraw spec compliance
+
+- Line types 0–5. BFC: `CERTIFY`, `CCW`/`CW`, `INVERTNEXT`, `NOCLIP`, inverted matrices.
+- MPD: `0 FILE` / `0 NOFILE`, and `0 !DATA` (base64 PNGs). An MPD file is a part or a model by its `!LDRAW_ORG` type, otherwise by whether it has its own geometry. Embedded parts override library parts.
+- Geometry drawn directly in model files (type 2–5 lines outside parts), on by default.
+- `0 STEP`, nested submodel step sequencing, `0 ROTSTEP` (`REL`/`ADD`/`ABS`/`END`), and `0 BUFEXCHG`.
+- `!TEXMAP` `START`/`NEXT`/`FALLBACK`/`END`, with `PLANAR`, `CYLINDRICAL` and `SPHERICAL` projections (orientation matches LDView), and model-level `!TEXMAP` around part references.
+- Colours: LDConfig `!COLOUR`, edge colours, main/edge colour inheritance (16/24), and direct colours (`0x2RRGGBB`).
+- Case-insensitive, backslash-normalized file lookup; `~Moved to` alias parts.
+
+## Limitations
+
+- **Transparency:** transparent colours render opaque.
+- **Opt-in pack features:** conditional lines need packs built with `cond`. Printed parts show their images only from `textures` packs (the embedded PNGs dominate the pack size); default packs draw the FALLBACK geometry.
+- **ROTSTEP** is reported (`stepViews`, `instance.view`), not applied. Rotating the camera per step is up to your app.
+- **Packs are static:** they hold only the parts they were built for. A model that uses parts missing from the pack lists them in `stats.missing`.
+- **Occlusion culling:** beyond hidden studs and undersides there is no occlusion culling (bricks enclosed by other bricks are still drawn). Frustum culling and LOD apply per spatial cluster.
+- **LOD and edges:** at the default `lodEdgePx` edges disappear where bricks are a few pixels wide, which visibly lightens far-away views drawn with edges (4–7% of pixels on Datsville overviews). Set `lodEdgePx: 0` to keep every edge (much slower on large models), or `lod: false` to turn LOD off entirely.
+
+## Attribution and license
+
+- **Code:** MIT © Evan Bacon.
+- **LDraw parts:** packs you build contain geometry from the **LDraw.org Parts Library**, which is licensed **CC BY 2.0** (newer files CC BY 4.0, per file header). If you ship packs, credit "LDraw.org Parts Library (CC BY 2.0)" in your app. See <https://www.ldraw.org/legal-info>.
+- **Datsville:** the benchmark model is by [mjhorvath/Datsville](https://github.com/mjhorvath/Datsville) (CC BY-SA 4.0). It is used for benchmarking only and is not redistributed.
+- **Trademarks:** LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project. LDraw™ is a trademark of the Estate of James Jessiman.

package/dist/cdn.d.ts

@@ -0,0 +1,62 @@
+import { type Pack } from "./render.js";
+import { type PartInstance } from "./model.js";
+import { type LdrObject, type LdrObjectOptions } from "./scene.js";
+/** Default parts CDN (LDraw library parts, CC BY 2.0 / 4.0, compiled by ldr; hosted with the demo site). */
+export declare const DEFAULT_PARTS_CDN = "https://ldr-demo.vercel.app/cdn/v1/";
+export interface PartsCdnIndex {
+    format: string;
+    release?: string;
+    license?: string;
+    archives: string[];
+    bytes: number;
+    colors: Record<string, string>;
+    parts: Record<string, [number, number, number]>;
+}
+export interface LoadPartsOptions {
+    /** Base URL of the parts CDN (ending in /). Default `DEFAULT_PARTS_CDN`. */
+    cdn?: string;
+    /** Merge two byte ranges into one request when the gap between them is at most this many bytes. Default 64 KB. */
+    gap?: number;
+    /** Max parallel Range requests. Default 6. */
+    concurrency?: number;
+    fetch?: typeof fetch;
+}
+/** Fetch (and cache) a parts CDN index. */
+export declare function loadPartsIndex(cdn?: string, f?: typeof fetch): Promise<PartsCdnIndex>;
+/** Merge several packs into one (parts and stud kinds; the first pack's definition wins on name clashes). */
+export declare function mergePacks(packs: Pack[], extra?: Record<string, unknown>): Pack;
+/**
+ * Fetch the given parts from a parts CDN and return them as one Pack (with the LDConfig colour table).
+ * Parts the CDN does not have are listed in `missing`.
+ */
+export declare function loadParts(names: Iterable<string>, o?: LoadPartsOptions): Promise<{
+    pack: Pack;
+    missing: string[];
+    requests: number;
+    bytes: number;
+}>;
+export interface LoadModelOptions extends LdrObjectOptions, LoadPartsOptions {
+    /** Treat `source` as LDraw text instead of a URL. */
+    text?: boolean;
+    /** File name used for the main model (MPD resolution). Default: last URL segment. */
+    name?: string;
+}
+export interface LoadedModel extends LdrObject {
+    pack: Pack; /** The flattened model (part instances). */
+    instances: PartInstance[];
+    timings: {
+        fetchModel: number;
+        parse: number;
+        parts: number;
+        build: number;
+        total: number;
+    };
+    requests: number;
+    bytes: number;
+}
+/**
+ * One call from an `.ldr` / `.mpd` URL (or text) to a three.js object: fetches the model, fetches just the parts it uses from the
+ * parts CDN and builds an instanced `LdrObject`. No LDraw library or parts pack needed.
+ * Limits (v1): parts defined inside the model (MPD-embedded parts) and loose geometry in model files are skipped (listed in `stats.missing`).
+ */
+export declare function loadModel(source: string, o?: LoadModelOptions): Promise<LoadedModel>;