@chestnutlabs/gcode-model-renderer 0.6.0 → 0.8.1

package/README.md

@@ -0,0 +1,61 @@
+# @chestnutlabs/gcode-model-renderer
+
+Three.js **presentation** renderer for source models — draws an `.stl` or `.3mf` mesh as a clean,
+studio-lit thumbnail. It answers *"what object is this?"*, and is deliberately **separate** from the
+toolpath renderer, which answers *"how does this print/cut run?"* (design: DD-018).
+
+> **Peer dependency:** `three` (supported range `^0.178.0`) — install it alongside this package.
+
+![Two presentation thumbnails: a neutral gray STL part (materials: unavailable) beside a red/amber/green three-object 3MF (materials: known)](https://raw.githubusercontent.com/ChestnutLabs/gcode-preview/dev/docs/media/model-render-stl-3mf.png)
+
+Use it for file-browser thumbnails, library cards, and "what's in this file" previews — the picture a
+slicer shows of a part, not the toolpath. For inspecting the actual moves (layers, travel, seams,
+color modes, live progress), use [`@chestnutlabs/gcode-renderer-three`](../gcode-renderer-three)
+instead.
+
+- **STL and 3MF** — a bare STL is a single object with no declared material; a 3MF brings its own
+  multi-object structure, per-object transforms, and per-object / per-triangle material colors,
+  including files that use the 3MF **Production Extension** (`p:path` external parts).
+- **Production multicolor** — real Bambu Studio / OrcaSlicer files paint per-region color with a
+  proprietary `paint_color` facet attribute and keep the palette in `project_settings.config`, not in
+  standard 3MF materials. The renderer decodes that facet-paint format (clean-room, see
+  [RR-005](../../docs/research/RR-005-3mf-paint-color-facet-format.md)) and reads the `filament_colour`
+  palette itself, so a designer's multicolor model renders in its true colors without slicing.
+- **Capability-honest color** — when the source declares colors — standard 3MF `basematerials`, or
+  `paint_color` + a filament palette — the render uses them and reports `materials: 'known'`
+  (`'approximated'` when a handful of multi-color facets are flattened). When it declares none — a
+  plain STL, or a paint format with no palette present — it draws a neutral default and reports
+  `materials: 'unavailable'`. It never invents a source color.
+- **Fixed presentation pose** — framed at a 3/4 angle on the shared render "stage" from
+  `@chestnutlabs/gcode-renderer-three`, under a neutral studio light rig, on a transparent (default)
+  or solid background you can composite onto a card.
+- **Headless still** — `renderModelStill` mirrors the toolpath side's `renderStill`: hand it bytes,
+  get back a canvas plus a stable `cacheKey` and the `materials` confidence for that render. Runs in
+  any Chromium-class WebGL2 context (an `OffscreenCanvas` in a Worker, or headless Chromium).
+- **Three-free public types** — `ModelScene` / `ModelObject` / `MeshGeometry` are plain typed arrays,
+  so the package's surface never leaks `three`; the renderer builds three meshes internally.
+
+```ts
+import { renderModelStill } from '@chestnutlabs/gcode-model-renderer';
+
+// In a Worker with an OffscreenCanvas, or headless Chromium:
+const { canvas, objectCount, materials, cacheKey } = await renderModelStill(
+  { kind: '3mf', bytes },                        // or { kind: 'stl', bytes }
+  { canvas: new OffscreenCanvas(512, 512), background: 'transparent' }
+);
+// materials === 'known'  → the render used colors the file declared
+// materials === 'unavailable' → the file carried none; a neutral default was used (never faked)
+const blob = await canvas.convertToBlob();
+```
+
+Already hold a corrected or richer filament palette (e.g. re-rendering a sliced file)? Pass
+`filamentPalette` (hex per 0-based slot) to `renderModelStill` / `parse3mf` to override the one read
+from `project_settings.config`. Optional — the renderer reads the file's own palette without it.
+
+Want to build your own scene or drive the renderer interactively? `parseStl` / `parse3mf` return a
+three-free `ModelScene`, and `ModelRenderer` renders one onto a canvas you own.
+
+Determinism: same input + same environment ⇒ identical output. Cross-GPU/driver pixel identity is not
+promised — cache by the returned `cacheKey`.
+
+Part of [Chestnut Labs G-code Preview](../../README.md) · MIT

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { renderModelStill } from './render-model-still.js';
 export type { ModelSource, RenderModelStillOptions, RenderModelStillResult } from './render-model-still.js';
 export { parseStl } from './stl.js';
 export { parse3mf } from './three-mf.js';
+export type { Parse3mfOptions } from './three-mf.js';
 export { computeCacheKey, defaultEnvId } from './cache-key.js';
 export { DEFAULT_LIMITS, resolveLimits, ModelParseError } from './limits.js';
 export type { ModelLimits, ResolvedLimits } from './limits.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACnG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/render-model-still.d.ts

@@ -33,6 +33,12 @@ export interface RenderModelStillOptions {
     view?: PresentationView;
     createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
     limits?: ModelLimits;
+    /**
+     * Override the 3MF source-model filament palette (hex `#RRGGBB` per 0-based slot) used to colour
+     * `paint_color` facets, instead of the file's own `project_settings.config`. Niche: for consumers
+     * re-rendering a file with a corrected/richer palette. Ignored for STL and pre-built scenes.
+     */
+    filamentPalette?: readonly (string | undefined)[];
     /** Override the environment id folded into the cache key (default: the `three` revision). */
     envId?: string;
 }

package/dist/render-model-still.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-model-still.d.ts","sourceRoot":"","sources":["../src/render-model-still.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,yEAAyE;AACzE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD,UAAU,CAAC;AAEf,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,qCAAqC;IACrC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,SAAS,EAAE,UAAU,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAoBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAiCjC"}
+{"version":3,"file":"render-model-still.d.ts","sourceRoot":"","sources":["../src/render-model-still.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,yEAAyE;AACzE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAChD,UAAU,CAAC;AAEf,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,qCAAqC;IACrC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAClD,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,sGAAsG;IACtG,SAAS,EAAE,UAAU,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAqBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAiCjC"}

package/dist/render-model-still.js

@@ -5,14 +5,14 @@ import { computeCacheKey } from './cache-key.js';
 function isModelScene(s) {
     return s.objects !== undefined && s.kind === undefined;
 }
-async function toScene(source, limits) {
+async function toScene(source, limits, filamentPalette) {
     if (isModelScene(source)) {
         // No raw bytes for a pre-built scene: key off a stable structural summary instead.
         const summary = JSON.stringify({ n: source.objects.length, b: source.bounds, c: source.capabilities });
         return { scene: source, sourceBytes: new TextEncoder().encode(summary) };
     }
     const bytes = source.bytes instanceof Uint8Array ? source.bytes : new Uint8Array(source.bytes);
-    const scene = source.kind === '3mf' ? await parse3mf(bytes, limits) : parseStl(bytes, limits);
+    const scene = source.kind === '3mf' ? await parse3mf(bytes, limits, { filamentPalette }) : parseStl(bytes, limits);
     return { scene, sourceBytes: bytes };
 }
 /**
@@ -26,7 +26,7 @@ export async function renderModelStill(source, options) {
     const height = options.height ?? canvas.height;
     const background = options.background ?? 'transparent';
     const view = options.view ?? 'iso';
-    const { scene, sourceBytes } = await toScene(source, options.limits);
+    const { scene, sourceBytes } = await toScene(source, options.limits, options.filamentPalette);
     const renderer = new ModelRenderer({
         canvas,
         background,
@@ -37,7 +37,7 @@ export async function renderModelStill(source, options) {
         renderer.resize(width, height);
         renderer.setScene(scene);
         renderer.render();
-        const optionsJson = JSON.stringify({ width, height, background, view });
+        const optionsJson = JSON.stringify({ width, height, background, view, palette: options.filamentPalette });
         const cacheKey = computeCacheKey(sourceBytes, optionsJson, options.envId);
         return {
             canvas,

package/dist/three-mf.d.ts

@@ -1,5 +1,13 @@
 import { type ModelScene } from './scene-model.js';
 import { type ModelLimits } from './limits.js';
-/** Parse 3MF bytes into a {@link ModelScene}. Rejects with {@link ModelParseError} on failure. */
-export declare function parse3mf(source: Uint8Array | ArrayBuffer, limits?: ModelLimits): Promise<ModelScene>;
+export interface Parse3mfOptions {
+    /**
+     * Override the source-model filament palette (hex `#RRGGBB` per 0-based slot) used to colour
+     * `paint_color` facets, instead of reading it from `project_settings.config`. For consumers that
+     * already hold a corrected/richer palette (e.g. re-rendering a sliced `.gcode.3mf`). Ignored when
+     * empty; the file's own palette is still read.
+     */
+    filamentPalette?: readonly (string | undefined)[];
+}
+export declare function parse3mf(source: Uint8Array | ArrayBuffer, limits?: ModelLimits, opts?: Parse3mfOptions): Promise<ModelScene>;
 //# sourceMappingURL=three-mf.d.ts.map

package/dist/three-mf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"three-mf.d.ts","sourceRoot":"","sources":["../src/three-mf.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkC,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAyE/E,kGAAkG;AAClG,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAoG1G"}
+{"version":3,"file":"three-mf.d.ts","sourceRoot":"","sources":["../src/three-mf.ts"],"names":[],"mappings":"AAqBA,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkC,KAAK,WAAW,EAAuB,MAAM,aAAa,CAAC;AA4VpG,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACnD;AAKD,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,UAAU,GAAG,WAAW,EAChC,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,UAAU,CAAC,CAwJrB"}

package/dist/three-mf.js

@@ -1,16 +1,18 @@
 /**
- * 3MF → {@link ModelScene} (DD-018 Phase 2). Multi-object, per-object/per-triangle **solid** colors,
- * build-item transforms — a multicolor model becomes a multicolor thumbnail without slicing.
+ * 3MF → {@link ModelScene} (DD-018 Phase 2, + production-extension follow-up). Multi-object,
+ * per-object/per-triangle **solid** colors, build-item transforms, and the **3MF Production Extension**
+ * (Bambu/MakerWorld default): `<components>` whose `<component p:path=…>` reference external
+ * `/3D/Objects/*.model` parts. A multicolor model becomes a multicolor thumbnail without slicing.
  *
  * 3MF is an OPC (ZIP) package; the ZIP is opened with the hardened, zero-dep reader from
- * `@chestnutlabs/gcode-containers` (DD-005 §7 — zip-bomb / traversal / size caps reused verbatim). The
- * 3D model part is a small XML document parsed here with a minimal, worker-safe scan (no `DOMParser`,
- * which Web Workers lack; no dependency). Only the subset needed for a presentation render is read:
+ * `@chestnutlabs/gcode-containers` (DD-005 §7 — zip-bomb / traversal / size caps reused verbatim). Each
+ * model part is a small XML document parsed with a minimal, worker-safe scan (no `DOMParser`, which Web
+ * Workers lack; no dependency). Only the subset needed for a presentation render is read:
  * `<vertices>/<triangles>`, object/triangle material refs, `<basematerials>`/`<m:colorgroup>` palettes,
- * and `<build><item>` transforms. Textures and non-color material properties are ignored (disclosed via
- * capability honesty), never fetched (no network).
+ * `<components><component>` (with `p:path`), and `<build><item>` transforms. Textures and non-color
+ * material properties are ignored (disclosed via capability honesty), never fetched (no network).
  */
-import { readDirectory, extractEntry, DEFAULT_CONTAINER_LIMITS } from '@chestnutlabs/gcode-containers';
+import { readDirectory, extractEntry, filamentColoursFromSettings, DEFAULT_CONTAINER_LIMITS } from '@chestnutlabs/gcode-containers';
 import { IDENTITY_MAT4 } from './scene-model.js';
 import { ModelParseError, resolveLimits } from './limits.js';
 /** millimeter is the 3MF default; convert others to mm. */
@@ -22,6 +24,8 @@ const UNIT_TO_MM = {
     inch: 25.4,
     foot: 304.8
 };
+/** Max component-resolution depth (guards cyclic / pathological assemblies). */
+const MAX_DEPTH = 50;
 const TAG_RE = /<(\/?)([\w:.-]+)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
 const ATTR_RE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
 function localName(tag) {
@@ -52,48 +56,100 @@ function srgbHexToLinear(hex) {
     const b = to(4);
     return Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) ? null : [r, g, b];
 }
-async function findModelXml(bytes) {
-    const limits = DEFAULT_CONTAINER_LIMITS;
-    const dir = readDirectory(bytes, limits);
-    // Prefer the conventional path, then the OPC-declared StartPart, then any *.model.
-    const byName = (pred) => dir.entries.find((e) => pred(e.name.toLowerCase()));
-    let entry = byName((n) => n === '3d/3dmodel.model');
-    if (entry === undefined) {
-        const rels = byName((n) => n === '_rels/.rels');
-        if (rels !== undefined) {
-            const relXml = new TextDecoder().decode(await extractEntry(bytes, rels, limits.maxMetadataBytes));
-            const target = /Target="\/?([^"]+\.model)"/i.exec(relXml)?.[1];
-            if (target !== undefined)
-                entry = byName((n) => n === target.toLowerCase());
-        }
-    }
-    if (entry === undefined)
-        entry = byName((n) => n.endsWith('.model'));
-    if (entry === undefined)
-        throw new ModelParseError('E_MODEL_PARSE', '3MF contains no 3D model part');
-    return extractEntry(bytes, entry, limits.maxExpandedBytesPerEntry);
-}
-/** Parse 3MF bytes into a {@link ModelScene}. Rejects with {@link ModelParseError} on failure. */
-export async function parse3mf(source, limits) {
-    const lim = resolveLimits(limits);
-    const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
-    if (bytes.byteLength === 0)
-        throw new ModelParseError('E_MODEL_EMPTY', '3MF source is empty');
-    if (bytes.byteLength > lim.maxSourceBytes) {
-        throw new ModelParseError('E_MODEL_TOO_LARGE', `3MF source ${bytes.byteLength} bytes exceeds limit ${lim.maxSourceBytes}`);
+/**
+ * Decode a Bambu/Orca `paint_color` facet-paint attribute (clean-room from the observed format —
+ * see RR-005, NOT from Orca/PrusaSlicer GPL source). The value is a **little-endian** stream of 4-bit
+ * nibble tokens forming a recursive triangle-split tree:
+ *
+ * - `token & 0b11` = split-sides: `0` ⇒ a **leaf**, otherwise the triangle is split into
+ *   `split_sides + 1` children (2/3/4) that follow, decoded depth-first (`token >> 2` is the split
+ *   side — irrelevant to a presentation render).
+ * - a leaf's state is `token >> 2`, with `3` escaping into the following nibble (`3 + next`).
+ *
+ * **State 0 = the object's default extruder (unpainted); state s ≥ 1 = filament index s − 1.**
+ * Returns the dominant leaf state plus whether the facet was subdivided (so the caller can flatten it
+ * to one colour and disclose `approximated`), or `null` if the value is malformed/truncated.
+ */
+function decodePaintState(hex) {
+    const clean = hex.trim();
+    if (clean.length === 0)
+        return null;
+    const nibbles = [];
+    for (let i = clean.length - 1; i >= 0; i--) {
+        const n = parseInt(clean[i], 16);
+        if (Number.isNaN(n))
+            return null;
+        nibbles.push(n);
     }
-    let xml;
+    let pos = 0;
+    const states = [];
+    const next = () => {
+        if (pos >= nibbles.length)
+            throw new ModelParseError('E_MODEL_PARSE', 'paint_color underflow');
+        return nibbles[pos++];
+    };
+    const node = (depth) => {
+        if (depth > 16)
+            throw new ModelParseError('E_MODEL_PARSE', 'paint_color too deep');
+        const t = next();
+        const ss = t & 0b11;
+        if (ss === 0) {
+            const s2 = t >> 2;
+            states.push(s2 === 3 ? 3 + next() : s2);
+        }
+        else {
+            for (let i = 0; i <= ss; i++)
+                node(depth + 1);
+        }
+    };
     try {
-        xml = new TextDecoder().decode(await findModelXml(bytes));
+        node(0);
     }
-    catch (e) {
-        if (e instanceof ModelParseError)
-            throw e;
-        throw new ModelParseError('E_MODEL_PARSE', `3MF unzip failed: ${e.message}`);
+    catch {
+        return null;
     }
-    // Single scan over the model XML.
+    if (states.length === 0)
+        return null;
+    // Dominant leaf state — subdivided facets are a tiny fraction of any real model, so flattening them
+    // to their most-common state (and reporting `approximated`) is a faithful presentation trade-off.
+    const counts = new Map();
+    let best = states[0];
+    let bestN = 0;
+    for (const s of states) {
+        const c = (counts.get(s) ?? 0) + 1;
+        counts.set(s, c);
+        if (c > bestN) {
+            bestN = c;
+            best = s;
+        }
+    }
+    return { state: best, subdivided: states.length > 1 };
+}
+function parseTransform(s) {
+    if (s === undefined)
+        return null;
+    const v = s.trim().split(/\s+/).map(Number);
+    return v.length === 12 && v.every((n) => !Number.isNaN(n)) ? v : null;
+}
+/** Apply a 3MF row-vector affine (12 values) to a point. */
+function applyTransform(v, x, y, z) {
+    return [
+        v[0] * x + v[3] * y + v[6] * z + v[9],
+        v[1] * x + v[4] * y + v[7] * z + v[10],
+        v[2] * x + v[5] * y + v[8] * z + v[11]
+    ];
+}
+/** Apply a chain of transforms in order (innermost first): comp → … → build item. */
+function applyChain(chain, x, y, z) {
+    let p = [x, y, z];
+    for (const t of chain)
+        p = applyTransform(t, p[0], p[1], p[2]);
+    return p;
+}
+/** Parse ONE model part's XML into objects/palettes/items (no cross-part resolution). */
+function parseModelPart(xml, lim) {
     let unitScale = 1;
-    const palettes = new Map(); // resource id → colors
+    const palettes = new Map();
     const objects = new Map();
     const items = [];
     let curObj = null;
@@ -138,7 +194,15 @@ export async function parse3mf(source, limits) {
             else {
                 const a = attrs(raw);
                 curObjId = a.id ?? null;
-                curObj = { vertices: [], tris: [], triColorIdx: [], triPid: [], name: a.name };
+                curObj = {
+                    vertices: [],
+                    tris: [],
+                    triColorIdx: [],
+                    triPid: [],
+                    triPaint: [],
+                    components: [],
+                    name: a.name
+                };
                 if (a.pid !== undefined)
                     curObj.objPid = a.pid;
                 if (a.pindex !== undefined)
@@ -149,6 +213,18 @@ export async function parse3mf(source, limits) {
                 }
             }
         }
+        else if (name === 'component' && curObj !== null) {
+            // Production extension: a sub-object, possibly in an external part via `p:path` (any prefix).
+            const a = attrs(raw);
+            const path = a['p:path'] ?? a.path;
+            if (a.objectid !== undefined) {
+                curObj.components.push({
+                    ...(path !== undefined ? { path } : {}),
+                    objectid: a.objectid,
+                    transform: parseTransform(a.transform)
+                });
+            }
+        }
         else if (name === 'vertex' && curObj !== null) {
             const a = attrs(raw);
             curObj.vertices.push(Number(a.x) || 0, Number(a.y) || 0, Number(a.z) || 0);
@@ -161,7 +237,7 @@ export async function parse3mf(source, limits) {
             }
             const pid = a.pid ?? curObj.objPid ?? null;
             curObj.triPid.push(pid);
-            // Per-vertex color indices p1/p2/p3 (fall back to p1 for all, then object pindex).
+            curObj.triPaint.push(a.paint_color ?? null);
             if (a.p1 !== undefined) {
                 const p1 = Number(a.p1);
                 const p2 = a.p2 !== undefined ? Number(a.p2) : p1;
@@ -182,107 +258,231 @@ export async function parse3mf(source, limits) {
         else if (name === 'item' && inBuild && !closing) {
             const a = attrs(raw);
             if (a.objectid !== undefined)
-                items.push({ objectid: a.objectid, transform: a.transform });
+                items.push({ objectid: a.objectid, transform: parseTransform(a.transform) });
         }
     }
-    return assemble(objects, palettes, items, unitScale, lim.maxTriangles);
-}
-function parseTransform(s) {
-    if (s === undefined)
-        return null;
-    const v = s.trim().split(/\s+/).map(Number);
-    return v.length === 12 && v.every((n) => !Number.isNaN(n)) ? v : null;
-}
-/** Apply a 3MF row-vector affine (12 values) to a point. */
-function applyTransform(v, x, y, z) {
-    return [
-        v[0] * x + v[3] * y + v[6] * z + v[9],
-        v[1] * x + v[4] * y + v[7] * z + v[10],
-        v[2] * x + v[5] * y + v[8] * z + v[11]
-    ];
+    return { objects, palettes, unitScale, items };
 }
-function assemble(objects, palettes, items, unitScale, maxTriangles) {
-    // With no <build>, render every declared object at identity (some minimal 3MFs omit build).
-    const instances = items.length > 0 ? items : [...objects.keys()].map((objectid) => ({ objectid, transform: undefined }));
-    const built = [];
-    let anyColor = false;
-    let anyTransform = false;
-    const min = [Infinity, Infinity, Infinity];
-    const max = [-Infinity, -Infinity, -Infinity];
-    let totalTris = 0;
-    for (const inst of instances) {
-        const obj = objects.get(inst.objectid);
-        if (obj === undefined || obj.tris.length === 0)
-            continue;
-        const xform = parseTransform(inst.transform);
-        if (xform !== null)
-            anyTransform = true;
-        const triCount = obj.tris.length / 3;
-        totalTris += triCount;
-        if (totalTris > maxTriangles)
-            throw new ModelParseError('E_MODEL_TOO_MANY_TRIANGLES', `3MF exceeds triangle limit ${maxTriangles}`);
-        // Expand to a non-indexed mesh (per-triangle colors need independent vertices).
-        const positions = new Float32Array(triCount * 9);
-        let colors = null;
-        let objHasColor = false;
-        for (let ti = 0; ti < triCount; ti++) {
-            const pid = obj.triPid[ti];
-            const palette = pid !== null ? palettes.get(pid) : undefined;
-            const cidx = obj.triColorIdx[ti];
-            for (let k = 0; k < 3; k++) {
-                const vi = obj.tris[ti * 3 + k] * 3;
-                let x = obj.vertices[vi] * unitScale;
-                let y = obj.vertices[vi + 1] * unitScale;
-                let z = obj.vertices[vi + 2] * unitScale;
-                if (xform !== null)
-                    [x, y, z] = applyTransform(xform, x, y, z);
-                const o = (ti * 3 + k) * 3;
-                positions[o] = x;
-                positions[o + 1] = y;
-                positions[o + 2] = z;
-                if (x < min[0])
-                    min[0] = x;
-                if (y < min[1])
-                    min[1] = y;
-                if (z < min[2])
-                    min[2] = z;
-                if (x > max[0])
-                    max[0] = x;
-                if (y > max[1])
-                    max[1] = y;
-                if (z > max[2])
-                    max[2] = z;
-                if (palette !== undefined && cidx !== null) {
-                    const col = palette[cidx[k]] ?? palette[0];
-                    if (col !== undefined) {
-                        if (colors === null)
-                            colors = new Float32Array(triCount * 9);
-                        colors[o] = col[0];
-                        colors[o + 1] = col[1];
-                        colors[o + 2] = col[2];
-                        objHasColor = true;
-                    }
+/** Bake one mesh object (its own triangles) into a `ModelObject`, applying the transform chain. */
+function bakeMesh(obj, part, chain, id, st, lim) {
+    const triCount = obj.tris.length / 3;
+    st.totalTris += triCount;
+    if (st.totalTris > lim.maxTriangles) {
+        throw new ModelParseError('E_MODEL_TOO_MANY_TRIANGLES', `3MF exceeds triangle limit ${lim.maxTriangles}`);
+    }
+    const positions = new Float32Array(triCount * 9);
+    let colors = null;
+    let objHasColor = false;
+    // A mesh painted with Bambu/Orca `paint_color` (only meaningful when we have a filament palette).
+    const objHasPaint = st.paintPalette.length > 0 && obj.triPaint.some((p) => p !== null);
+    for (let ti = 0; ti < triCount; ti++) {
+        // Paint path: one filament colour for the whole triangle. Painted facets decode to a state; the
+        // unpainted facets of a painted mesh take the object's default-extruder colour (never left blank).
+        let paintCol;
+        if (objHasPaint) {
+            let idx = st.defaultExtruderIdx;
+            const paint = obj.triPaint[ti];
+            if (paint !== null) {
+                const dec = decodePaintState(paint);
+                if (dec !== null) {
+                    idx = dec.state === 0 ? st.defaultExtruderIdx : dec.state - 1;
+                    if (dec.subdivided)
+                        st.anyApprox = true;
                 }
             }
+            paintCol = st.paintPalette[idx] ?? st.paintPalette[st.defaultExtruderIdx];
+        }
+        // Standard 3MF material path (basematerials / colorgroup + pid) — fallback when there's no paint.
+        const pid = obj.triPid[ti];
+        const palette = pid !== null ? part.palettes.get(pid) : undefined;
+        const cidx = obj.triColorIdx[ti];
+        for (let k = 0; k < 3; k++) {
+            const vi = obj.tris[ti * 3 + k] * 3;
+            const [x, y, z] = applyChain(chain, obj.vertices[vi] * part.unitScale, obj.vertices[vi + 1] * part.unitScale, obj.vertices[vi + 2] * part.unitScale);
+            const o = (ti * 3 + k) * 3;
+            positions[o] = x;
+            positions[o + 1] = y;
+            positions[o + 2] = z;
+            if (x < st.min[0])
+                st.min[0] = x;
+            if (y < st.min[1])
+                st.min[1] = y;
+            if (z < st.min[2])
+                st.min[2] = z;
+            if (x > st.max[0])
+                st.max[0] = x;
+            if (y > st.max[1])
+                st.max[1] = y;
+            if (z > st.max[2])
+                st.max[2] = z;
+            const col = paintCol ?? (palette !== undefined && cidx !== null ? (palette[cidx[k]] ?? palette[0]) : undefined);
+            if (col !== undefined) {
+                if (colors === null)
+                    colors = new Float32Array(triCount * 9);
+                colors[o] = col[0];
+                colors[o + 1] = col[1];
+                colors[o + 2] = col[2];
+                objHasColor = true;
+            }
+        }
+    }
+    if (objHasColor)
+        st.anyColor = true;
+    const geometry = colors !== null ? { positions, colors } : { positions };
+    const built = { id, geometry, transform: IDENTITY_MAT4 };
+    if (obj.name !== undefined)
+        built.name = obj.name;
+    st.built.push(built);
+}
+const hexPaletteToLinear = (hexes) => hexes.map((hex) => (hex !== undefined ? (srgbHexToLinear(hex) ?? [0.8, 0.8, 0.82]) : [0.8, 0.8, 0.82]));
+export async function parse3mf(source, limits, opts) {
+    const lim = resolveLimits(limits);
+    const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
+    if (bytes.byteLength === 0)
+        throw new ModelParseError('E_MODEL_EMPTY', '3MF source is empty');
+    if (bytes.byteLength > lim.maxSourceBytes) {
+        throw new ModelParseError('E_MODEL_TOO_LARGE', `3MF source ${bytes.byteLength} bytes exceeds limit ${lim.maxSourceBytes}`);
+    }
+    const climits = DEFAULT_CONTAINER_LIMITS;
+    let dir;
+    try {
+        dir = readDirectory(bytes, climits);
+    }
+    catch (e) {
+        throw new ModelParseError('E_MODEL_PARSE', `3MF unzip failed: ${e.message}`);
+    }
+    const entryByName = (nameLower) => dir.entries.find((e) => e.name.toLowerCase() === nameLower);
+    // Locate the primary model part: conventional path, then OPC StartPart, then any *.model.
+    let mainEntry = entryByName('3d/3dmodel.model');
+    if (mainEntry === undefined) {
+        const rels = entryByName('_rels/.rels');
+        if (rels !== undefined) {
+            const relXml = new TextDecoder().decode(await extractEntry(bytes, rels, climits.maxMetadataBytes));
+            const target = /Target="\/?([^"]+\.model)"/i.exec(relXml)?.[1];
+            if (target !== undefined)
+                mainEntry = entryByName(target.toLowerCase());
+        }
+    }
+    if (mainEntry === undefined)
+        mainEntry = dir.entries.find((e) => e.name.toLowerCase().endsWith('.model'));
+    if (mainEntry === undefined)
+        throw new ModelParseError('E_MODEL_PARSE', '3MF contains no 3D model part');
+    // Lazily parse model parts by absolute OPC path (production-extension components reference them).
+    const partCache = new Map();
+    const parseEntry = async (entry) => {
+        const key = entry.name.toLowerCase();
+        const cached = partCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const xml = new TextDecoder().decode(await extractEntry(bytes, entry, climits.maxExpandedBytesPerEntry));
+        const part = parseModelPart(xml, lim);
+        partCache.set(key, part);
+        return part;
+    };
+    const getPartByPath = async (path) => {
+        const norm = path.replace(/^\//, '').toLowerCase();
+        const entry = entryByName(norm);
+        return entry === undefined ? null : parseEntry(entry);
+    };
+    let mainPart;
+    try {
+        mainPart = await parseEntry(mainEntry);
+    }
+    catch (e) {
+        if (e instanceof ModelParseError)
+            throw e;
+        throw new ModelParseError('E_MODEL_PARSE', `3MF unzip failed: ${e.message}`);
+    }
+    // Source-model filament palette for Bambu/Orca `paint_color`: it lives in `project_settings.config`
+    // (`filament_colour`), NOT the model XML, so the render is self-contained and needs no slicer output.
+    let paintPalette = [];
+    const override = opts?.filamentPalette;
+    if (override !== undefined && override.length > 0) {
+        // Consumer-supplied palette wins over the file's own (e.g. a corrected slicer palette).
+        paintPalette = hexPaletteToLinear(override);
+    }
+    else {
+        const settingsEntry = entryByName('metadata/project_settings.config');
+        if (settingsEntry !== undefined) {
+            try {
+                const json = new TextDecoder().decode(await extractEntry(bytes, settingsEntry, climits.maxMetadataBytes));
+                const settings = JSON.parse(json);
+                paintPalette = hexPaletteToLinear(filamentColoursFromSettings(settings));
+            }
+            catch {
+                // Malformed/oversized settings → no palette; paint stays capability-honest `unavailable`.
+                paintPalette = [];
+            }
+        }
+    }
+    // Default extruder (1-based) for a painted mesh's unpainted facets; from `model_settings.config`, else 1.
+    let defaultExtruderIdx = 0;
+    const modelSettingsEntry = entryByName('metadata/model_settings.config');
+    if (modelSettingsEntry !== undefined) {
+        try {
+            const xml = new TextDecoder().decode(await extractEntry(bytes, modelSettingsEntry, climits.maxMetadataBytes));
+            const m = /key="extruder"\s+value="(\d+)"/i.exec(xml);
+            const n = m !== null ? parseInt(m[1], 10) : NaN;
+            if (Number.isFinite(n) && n >= 1)
+                defaultExtruderIdx = n - 1;
         }
-        if (objHasColor)
-            anyColor = true;
-        const geometry = colors !== null ? { positions, colors } : { positions };
-        const built1 = { id: inst.objectid, geometry, transform: IDENTITY_MAT4 };
-        if (obj.name !== undefined)
-            built1.name = obj.name;
-        built.push(built1);
+        catch {
+            defaultExtruderIdx = 0;
+        }
+    }
+    const st = {
+        built: [],
+        anyColor: false,
+        anyTransform: false,
+        anyApprox: false,
+        paintPalette,
+        defaultExtruderIdx,
+        min: [Infinity, Infinity, Infinity],
+        max: [-Infinity, -Infinity, -Infinity],
+        totalTris: 0
+    };
+    // Resolve an object (mesh and/or components) within `part`, applying the transform chain.
+    const resolve = async (part, objectid, chain, id, depth) => {
+        if (depth > MAX_DEPTH)
+            return;
+        const obj = part.objects.get(objectid);
+        if (obj === undefined)
+            return;
+        if (obj.tris.length > 0)
+            bakeMesh(obj, part, chain, id, st, lim);
+        for (let ci = 0; ci < obj.components.length; ci++) {
+            const comp = obj.components[ci];
+            const targetPart = comp.path !== undefined ? await getPartByPath(comp.path) : part;
+            if (targetPart === null)
+                continue;
+            // Apply the component transform FIRST (child space → this object), then the existing chain.
+            const childChain = comp.transform !== null ? [comp.transform, ...chain] : chain;
+            if (comp.transform !== null)
+                st.anyTransform = true;
+            await resolve(targetPart, comp.objectid, childChain, `${id}.${ci}`, depth + 1);
+        }
+    };
+    // With no <build>, resolve every declared object at identity (some minimal 3MFs omit build).
+    const instances = mainPart.items.length > 0
+        ? mainPart.items
+        : [...mainPart.objects.keys()].map((objectid) => ({ objectid, transform: null }));
+    for (const inst of instances) {
+        const chain = inst.transform !== null ? [inst.transform] : [];
+        if (inst.transform !== null)
+            st.anyTransform = true;
+        await resolve(mainPart, inst.objectid, chain, inst.objectid, 0);
     }
-    if (built.length === 0)
+    if (st.built.length === 0)
         throw new ModelParseError('E_MODEL_EMPTY', '3MF contains no renderable geometry');
-    const bounds = { min, max };
+    const bounds = { min: st.min, max: st.max };
     return {
-        objects: built,
+        objects: st.built,
         bounds,
         capabilities: {
-            materials: anyColor ? 'known' : 'unavailable',
-            transforms: anyTransform ? 'known' : 'unavailable',
-            multiObject: built.length > 1 ? 'known' : 'unavailable'
+            // `approximated` when any colour came from flattening a subdivided `paint_color` facet.
+            materials: st.anyApprox ? 'approximated' : st.anyColor ? 'known' : 'unavailable',
+            transforms: st.anyTransform ? 'known' : 'unavailable',
+            multiObject: st.built.length > 1 ? 'known' : 'unavailable'
         }
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chestnutlabs/gcode-model-renderer",
-  "version": "0.6.0",
+  "version": "0.8.1",
   "description": "Three.js presentation renderer for source models (STL/3MF) — clean thumbnails/cards, distinct from toolpath inspection (DD-018).",
   "keywords": [
     "3d-printing",
@@ -51,9 +51,9 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@chestnutlabs/gcode-containers": "0.6.0",
-    "@chestnutlabs/gcode-renderer-three": "0.6.0",
-    "@chestnutlabs/toolpath-core": "0.6.0"
+    "@chestnutlabs/gcode-containers": "0.8.1",
+    "@chestnutlabs/gcode-renderer-three": "0.8.1",
+    "@chestnutlabs/toolpath-core": "0.8.1"
   },
   "devDependencies": {
     "@types/three": "0.178.0"