@chestnutlabs/gcode-model-renderer 0.7.0 → 0.9.0

package/README.md

@@ -0,0 +1,97 @@
+# @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).
+- **Interactive viewer** — `createModelViewer` is the live analogue of the still: orbit, zoom, and pan
+  the same STL / 3MF (including production multicolor) in a browser `<canvas>`, with camera presets, a
+  serializable camera state, and an event stream for readiness and errors.
+- **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.
+
+## Interactive viewer
+
+For a live surface a user can orbit — a "View in 3D" for a source model, as opposed to a static
+thumbnail — `createModelViewer` drives the same scene under the shared camera and orbit controls the
+toolpath renderer uses:
+
+```ts
+import { createModelViewer } from '@chestnutlabs/gcode-model-renderer';
+
+const viewer = createModelViewer(canvas);           // a real <canvas> in the page
+viewer.onEvent((e) => {
+  if (e.type === 'ready') {
+    // e.info.materials === 'known' | 'approximated' → showing the file's true colors
+    // e.info.materials === 'unavailable'            → neutral render; don't claim "true colors"
+    console.log(e.info.objectCount, e.info.materials, e.info.bounds);
+  }
+  if (e.type === 'renderer-unsupported') {
+    // No WebGL — fall back to a renderModelStill image or a static thumbnail
+  }
+});
+
+await viewer.setSource({ kind: '3mf', bytes });     // or { kind: 'stl', bytes }; parse → build → frame
+viewer.setView('front');                            // 'iso' | 'top' | 'front' | 'back' | 'left' | 'right' | 'bottom'
+// ...on unmount:
+viewer.dispose();
+```
+
+Drag to orbit, scroll to zoom, right-drag to pan. `getCameraState()` / `setCameraState()` persist and
+restore a pose (the same serializable `CameraState` as the toolpath renderer), `resize(w, h)` matches a
+`ResizeObserver`, and `setInteractionQuality('auto')` trades detail for smoothness while orbiting. New
+source formats become viewable by registering a `ModelLoader` for a new `kind`, with no change to the
+viewer's API (design: [DD-021](../../docs/design/DD-021-interactive-model-viewer.md)).
+
+Prefer to build your own scene? `parseStl` / `parse3mf` return a three-free `ModelScene`, and both the
+still and the viewer accept a pre-built `ModelScene` directly.
+
+Determinism (stills): 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

@@ -1,15 +1,22 @@
 /**
- * @chestnutlabs/gcode-model-renderer — Three.js **presentation** renderer for source models
- * (STL now; 3MF multi-object/material next) — clean thumbnails/cards answering "what object is this?",
- * distinct from toolpath inspection (DD-018). Sits on the shared render "stage" from
- * `@chestnutlabs/gcode-renderer-three`. `three` is a peer dependency.
+ * @chestnutlabs/gcode-model-renderer — Three.js **presentation** renderer for source models (STL and
+ * 3MF multi-object/material, incl. production `paint_color` multicolor) — clean thumbnails/cards
+ * answering "what object is this?", distinct from toolpath inspection. A headless still
+ * (`renderModelStill`, DD-018) and an interactive viewer (`createModelViewer`, DD-021) share one scene
+ * core. Sits on the shared render "stage" from `@chestnutlabs/gcode-renderer-three`. `three` is a peer
+ * dependency.
  */
 export { ModelRenderer, NEUTRAL_MATERIAL_COLOR } from './model-renderer.js';
 export type { ModelRendererOptions, ModelBackground, PresentationView } from './model-renderer.js';
 export { renderModelStill } from './render-model-still.js';
 export type { ModelSource, RenderModelStillOptions, RenderModelStillResult } from './render-model-still.js';
+export { createModelViewer } from './model-viewer.js';
+export type { ModelViewer, ModelViewerOptions, ModelViewerEvent, ModelReadyInfo } from './model-viewer.js';
 export { parseStl } from './stl.js';
 export { parse3mf } from './three-mf.js';
+export type { Parse3mfOptions } from './three-mf.js';
+export { stlLoader, threeMfLoader, DEFAULT_MODEL_LOADERS, isModelScene, resolveModelScene } from './loaders.js';
+export type { ModelLoader, ModelLoadOptions, ModelSourceInput } from './loaders.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;;;;;;;GAOG;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,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC3G,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,SAAS,EAAE,aAAa,EAAE,qBAAqB,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChH,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACpF,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/index.js

@@ -1,13 +1,17 @@
 /**
- * @chestnutlabs/gcode-model-renderer — Three.js **presentation** renderer for source models
- * (STL now; 3MF multi-object/material next) — clean thumbnails/cards answering "what object is this?",
- * distinct from toolpath inspection (DD-018). Sits on the shared render "stage" from
- * `@chestnutlabs/gcode-renderer-three`. `three` is a peer dependency.
+ * @chestnutlabs/gcode-model-renderer — Three.js **presentation** renderer for source models (STL and
+ * 3MF multi-object/material, incl. production `paint_color` multicolor) — clean thumbnails/cards
+ * answering "what object is this?", distinct from toolpath inspection. A headless still
+ * (`renderModelStill`, DD-018) and an interactive viewer (`createModelViewer`, DD-021) share one scene
+ * core. Sits on the shared render "stage" from `@chestnutlabs/gcode-renderer-three`. `three` is a peer
+ * dependency.
  */
 export { ModelRenderer, NEUTRAL_MATERIAL_COLOR } from './model-renderer.js';
 export { renderModelStill } from './render-model-still.js';
