ldr 0.29.1 → 0.31.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 12 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 a fleet of 75 UCS Millennium Falcons (394,950 bricks) from 205 ms to 29 ms per frame, and its load time from 2.4 s to 1.0 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`.
@@ -83,7 +83,7 @@ Light the scene (or set `scene.environment`) as you would for any `MeshStandardM
 | export | description |
 |---|---|
 | `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. `colour` (an `LDrawColor`) is set when a `0 !COLOUR` line in the model itself defines the instance's colour. |
+| `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. `colour` (an `LDrawColor`) is set when a `0 !COLOUR` line in the model itself defines the instance's colour. `colPart` / `colSource` name the part with the model's definitions in scope applied inside it (a synthetic part, `<part>#col-<hash>`; packs from `buildPack` have it only when it changes a colour, and the renderer falls back to `part`). |
 | `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, luminance, finish }` (CHROME / PEARLESCENT / RUBBER / METAL / MATTE_METALLIC / MATERIAL GLITTER|SPECKLE|FABRIC). |
@@ -178,29 +178,31 @@ All numbers below were measured with the harness in [`bench/`](https://github.co
 - **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.
+- **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.
 - **ldr settings:** the defaults: LOD pack, distance LOD, low-detail studs, stud and underside culling, single-sided faces, no edges.
 
-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.
+Sources: `bench/results/2026-10-18T18-10-46-518Z-falcon-vs-stock.md` (the Falcon rows), `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 | **2.7 ms** | 0.2 s | 0.3 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** |
+| Millennium Falcon ×2 | 10,532 | 8.0 ms | 8.2 ms | 1.98 s | **0.14 s** |
+| Millennium Falcon ×19 | 100,054 | 54.2 ms | **19.6 ms** | 2.04 s | **0.38 s** |
+| Millennium Falcon ×75 | 394,950 | 204.7 ms | **29.2 ms** | 2.40 s | **1.03 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 (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é).
+The benchmark model is a fleet: the LDraw OMR model of set 10179 (UCS Millennium Falcon, 5,266 parts, 251 unique) placed 2, 19 or 75 times on a grid (`apps/demo-site/scripts/build-fleet.ts`). It is a hard case for ldr: dense, detailed ships stay large on screen, so distance LOD can't drop much and the overview still draws ~32M triangles; on two ships ldr only matches stock instancing per frame (it still loads 14× faster). Datsville, the benchmark until Round 60 (a flat town, 392,514 bricks, mostly baseplates), went from 409.6 to 12.5 ms per frame and 24.7 to 1.6 s load.
 
-- **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.
+How much each optimization contributed on Datsville 100k (Rounds 1–20, before the Falcon fleets), 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:** the Falcon fleet (251 unique parts) is 24.5 MB raw and **1.65 MB zstd** with LOD meshes, at any number of ships. 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.
 - **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 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).
+- **Conditional lines** (opt-in `cond` packs) cost **+12–14 %** frame time on Datsville 10k and 100k (M4 Pro, before Round 60), and add 7–14 % to the zstd pack size.
+- **Edges:** with LOD, edges take the Falcon fleet from 19.8 → 42.2 ms (19 ships) and 29.4 → 56.3 ms (75 ships). Each cluster draws only edge segments at least 0.15 px long (`lodEdgeMinPx`) and none where bricks are sub-pixel (`lodEdgePx`), which saves little on ships that fill the screen. Far views drawn with edges get lighter (≤ 4.7% of pixels on Datsville overviews, 0.27% on the fleet); `lodEdgeMinPx: 0, lodEdgePx: 0` keeps every edge.
+- **Build steps:** `setStep` takes 39 ms on the 19-ship fleet (26,619 steps); on Datsville 100k it went from a full rebuild (752 ms) to 66 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)).
@@ -213,7 +215,7 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 - `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), `GLOSSMAP` (alpha = gloss amount, same UVs), and model-level `!TEXMAP` around part references.
 - Colours: LDConfig `!COLOUR`, edge colours, main/edge colour inheritance (16/24), and direct colours (`0x2RRGGBB`).
