@chestnutlabs/gcode-model-renderer 0.6.0

package/dist/cache-key.d.ts

@@ -0,0 +1,9 @@
+/** The default environment id — the `three` revision, which gates render determinism. */
+export declare function defaultEnvId(): string;
+/**
+ * Compute a stable cache key. `optionsJson` should be a canonical serialization of the render options
+ * that affect output (size, background, view, lighting) — the caller passes it so only output-affecting
+ * fields are folded in. `envId` defaults to {@link defaultEnvId}.
+ */
+export declare function computeCacheKey(sourceBytes: Uint8Array, optionsJson: string, envId?: string): string;
+//# sourceMappingURL=cache-key.d.ts.map

package/dist/cache-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../src/cache-key.ts"],"names":[],"mappings":"AAuCA,yFAAyF;AACzF,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,MAAuB,GAAG,MAAM,CAKpH"}

package/dist/cache-key.js

@@ -0,0 +1,49 @@
+/**
+ * Deterministic cache key for a rendered still (DD-018 §4.3). A stable identity a consumer persists as
+ * thumbnail provenance and regenerates only when it changes: a hash of the source bytes, the
+ * output-affecting options, and an env id. The env id folds in the renderer/three version, because
+ * render output can change across three versions — determinism is promised **per environment**, not
+ * across GPUs/versions.
+ *
+ * The hash is FNV-1a (non-cryptographic): cache keys need determinism + change-sensitivity, not
+ * collision resistance. No dependencies, no Web Crypto (works identically in a worker/OffscreenCanvas).
+ */
+import { REVISION } from 'three';
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+function fnv1aBytes(bytes, seed = FNV_OFFSET) {
+    let h = seed >>> 0;
+    for (let i = 0; i < bytes.length; i++) {
+        h ^= bytes[i];
+        h = Math.imul(h, FNV_PRIME);
+    }
+    return h >>> 0;
+}
+function fnv1aString(s, seed = FNV_OFFSET) {
+    let h = seed >>> 0;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i) & 0xff;
+        h = Math.imul(h, FNV_PRIME);
+        h ^= (s.charCodeAt(i) >> 8) & 0xff;
+        h = Math.imul(h, FNV_PRIME);
+    }
+    return h >>> 0;
+}
+function hex8(n) {
+    return (n >>> 0).toString(16).padStart(8, '0');
+}
+/** The default environment id — the `three` revision, which gates render determinism. */
+export function defaultEnvId() {
+    return `three${REVISION}`;
+}
+/**
+ * Compute a stable cache key. `optionsJson` should be a canonical serialization of the render options
+ * that affect output (size, background, view, lighting) — the caller passes it so only output-affecting
+ * fields are folded in. `envId` defaults to {@link defaultEnvId}.
+ */
+export function computeCacheKey(sourceBytes, optionsJson, envId = defaultEnvId()) {
+    const src = fnv1aBytes(sourceBytes);
+    const opt = fnv1aString(optionsJson, src); // chain so ordering matters
+    const env = fnv1aString(envId, opt);
+    return `mr1_${hex8(src)}${hex8(opt)}${hex8(env)}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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.
+ */
+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 { parseStl } from './stl.js';
+export { parse3mf } from './three-mf.js';
+export { computeCacheKey, defaultEnvId } from './cache-key.js';
+export { DEFAULT_LIMITS, resolveLimits, ModelParseError } from './limits.js';
+export type { ModelLimits, ResolvedLimits } from './limits.js';
+export { IDENTITY_MAT4 } from './scene-model.js';
+export type { ModelScene, ModelObject, ModelMaterial, MeshGeometry, ModelBounds, RGB, Mat4 } from './scene-model.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @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.
+ */
+export { ModelRenderer, NEUTRAL_MATERIAL_COLOR } from './model-renderer.js';
+export { renderModelStill } from './render-model-still.js';
+export { parseStl } from './stl.js';
+export { parse3mf } from './three-mf.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/limits.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resource limits for untrusted source models (DD-018 §7). Source bytes are untrusted input; nothing
+ * is executed. Bounds are checked before large allocations so a hostile file fails cleanly.
+ */
+export interface ModelLimits {
+    /** Max triangles across the whole scene. Default 5,000,000. */
+    maxTriangles?: number;
+    /** Max objects in a scene (3MF). Default 10,000. */
+    maxObjects?: number;
+    /** Max source bytes accepted before parsing. Default 256 MiB. */
+    maxSourceBytes?: number;
+}
+export interface ResolvedLimits {
+    maxTriangles: number;
+    maxObjects: number;
+    maxSourceBytes: number;
+}
+export declare const DEFAULT_LIMITS: ResolvedLimits;
+export declare function resolveLimits(limits?: ModelLimits): ResolvedLimits;
+/** A bounded, structured model-parse failure (DD-018 §6). */
+export declare class ModelParseError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,cAAc,EAAE,cAI5B,CAAC;AAEF,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAMlE;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C"}

package/dist/limits.js

@@ -0,0 +1,21 @@
+export const DEFAULT_LIMITS = {
+    maxTriangles: 5_000_000,
+    maxObjects: 10_000,
+    maxSourceBytes: 256 * 1024 * 1024
+};
+export function resolveLimits(limits) {
+    return {
+        maxTriangles: limits?.maxTriangles ?? DEFAULT_LIMITS.maxTriangles,
+        maxObjects: limits?.maxObjects ?? DEFAULT_LIMITS.maxObjects,
+        maxSourceBytes: limits?.maxSourceBytes ?? DEFAULT_LIMITS.maxSourceBytes
+    };
+}
+/** A bounded, structured model-parse failure (DD-018 §6). */
+export class ModelParseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ModelParseError';
+        this.code = code;
+    }
+}

package/dist/model-renderer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `ModelRenderer` (DD-018 §4.2) — a presentation render of a {@link ModelScene}, on the shared render
+ * "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.
+ */
+import { PerspectiveCamera, Scene } from 'three';
+import { type GLRendererLike, type RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+import type { ModelScene, RGB } 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. */
+export type PresentationView = 'iso';
+export interface ModelRendererOptions {
+    canvas: RenderTargetCanvas;
+    background?: ModelBackground;
+    /** Injected GL (tests / exotic hosts). Default: the shared stage builder, alpha on for transparency. */
+    createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
+    preserveDrawingBuffer?: boolean;
+}
+export declare class ModelRenderer {
+    readonly scene: Scene;
+    readonly camera: PerspectiveCamera;
+    private readonly gl;
+    private readonly root;
+    private readonly disposables;
+    private width;
+    private height;
+    private disposed;
+    constructor(opts: ModelRendererOptions);
+    /** Build meshes for the scene and frame the camera. Replaces any previously-set scene. */
+    setScene(scene: ModelScene): void;
+    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;
+//# sourceMappingURL=model-renderer.d.ts.map

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

@@ -0,0 +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"}

package/dist/model-renderer.js

@@ -0,0 +1,115 @@
+/**
+ * `ModelRenderer` (DD-018 §4.2) — a presentation render of a {@link ModelScene}, on the shared render
+ * "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.
+ */
+import { BufferAttribute, BufferGeometry, Color, DirectionalLight, Group, HemisphereLight, Mesh, MeshStandardMaterial, PerspectiveCamera, Scene, Vector3 } 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];
+export class ModelRenderer {
+    scene = new Scene();
+    camera = new PerspectiveCamera(50, 1, 0.1, 100_000);
+    gl;
+    root = new Group();
+    disposables = [];
+    width = 300;
+    height = 300;
+    disposed = false;
+    constructor(opts) {
+        const transparent = (opts.background ?? 'transparent') === 'transparent';
+        this.gl =
+            opts.createRenderer?.(opts.canvas) ??
+                createDefaultGLRenderer(opts.canvas, {
+                    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);
+    }
+    /** 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.camera.position.copy(position);
+        this.camera.lookAt(target);
+        this.camera.updateProjectionMatrix();
+    }
+    resize(width, height) {
+        this.width = width;
+        this.height = height;
+        this.camera.aspect = height > 0 ? width / height : 1;
+        this.camera.updateProjectionMatrix();
+        this.gl.setSize(width, height, false);
+    }
+    render() {
+        if (this.disposed)
+            return;
+        this.gl.render(this.scene, this.camera);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.clearMeshes();
+        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;

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

@@ -0,0 +1,55 @@
+/**
+ * `renderModelStill` (DD-018 §4.3) — the headless presentation-thumbnail preset, mirroring
+ * `renderStill` on the toolpath side. Parse a source model → build a {@link ModelScene} → render one
+ * deterministic frame → return the canvas + a stable cache key. The caller extracts pixels in its own
+ * environment (`OffscreenCanvas.convertToBlob`, `toDataURL`, `readPixels`).
+ *
+ * Environment: any Chromium-class WebGL2 context — an OffscreenCanvas in a Worker, or headless
+ * Chromium via ANGLE→SwiftShader (the software-GL path). A windowed GLX/GLFW path is out of scope.
+ *
+ * Determinism: same input + same environment ⇒ identical output. Cross-GPU/driver pixel identity is
+ * not promised; cache by the `cacheKey` on the returned {@link RenderModelStillResult}.
+ */
+import type { Confidence } from '@chestnutlabs/toolpath-core';
+import type { GLRendererLike, RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+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`. */
+export type ModelSource = {
+    kind: 'stl';
+    bytes: Uint8Array | ArrayBuffer;
+} | {
+    kind: '3mf';
+    bytes: Uint8Array | ArrayBuffer;
+} | ModelScene;
+export interface RenderModelStillOptions {
+    canvas: RenderTargetCanvas;
+    width?: number;
+    height?: number;
+    /** Background: `'transparent'` (default — composite on a card) or a solid CSS color / 0xRRGGBB. */
+    background?: ModelBackground;
+    /** Preset angle; default `'iso'`. */
+    view?: PresentationView;
+    createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
+    limits?: ModelLimits;
+    /** Override the environment id folded into the cache key (default: the `three` revision). */
+    envId?: string;
+}
+export interface RenderModelStillResult {
+    canvas: RenderTargetCanvas;
+    width: number;
+    height: number;
+    objectCount: number;
+    /** Whether source colors/materials were real — `'unavailable'` means the neutral default was used. */
+    materials: Confidence;
+    /** Stable identity for caching: `hash(source) + options + envId`. */
+    cacheKey: string;
+}
+/**
+ * Render one presentation still. Async because the 3MF path unzips with the container reader
+ * (`DecompressionStream`); the STL and pre-built-`ModelScene` paths resolve promptly. Mirrors the
+ * async `renderStill` on the toolpath side.
+ */
+export declare function renderModelStill(source: ModelSource, options: RenderModelStillOptions): Promise<RenderModelStillResult>;
+//# sourceMappingURL=render-model-still.d.ts.map

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

@@ -0,0 +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"}

package/dist/render-model-still.js

@@ -0,0 +1,54 @@
+import { ModelRenderer } from './model-renderer.js';
+import { parseStl } from './stl.js';
+import { parse3mf } from './three-mf.js';
+import { computeCacheKey } from './cache-key.js';
+function isModelScene(s) {
+    return s.objects !== undefined && s.kind === undefined;
+}
+async function toScene(source, limits) {
+    if (isModelScene(source)) {
+        // No raw bytes for a pre-built scene: key off a stable structural summary instead.
+        const summary = JSON.stringify({ n: source.objects.length, b: source.bounds, c: source.capabilities });
+        return { scene: source, sourceBytes: new TextEncoder().encode(summary) };
+    }
+    const bytes = source.bytes instanceof Uint8Array ? source.bytes : new Uint8Array(source.bytes);
+    const scene = source.kind === '3mf' ? await parse3mf(bytes, limits) : parseStl(bytes, limits);
+    return { scene, sourceBytes: bytes };
+}
+/**
+ * Render one presentation still. Async because the 3MF path unzips with the container reader
+ * (`DecompressionStream`); the STL and pre-built-`ModelScene` paths resolve promptly. Mirrors the
+ * async `renderStill` on the toolpath side.
+ */
+export async function renderModelStill(source, options) {
+    const { canvas } = options;
+    const width = options.width ?? canvas.width;
+    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 renderer = new ModelRenderer({
+        canvas,
+        background,
+        ...(options.createRenderer ? { createRenderer: options.createRenderer } : {}),
+        preserveDrawingBuffer: true
+    });
+    try {
+        renderer.resize(width, height);
+        renderer.setScene(scene);
+        renderer.render();
+        const optionsJson = JSON.stringify({ width, height, background, view });
+        const cacheKey = computeCacheKey(sourceBytes, optionsJson, options.envId);
+        return {
+            canvas,
+            width,
+            height,
+            objectCount: scene.objects.length,
+            materials: scene.capabilities.materials,
+            cacheKey
+        };
+    }
+    finally {
+        renderer.dispose();
+    }
+}

package/dist/scene-model.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The three-free presentation scene model (DD-018 §4.1).
+ *
+ * `ModelScene` is what `ModelRenderer` renders: one or more positioned objects with optional
+ * per-object material/color. It is **multi-object and material-capable from day one** — STL is the
+ * degenerate single-object, no-material case; 3MF (Phase 2) is the general multi-object/material case.
+ * Keeping the public shape general now means the STL slice cannot lock in a model that 3MF must replace.
+ *
+ * The types are deliberately three-free (plain numbers / typed arrays) so the package's public surface
+ * never leaks `three`; `ModelRenderer` builds three meshes/materials from a `ModelScene` internally.
+ */
+import type { Confidence } from '@chestnutlabs/toolpath-core';
+/** Linear RGB in 0..1. */
+export type RGB = [number, number, number];
+/** A 4×4 column-major transform (three's `Matrix4.elements` layout). Identity for a bare STL. */
+export type Mat4 = readonly number[];
+/** Axis-aligned bounds in scene units (mm assumed unless the source declares otherwise). */
+export interface ModelBounds {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}
+/** Triangle mesh geometry (three-free). Positions are required; normals/indices/colors are optional. */
+export interface MeshGeometry {
+    /** Flat XYZ positions, length = 3·vertexCount. */
+    positions: Float32Array;
+    /** Optional flat XYZ normals (same length as positions); recomputed if absent. */
+    normals?: Float32Array;
+    /** Optional triangle indices; non-indexed (soup) when absent. */
+    indices?: Uint32Array;
+    /**
+     * Optional flat per-vertex **linear** RGB colors (length = positions.length), for a single mesh that
+     * carries multiple colors (per-triangle material assignment in 3MF). When present the renderer uses
+     * vertex colors; when absent the object's {@link ModelObject.material} (or the neutral default) applies.
+     */
+    colors?: Float32Array;
+}
+/** A source material for an object — solid color only in v1 (textures deferred, DD-018 §13). */
+export interface ModelMaterial {
+    /** Base color when the source declared one; omit for "no declared material". */
+    color?: RGB;
+}
+/** One positioned object in a scene. */
+export interface ModelObject {
+    /** Stable within a scene (3MF object id; `'stl'` for a bare STL). */
+    id: string;
+    /** Source-declared object name when present. */
+    name?: string;
+    geometry: MeshGeometry;
+    /** Object→scene transform (identity for STL). */
+    transform: Mat4;
+    /** Omitted ⇒ no source material ⇒ neutral default render + `capabilities.materials: 'unavailable'`. */
+    material?: ModelMaterial;
+}
+/** A presentation scene: one or more objects plus capability honesty about what the source carried. */
+export interface ModelScene {
+    objects: ModelObject[];
+    bounds: ModelBounds;
+    /** What the source actually carried (DD-001 ethos — never fabricated). */
+    capabilities: {
+        /** `'known'` when the source assigned colors/materials, else `'unavailable'`. */
+        materials: Confidence;
+        /** `'known'` for real per-object transforms (3MF); `'unavailable'` for a bare STL. */
+        transforms: Confidence;
+        /** `'known'` when the source declared more than one object. */
+        multiObject: Confidence;
+    };
+}
+/** The identity transform (column-major), for single-object sources. */
+export declare const IDENTITY_MAT4: Mat4;
+//# sourceMappingURL=scene-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-model.d.ts","sourceRoot":"","sources":["../src/scene-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,0BAA0B;AAC1B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3C,iGAAiG;AACjG,MAAM,MAAM,IAAI,GAAG,SAAS,MAAM,EAAE,CAAC;AAErC,4FAA4F;AAC5F,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,GAAG,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,wGAAwG;AACxG,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,SAAS,EAAE,YAAY,CAAC;IACxB,kFAAkF;IAClF,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iEAAiE;IACjE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,KAAK,CAAC,EAAE,GAAG,CAAC;CACb;AAED,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,iDAAiD;IACjD,SAAS,EAAE,IAAI,CAAC;IAChB,uGAAuG;IACvG,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,uGAAuG;AACvG,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE;QACZ,iFAAiF;QACjF,SAAS,EAAE,UAAU,CAAC;QACtB,sFAAsF;QACtF,UAAU,EAAE,UAAU,CAAC;QACvB,+DAA+D;QAC/D,WAAW,EAAE,UAAU,CAAC;KACzB,CAAC;CACH;AAED,wEAAwE;AACxE,eAAO,MAAM,aAAa,EAAE,IAAuD,CAAC"}

package/dist/scene-model.js

@@ -0,0 +1,2 @@
+/** The identity transform (column-major), for single-object sources. */
+export const IDENTITY_MAT4 = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];