+export { createModelViewer } from './model-viewer.js';
 export { parseStl } from './stl.js';
 export { parse3mf } from './three-mf.js';
+export { stlLoader, threeMfLoader, DEFAULT_MODEL_LOADERS, isModelScene, resolveModelScene } from './loaders.js';
 export { computeCacheKey, defaultEnvId } from './cache-key.js';
 export { DEFAULT_LIMITS, resolveLimits, ModelParseError } from './limits.js';
 export { IDENTITY_MAT4 } from './scene-model.js';

package/dist/loaders.d.ts

@@ -0,0 +1,42 @@
+import { type ModelLimits } from './limits.js';
+import type { ModelScene } from './scene-model.js';
+/**
+ * Format-agnostic parse options carried through the registry. A loader that has no use for a field
+ * ignores it; the bag stays generic so registering a new `kind` never widens the public seam.
+ */
+export interface ModelLoadOptions {
+    /**
+     * 3MF `paint_color` palette override (hex `#RRGGBB` per 0-based slot), instead of the file's own
+     * `project_settings.config`. Ignored by loaders that don't consume it (e.g. STL).
+     */
+    filamentPalette?: readonly (string | undefined)[];
+}
+/** A loader turns source bytes of one `kind` into the neutral {@link ModelScene} (DD-018 §4.1). */
+export interface ModelLoader {
+    /** `'stl' | '3mf' | (future) 'obj' | 'step' | 'ply' | …` — an open string, not a closed union. */
+    readonly kind: string;
+    parse(bytes: Uint8Array, limits?: ModelLimits, opts?: ModelLoadOptions): ModelScene | Promise<ModelScene>;
+}
+/**
+ * The viewer/still input: raw bytes tagged by an open `kind`, or an already-built {@link ModelScene}.
+ * `kind` is NOT an STL|3MF union — new formats register a {@link ModelLoader}.
+ */
+export type ModelSourceInput = {
+    kind: string;
+    bytes: Uint8Array | ArrayBuffer;
+} | ModelScene;
+/** STL loader (binary + ASCII); no colour/structure, so the honest single-object, no-material case. */
+export declare const stlLoader: ModelLoader;
+/** 3MF loader — multi-object/material incl. production `paint_color` multicolor (RR-005). */
+export declare const threeMfLoader: ModelLoader;
+/** The v1 default registry: STL + 3MF. */
+export declare const DEFAULT_MODEL_LOADERS: readonly ModelLoader[];
+/** True for a pre-built {@link ModelScene} input (has `objects`, carries no `kind` tag). */
+export declare function isModelScene(input: ModelSourceInput): input is ModelScene;
+/**
+ * Resolve any {@link ModelSourceInput} to a {@link ModelScene} through the registry: a pre-built scene
+ * passes through; a `{kind, bytes}` input dispatches to the matching loader. Throws
+ * {@link ModelParseError} `E_MODEL_UNSUPPORTED_KIND` when no loader is registered for the `kind` (DD §6).
+ */
+export declare function resolveModelScene(input: ModelSourceInput, loaders?: readonly ModelLoader[], limits?: ModelLimits, opts?: ModelLoadOptions): Promise<ModelScene>;
+//# sourceMappingURL=loaders.d.ts.map

package/dist/loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.d.ts","sourceRoot":"","sources":["../src/loaders.ts"],"names":[],"mappings":"AAWA,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;CACnD;AAED,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC3G;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAA;CAAE,GAAG,UAAU,CAAC;AAE9F,uGAAuG;AACvG,eAAO,MAAM,SAAS,EAAE,WAGvB,CAAC;AAEF,6FAA6F;AAC7F,eAAO,MAAM,aAAa,EAAE,WAI3B,CAAC;AAEF,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,EAAE,SAAS,WAAW,EAA+B,CAAC;AAExF,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,KAAK,IAAI,UAAU,CAEzE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,SAAS,WAAW,EAA0B,EACvD,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,UAAU,CAAC,CAQrB"}

package/dist/loaders.js

@@ -0,0 +1,43 @@
+/**
+ * The generic model-source seam (DD-021 §4.1) — a loader registry keyed by an **open** `kind` string,
+ * so the public input is a generic model source rather than an `STL | 3MF` union. New formats
+ * (OBJ/STEP/PLY/…) become viewable by registering a {@link ModelLoader}, with no change to the viewer
+ * or still-render signatures.
+ *
+ * v1 registers `stlLoader` (`kind:'stl'`) and `threeMfLoader` (`kind:'3mf'`). Both `renderModelStill`
+ * (DD-018) and `createModelViewer` (DD-021) resolve their source through this one registry.
+ */
+import { parseStl } from './stl.js';
+import { parse3mf } from './three-mf.js';
+import { ModelParseError } from './limits.js';
+/** STL loader (binary + ASCII); no colour/structure, so the honest single-object, no-material case. */
+export const stlLoader = {
+    kind: 'stl',
+    parse: (bytes, limits) => parseStl(bytes, limits)
+};
+/** 3MF loader — multi-object/material incl. production `paint_color` multicolor (RR-005). */
+export const threeMfLoader = {
+    kind: '3mf',
+    parse: (bytes, limits, opts) => parse3mf(bytes, limits, opts?.filamentPalette ? { filamentPalette: opts.filamentPalette } : undefined)
+};
+/** The v1 default registry: STL + 3MF. */
+export const DEFAULT_MODEL_LOADERS = [stlLoader, threeMfLoader];
+/** True for a pre-built {@link ModelScene} input (has `objects`, carries no `kind` tag). */
+export function isModelScene(input) {
+    return input.objects !== undefined && input.kind === undefined;
+}
+/**
+ * Resolve any {@link ModelSourceInput} to a {@link ModelScene} through the registry: a pre-built scene
+ * passes through; a `{kind, bytes}` input dispatches to the matching loader. Throws
+ * {@link ModelParseError} `E_MODEL_UNSUPPORTED_KIND` when no loader is registered for the `kind` (DD §6).
+ */
+export async function resolveModelScene(input, loaders = DEFAULT_MODEL_LOADERS, limits, opts) {
+    if (isModelScene(input))
+        return input;
+    const loader = loaders.find((l) => l.kind === input.kind);
+    if (loader === undefined) {
+        throw new ModelParseError('E_MODEL_UNSUPPORTED_KIND', `no model loader registered for kind '${input.kind}'`);
+    }
+    const bytes = input.bytes instanceof Uint8Array ? input.bytes : new Uint8Array(input.bytes);
+    return loader.parse(bytes, limits, opts);
+}

