ldr 0.5.1 → 0.7.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, 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.
+`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 12 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`.
@@ -58,7 +58,7 @@ 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 / raw .bin (detected from the bytes)
 ]);
 
 const model = createLdrObject(parseModel(text, "car.ldr"), pack, {
@@ -136,11 +136,22 @@ MPD-embedded parts, such as Studio/OMR unofficial parts or stickers, become part
 | `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. |
+| `lodEdgeMinPx` | `0.15` | LOD: draw only edge segments at least this many pixels long on screen. `0` = every segment. |
+| `lodUnder` | `true` | LOD: skip undersides that can't be seen (camera behind every bottom face of a cluster's parts, or the body drawn as its closed bounding box). Lossless in the fidelity checks. |
 
 `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.
 
+**Building instructions.** `parseModel(text, name, { callouts: true })` (or `loadModel(url, { callouts: true })`) sequences a
+submodel placed N times in one step like a booklet: the first copy is built step by step (its instances get `mult = N`, the "xN"),
+the other copies appear finished at the end of that step. `planStepViews(instances, pack.header.parts, stepOf, stepCount)` plans a
+camera per step (`view(step)` → `{ dir, target, radius, minVis, meanVis, below, isolate }`, LDraw space): the booklet view (30° up,
+45° round) while it shows the new parts at least half visible on average, otherwise the best of 24 views from above (or from below for
+parts added underneath), preferring front three-quarter views and small turns (thresholds from Agrawala et al., SIGGRAPH 2003).
+`isolate` is set while a sub-assembly is being built: show it on its own with `setStep(step, isolateMask(instances, view.isolate))`.
+Visibility is measured on part bounding boxes, so it needs no GPU and also runs in Node.
+
 ### `ldr/node` (Node / Bun only)
 
 Everything above, plus:
@@ -167,20 +178,20 @@ Sources: `bench/results/latest-perf.md` (the regression gate, `bench/baselines/d
 | model | bricks | baseline frame | **ldr frame** | baseline load | **ldr load** |
 |---|---|---|---|---|---|
 | 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** |
+| Datsville 10k | 10,000 | 45.9 ms | **1.9 ms** | 13.5 s | **0.36 s** |
+| Datsville 100k | 100,000 | 105.7 ms | **4.4 ms** | 19.5 s | **0.79 s** |
+| Datsville (full) | 392,514 | 409.6 ms | **12.5 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é).
+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 (Rounds 19–20: simplified and bounding-box levels with a silhouette-coverage error, sub-pixel studs dropped, undersides skipped where they can't be seen) then takes it to 4.4 ms and 4.0M triangles; ≤ 1.5% 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**.
+- **Pack size:** Datsville 100k (290 unique parts) is about 26 MB raw and **1.46 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):
+- **Original demo app** (retired; 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).
+- **Edges:** with LOD, edges cost Datsville 10k 1.9 → 3.3 ms and 100k 4.4 → 5.2 ms, and full Datsville nothing measurable, because each cluster draws only edge segments at least 0.15 px long (`lodEdgeMinPx`) and none where bricks are sub-pixel (`lodEdgePx`). Far views drawn with edges get lighter (≤ 4.7% of pixels on Datsville overviews); `lodEdgeMinPx: 0, lodEdgePx: 0` keeps every edge.
 - **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.
 
@@ -200,14 +211,14 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 
 - **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.
+- **ROTSTEP** is reported (`stepViews`, `instance.view`), not applied; `planStepViews` takes a `fixed(step)` override if you want to honour it.
 - **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.
+- **LOD and edges:** edge LOD drops sub-pixel edge segments and hides edges where bricks are a fraction of a pixel, which visibly lightens far-away views drawn with edges (up to 4.7% of pixels on Datsville overviews). Set `lodEdgeMinPx: 0, 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.
+- **Trademarks:** LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize or endorse this project; ldr is not affiliated with the LEGO Group. LDraw™ is a trademark of the Estate of James Jessiman.

package/dist/cdn.d.ts

@@ -1,45 +1,11 @@
-import { type Pack } from "./render.js";
-import { type PartInstance } from "./model.js";
+import { type Pack } from "./pack-io.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;
+import { type PrepareOptions } from "./parts-cdn.js";
+export { DEFAULT_PARTS_CDN, loadPartsIndex, loadParts, mergePacks, prepareModel, type PartsCdnIndex, type LoadPartsOptions, type PrepareOptions, type PreparedModel } from "./parts-cdn.js";
+export interface LoadModelOptions extends LdrObjectOptions, PrepareOptions {
+    /** Run parsing / part inflation / pack merging in a Web Worker (default true when available; ignored with a custom `fetch`). */
+    worker?: boolean;
 }
 export interface LoadedModel extends LdrObject {
     pack: Pack; /** The flattened model (part instances). */
@@ -53,6 +19,7 @@ export interface LoadedModel extends LdrObject {
     };
     requests: number;
     bytes: number;
+    /** Where the prepare step ran. */ ranIn: "worker" | "main";
 }
 /**
  * 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

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/cli.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/cli.ts
 import fs4 from "node:fs";
 import zlib from "node:zlib";
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/node/build-pack.ts
 import fs3 from "node:fs";
 import path3 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/node/resolver.ts
 import fs from "node:fs";
 import path from "node:path";
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/spec.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/spec.ts
 var norm = (s) => s.trim().toLowerCase().replace(/\\/g, "/").replace(/\/+/g, "/");
 function parseColor(tok) {
   if (/^0x/i.test(tok))
@@ -100,6 +100,36 @@ var b64 = (s) => {
     out[i] = bin.charCodeAt(i);
   return out;
 };
+function type1Fast(line) {
+  const n = line.length;
+  let i = 1;
+  const ws = (c) => c === 32 || c === 9;
+  const next = () => {
+    while (i < n && ws(line.charCodeAt(i)))
+      i++;
+    const a = i;
+    while (i < n && !ws(line.charCodeAt(i)))
+      i++;
+    return a < i ? line.slice(a, i) : null;
+  };
+  const ct = next();
+  if (ct === null)
+    return null;
+  const m = new Array(12);
+  for (let k = 0;k < 12; k++) {
+    const t = next();
+    if (t === null)
+      return null;
+    m[k] = +t;
+  }
+  while (i < n && ws(line.charCodeAt(i)))
+    i++;
+  if (i >= n)
+    return null;
+  const rest = line.slice(i);
+  const file = /[ \t]{2,}|\t/.test(rest) ? rest.split(/\s+/).join(" ") : rest;
+  return { t: 1, color: parseColor(ct), m, file: norm(file) };
+}
 function geomLine(tk) {
   const t = +tk[0];
   if (!(t >= 1 && t <= 5) || tk.length < 2)
@@ -168,7 +198,8 @@ function parse(src, name = "main.ldr", popts = {}) {
     } else
       c.tex = top.map;
   };
-  for (const raw of src.split(/\r?\n/)) {
+  for (const raw of src.split(`
+`)) {
     const line = raw.trim();
     if (!line)
       continue;
@@ -219,6 +250,17 @@ function parse(src, name = "main.ldr", popts = {}) {
         continue;
       }
     }
+    if (line.charCodeAt(0) === 49 && (line.charCodeAt(1) === 32 || line.charCodeAt(1) === 9) && !dataCur && !skip) {
+      const g = type1Fast(line);
+      if (g) {
+        if (!cur)
+          start(name);
+        annotate(g, false);
+        cur.cmds.push(g);
+        inHeader = false;
+        continue;
+      }
+    }
     const tk = line.split(/\s+/);
     const t = +tk[0];
     if (t === 0) {
@@ -427,6 +469,7 @@ function transformTexMap(map, m) {
   const x = (q) => [m[3] * q[0] + m[4] * q[1] + m[5] * q[2] + m[0], m[6] * q[0] + m[7] * q[1] + m[8] * q[2] + m[1], m[9] * q[0] + m[10] * q[1] + m[11] * q[2] + m[2]];
   return { ...map, p1: x(map.p1), p2: x(map.p2), p3: x(map.p3) };
 }
+var STUB_OVERRIDES = { "32531.dat": "32531a.dat" };
 function mul(a, b) {
   const [ax, ay, az, a0, a1, a2, a3, a4, a5, a6, a7, a8] = a, [bx, by, bz, b0, b1, b2, b3, b4, b5, b6, b7, b8] = b;
   return [
@@ -662,12 +705,15 @@ function fileStepViews(f) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/model.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/model.ts
+var CALLOUT_END = 999999;
+var stepKey = (steps) => steps.map((x) => String(x).padStart(6, "0")).join(".") + "~";
 function flatten(doc, opts = {}) {
   const out = [];
   const maxDepth = opts.maxDepth ?? 64;
-  const loose = opts.looseGeometry !== false, tx = !!opts.textures;
+  const loose = opts.looseGeometry !== false, tx = !!opts.textures, co = !!opts.callouts;
   const src = new Map;
+  let subs = 0;
   const lazy = (f, k) => {
     const key = f.name + "#" + k;
     let fn = src.get(key);
@@ -678,16 +724,44 @@ function flatten(doc, opts = {}) {
     }
     return fn;
   };
-  const walk = (d, fname, m, color, path, stepPath, depth, texIn) => {
+  const walk = (d, fname, m, color, path, stepPath, depth, texIn, fixed = null, subPath = [], subMats = []) => {
     const f = d.files.get(fname);
     if (!f || depth > maxDepth)
       return;
     let s = 0;
+    const subId = depth > 0 ? ++subs : 0;
+    const sp0 = co && subId ? [...subPath, subId] : subPath;
+    const sm0 = co && subId ? [...subMats, m] : subMats;
+    const groups = co && !fixed ? new Map : null;
+    let ordStep = -1, ord = 0;
+    const sub = (sd, file, mm, col, sp, lt) => {
+      if (ordStep !== s) {
+        ordStep = s;
+        ord = 0;
+      }
+      const g = groups?.get(s + "|" + file);
+      if (g) {
+        g.n++;
+        return walk(sd, sd === d ? file : sd.main, mm, col, path + "/" + file, [...sp, CALLOUT_END], depth + 1, lt, [...sp, CALLOUT_END], sp0, sm0);
+      }
+      const spo = [...sp, ord++], from = out.length;
+      walk(sd, sd === d ? file : sd.main, mm, col, path + "/" + file, spo, depth + 1, lt, fixed, sp0, sm0);
+      groups?.set(s + "|" + file, { n: 1, from, to: out.length });
+    };
     const views = fileStepViews(f);
     const ls = loose ? looseSteps(f) : [];
     let li = 0;
     const emit = (part, col, mm, sp, k, embedded, tex) => {
+      if (fixed)
+        sp = fixed;
       const i = { part, color: col, m: mm, step: sp[0], steps: sp, localStep: k, path };
+      if (subId) {
+        i.sub = subId;
+        if (co) {
+          i.subPath = sp0;
+          i.subMats = sm0;
+        }
+      }
       if (embedded)
         i.embedded = true;
       if (tex) {
@@ -733,7 +807,7 @@ function flatten(doc, opts = {}) {
       const lt = tex && local ? transformTexMap(tex, local) : null;
       if (d.files.has(c.file)) {
         if (fileKind(d, c.file) === "model") {
-          walk(d, c.file, mm, col, path + "/" + c.file, sp, depth + 1, lt);
+          sub(d, c.file, mm, col, sp, lt);
           continue;
         }
         emit(c.file, col, mm, sp, s, true, lt);
@@ -741,12 +815,18 @@ function flatten(doc, opts = {}) {
       }
       const ext = opts.resolveModel?.(c.file);
       if (ext) {
-        walk(ext, ext.main, mm, col, path + "/" + c.file, sp, depth + 1, lt);
+        sub(ext, c.file, mm, col, sp, lt);
         continue;
       }
       emit(c.file, col, mm, sp, s, false, lt);
     }
     flushLoose(Infinity);
+    if (groups) {
+      for (const g of groups.values())
+        if (g.n > 1)
+          for (let j = g.from;j < g.to; j++)
+            out[j].mult ??= g.n;
+    }
   };
   if (fileKind(doc, doc.main) === "part") {
     const f = doc.files.get(doc.main);
@@ -758,10 +838,10 @@ function flatten(doc, opts = {}) {
   return out;
 }
 function parseModel(text, name = "main.ldr", opts) {
-  return flatten(parse(text, name), opts);
+  return flatten(parse(text, name, { geometryText: true }), opts);
 }
 function sequenceSteps(insts) {
-  const key = (i) => i.steps.map((x) => String(x).padStart(6, "0")).join(".");
+  const key = (i) => stepKey(i.steps);
   const uniq = [...new Set(insts.map(key))].sort();
   const rank = new Map(uniq.map((k, j) => [k, j]));
   const stepOf = new Int32Array(insts.length);
@@ -784,7 +864,7 @@ function parseLDConfig(text) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/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();
@@ -854,7 +934,7 @@ class Library {
     return key;
   }
   resolve(ref) {
-    const n = norm2(ref);
+    const n0 = norm2(ref), n = STUB_OVERRIDES[n0] ?? n0;
     if (this.virtual.size && this.virtual.has(n))
       return "mpd/" + n;
     for (const pre of ["parts/", "p/", "models/"])
@@ -1054,11 +1134,11 @@ function collectDeps(lib, refs) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/node/compile.ts
 import fs2 from "node:fs";
 import path2 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/lod.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/node/lod.ts
 import { MeshoptSimplifier, MeshoptEncoder } from "meshoptimizer";
 await Promise.all([MeshoptSimplifier.ready, MeshoptEncoder.ready]);
 function reorderMesh(P, N, C, I) {
@@ -1081,8 +1161,10 @@ function reorderMesh(P, N, C, I) {
   }
   return { P: P2, N: N2, C: C2, I: idx };
 }
-var TARGETS = [0.25, 0.08];
+var TARGETS = [0.25, 0.08, 0.025];
 var MIN_TRIS = 64;
+var MIN_BOX_TRIS = 24;
+var COVERAGE_WEIGHT = Number(process.env.LDR_LOD_COVERAGE ?? 0.5);
 function flatMesh(tris) {
   const map = new Map;
   const P = [], N = [], C = [], I = [];
@@ -1112,9 +1194,62 @@ function flatMesh(tris) {
     }
   return { P: new Float32Array(P), N: new Float32Array(N), C: new Float32Array(C), I: new Uint32Array(I) };
 }
+var G = 64;
+function silhouettes(P, I, box) {
+  const masks = [0, 1, 2].map(() => new Uint8Array(G * G));
+  for (let ax = 0;ax < 3; ax++) {
+    const u = (ax + 1) % 3, v = (ax + 2) % 3;
+    const m = masks[ax];
+    const su = (box.hi[u] - box.lo[u]) / G || 1, sv = (box.hi[v] - box.lo[v]) / G || 1;
+    for (let t = 0;t < I.length; t += 3) {
+      const p = [I[t], I[t + 1], I[t + 2]].map((k) => [(P[k * 3 + u] - box.lo[u]) / su, (P[k * 3 + v] - box.lo[v]) / sv]);
+      const area = (p[1][0] - p[0][0]) * (p[2][1] - p[0][1]) - (p[2][0] - p[0][0]) * (p[1][1] - p[0][1]);
+      if (Math.abs(area) < 0.000000000001)
+        continue;
+      const x0 = Math.max(0, Math.floor(Math.min(p[0][0], p[1][0], p[2][0]))), x1 = Math.min(G - 1, Math.ceil(Math.max(p[0][0], p[1][0], p[2][0])));
+      const y0 = Math.max(0, Math.floor(Math.min(p[0][1], p[1][1], p[2][1]))), y1 = Math.min(G - 1, Math.ceil(Math.max(p[0][1], p[1][1], p[2][1])));
+      for (let y = y0;y <= y1; y++)
+        for (let x = x0;x <= x1; x++) {
+          if (m[y * G + x])
+            continue;
+          const cx = x + 0.5, cy = y + 0.5;
+          let inside = true;
+          for (let e = 0;e < 3 && inside; e++) {
+            const a0 = p[e], a1 = p[(e + 1) % 3];
+            const w = (a1[0] - a0[0]) * (cy - a0[1]) - (cx - a0[0]) * (a1[1] - a0[1]);
+            if (w * area < 0)
+              inside = false;
+          }
+          if (inside)
+            m[y * G + x] = 1;
+        }
+    }
+  }
+  return masks;
+}
+function silhouetteDiff(a, b) {
+  let worst = 0;
+  for (let ax = 0;ax < 3; ax++) {
+    let d = 0;
+    for (let i = 0;i < G * G; i++)
+      d += a[ax][i] ^ b[ax][i];
+    worst = Math.max(worst, d / (G * G));
+  }
+  return worst;
+}
+function boxMesh(box, col) {
+  const [x0, y0, z0] = box.lo, [x1, y1, z1] = box.hi;
+  const c = [[x0, y0, z0], [x1, y0, z0], [x1, y1, z0], [x0, y1, z0], [x0, y0, z1], [x1, y0, z1], [x1, y1, z1], [x0, y1, z1]];
+  const quads = [[0, 3, 2, 1], [4, 5, 6, 7], [0, 1, 5, 4], [3, 7, 6, 2], [0, 4, 7, 3], [1, 2, 6, 5]];
+  const p = new Float32Array(c.flat());
+  const idx = [];
+  for (const q of quads)
+    idx.push(q[0], q[1], q[2], q[0], q[2], q[3]);
+  return flatMesh([{ p, i: Uint32Array.from(idx), col }]);
+}
 function lodChain(P, C, I) {
   const nTris = I.length / 3;
-  if (nTris < MIN_TRIS)
+  if (nTris < MIN_BOX_TRIS)
     return [];
   const groups = new Map;
   for (let t = 0;t < I.length; t += 3) {
@@ -1145,27 +1280,57 @@ function lodChain(P, C, I) {
   });
   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 lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+  for (let v = 0;v < P.length; v += 3)
+    for (let k = 0;k < 3; k++) {
+      lo[k] = Math.min(lo[k], P[v + k]);
+      hi[k] = Math.max(hi[k], P[v + k]);
     }
-    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;
+  const box = { lo, hi };
+  const diag = Math.hypot(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]);
+  const S0 = silhouettes(P, I, box);
+  const coverageErr = (m) => COVERAGE_WEIGHT * silhouetteDiff(S0, silhouettes(m.P, m.I, box)) * diag;
+  for (let li = 0;li < (nTris >= MIN_TRIS ? TARGETS.length : 0); li++) {
+    let best = null;
+    for (const sloppy of [false, true]) {
+      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] = sloppy ? MeshoptSimplifier.simplifySloppy(g.i, g.p, 3, null, target, 1e9) : MeshoptSimplifier.simplify(g.i, g.p, 3, target, 1e9, li ? ["ErrorAbsolute", "Prune"] : ["ErrorAbsolute"]);
+        err = Math.max(err, sloppy ? e * MeshoptSimplifier.getScale(g.p, 3) : 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 || t > prevTris * 0.7)
+        continue;
+      const e = +Math.max(err, coverageErr(m), 0.001).toFixed(3);
+      if (!best || e < best.err)
+        best = { ...m, err: e };
+    }
+    if (best) {
+      out.push(best);
+      prevTris = best.I.length / 3;
+    }
+  }
+  if (prevTris * 0.7 >= 12) {
+    const main = welded.reduce((a, g) => g.i.length > a.i.length ? g : a);
+    const m = boxMesh(box, main.col);
+    let inner = 0;
+    for (let v = 0;v < P.length; v += 3) {
+      let d = Infinity;
+      for (let k = 0;k < 3; k++)
+        d = Math.min(d, P[v + k] - lo[k], hi[k] - P[v + k]);
+      inner = Math.max(inner, d);
+    }
+    out.push({ ...m, err: +Math.max(inner, coverageErr(m) / COVERAGE_WEIGHT, out.length ? out[out.length - 1].err : 0, 0.001).toFixed(3) });
   }
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/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/)) {
@@ -1748,7 +1913,7 @@ function encodePack(parts, studKinds, weld, extra, options = {}) {
   return Buffer.concat([head, ...chunks.map((c) => new Uint8Array(c.buffer, c.byteOffset, c.byteLength))]);
 }
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/node/build-pack.ts
 function buildPack(o) {
   const lib = new Library(o.ldrawRoot);
   const refs = new Map;
@@ -1811,7 +1976,7 @@ function buildPack(o) {
   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 } : {} };
 }
 
-// ../../../../../../../tmp/ldr-build-pIke9r/src/cli.ts
+// ../../../../../../../tmp/ldr-build-zzND7A/src/cli.ts
 var HELP = `ldr pack — build a parts pack for the ldr three.js renderer
 
 Usage:

package/dist/cull.d.ts

@@ -0,0 +1,68 @@
+import type { PartInstance } from './model.js';
+export type Inst = {
+    part: string;
+    color: string;
+    m: number[];
+};
+export declare const upright: (m: ArrayLike<number>, o?: number) => boolean;
+/** Per-part data used by culling and stud placement, prepared once per pack header. */
+export type PrepPart = {
+    nStuds: number;
+    studM: Float64Array;
+    kind: string[];
+    color: string[];
+    mask: Uint8Array | null;
+    nx: number;
+    nz: number;
+};
+export declare function prepPart(H: any, part: string): PrepPart | null;
+/** w = a * b for LDraw 12-number matrices (x y z a b c d e f g h i); same arithmetic as the instance flattener. */
+export declare function mul12To(a: ArrayLike<number>, b: ArrayLike<number>, bo: number, w: Float64Array, ao?: number): void;
+export declare const det12: (m: ArrayLike<number>) => number;
+/** Open-addressing hash table from int32 triples to int32 values (-1 = absent); grows as needed. */
+export declare class Int3Table {
+    a: Int32Array;
+    b: Int32Array;
+    c: Int32Array;
+    vals: Int32Array;
+    used: Uint8Array;
+    mask: number;
+    size: number;
+    constructor(cap?: number);
+    private slot;
+    get(x: number, y: number, z: number): number;
+    /** Sets (x, y, z) -> v and returns the previous value (-1 if none). */
+    put(x: number, y: number, z: number, v: number): number;
+    private grow;
+}
+export declare const inRange: (x: number, y: number, z: number) => boolean;
+/** Culling result in flat arrays. Studs are enumerated in instance order, then each part's `studs` order (the order `forEachStud` visits). */
+export type CullResult = {
+    nStuds: number;
+    studHidden: Uint8Array;
+    studUp: Uint8Array;
+    underHidden: Uint8Array;
+    studsHidden: number;
+    /** With `steps`: the first build step at which each stud / underside is hidden (STEP_NEVER = never), for step-aware culling. */
+    studHideStep?: Int32Array;
+    underHideStep?: Int32Array;
+};
+/** `studHideStep` / `underHideStep` value for "never hidden". */
+export declare const STEP_NEVER = 2147483647;
+/** Visit every stud (instance order, then part stud order) with its world matrix `w` (scratch; copy to keep). */
+export declare function forEachStud(insts: Inst[], H: any, fn: (j: number, inst: number, w: Float64Array, kind: string, color: string, stud: number) => void): void;
+/** `steps` (optional, per instance): also compute when each stud / underside becomes hidden as the model is built step by step. */
+export declare function cullCore(insts: Inst[], H: any, steps?: ArrayLike<number>): CullResult;
+/** Scene instances and per-instance step ranks as `createLdrObject` builds them (shared with the load worker). */
+export declare function sceneInstances(instances: PartInstance[], H: any, useTex: boolean): {
+    all: {
+        part: string;
+        color: string;
+        m: import("./spec.js").M;
+        steps: number[];
+    }[];
+    stepOf: number[];
+    nSteps: number;
+};
+/** Culling for `createLdrObject(instances, pack, { textures })`, computable off the main thread and passed back as `precomputedCull`. */
+export declare function precomputeCull(instances: PartInstance[], H: any, useTex?: boolean): CullResult;

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export { parse, parseColor, isDirectColor, mul, I as IDENTITY, norm, smoothNormals, parseTexMap, texmapUV, texmapTriangleUV, transformTexMap, resolveTexture, fileKind, looseSteps, looseSource, looseFile, loosePartName, texWrapper, invert, hash32, colorToken, rotStepMatrix, stepViewMatrix, fileStepViews } from "./spec.js";
 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 { flatten, parseModel, sequenceSteps, stepKey, parseLDConfig, CALLOUT_END } from "./model.js";
+export { planStepViews, isolateMask, viewDir, instanceBoxes, MIN_VIS, REORIENT } from "./instructions.js";
+export type { StepCameraView, StepCameraOptions, Vec3 } from "./instructions.js";
 export type { PartInstance, FlattenOptions, LDrawColor } from "./model.js";
-export { loadPack, decodePack, buildLdrScene, makeMaterial, createInstancedEdges, computeCulling, cullCore, forEachStud, conditionalLines, createInstancedConditionalEdges, conditionalLineVisible } from "./render.js";
+export { loadPack, decodePack, buildLdrScene, makeMaterial, createInstancedEdges, computeCulling, cullCore, forEachStud, conditionalLines, createInstancedConditionalEdges, conditionalLineVisible, warmPackGeometry } from "./render.js";
+export { precomputeCull, sceneInstances } from "./cull.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";
+export { loadModel, loadParts, loadPartsIndex, mergePacks, prepareModel, DEFAULT_PARTS_CDN } from "./cdn.js";
+export type { LoadModelOptions, LoadedModel, LoadPartsOptions, PartsCdnIndex, PrepareOptions, PreparedModel } from "./cdn.js";