-- `!COLOUR` lines in a model follow the spec's scope rule. A definition applies from its line to the end of its file and to the files that file references, and it never leaks back to the parent. It sets the instance colour and finish. `!COLOUR` lines inside a part (an MPD-embedded part and its subparts) follow the same rule when the part is compiled, and a model file's own loose geometry sees that file's definitions: its triangles and studs take the part's own definitions (RGB; baked part colours are opaque, as for LDConfig codes). A model's definitions don't reach the colours hard-coded inside the parts it places: those come from LDConfig or the part's own definitions, because parts are precompiled.
+- `!COLOUR` lines in a model follow the spec's scope rule. A definition applies from its line to the end of its file and to the files that file references, and it never leaks back to the parent. It sets the instance colour and finish. `!COLOUR` lines inside a part (an MPD-embedded part and its subparts) follow the same rule when the part is compiled, and a model file's own loose geometry sees that file's definitions: its triangles and studs take the part's own definitions (RGB; baked part colours are opaque, as for LDConfig codes). A model's definitions also reach the colours hard-coded inside the parts it places ("passed to subfiles"): `buildPack` compiles a variant of such a part with those definitions applied (only where one changes a colour the part uses), and the renderer draws it; the part's own later definitions still win inside it. Parts from the hosted parts CDN (`loadModel` / `prepareModel`) don't have these variants yet, so there the colours inside parts come from LDConfig or the part's own definitions.
 - Named colour codes: a `!COLOUR` CODE may be an identifier instead of a number (`0 !COLOUR My_Red CODE MyRed VALUE #FF0000 EDGE #333333`, then `1 myred ...`), which the spec allows outside strict LDraw compatibility. Identifiers are case-insensitive and follow the same scope rule. `parseColor` turns one into a stable negative code (`namedColorCode`, `isNamedColor`), and `colorToken` turns it back into the identifier. A named code with no definition in scope draws the fallback colour.
 - Blended colour codes 256-511 that LDConfig doesn't define (used by old models, e.g. 382 in Datsville) render as the spec's average of two ldraw.exe colours instead of the fallback grey.
 - Case-insensitive, backslash-normalized file lookup; `~Moved to` alias parts.
@@ -221,7 +223,7 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 ## Limitations
 
 - **Finishes:** `!COLOUR` CHROME / PEARLESCENT / RUBBER / METAL / MATTE_METALLIC map to MeshStandard/Physical PBR (same numbers as three.js `LDrawLoader`). MATERIAL GLITTER / SPECKLE use a procedural grain approximation; FABRIC uses sheen. ALPHA sets opacity; LUMINANCE drives emissive.
-- **Transparency:** transparent colours (`ALPHA < 255`) render with opacity and `depthWrite: false` (one material bucket per finish × opacity class).
+- **Transparency:** transparent colours (`ALPHA < 255`) render with their opacity and `depthWrite: false` (one material bucket per finish × opacity class), from `ldr pack` packs and, since 0.31, from the parts CDN (`loadModel`), whose index now carries the colour materials. Studs and undersides behind a transparent part are never culled. Transparent batches are sorted per batch (InstancedMesh), not per instance or triangle, so overlapping transparent parts can blend in the wrong order.
 - **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; `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`.