package/dist/model-content.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `ModelContent` (DD-021 Phase 1) — the shared presentation **scene core**: given a three.js `Scene`,
+ * it adds the model root (Z-up→Y-up) and the studio light rig, then builds capability-honest meshes for
+ * a {@link ModelScene} (incl. per-triangle `paint_color` vertex colours) and reports the model's framing
+ * (center + radius) for the camera.
+ *
+ * It owns **no** GL renderer, camera, or controls — only scene content — so both the headless still
+ * (`ModelRenderer` → `renderModelStill`, DD-018) and the interactive viewer (`createModelViewer`,
+ * DD-021) build meshes and lighting through **one** path instead of parallel copies. The still keeps its
+ * own GL + camera; the viewer drives the shared `InteractiveStage`. Both hand this class a `Scene`.
+ */
+import { Scene, Vector3 } from 'three';
+import type { ModelScene, RGB } from './scene-model.js';
+/** The framing a {@link ModelScene} implies: scene-space center and a bounding radius (model coords). */
+export interface ModelFraming {
+    center: Vector3;
+    radius: number;
+}
+/**
+ * Adds the model root + studio rig to a provided `Scene` and builds meshes into it. The root carries the
+ * same Z-up(model)→Y-up(scene) rotation as the toolpath renderer, so the shared framing helper places
+ * the camera identically. Lights live in scene space (not under the rotated root) so the key stays
+ * top-ish regardless of model orientation.
+ */
+export declare class ModelContent {
+    private readonly scene;
+    private readonly root;
+    private readonly disposables;
+    private framedModel;
+    constructor(scene: Scene);
+    /** Build meshes for the scene and record its framing. Replaces (and disposes) any previous meshes. */
+    setScene(scene: ModelScene): void;
+    /** The framing of the last-set scene (`null` before the first {@link setScene}). */
+    get framing(): ModelFraming | null;
+    private buildMesh;
+    private clearMeshes;
+    /** Dispose all built geometries/materials (leaves the lights; the owner disposes the `Scene`). */
+    dispose(): void;
+}
+/** Exposed for tests: the neutral default color used when a model declares no material. */
+export declare const NEUTRAL_MATERIAL_COLOR: RGB;
+//# sourceMappingURL=model-content.d.ts.map

package/dist/model-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-content.d.ts","sourceRoot":"","sources":["../src/model-content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAQL,KAAK,EACL,OAAO,EACR,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAe,UAAU,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAKrE,yGAAyG;AACzG,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJlC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,WAAW,CAA6B;gBAEnB,KAAK,EAAE,KAAK;IAezC,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAWjC,oFAAoF;IACpF,IAAI,OAAO,IAAI,YAAY,GAAG,IAAI,CAEjC;IAED,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,WAAW;IAMnB,kGAAkG;IAClG,OAAO,IAAI,IAAI;CAGhB;AAED,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,EAAE,GAAmB,CAAC"}

package/dist/model-content.js

