@chestnutlabs/gcode-model-renderer 0.8.1 → 0.10.0

package/README.md

@@ -32,6 +32,9 @@ instead.
 - **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.
 
@@ -52,10 +55,43 @@ Already hold a corrected or richer filament palette (e.g. re-rendering a sliced
 `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.
+## Interactive viewer
 
-Determinism: same input + same environment ⇒ identical output. Cross-GPU/driver pixel identity is not
-promised — cache by the returned `cacheKey`.
+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,16 +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,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"}
+{"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":"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"}

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;

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;;;;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"}
+{"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, 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, { filamentPalette }) : parseStl(bytes, limits);
+    const scene = await resolveModelScene(source, undefined, limits, filamentPalette ? { filamentPalette } : undefined);
     return { scene, sourceBytes: bytes };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chestnutlabs/gcode-model-renderer",
-  "version": "0.8.1",
+  "version": "0.10.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.8.1",
-    "@chestnutlabs/gcode-renderer-three": "0.8.1",
-    "@chestnutlabs/toolpath-core": "0.8.1"
+    "@chestnutlabs/gcode-containers": "0.10.0",
+    "@chestnutlabs/gcode-renderer-three": "0.10.0",
+    "@chestnutlabs/toolpath-core": "0.10.0"
   },
   "devDependencies": {
     "@types/three": "0.178.0"