package/dist/stl.d.ts

@@ -0,0 +1,5 @@
+import { type ModelScene } from './scene-model.js';
+import { type ModelLimits } from './limits.js';
+/** Parse STL bytes into a single-object {@link ModelScene}. Throws {@link ModelParseError} on failure. */
+export declare function parseStl(source: Uint8Array | ArrayBuffer, limits?: ModelLimits): ModelScene;
+//# sourceMappingURL=stl.d.ts.map

package/dist/stl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stl.d.ts","sourceRoot":"","sources":["../src/stl.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsD,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvG,OAAO,EAAkC,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAgB/E,0GAA0G;AAC1G,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,UAAU,CAmD3F"}

package/dist/stl.js

@@ -0,0 +1,92 @@
+/**
+ * STL → {@link ModelScene} (DD-018 Phase 1). Binary and ASCII, via three's `STLLoader`.
+ *
+ * STL carries no color/material and no object structure, so it is the degenerate single-object,
+ * no-material case: one object, identity transform, `materials: 'unavailable'`,
+ * `transforms: 'unavailable'`, `multiObject: 'unavailable'` — honest, never fabricated.
+ */
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+import { IDENTITY_MAT4 } from './scene-model.js';
+import { ModelParseError, resolveLimits } from './limits.js';
+function toArrayBuffer(bytes) {
+    if (bytes instanceof ArrayBuffer)
+        return bytes;
+    // Copy out the exact view (a Uint8Array may be a partial window over a larger buffer).
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+/** Binary-STL triangle count from its header (bytes 80..84, little-endian), or null if not binary-shaped. */
+function binaryTriangleCount(buf) {
+    if (buf.byteLength < 84)
+        return null;
+    const n = new DataView(buf).getUint32(80, true);
+    // Binary STL is exactly 84 + 50·n bytes. If that doesn't hold, it's ASCII (or malformed).
+    return 84 + n * 50 === buf.byteLength ? n : null;
+}
+/** Parse STL bytes into a single-object {@link ModelScene}. Throws {@link ModelParseError} on failure. */
+export function parseStl(source, limits) {
+    const lim = resolveLimits(limits);
+    const buf = toArrayBuffer(source);
+    if (buf.byteLength === 0)
+        throw new ModelParseError('E_MODEL_EMPTY', 'STL source is empty');
+    if (buf.byteLength > lim.maxSourceBytes) {
+        throw new ModelParseError('E_MODEL_TOO_LARGE', `STL source ${buf.byteLength} bytes exceeds limit ${lim.maxSourceBytes}`);
+    }
+    // Pre-check binary triangle count before the loader allocates buffers for it.
+    const preTris = binaryTriangleCount(buf);
+    if (preTris !== null && preTris > lim.maxTriangles) {
+        throw new ModelParseError('E_MODEL_TOO_MANY_TRIANGLES', `STL declares ${preTris} triangles, exceeds limit ${lim.maxTriangles}`);
+    }
+    let geom;
+    try {
+        geom = new STLLoader().parse(buf);
+    }
+    catch (e) {
+        throw new ModelParseError('E_MODEL_PARSE', `STL parse failed: ${e.message}`);
+    }
+    const posAttr = geom.getAttribute('position');
+    if (posAttr === undefined || posAttr.count === 0) {
+        throw new ModelParseError('E_MODEL_EMPTY', 'STL contains no triangles');
+    }
+    const triangles = Math.floor(posAttr.count / 3);
+    if (triangles > lim.maxTriangles) {
+        geom.dispose();
+        throw new ModelParseError('E_MODEL_TOO_MANY_TRIANGLES', `STL has ${triangles} triangles, exceeds limit ${lim.maxTriangles}`);
+    }
+    const positions = new Float32Array(posAttr.array);
+    const normAttr = geom.getAttribute('normal');
+    const normals = normAttr !== undefined ? new Float32Array(normAttr.array) : undefined;
+    const bounds = boundsOf(positions);
+    geom.dispose();
+    const geometry = normals !== undefined ? { positions, normals } : { positions };
+    return {
+        objects: [{ id: 'stl', geometry, transform: IDENTITY_MAT4 }],
+        bounds,
+        capabilities: { materials: 'unavailable', transforms: 'unavailable', multiObject: 'unavailable' }
+    };
+}
+function boundsOf(positions) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let i = 0; i < positions.length; i += 3) {
+        const x = positions[i];
+        const y = positions[i + 1];
+        const z = positions[i + 2];
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (z < minZ)
+            minZ = z;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+        if (z > maxZ)
+            maxZ = z;
+    }
+    return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}