@@ -0,0 +1,92 @@
+/**
+ * `ModelContent` (DD-021 Phase 1) — the shared presentation **scene core**: given a three.js `Scene`,
+ * it adds the model root (Z-up→Y-up) and the studio light rig, then builds capability-honest meshes for
+ * a {@link ModelScene} (incl. per-triangle `paint_color` vertex colours) and reports the model's framing
+ * (center + radius) for the camera.
+ *
+ * It owns **no** GL renderer, camera, or controls — only scene content — so both the headless still
+ * (`ModelRenderer` → `renderModelStill`, DD-018) and the interactive viewer (`createModelViewer`,
+ * DD-021) build meshes and lighting through **one** path instead of parallel copies. The still keeps its
+ * own GL + camera; the viewer drives the shared `InteractiveStage`. Both hand this class a `Scene`.
+ */
+import { BufferAttribute, BufferGeometry, DirectionalLight, Group, HemisphereLight, Mesh, MeshStandardMaterial, Vector3 } from 'three';
+/** Neutral default surface when the source declares no material (never a fabricated source color). */
+const NEUTRAL_COLOR = [0.8, 0.8, 0.82];
+/**
+ * Adds the model root + studio rig to a provided `Scene` and builds meshes into it. The root carries the
+ * same Z-up(model)→Y-up(scene) rotation as the toolpath renderer, so the shared framing helper places
+ * the camera identically. Lights live in scene space (not under the rotated root) so the key stays
+ * top-ish regardless of model orientation.
+ */
+export class ModelContent {
+    scene;
+    root = new Group();
+    disposables = [];
+    framedModel = null;
+    constructor(scene) {
+        this.scene = scene;
+        this.root.rotation.x = -Math.PI / 2;
+        this.scene.add(this.root);
+        // Studio rig (presentation-specific): soft hemisphere fill + a key directional + a low fill.
+        const hemi = new HemisphereLight(0xffffff, 0x9098a5, 2.0);
+        this.scene.add(hemi);
+        const key = new DirectionalLight(0xffffff, 1.6);
+        key.position.set(0.6, 1, 0.8);
+        this.scene.add(key);
+        const fill = new DirectionalLight(0xffffff, 0.5);
+        fill.position.set(-0.7, 0.3, -0.5);
+        this.scene.add(fill);
+    }
+    /** Build meshes for the scene and record its framing. Replaces (and disposes) any previous meshes. */
+    setScene(scene) {
+        this.clearMeshes();
+        for (const obj of scene.objects)
+            this.root.add(this.buildMesh(obj));
+        const [minX, minY, minZ] = scene.bounds.min;
+        const [maxX, maxY, maxZ] = scene.bounds.max;
+        const center = new Vector3((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
+        const radius = Math.max(1e-3, center.distanceTo(new Vector3(minX, minY, minZ)));
+        this.framedModel = { center, radius };
+    }
+    /** The framing of the last-set scene (`null` before the first {@link setScene}). */
+    get framing() {
+        return this.framedModel;
+    }
+    buildMesh(obj) {
+        const g = new BufferGeometry();
+        g.setAttribute('position', new BufferAttribute(obj.geometry.positions, 3));
+        if (obj.geometry.indices !== undefined)
+            g.setIndex(new BufferAttribute(obj.geometry.indices, 1));
+        if (obj.geometry.normals !== undefined)
+            g.setAttribute('normal', new BufferAttribute(obj.geometry.normals, 3));
+        else
+            g.computeVertexNormals();
+        const mat = new MeshStandardMaterial({ roughness: 0.62, metalness: 0.0 });
+        if (obj.geometry.colors !== undefined) {
+            // A single mesh carrying multiple colors (per-triangle 3MF material) → vertex colors.
+            g.setAttribute('color', new BufferAttribute(obj.geometry.colors, 3));
+            mat.vertexColors = true;
+        }
+        else {
+            const color = obj.material?.color ?? NEUTRAL_COLOR;
+            mat.color.setRGB(color[0], color[1], color[2]);
+        }
+        const mesh = new Mesh(g, mat);
+        mesh.matrixAutoUpdate = false;
+        mesh.matrix.fromArray(obj.transform);
+        this.disposables.push(g, mat);
+        return mesh;
+    }
+    clearMeshes() {
+        for (const d of this.disposables)
+            d.dispose();
+        this.disposables.length = 0;
+        this.root.clear();
+    }
+    /** Dispose all built geometries/materials (leaves the lights; the owner disposes the `Scene`). */
+    dispose() {
+        this.clearMeshes();
+    }
+}
+/** Exposed for tests: the neutral default color used when a model declares no material. */
+export const NEUTRAL_MATERIAL_COLOR = NEUTRAL_COLOR;

package/dist/model-renderer.d.ts

@@ -3,12 +3,15 @@
  * "stage" from `@chestnutlabs/gcode-renderer-three` (framing pose, GL builder, GL type contracts).
  *
  * Distinct from the toolpath renderer: no tubes/travel/layers — just the model, framed at a fixed 3/4
- * angle under neutral studio lighting, on a transparent or themed background. Its lighting is its own
- * (DD-018 §4.3): a presentation studio rig, not the toolpath light rig.
+ * angle under neutral studio lighting, on a transparent or themed background. Its scene content (root,
+ * studio lights, capability-honest meshes) is built by the shared {@link ModelContent} core (DD-021),
+ * so the still and the interactive viewer share one mesh/lighting/paint path; this class adds the
+ * headless GL + camera + framing on top.
  */
 import { PerspectiveCamera, Scene } from 'three';
 import { type GLRendererLike, type RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
-import type { ModelScene, RGB } from './scene-model.js';
+import { NEUTRAL_MATERIAL_COLOR } from './model-content.js';
+import type { ModelScene } from './scene-model.js';
 /** Background: `'transparent'` (composite on a card) or a solid CSS color / 0xRRGGBB. */
 export type ModelBackground = 'transparent' | string | number;
 /** Preset presentation angle. v1 implements `'iso'` (the shared 3/4 pose); others are reserved. */
@@ -24,8 +27,7 @@ export declare class ModelRenderer {
     readonly scene: Scene;
     readonly camera: PerspectiveCamera;
     private readonly gl;
-    private readonly root;
-    private readonly disposables;
+    private readonly content;
     private width;
     private height;
     private disposed;
@@ -35,9 +37,7 @@ export declare class ModelRenderer {
     resize(width: number, height: number): void;
     render(): void;
     dispose(): void;
-    private buildMesh;
-    private clearMeshes;
 }
 /** Exposed for tests: the neutral default color used when a model declares no material. */
-export declare const NEUTRAL_MATERIAL_COLOR: RGB;
+export { NEUTRAL_MATERIAL_COLOR };
 //# sourceMappingURL=model-renderer.d.ts.map

package/dist/model-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-renderer.d.ts","sourceRoot":"","sources":["../src/model-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EASL,iBAAiB,EACjB,KAAK,EAEN,MAAM,OAAO,CAAC;AACf,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAe,UAAU,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAErE,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9D,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAKrC,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,wGAAwG;IACxG,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,KAAK,QAAe;IAC7B,QAAQ,CAAC,MAAM,oBAA8C;IAC7D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,KAAK,CAAO;IACpB,OAAO,CAAC,MAAM,CAAO;IACrB,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,oBAAoB;IA2BtC,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgBjC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ3C,MAAM,IAAI,IAAI;IAKd,OAAO,IAAI,IAAI;IAOf,OAAO,CAAC,SAAS;IAwBjB,OAAO,CAAC,WAAW;CAKpB;AAED,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,EAAE,GAAmB,CAAC"}
+{"version":3,"file":"model-renderer.d.ts","sourceRoot":"","sources":["../src/model-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAS,iBAAiB,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACxD,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAgB,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9D,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAErC,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,wGAAwG;IACxG,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,KAAK,QAAe;IAC7B,QAAQ,CAAC,MAAM,oBAA8C;IAC7D,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,KAAK,CAAO;IACpB,OAAO,CAAC,MAAM,CAAO;IACrB,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,oBAAoB;IActC,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAWjC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ3C,MAAM,IAAI,IAAI;IAKd,OAAO,IAAI,IAAI;CAMhB;AAED,2FAA2F;AAC3F,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/model-renderer.js

@@ -3,19 +3,19 @@
  * "stage" from `@chestnutlabs/gcode-renderer-three` (framing pose, GL builder, GL type contracts).
  *
  * Distinct from the toolpath renderer: no tubes/travel/layers — just the model, framed at a fixed 3/4
- * angle under neutral studio lighting, on a transparent or themed background. Its lighting is its own
- * (DD-018 §4.3): a presentation studio rig, not the toolpath light rig.
+ * angle under neutral studio lighting, on a transparent or themed background. Its scene content (root,
+ * studio lights, capability-honest meshes) is built by the shared {@link ModelContent} core (DD-021),
+ * so the still and the interactive viewer share one mesh/lighting/paint path; this class adds the
+ * headless GL + camera + framing on top.
  */
-import { BufferAttribute, BufferGeometry, Color, DirectionalLight, Group, HemisphereLight, Mesh, MeshStandardMaterial, PerspectiveCamera, Scene, Vector3 } from 'three';
+import { Color, PerspectiveCamera, Scene } from 'three';
 import { createDefaultGLRenderer, framingFromCenterRadius } from '@chestnutlabs/gcode-renderer-three';
-/** Neutral default surface when the source declares no material (never a fabricated source color). */
-const NEUTRAL_COLOR = [0.8, 0.8, 0.82];
+import { ModelContent, NEUTRAL_MATERIAL_COLOR } from './model-content.js';
 export class ModelRenderer {
     scene = new Scene();
     camera = new PerspectiveCamera(50, 1, 0.1, 100_000);
     gl;
-    root = new Group();
-    disposables = [];
+    content;
     width = 300;
     height = 300;
     disposed = false;
@@ -27,35 +27,19 @@ export class ModelRenderer {
                     alpha: transparent,
                     preserveDrawingBuffer: opts.preserveDrawingBuffer ?? true
                 });
-        // Same Z-up(printer/model) → Y-up(scene) convention as the toolpath renderer, so the shared
-        // framing helper places the camera identically.
-        this.root.rotation.x = -Math.PI / 2;
-        this.scene.add(this.root);
         this.scene.background = transparent ? null : new Color(opts.background);
-        // Studio rig (presentation-specific): soft hemisphere fill + a key directional. Lights live in
-        // scene space (not under the rotated root) so the key stays top-ish regardless of model orientation.
-        const hemi = new HemisphereLight(0xffffff, 0x9098a5, 2.0);
-        this.scene.add(hemi);
-        const key = new DirectionalLight(0xffffff, 1.6);
-        key.position.set(0.6, 1, 0.8);
-        this.scene.add(key);
-        const fill = new DirectionalLight(0xffffff, 0.5);
-        fill.position.set(-0.7, 0.3, -0.5);
-        this.scene.add(fill);
+        // Root + studio rig + mesh building live in the shared scene core (DD-021).
+        this.content = new ModelContent(this.scene);
     }
     /** Build meshes for the scene and frame the camera. Replaces any previously-set scene. */
     setScene(scene) {
         if (this.disposed)
             return;
-        this.clearMeshes();
-        for (const obj of scene.objects)
-            this.root.add(this.buildMesh(obj));
-        // Frame from the model's own bounds (model/printer coords), via the shared stage pose.
-        const [minX, minY, minZ] = scene.bounds.min;
-        const [maxX, maxY, maxZ] = scene.bounds.max;
-        const center = new Vector3((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
-        const radius = Math.max(1e-3, center.distanceTo(new Vector3(minX, minY, minZ)));
-        const { target, position } = framingFromCenterRadius(center, radius);
+        this.content.setScene(scene);
+        const framing = this.content.framing;
+        if (framing === null)
+            return;
+        const { target, position } = framingFromCenterRadius(framing.center, framing.radius);
         this.camera.position.copy(position);
         this.camera.lookAt(target);
         this.camera.updateProjectionMatrix();
@@ -76,40 +60,9 @@ export class ModelRenderer {
         if (this.disposed)
             return;
         this.disposed = true;
-        this.clearMeshes();
+        this.content.dispose();
         this.gl.dispose();
     }
-    buildMesh(obj) {
-        const g = new BufferGeometry();
-        g.setAttribute('position', new BufferAttribute(obj.geometry.positions, 3));
-        if (obj.geometry.indices !== undefined)
-            g.setIndex(new BufferAttribute(obj.geometry.indices, 1));
-        if (obj.geometry.normals !== undefined)
-            g.setAttribute('normal', new BufferAttribute(obj.geometry.normals, 3));
-        else
-            g.computeVertexNormals();
-        const mat = new MeshStandardMaterial({ roughness: 0.62, metalness: 0.0 });
-        if (obj.geometry.colors !== undefined) {
-            // A single mesh carrying multiple colors (per-triangle 3MF material) → vertex colors.
-            g.setAttribute('color', new BufferAttribute(obj.geometry.colors, 3));
-            mat.vertexColors = true;
-        }
-        else {
-            const color = obj.material?.color ?? NEUTRAL_COLOR;
-            mat.color.setRGB(color[0], color[1], color[2]);
-        }
-        const mesh = new Mesh(g, mat);
-        mesh.matrixAutoUpdate = false;
-        mesh.matrix.fromArray(obj.transform);
-        this.disposables.push(g, mat);
-        return mesh;
-    }
-    clearMeshes() {
-        for (const d of this.disposables)
-            d.dispose();
-        this.disposables.length = 0;
-        this.root.clear();
-    }
 }
 /** Exposed for tests: the neutral default color used when a model declares no material. */
-export const NEUTRAL_MATERIAL_COLOR = NEUTRAL_COLOR;
+export { NEUTRAL_MATERIAL_COLOR };

package/dist/model-viewer.d.ts

@@ -0,0 +1,72 @@
+import { type CameraMode, type CameraState, type CameraView, type GLRendererLike, type InteractiveStageOptions, type RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+import type { Confidence } from '@chestnutlabs/toolpath-core';
+import { type ModelLoader, type ModelSourceInput } from './loaders.js';
+import { type ModelLimits } from './limits.js';
+import type { ModelBackground, PresentationView } from './model-renderer.js';
+import type { ModelBounds } from './scene-model.js';
+export interface ModelViewerOptions {
+    /** Loader registry (open `kind`). Default: `[stlLoader, threeMfLoader]`. */
+    loaders?: readonly ModelLoader[];
+    /** `'transparent'` (default) | CSS colour | `0xRRGGBB` (DD-018). */
+    background?: ModelBackground;
+    /** DD-020 interaction-aware quality; default `'auto'` (the interactive default). */
+    interactionQuality?: 'off' | 'auto';
+    /** Initial camera projection; default `'perspective'`. */
+    cameraMode?: CameraMode;
+    /** Source-model triangle / byte caps (DD-018 `ModelLimits`). */
+    limits?: ModelLimits;
+    /** 3MF `paint_color` palette override (hex `#RRGGBB` per 0-based slot); parity with `renderModelStill`. */
+    filamentPalette?: readonly (string | undefined)[];
+    /** Injected GL (tests / exotic hosts). Default: the shared stage builder with alpha on. */
+    createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
+    /** Injected orbit controls (tests). Default: three `OrbitControls` via the stage. */
+    createControls?: NonNullable<InteractiveStageOptions['createControls']>;
+}
+/** What the source actually carried, surfaced on `ready` (never fabricated — DD-001). */
+export interface ModelReadyInfo {
+    objectCount: number;
+    materials: Confidence;
+    bounds: ModelBounds;
+}
+export type ModelViewerEvent = {
+    type: 'ready';
+    info: ModelReadyInfo;
+} | {
+    type: 'camera-changed';
+    state: CameraState;
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+} | {
+    type: 'renderer-unsupported';
+    feature: string;
+    message: string;
+} | {
+    type: 'context-lost';
+} | {
+    type: 'context-restored';
+};
+export interface ModelViewer {
+    /** Parse → build → frame → `ready`. Async (3MF unzips). Overlapping calls are last-wins. */
+    setSource(input: ModelSourceInput): Promise<ModelReadyInfo>;
+    /** Snap to a preset orientation (shared with the toolpath camera). */
+    setView(view: PresentationView | CameraView): void;
+    /** Current camera pose, or `null` before a source is set / when the renderer is unsupported. */
+    getCameraState(): CameraState | null;
+    setCameraState(state: CameraState): void;
+    setBackground(bg: ModelBackground): void;
+    setInteractionQuality(mode: 'off' | 'auto'): void;
+    resize(width: number, height: number): void;
+    /** Re-fit the camera to the current model bounds. */
+    frame(): void;
+    onEvent(cb: (e: ModelViewerEvent) => void): () => void;
+    dispose(): void;
+}
+/**
+ * Create an interactive model viewer bound to a live `<canvas>`. If WebGL is unavailable the handle is
+ * still returned but inert; it emits a `renderer-unsupported` event (flushed to the first `onEvent`
+ * subscriber) so the consumer can fall back to a `renderModelStill` image (DD-021 §6).
+ */
+export declare function createModelViewer(canvas: RenderTargetCanvas, options?: ModelViewerOptions): ModelViewer;
+//# sourceMappingURL=model-viewer.d.ts.map

package/dist/model-viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-viewer.d.ts","sourceRoot":"","sources":["../src/model-viewer.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAA4C,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjH,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACjC,oEAAoE;IACpE,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACpC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,2GAA2G;IAC3G,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAClD,2FAA2F;IAC3F,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;IAChE,qFAAqF;IACrF,cAAc,CAAC,EAAE,WAAW,CAAC,uBAAuB,CAAC,gBAAgB,CAAC,CAAC,CAAC;CACzE;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,UAAU,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;CAErB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GACxB;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,WAAW;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,sEAAsE;IACtE,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,UAAU,GAAG,IAAI,CAAC;IACnD,gGAAgG;IAChG,cAAc,IAAI,WAAW,GAAG,IAAI,CAAC;IACrC,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,aAAa,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,qBAAqB,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,qDAAqD;IACrD,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvD,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,kBAAkB,EAAE,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAoI3G"}

package/dist/model-viewer.js

@@ -0,0 +1,162 @@
+/**
+ * `createModelViewer` (DD-021 Phase 1) — the **interactive** analogue of `renderModelStill`: orbit /
+ * zoom / pan a source model (STL / 3MF, incl. production `paint_color` multicolor) in the browser.
+ *
+ * It composes the pieces that already exist rather than building a parallel renderer:
+ *  - the shared {@link InteractiveStage} (GL + dual camera + orbit/zoom/pan + context-loss recovery +
+ *    DD-020 interaction quality) from `@chestnutlabs/gcode-renderer-three`,
+ *  - the shared {@link ModelContent} scene core (root + studio lights + capability-honest meshes),
+ *  - the open-`kind` {@link resolveModelScene} loader registry.
+ *
+ * It is a **distinct surface** from `ToolpathRenderer` / `<GcodePreview>` (no layers/travel/scrub/IR);
+ * capability tiers are passed through from the parsed `ModelScene`, never recomputed (DD-001 honesty).
+ * Interactive is a browser concern — headless/offscreen stills stay `renderModelStill` (DD-018 §4.3).
+ */
+import { Color, Scene } from 'three';
+import { InteractiveStage, createDefaultGLRenderer } from '@chestnutlabs/gcode-renderer-three';
+import { ModelContent } from './model-content.js';
+import { DEFAULT_MODEL_LOADERS, resolveModelScene } from './loaders.js';
+import { ModelParseError } from './limits.js';
+function backgroundColor(bg) {
+    return bg === 'transparent' ? null : new Color(bg);
+}
+/**
+ * Create an interactive model viewer bound to a live `<canvas>`. If WebGL is unavailable the handle is
+ * still returned but inert; it emits a `renderer-unsupported` event (flushed to the first `onEvent`
+ * subscriber) so the consumer can fall back to a `renderModelStill` image (DD-021 §6).
+ */
+export function createModelViewer(canvas, options = {}) {
+    const loaders = options.loaders ?? DEFAULT_MODEL_LOADERS;
+    const limits = options.limits;
+    const filamentPalette = options.filamentPalette;
+    const background = options.background ?? 'transparent';
+    const listeners = new Set();
+    // Events emitted before any subscriber attaches (e.g. renderer-unsupported at construction) are held
+    // and flushed to the first subscriber, so the create-then-onEvent consumer flow never drops them.
+    const pending = [];
+    const emit = (e) => {
+        if (listeners.size === 0) {
+            pending.push(e);
+            return;
+        }
+        for (const l of listeners)
+            l(e);
+    };
+    const scene = new Scene();
+    scene.background = backgroundColor(background);
+    const content = new ModelContent(scene);
+    // Retained so context-loss recovery can rebuild meshes from the last-set scene.
+    let currentScene = null;
+    let disposed = false;
+    // Monotonic token for last-wins overlapping setSource (stale async results are discarded).
+    let sourceToken = 0;
+    let stage = null;
+    try {
+        stage = new InteractiveStage({
+            canvas,
+            scene,
+            cameraMode: options.cameraMode ?? 'perspective',
+            interactionQuality: options.interactionQuality ?? 'auto',
+            createRenderer: options.createRenderer ?? ((c) => createDefaultGLRenderer(c, { alpha: true })),
+            ...(options.createControls ? { createControls: options.createControls } : {}),
+            onCameraChanged: (state) => emit({ type: 'camera-changed', state }),
+            onContextLost: () => emit({ type: 'context-lost' }),
+            onContextRestored: () => {
+                // GPU resources are gone; rebuild meshes from the retained scene and reframe, mirroring the
+                // toolpath renderer's recovery.
+                if (currentScene !== null && stage !== null) {
+                    content.setScene(currentScene);
+                    const f = content.framing;
+                    if (f !== null)
+                        stage.frameTo(f.center, f.radius);
+                }
+                emit({ type: 'context-restored' });
+            }
+        });
+    }
+    catch (err) {
+        emit({
+            type: 'renderer-unsupported',
+            feature: 'webgl2',
+            message: err instanceof Error ? err.message : String(err)
+        });
+    }
+    async function setSource(input) {
+        const my = ++sourceToken;
+        if (stage === null || disposed) {
+            const message = disposed ? 'model viewer is disposed' : 'WebGL renderer unavailable';
+            emit({ type: 'error', code: 'E_MODEL_RENDERER_UNAVAILABLE', message });
+            throw new ModelParseError('E_MODEL_RENDERER_UNAVAILABLE', message);
+        }
+        try {
+            const parsed = await resolveModelScene(input, loaders, limits, filamentPalette ? { filamentPalette } : undefined);
+            const info = {
+                objectCount: parsed.objects.length,
+                materials: parsed.capabilities.materials,
+                bounds: parsed.bounds
+            };
+            // Last-wins: a newer setSource (or a dispose) superseded this one — discard without mutating.
+            if (my !== sourceToken || disposed || stage === null)
+                return info;
+            content.setScene(parsed);
+            currentScene = parsed;
+            const f = content.framing;
+            if (f !== null)
+                stage.frameTo(f.center, f.radius);
+            emit({ type: 'ready', info });
+            return info;
+        }
+        catch (err) {
+            const code = err instanceof ModelParseError ? err.code : 'E_MODEL_PARSE';
+            const message = err instanceof Error ? err.message : String(err);
+            // Loader/limit failures surface as an event, never thrown out of the render loop (DD §6) — but the
+            // returned promise still rejects so an awaiting caller sees the failure.
+            emit({ type: 'error', code, message });
+            throw err;
+        }
+    }
+    return {
+        setSource,
+        setView(view) {
+            stage?.setView(view);
+        },
+        getCameraState() {
+            return stage ? stage.getCameraState() : null;
+        },
+        setCameraState(state) {
+            stage?.setCameraState(state);
+        },
+        setBackground(bg) {
+            scene.background = backgroundColor(bg);
+            stage?.render();
+        },
+        setInteractionQuality(mode) {
+            stage?.setInteractionQuality(mode);
+        },
+        resize(width, height) {
+            stage?.resize(width, height);
+        },
+        frame() {
+            const f = content.framing;
+            if (f !== null)
+                stage?.frameTo(f.center, f.radius);
+        },
+        onEvent(cb) {
+            listeners.add(cb);
+            if (pending.length > 0) {
+                const flushed = pending.splice(0, pending.length);
+                for (const e of flushed)
+                    cb(e);
+            }
+            return () => listeners.delete(cb);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stage?.dispose();
+            content.dispose();
+            listeners.clear();
+        }
+    };
+}

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

@@ -15,7 +15,11 @@ import type { GLRendererLike, RenderTargetCanvas } from '@chestnutlabs/gcode-ren
 import { type ModelBackground, type PresentationView } from './model-renderer.js';
 import type { ModelScene } from './scene-model.js';
 import type { ModelLimits } from './limits.js';
-/** A source model: STL bytes, 3MF bytes, or a pre-built `ModelScene`. */
+/**
+ * A source model: STL bytes, 3MF bytes, or a pre-built `ModelScene`. This concrete union is the
+ * backward-compatible still-render input; it flows through the shared open-`kind` loader registry
+ * (`ModelSourceInput`, DD-021 §4.1), so any registered `kind` is also accepted.
+ */
 export type ModelSource = {
     kind: 'stl';
     bytes: Uint8Array | ArrayBuffer;
@@ -33,6 +37,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;AAEjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;GAIG;AACH,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;AAkBD;;;;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

@@ -1,18 +1,15 @@
 import { ModelRenderer } from './model-renderer.js';
-import { parseStl } from './stl.js';
-import { parse3mf } from './three-mf.js';
+import { isModelScene, resolveModelScene } from './loaders.js';
 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) };
     }
+    // Dispatch through the shared open-`kind` loader registry (DD-021 §4.1) — same parse result as before.
     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 = await resolveModelScene(source, undefined, limits, filamentPalette ? { filamentPalette } : undefined);
     return { scene, sourceBytes: bytes };
 }
 /**
@@ -26,7 +23,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 +34,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,4 +1,13 @@
 import { type ModelScene } from './scene-model.js';
 import { type ModelLimits } from './limits.js';
-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":"AAoBA,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkC,KAAK,WAAW,EAAuB,MAAM,aAAa,CAAC;AA8PpG,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAkH1G"}
+{"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

@@ -12,7 +12,7 @@
  * `<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. */
@@ -56,6 +56,75 @@ function srgbHexToLinear(hex) {
     const b = to(4);
     return Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) ? null : [r, g, b];
 }
+/**
+ * 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 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 {
+        node(0);
+    }
+    catch {
+        return null;
+    }
+    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;
@@ -125,7 +194,15 @@ function parseModelPart(xml, lim) {
             else {
                 const a = attrs(raw);
                 curObjId = a.id ?? null;
-                curObj = { vertices: [], tris: [], triColorIdx: [], triPid: [], components: [], 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)
@@ -160,6 +237,7 @@ function parseModelPart(xml, lim) {
             }
             const pid = a.pid ?? curObj.objPid ?? null;
             curObj.triPid.push(pid);
+            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;
@@ -195,7 +273,26 @@ function bakeMesh(obj, part, chain, id, st, lim) {
     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];
@@ -218,16 +315,14 @@ function bakeMesh(obj, part, chain, id, st, lim) {
                 st.max[1] = y;
             if (z > st.max[2])
                 st.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;
-                }
+            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;
             }
         }
     }
@@ -239,7 +334,8 @@ function bakeMesh(obj, part, chain, id, st, lim) {
         built.name = obj.name;
     st.built.push(built);
 }
-export async function parse3mf(source, limits) {
+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)
@@ -297,10 +393,50 @@ export async function parse3mf(source, limits) {
             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;
+        }
+        catch {
+            defaultExtruderIdx = 0;
+        }
+    }
     const st = {
         built: [],
         anyColor: false,
         anyTransform: false,
+        anyApprox: false,
+        paintPalette,
+        defaultExtruderIdx,
         min: [Infinity, Infinity, Infinity],
         max: [-Infinity, -Infinity, -Infinity],
         totalTris: 0
@@ -343,7 +479,8 @@ export async function parse3mf(source, limits) {
         objects: st.built,
         bounds,
         capabilities: {
-            materials: st.anyColor ? '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.7.0",
+  "version": "0.9.0",
   "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.7.0",
-    "@chestnutlabs/gcode-renderer-three": "0.7.0",
-    "@chestnutlabs/toolpath-core": "0.7.0"
+    "@chestnutlabs/gcode-containers": "0.9.0",
+    "@chestnutlabs/gcode-renderer-three": "0.9.0",
+    "@chestnutlabs/toolpath-core": "0.9.0"
   },
   "devDependencies": {
     "@types/three": "0.178.0"