ldr 0.4.1 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Render 100,000-brick LEGO® (LDraw) models in three.js at interactive frame rates.**
 
-`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, low-detail studs, single-sided (BFC) faces and indexed edge lines. On an Apple M4 Pro that takes Datsville (392,514 bricks) from 410 ms to 97 ms per frame, and its load time from 24.7 s to 3.4 s.
+`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`.
@@ -29,7 +29,7 @@ bunx ldr pack --ldraw ./ldraw -o public/car.pack.zst models/car.ldr
 ```
 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]
+         [--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.
@@ -114,7 +114,7 @@ MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part
 | `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`, `makeMaterial` | Low-level renderer used by the benchmarks. |
+| `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`:
 
@@ -133,8 +133,13 @@ MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part
 | `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`), `stepCount`, `stepViews`, `texturesReady`, `setStep(n | null)`, `setEdges(on)`, `setConditionalLines(on)`, `setCulling(studs, undersides)`, `setSide(side)`, `getBox(target?)`, `dispose()`.
+`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)
 
@@ -142,7 +147,7 @@ Everything above, plus:
 
 | 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`), `onProgress`. |
+| `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. |
@@ -155,30 +160,31 @@ All numbers below were measured with the harness in [`bench/`](https://github.co
 - **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:** low-detail studs, welded pack, stud and underside culling, single-sided faces, no edges.
+- **ldr settings:** the defaults: LOD pack, distance LOD, low-detail studs, stud and underside culling, single-sided faces, no edges.
 
-Sources: `bench/results/latest-mac-ablation.md`, `latest-mac.md`, and `research.md` §7.
+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 | bricks | baseline frame | **ldr frame** | baseline load | **ldr load** |
 |---|---|---|---|---|---|
-| synthetic grid | 100,021 | 24.4 ms | **3.6 ms** | 0.2 s | 0.6 s |
-| Datsville 10k | 10,000 | 45.9 ms | **10.9 ms** | 13.5 s | **1.0 s** |
-| Datsville 100k | 100,000 | 105.7 ms | **30.1 ms** | 19.5 s | **2.2 s** |
-| Datsville (full) | 392,514 | 409.6 ms | **97.2 ms** | 24.7 s | **3.4 s** |
+| 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.
+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 22.4 MB raw, 3.13 MB gzip and **1.08 MB zstd**. Decoding the zstd pack in the browser (fzstd) takes **58 ms**.
+- **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:** turning `edges` on costs more than that on dense scenes: Datsville 100k goes from 30.1 to 98.2 ms per frame. For very large models, consider `edges: false`.
+- **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 bench` (see [`bench/README.md`](https://github.com/EvanBacon/ldr/blob/main/bench/README.md)).
+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
 
@@ -195,9 +201,9 @@ Reproduce: `cd bench && bun run setup && bun run bench` (see [`bench/README.md`]
 - **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.
-- **`setStep`** rebuilds batches. That is fast for instruction-sized models, and culling is recomputed for the partial build.
 - **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 and LOD:** there is no occlusion culling and no distance LOD yet. Only three.js frustum culling applies, per batch.
+- **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
 

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>;

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// src/cli.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/cli.ts
 import fs4 from "node:fs";
 import zlib from "node:zlib";
 
-// src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/build-pack.ts
 import fs3 from "node:fs";
 import path3 from "node:path";
 
-// src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/resolver.ts
 import fs from "node:fs";
 import path from "node:path";
 
-// src/spec.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/spec.ts
 var norm = (s) => s.trim().toLowerCase().replace(/\\/g, "/").replace(/\/+/g, "/");
 function parseColor(tok) {
   if (/^0x/i.test(tok))
@@ -662,7 +662,7 @@ function fileStepViews(f) {
   return out;
 }
 
-// src/model.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/model.ts
 function flatten(doc, opts = {}) {
   const out = [];
   const maxDepth = opts.maxDepth ?? 64;
@@ -784,7 +784,7 @@ function parseLDConfig(text) {
   return out;
 }
 
-// src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/resolver.ts
 var TOP_STUD_RE = /^(stud|studa|stud2|stud2a|stud6|stud6a|stud10|stud15|stud2s|stud2s2|stud-logo\d*|stud2-logo\d*)\.dat$/i;
 var UNDER_STUD_RE = /^(stud3|stud3a|stud4.*|stud12|stud16.*|stud18a)\.dat$/i;
 var norm2 = (ref) => ref.trim().replace(/\\/g, "/").toLowerCase();
@@ -1054,9 +1054,118 @@ function collectDeps(lib, refs) {
   return out;
 }
 
-// src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/compile.ts
 import fs2 from "node:fs";
 import path2 from "node:path";
+
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/lod.ts
+import { MeshoptSimplifier, MeshoptEncoder } from "meshoptimizer";
+await Promise.all([MeshoptSimplifier.ready, MeshoptEncoder.ready]);
+function reorderMesh(P, N, C, I) {
+  const idx = Uint32Array.from(I);
+  const n = P.length / 3;
+  const [remap] = MeshoptEncoder.reorderMesh(idx, true, false);
+  const P2 = new Float32Array(P.length), N2 = new Float32Array(N.length), C2 = new Float32Array(C.length);
+  for (let v = 0;v < n; v++) {
+    const r = remap[v];
+    if (r === 4294967295)
+      continue;
+    P2[r * 3] = P[v * 3];
+    P2[r * 3 + 1] = P[v * 3 + 1];
+    P2[r * 3 + 2] = P[v * 3 + 2];
+    N2[r * 3] = N[v * 3];
+    N2[r * 3 + 1] = N[v * 3 + 1];
+    N2[r * 3 + 2] = N[v * 3 + 2];
+    for (let k = 0;k < 4; k++)
+      C2[r * 4 + k] = C[v * 4 + k];
+  }
+  return { P: P2, N: N2, C: C2, I: idx };
+}
+var TARGETS = [0.25, 0.08];
+var MIN_TRIS = 64;
+function flatMesh(tris) {
+  const map = new Map;
+  const P = [], N = [], C = [], I = [];
+  for (const { p, i: idx, col } of tris)
+    for (let t = 0;t < idx.length; t += 3) {
+      const a = idx[t] * 3, b = idx[t + 1] * 3, c = idx[t + 2] * 3;
+      const ux = p[b] - p[a], uy = p[b + 1] - p[a + 1], uz = p[b + 2] - p[a + 2], vx = p[c] - p[a], vy = p[c + 1] - p[a + 1], vz = p[c + 2] - p[a + 2];
+      let nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+      const l = Math.hypot(nx, ny, nz);
+      if (!(l > 0.000000001))
+        continue;
+      nx /= l;
+      ny /= l;
+      nz /= l;
+      for (const o of [a, b, c]) {
+        const k = `${p[o].toFixed(3)},${p[o + 1].toFixed(3)},${p[o + 2].toFixed(3)},${nx.toFixed(3)},${ny.toFixed(3)},${nz.toFixed(3)},${col.join()}`;
+        let j = map.get(k);
+        if (j === undefined) {
+          j = P.length / 3;
+          map.set(k, j);
+          P.push(p[o], p[o + 1], p[o + 2]);
+          N.push(nx, ny, nz);
+          C.push(...col);
+        }
+        I.push(j);
+      }
+    }
+  return { P: new Float32Array(P), N: new Float32Array(N), C: new Float32Array(C), I: new Uint32Array(I) };
+}
+function lodChain(P, C, I) {
+  const nTris = I.length / 3;
+  if (nTris < MIN_TRIS)
+    return [];
+  const groups = new Map;
+  for (let t = 0;t < I.length; t += 3) {
+    const v = I[t] * 4;
+    const col = [C[v], C[v + 1], C[v + 2], C[v + 3]];
+    const k = col.join();
+    let g = groups.get(k);
+    if (!g)
+      groups.set(k, g = { col, tri: [] });
+    g.tri.push(I[t], I[t + 1], I[t + 2]);
+  }
+  const welded = [...groups.values()].map(({ col, tri }) => {
+    const map = new Map;
+    const pos = [];
+    const idx = new Uint32Array(tri.length);
+    for (let i = 0;i < tri.length; i++) {
+      const o = tri[i] * 3;
+      const k = `${P[o].toFixed(3)},${P[o + 1].toFixed(3)},${P[o + 2].toFixed(3)}`;
+      let j = map.get(k);
+      if (j === undefined) {
+        j = pos.length / 3;
+        map.set(k, j);
+        pos.push(P[o], P[o + 1], P[o + 2]);
+      }
+      idx[i] = j;
+    }
+    return { col, p: new Float32Array(pos), i: idx };
+  });
+  const out = [];
+  let prevTris = nTris;
+  for (let li = 0;li < TARGETS.length; li++) {
+    let err = 0;
+    const parts = [];
+    for (const g of welded) {
+      const target = Math.max(3, Math.floor(g.i.length * TARGETS[li] / 3) * 3);
+      const [idx, e] = MeshoptSimplifier.simplify(g.i, g.p, 3, target, 1e9, li ? ["ErrorAbsolute", "Prune"] : ["ErrorAbsolute"]);
+      err = Math.max(err, e);
+      if (idx.length)
+        parts.push({ p: g.p, i: idx, col: g.col });
+    }
+    const m = flatMesh(parts);
+    const t = m.I.length / 3;
+    if (t > prevTris * 0.7 || !t)
+      continue;
+    out.push({ ...m, err: +Math.max(err, 0.001).toFixed(3) });
+    prevTris = t;
+  }
+  return out;
+}
+
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/compile.ts
 function loadColors(root) {
   const map = new Map;
   for (const l of fs2.readFileSync(path2.join(root, "LDConfig.ldr"), "latin1").split(/\r?\n/)) {
@@ -1473,7 +1582,8 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
     return r;
   };
   let lastPos = [];
-  const bucket = (b) => {
+  let anyLod = false;
+  const bucket = (b, lod = false) => {
     const n = b.pos.length / 3;
     lastPos = [];
     if (!n)
@@ -1512,9 +1622,20 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
       }
       I.push(j);
     }
-    const vcount = P.length / 3;
-    lastPos = P;
-    return { pos: put(new Float32Array(P)), nrm: put(new Float32Array(N)), col: put(new Float32Array(C)), idx: put(vcount < 65536 ? new Uint16Array(I) : new Uint32Array(I)), tris: n / 3 };
+    let m = { P, N, C, I };
+    if (options.reorder && I.length >= 3)
+      m = reorderMesh(P, N, C, I);
+    const vcount = m.P.length / 3;
+    lastPos = m.P;
+    const out = { pos: put(Float32Array.from(m.P)), nrm: put(Float32Array.from(m.N)), col: put(Float32Array.from(m.C)), idx: put(vcount < 65536 ? Uint16Array.from(m.I) : Uint32Array.from(m.I)), tris: n / 3 };
+    if (lod && options.lod) {
+      const chain = lodChain(P, C, I).map((l) => options.reorder ? { ...l, ...reorderMesh(l.P, l.N, l.C, l.I) } : l);
+      if (chain.length) {
+        anyLod = true;
+        out.lod = chain.map((l) => ({ pos: put(l.P), col: put(Uint8Array.from(l.C, (x) => Math.round(x * 255))), idx: put(l.P.length / 3 < 65536 ? new Uint16Array(l.I) : l.I), tris: l.I.length / 3, err: l.err }));
+      }
+    }
+    return out;
   };
   let anyCond = false;
   const condl = (a, pools) => {
@@ -1605,18 +1726,18 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
     });
     return { tbody: bucket(c.tbody), tex };
   };
-  const enc = (c) => {
-    const body = bucket(c.body), bodyP = lastPos, under = bucket(c.under), underP = lastPos;
+  const enc = (c, lod = false) => {
+    const body = bucket(c.body, lod), bodyP = lastPos, under = bucket(c.under, lod), underP = lastPos;
     const edges = c.edges.length ? put(new Float32Array(c.edges)) : null;
     const condlB = condl(c.cond, [bodyP, underP, c.edges]), condlU = condl(c.condUnder, [bodyP, underP, c.edges]);
     return { body, under, edges, cond: c.condLines, condl: condlB, condlu: condlU, studs: c.studs.map((s) => [s.kind, s.color, ...s.m.map((x) => +x.toFixed(4))]), bbox: c.bbox, fullBottom: c.fullBottom, uncert: !!c.uncertified, mask: c.bottomMask ? [c.bottomMask.nx, c.bottomMask.nz, c.bottomMask.bits.join("")] : null, ...encTex(c) };
   };
-  const encParts = Object.fromEntries([...parts].map(([k, c]) => [k, enc(c)])), encKinds = Object.fromEntries([...studKinds].map(([k, c]) => [k, enc(c)]));
+  const encParts = Object.fromEntries([...parts].map(([k, c]) => [k, enc(c, true)])), encKinds = Object.fromEntries([...studKinds].map(([k, c]) => [k, enc(c)]));
   const textures = texNames.map((name) => {
     const b = options.texture?.(name);
     return b ? { name, mime: "image/png", data: put(b) } : { name, missing: true };
   });
-  const features = [...anyCond ? ["cond"] : [], ...texNames.length ? ["tex"] : []];
+  const features = [...anyCond ? ["cond"] : [], ...texNames.length ? ["tex"] : [], ...anyLod ? ["lod"] : []];
   const header = { version: features.length ? 2 : 1, ...features.length ? { features } : {}, weld, parts: encParts, studKinds: encKinds, ...texNames.length ? { textures } : {}, ...extra };
   const hj = new TextEncoder().encode(JSON.stringify(header));
   const hpad = (4 - (4 + hj.length) % 4) % 4;
@@ -1627,7 +1748,7 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
   return Buffer.concat([head, ...chunks.map((c) => new Uint8Array(c.buffer, c.byteOffset, c.byteLength))]);
 }
 
-// src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/node/build-pack.ts
 function buildPack(o) {
   const lib = new Library(o.ldrawRoot);
   const refs = new Map;
@@ -1687,10 +1808,10 @@ function buildPack(o) {
     return b ? new Uint8Array(Buffer.from(b, "base64")) : comp.texture(n);
   };
   const warnings = [...lib.conflicts].map((n) => `${n}: defined differently by two models; the first definition is used`);
-  return { data: encodePack(parts, kinds, comp.opts.weld, extra, { texture }), parts: parts.size, studKinds: kinds.size, missing: [...missing], ...warnings.length ? { warnings } : {} };
+  return { data: encodePack(parts, kinds, comp.opts.weld, extra, { texture, lod: o.lod !== false, reorder: !!o.reorder }), parts: parts.size, studKinds: kinds.size, missing: [...missing], ...warnings.length ? { warnings } : {} };
 }
 
-// src/cli.ts
+// ../../../../../../../tmp/ldr-build-qIdKSv/src/cli.ts
 var HELP = `ldr pack — build a parts pack for the ldr three.js renderer
 
 Usage:
@@ -1707,6 +1828,8 @@ Options:
   --cond              Keep conditional (type-5) lines for curved-surface outlines (pack v2, ~+8-14% zstd)
   --textures          Keep printed/sticker parts' !TEXMAP geometry + UVs and embed their PNGs (pack v2; packs without
                       textured parts are unchanged). Textures come from model !DATA blocks, then <ldraw>/parts/textures
+  --no-lod            Skip distance-LOD meshes (simplified bodies drawn only where their error is under a pixel)
+  --reorder           Reorder triangles/vertices for vertex-cache reuse (~-3% frame time without LOD, +1% size)
   --no-colors         Don't embed the LDConfig colour table
   --no-loose-geometry Skip a model file's own type 2-5 lines (drawn in the model, not in a part). By default they become
                       synthetic parts "<file>#<step>" so the model renders as the LDraw spec says
@@ -1729,6 +1852,8 @@ var all = false;
 var cond = false;
 var textures = false;
 var loose = true;
+var lod = true;
+var reorder = false;
 for (let i = 0;i < a.length; i++) {
   const k = a[i];
   const v = () => {
@@ -1761,6 +1886,10 @@ for (let i = 0;i < a.length; i++) {
     loose = false;
   else if (k === "--all-parts")
     all = true;
+  else if (k === "--no-lod")
+    lod = false;
+  else if (k === "--reorder")
+    reorder = true;
   else if (k.startsWith("-")) {
     console.error(`unknown option ${k}
 
@@ -1778,7 +1907,7 @@ if (!fs4.existsSync(ldraw + "/LDConfig.ldr")) {
   process.exit(1);
 }
 var t0 = performance.now();
-var r = buildPack({ ldrawRoot: ldraw, models, parts, allParts: all, studs, primitives: prims, weld, colors, cond, textures, looseGeometry: loose });
+var r = buildPack({ ldrawRoot: ldraw, models, parts, allParts: all, studs, primitives: prims, weld, colors, cond, textures, looseGeometry: loose, lod, reorder });
 var data = r.data;
 if (out.endsWith(".gz"))
   data = zlib.gzipSync(data, { level: 9 });

package/dist/index.d.ts

@@ -2,8 +2,10 @@ export { parse, parseColor, isDirectColor, mul, I as IDENTITY, norm, smoothNorma
 export type { M as Matrix12, Doc, LFile, Cmd, RotStep, BufExchg, TexMap, TexMapCmd, TexMapMethod, TexAnno, DataBlock, PartMesh, FileKind, StepView } from "./spec.js";
 export { flatten, parseModel, sequenceSteps, parseLDConfig } from "./model.js";
 export type { PartInstance, FlattenOptions, LDrawColor } from "./model.js";
-export { loadPack, decodePack, buildLdrScene, makeMaterial, createInstancedEdges, computeCulling, conditionalLines, createInstancedConditionalEdges, conditionalLineVisible } from "./render.js";
-export type { Pack, LdrParams, Inst } from "./render.js";
+export { loadPack, decodePack, buildLdrScene, makeMaterial, createInstancedEdges, computeCulling, cullCore, forEachStud, conditionalLines, createInstancedConditionalEdges, conditionalLineVisible } from "./render.js";
+export type { Pack, LdrParams, Inst, CullResult } from "./render.js";
 export { createLdrObject } from "./scene.js";
 export type { LdrObject, LdrObjectOptions, LdrStats, ColorSource } from "./scene.js";
 export { decompressPack } from "./pack-io.js";
+export { loadModel, loadParts, loadPartsIndex, mergePacks, DEFAULT_PARTS_CDN } from "./cdn.js";
+export type { LoadModelOptions, LoadedModel, LoadPartsOptions, PartsCdnIndex } from "./cdn.js";