package/dist/three-mf.d.ts

@@ -0,0 +1,5 @@
+import { type ModelScene } from './scene-model.js';
+import { type ModelLimits } from './limits.js';
+/** Parse 3MF bytes into a {@link ModelScene}. Rejects with {@link ModelParseError} on failure. */
+export declare function parse3mf(source: Uint8Array | ArrayBuffer, limits?: ModelLimits): Promise<ModelScene>;
+//# sourceMappingURL=three-mf.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"three-mf.d.ts","sourceRoot":"","sources":["../src/three-mf.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkC,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAyE/E,kGAAkG;AAClG,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAoG1G"}

package/dist/three-mf.js

@@ -0,0 +1,288 @@
+/**
+ * 3MF → {@link ModelScene} (DD-018 Phase 2). Multi-object, per-object/per-triangle **solid** colors,
+ * build-item transforms — a multicolor model becomes a multicolor thumbnail without slicing.
+ *
+ * 3MF is an OPC (ZIP) package; the ZIP is opened with the hardened, zero-dep reader from
+ * `@chestnutlabs/gcode-containers` (DD-005 §7 — zip-bomb / traversal / size caps reused verbatim). The
+ * 3D model part is a small XML document parsed here with a minimal, worker-safe scan (no `DOMParser`,
+ * which Web Workers lack; no dependency). Only the subset needed for a presentation render is read:
+ * `<vertices>/<triangles>`, object/triangle material refs, `<basematerials>`/`<m:colorgroup>` palettes,
+ * and `<build><item>` transforms. Textures and non-color material properties are ignored (disclosed via
+ * capability honesty), never fetched (no network).
+ */
+import { readDirectory, extractEntry, 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. */
+const UNIT_TO_MM = {
+    micron: 0.001,
+    millimeter: 1,
+    centimeter: 10,
+    meter: 1000,
+    inch: 25.4,
+    foot: 304.8
+};
+const TAG_RE = /<(\/?)([\w:.-]+)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
+const ATTR_RE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+function localName(tag) {
+    const i = tag.indexOf(':');
+    return i === -1 ? tag : tag.slice(i + 1);
+}
+function attrs(s) {
+    const out = {};
+    ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RE.exec(s)) !== null)
+        out[m[1]] = m[2] ?? m[3] ?? '';
+    return out;
+}
+/** sRGB "#RRGGBB(AA)" → linear RGB in 0..1 (alpha ignored). Returns null on a malformed value. */
+function srgbHexToLinear(hex) {
+    const h = hex.trim().replace(/^#/, '');
+    if (h.length < 6)
+        return null;
+    const to = (o) => {
+        const c = parseInt(h.slice(o, o + 2), 16) / 255;
+        if (Number.isNaN(c))
+            return NaN;
+        return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    };
+    const r = to(0);
+    const g = to(2);
+    const b = to(4);
+    return Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b) ? null : [r, g, b];
+}
+async function findModelXml(bytes) {
+    const limits = DEFAULT_CONTAINER_LIMITS;
+    const dir = readDirectory(bytes, limits);
+    // Prefer the conventional path, then the OPC-declared StartPart, then any *.model.
+    const byName = (pred) => dir.entries.find((e) => pred(e.name.toLowerCase()));
+    let entry = byName((n) => n === '3d/3dmodel.model');
+    if (entry === undefined) {
+        const rels = byName((n) => n === '_rels/.rels');
+        if (rels !== undefined) {
+            const relXml = new TextDecoder().decode(await extractEntry(bytes, rels, limits.maxMetadataBytes));
+            const target = /Target="\/?([^"]+\.model)"/i.exec(relXml)?.[1];
+            if (target !== undefined)
+                entry = byName((n) => n === target.toLowerCase());
+        }
+    }
+    if (entry === undefined)
+        entry = byName((n) => n.endsWith('.model'));
+    if (entry === undefined)
+        throw new ModelParseError('E_MODEL_PARSE', '3MF contains no 3D model part');
+    return extractEntry(bytes, entry, limits.maxExpandedBytesPerEntry);
+}
+/** Parse 3MF bytes into a {@link ModelScene}. Rejects with {@link ModelParseError} on failure. */
+export async function parse3mf(source, limits) {
+    const lim = resolveLimits(limits);
+    const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
+    if (bytes.byteLength === 0)
+        throw new ModelParseError('E_MODEL_EMPTY', '3MF source is empty');
+    if (bytes.byteLength > lim.maxSourceBytes) {
+        throw new ModelParseError('E_MODEL_TOO_LARGE', `3MF source ${bytes.byteLength} bytes exceeds limit ${lim.maxSourceBytes}`);
+    }
+    let xml;
+    try {
+        xml = new TextDecoder().decode(await findModelXml(bytes));
+    }
+    catch (e) {
+        if (e instanceof ModelParseError)
+            throw e;
+        throw new ModelParseError('E_MODEL_PARSE', `3MF unzip failed: ${e.message}`);
+    }
+    // Single scan over the model XML.
+    let unitScale = 1;
+    const palettes = new Map(); // resource id → colors
+    const objects = new Map();
+    const items = [];
+    let curObj = null;
+    let curObjId = null;
+    let curPaletteId = null;
+    let inBuild = false;
+    TAG_RE.lastIndex = 0;
+    let t;
+    while ((t = TAG_RE.exec(xml)) !== null) {
+        const closing = t[1] === '/';
+        const name = localName(t[2]);
+        const selfClose = t[4] === '/';
+        const raw = t[3];
+        if (name === 'model' && !closing) {
+            const u = attrs(raw).unit;
+            if (u !== undefined && UNIT_TO_MM[u] !== undefined)
+                unitScale = UNIT_TO_MM[u];
+        }
+        else if (name === 'basematerials' || name === 'colorgroup') {
+            if (closing)
+                curPaletteId = null;
+            else {
+                curPaletteId = attrs(raw).id ?? null;
+                if (curPaletteId !== null)
+                    palettes.set(curPaletteId, []);
+            }
+        }
+        else if ((name === 'base' || name === 'color') && curPaletteId !== null) {
+            const a = attrs(raw);
+            const c = srgbHexToLinear(a.displaycolor ?? a.color ?? '');
+            const arr = palettes.get(curPaletteId);
+            if (arr !== undefined)
+                arr.push(c ?? [0.8, 0.8, 0.82]);
+        }
+        else if (name === 'object') {
+            if (closing) {
+                if (curObj !== null && curObjId !== null)
+                    objects.set(curObjId, curObj);
+                curObj = null;
+                curObjId = null;
+            }
+            else {
+                const a = attrs(raw);
+                curObjId = a.id ?? null;
+                curObj = { vertices: [], tris: [], triColorIdx: [], triPid: [], name: a.name };
+                if (a.pid !== undefined)
+                    curObj.objPid = a.pid;
+                if (a.pindex !== undefined)
+                    curObj.objPindex = Number(a.pindex);
+                if (selfClose) {
+                    curObj = null;
+                    curObjId = null;
+                }
+            }
+        }
+        else if (name === 'vertex' && curObj !== null) {
+            const a = attrs(raw);
+            curObj.vertices.push(Number(a.x) || 0, Number(a.y) || 0, Number(a.z) || 0);
+        }
+        else if (name === 'triangle' && curObj !== null) {
+            const a = attrs(raw);
+            curObj.tris.push(Number(a.v1) | 0, Number(a.v2) | 0, Number(a.v3) | 0);
+            if (curObj.tris.length / 3 > lim.maxTriangles) {
+                throw new ModelParseError('E_MODEL_TOO_MANY_TRIANGLES', `3MF exceeds triangle limit ${lim.maxTriangles}`);
+            }
+            const pid = a.pid ?? curObj.objPid ?? null;
+            curObj.triPid.push(pid);
+            // Per-vertex color indices p1/p2/p3 (fall back to p1 for all, then object pindex).
+            if (a.p1 !== undefined) {
+                const p1 = Number(a.p1);
+                const p2 = a.p2 !== undefined ? Number(a.p2) : p1;
+                const p3 = a.p3 !== undefined ? Number(a.p3) : p1;
+                curObj.triColorIdx.push([p1, p2, p3]);
+            }
+            else if (curObj.objPindex !== undefined) {
+                const p = curObj.objPindex;
+                curObj.triColorIdx.push([p, p, p]);
+            }
+            else {
+                curObj.triColorIdx.push(null);
+            }
+        }
+        else if (name === 'build') {
+            inBuild = !closing;
+        }
+        else if (name === 'item' && inBuild && !closing) {
+            const a = attrs(raw);
+            if (a.objectid !== undefined)
+                items.push({ objectid: a.objectid, transform: a.transform });
+        }
+    }
+    return assemble(objects, palettes, items, unitScale, lim.maxTriangles);
+}
+function parseTransform(s) {
+    if (s === undefined)
+        return null;
+    const v = s.trim().split(/\s+/).map(Number);
+    return v.length === 12 && v.every((n) => !Number.isNaN(n)) ? v : null;
+}
+/** Apply a 3MF row-vector affine (12 values) to a point. */
+function applyTransform(v, x, y, z) {
+    return [
+        v[0] * x + v[3] * y + v[6] * z + v[9],
+        v[1] * x + v[4] * y + v[7] * z + v[10],
+        v[2] * x + v[5] * y + v[8] * z + v[11]
+    ];
+}
+function assemble(objects, palettes, items, unitScale, maxTriangles) {
+    // With no <build>, render every declared object at identity (some minimal 3MFs omit build).
+    const instances = items.length > 0 ? items : [...objects.keys()].map((objectid) => ({ objectid, transform: undefined }));
+    const built = [];
+    let anyColor = false;
+    let anyTransform = false;
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    let totalTris = 0;
+    for (const inst of instances) {
+        const obj = objects.get(inst.objectid);
+        if (obj === undefined || obj.tris.length === 0)
+            continue;
+        const xform = parseTransform(inst.transform);
+        if (xform !== null)
+            anyTransform = true;
+        const triCount = obj.tris.length / 3;
+        totalTris += triCount;
+        if (totalTris > maxTriangles)
+            throw new ModelParseError('E_MODEL_TOO_MANY_TRIANGLES', `3MF exceeds triangle limit ${maxTriangles}`);
+        // Expand to a non-indexed mesh (per-triangle colors need independent vertices).
+        const positions = new Float32Array(triCount * 9);
+        let colors = null;
+        let objHasColor = false;
+        for (let ti = 0; ti < triCount; ti++) {
+            const pid = obj.triPid[ti];
+            const palette = pid !== null ? palettes.get(pid) : undefined;
+            const cidx = obj.triColorIdx[ti];
+            for (let k = 0; k < 3; k++) {
+                const vi = obj.tris[ti * 3 + k] * 3;
+                let x = obj.vertices[vi] * unitScale;
+                let y = obj.vertices[vi + 1] * unitScale;
+                let z = obj.vertices[vi + 2] * unitScale;
+                if (xform !== null)
+                    [x, y, z] = applyTransform(xform, x, y, z);
+                const o = (ti * 3 + k) * 3;
+                positions[o] = x;
+                positions[o + 1] = y;
+                positions[o + 2] = z;
+                if (x < min[0])
+                    min[0] = x;
+                if (y < min[1])
+                    min[1] = y;
+                if (z < min[2])
+                    min[2] = z;
+                if (x > max[0])
+                    max[0] = x;
+                if (y > max[1])
+                    max[1] = y;
+                if (z > max[2])
+                    max[2] = z;
+                if (palette !== undefined && cidx !== null) {
+                    const col = palette[cidx[k]] ?? palette[0];
+                    if (col !== undefined) {
+                        if (colors === null)
+                            colors = new Float32Array(triCount * 9);
+                        colors[o] = col[0];
+                        colors[o + 1] = col[1];
+                        colors[o + 2] = col[2];
+                        objHasColor = true;
+                    }
+                }
+            }
+        }
+        if (objHasColor)
+            anyColor = true;
+        const geometry = colors !== null ? { positions, colors } : { positions };
+        const built1 = { id: inst.objectid, geometry, transform: IDENTITY_MAT4 };
+        if (obj.name !== undefined)
+            built1.name = obj.name;
+        built.push(built1);
+    }
+    if (built.length === 0)
+        throw new ModelParseError('E_MODEL_EMPTY', '3MF contains no renderable geometry');
+    const bounds = { min, max };
+    return {
+        objects: built,
+        bounds,
+        capabilities: {
+            materials: anyColor ? 'known' : 'unavailable',
+            transforms: anyTransform ? 'known' : 'unavailable',
+            multiObject: built.length > 1 ? 'known' : 'unavailable'
+        }
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@chestnutlabs/gcode-model-renderer",
+  "version": "0.6.0",
+  "description": "Three.js presentation renderer for source models (STL/3MF) — clean thumbnails/cards, distinct from toolpath inspection (DD-018).",
+  "keywords": [
+    "3d-printing",
+    "stl",
+    "3mf",
+    "model",
+    "thumbnail",
+    "presentation",
+    "chestnutlabs",
+    "three",
+    "threejs",
+    "webgl",
+    "renderer",
+    "offscreen"
+  ],
+  "author": "Chestnut Labs",
+  "homepage": "https://github.com/ChestnutLabs/gcode-preview#readme",
+  "bugs": "https://github.com/ChestnutLabs/gcode-preview/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChestnutLabs/gcode-preview.git",
+    "directory": "packages/gcode-model-renderer"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/gcode-containers": "0.6.0",
+    "@chestnutlabs/gcode-renderer-three": "0.6.0",
+    "@chestnutlabs/toolpath-core": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/three": "0.178.0"
+  },
+  "peerDependencies": {
+    "three": "^0.178.0"
+  }
+}