@@ -232,5 +234,5 @@ Reproduce: `cd bench && bun run setup && bun run perf` (regression gate) or `bun
 
 - **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.
+- **Millennium Falcon:** the benchmark fleets place the [LDraw OMR model of set 10179](https://library.ldraw.org/omr/sets/320) by Roland Dahl [RolandD] (CC BY 2.0) N times.
 - **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/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/cli.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/cli.ts
 import fs4 from "node:fs";
 import zlib from "node:zlib";
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/node/build-pack.ts
 import fs3 from "node:fs";
 import path3 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/node/resolver.ts
 import fs from "node:fs";
 import path from "node:path";
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/spec.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/spec.ts
 var norm = (s) => s.trim().toLowerCase().replace(/\\/g, "/").replace(/\/+/g, "/");
 var COLOUR_ID_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 var namedCodes = new Map;
@@ -723,9 +723,35 @@ function fileStepViews(f) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/model.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/model.ts
 var CALLOUT_END = 999999;
 var stepKey = (steps) => steps.map((x) => String(x).padStart(6, "0")).join(".") + "~";
+var defLine = new WeakMap;
+var wrapMemo = new WeakMap;
+function scopeWrapper(part, scope) {
+  let w = wrapMemo.get(scope);
+  if (!w) {
+    const lines = [...scope.values()].map((d) => {
+      const t = defLine.get(d) ?? "";
+      const k = t.indexOf("!COLOUR");
+      return k < 0 ? "" : "0 " + t.slice(k).trim().replace(/\s+/g, " ");
+    }).filter(Boolean);
+    w = { head: lines.join(`
+`), parts: new Map };
+    wrapMemo.set(scope, w);
+  }
+  let r = w.parts.get(part);
+  if (!r) {
+    const n = norm(part), source = `0 ldr: ${n} placed in a model's !COLOUR scope
+0 BFC CERTIFY CCW
+${w.head}
+1 16 0 0 0 1 0 0 0 1 0 0 0 1 ${n}
+`;
+    r = { name: `${n}#col-${hash32(source)}`, source };
+    w.parts.set(part, r);
+  }
+  return r;
+}
 function flatten(doc, opts = {}) {
   const out = [];
   const maxDepth = opts.maxDepth ?? 64;
@@ -770,7 +796,7 @@ function flatten(doc, opts = {}) {
     const views = fileStepViews(f);
     const ls = loose ? looseSteps(f) : [];
     let li = 0;
-    const emit = (part, col, mm, sp, k, embedded, tex, cd) => {
+    const emit = (part, col, mm, sp, k, embedded, tex, cd, sc) => {
       if (fixed)
         sp = fixed;
       const i = { part, color: col, m: mm, step: sp[0], steps: sp, localStep: k, path };
@@ -789,6 +815,10 @@ function flatten(doc, opts = {}) {
         const w = texWrapper(part, tex);
         i.texPart = w.name;
         i.texSource = w.source;
+      } else if (sc) {
+        const w = scopeWrapper(part, sc);
+        i.colPart = w.name;
+        i.colSource = w.source;
       }
       const v = views[k];
       if (v)
@@ -799,7 +829,7 @@ function flatten(doc, opts = {}) {
     const flushLoose = (upTo) => {
       while (li < ls.length && ls[li] <= upTo) {
         const k = ls[li++];
-        emit(loosePartName(f.name, k), color, m, [...stepPath, k], k, false, null, colour).source = lazy(f, k);
+        emit(loosePartName(f.name, k), color, m, [...stepPath, k], k, false, null, colour, scope0).source = lazy(f, k);
       }
     };
     for (const c0 of f.cmds) {
@@ -815,8 +845,10 @@ function flatten(doc, opts = {}) {
       if (c.t === 0) {
         if (c.meta === "!COLOUR") {
           const def = parseColourLine(c.text);
-          if (def && def.code !== 16 && def.code !== 24)
+          if (def && def.code !== 16 && def.code !== 24) {
+            defLine.set(def, c.text);
             (scope = new Map(scope ?? [])).set(def.code, def);
+          }
           continue;
         }
         if (tx && c.geom?.t === 1)
@@ -837,7 +869,7 @@ function flatten(doc, opts = {}) {
           sub(d, c.file, mm, col, sp, lt, cd);
           continue;
         }
-        emit(c.file, col, mm, sp, s, true, lt, cd);
+        emit(c.file, col, mm, sp, s, true, lt, cd, scope);
         continue;
       }
       const ext = opts.resolveModel?.(c.file);
@@ -845,7 +877,7 @@ function flatten(doc, opts = {}) {
         sub(ext, c.file, mm, col, sp, lt, cd);
         continue;
       }
-      emit(c.file, col, mm, sp, s, false, lt, cd);
+      emit(c.file, col, mm, sp, s, false, lt, cd, scope);
     }
     flushLoose(Infinity);
     if (groups) {
@@ -1106,7 +1138,7 @@ function blendedColourHex(code) {
   return "#" + [0, 1, 2].map((k) => (a[k] + b[k] >> 1).toString(16).padStart(2, "0")).join("").toUpperCase();
 }
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/node/resolver.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/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();
@@ -1192,6 +1224,53 @@ class Library {
   isPart(key) {
     return key.startsWith("parts/") && !key.startsWith("parts/s/");
   }
+  #codes = new Map;
+  #ldconfig;
+  colourCodes(key) {
+    let s = this.#codes.get(key);
+    if (s)
+      return s;
+    s = new Set;
+    this.#codes.set(key, s);
+    for (const line of this.read(key).split(/\r?\n/)) {
+      const t = line.trim(), c = t[0];
+      if (c !== "1" && c !== "3" && c !== "4")
+        continue;
+      const tok = t.split(/\s+/);
+      if (tok.length < 2)
+        continue;
+      const code = parseColor(tok[1]);
+      if (code !== 16 && code !== 24 && !Number.isNaN(code))
+        s.add(code);
+      if (c === "1") {
+        const r = parseType1(t);
+        const ck = r && this.resolve(r.name);
+        if (ck)
+          for (const x of this.colourCodes(ck))
+            s.add(x);
+      }
+    }
+    return s;
+  }
+  scopeChanges(key, wrapperSource) {
+    if (!this.#ldconfig) {
+      const f = path.join(this.root, "LDConfig.ldr");
+      this.#ldconfig = fs.existsSync(f) ? parseLDConfig(fs.readFileSync(f, "latin1")) : new Map;
+    }
+    const used = this.colourCodes(key);
+    for (const line of wrapperSource.split(`
+`)) {
+      if (!line.startsWith("0 !COLOUR"))
+        continue;
+      const d = parseColourLine(line);
+      if (!d || !used.has(d.code))
+        continue;
+      const g = this.#ldconfig.get(d.code);
+      if (!g || g.hex.toUpperCase() !== d.hex.toUpperCase())
+        return true;
+    }
+    return false;
+  }
   fileStats(key) {
     if (this.stats.has(key))
       return this.stats.get(key);
@@ -1331,6 +1410,7 @@ function flatten2(model, lib, onInstance, opts = {}) {
     lib.addVirtual(n, t);
   const doc = modelDoc(model);
   const at = new Map;
+  const changes = new Map;
   for (const i of flatten(doc, opts)) {
     let key;
     if (i.embedded)
@@ -1351,6 +1431,15 @@ function flatten2(model, lib, onInstance, opts = {}) {
       r.texRef = i.texPart;
       r.texPart = lib.addVirtual(i.texPart, i.texSource);
     }
+    if (i.colPart) {
+      let ch = changes.get(i.colPart);
+      if (ch === undefined)
+        changes.set(i.colPart, ch = lib.scopeChanges(key, i.colSource));
+      if (ch) {
+        r.colRef = i.colPart;
+        r.colPart = lib.addVirtual(i.colPart, i.colSource);
+      }
+    }
     onInstance(r);
   }
   return { missing };
@@ -1376,11 +1465,11 @@ function collectDeps(lib, refs) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/node/compile.ts
 import fs2 from "node:fs";
 import path2 from "node:path";
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/node/lod.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/node/lod.ts
 import { MeshoptSimplifier, MeshoptEncoder } from "meshoptimizer";
 await Promise.all([MeshoptSimplifier.ready, MeshoptEncoder.ready]);
 function reorderMesh(P, N, C, I) {
@@ -1572,7 +1661,7 @@ function lodChain(P, C, I) {
   return out;
 }
 
-// ../../../../../../../tmp/ldr-build-Fyp0fs/src/node/compile.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/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/)) {
@@ -2287,7 +2376,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-Fyp0fs/src/node/build-pack.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/node/build-pack.ts
 function packCompilerOpts(o) {
   return { studs: o.studs ?? "low", prims: o.primitives ?? "full", weld: o.weld ?? true, separateStuds: true, cond: !!o.cond, tex: !!o.textures };
 }
@@ -2307,6 +2396,8 @@ function buildPack(o) {
         refs.set(i.ref, i.part);
         if (i.texRef)
           refs.set(i.texRef, i.texPart);
+        if (i.colRef)
+          refs.set(i.colRef, i.colPart);
       }, { textures, looseGeometry: o.looseGeometry });
       for (const k of r.missing.keys())
         missing.add(k);
@@ -2358,7 +2449,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-Fyp0fs/src/cli.ts
+// ../../../../../../../tmp/ldr-build-dLNbNv/src/cli.ts
 var HELP = `ldr pack — build a parts pack for the ldr three.js renderer
 
 Usage:

package/dist/cull.d.ts

@@ -51,7 +51,8 @@ export type CullResult = {
 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. */
+/** `steps` (optional, per instance): also compute when each stud / underside becomes hidden as the model is built step by step.
+ *  Transparent instances hide nothing (studs inside their hollow stay visible through them) and keep their own undersides. */
 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): {