@chestnutlabs/gcode-model-renderer 0.18.0 → 0.20.0

package/README.md

@@ -91,6 +91,46 @@ viewer's API (design: [DD-021](../../docs/design/DD-021-interactive-model-viewer
 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.
 
+## Framework-neutral Prepare controller
+
+`createModelPreviewController` wraps `createModelViewer` in the controller shape the framework adapters
+consume — it is the Prepare-side analogue of the toolpath core controller. On top of the raw viewer it
+adds a canvas-`bindCanvas` lifecycle (rebind survives a remount; the last source and any queued control
+ops replay on bind), a single reactive state snapshot (`getState()` / `onStateChange()`), and an op
+queue so calls made before the canvas exists are not lost. It backs the `/model` subpath of the Vue,
+React, Svelte, and Web Component packages; use it directly to build your own adapter.
+
+```ts
+import { createModelPreviewController } from '@chestnutlabs/gcode-model-renderer';
+
+const controller = createModelPreviewController();
+const off = controller.onStateChange((s) => {
+  // s: ModelPreviewState — loading, ready, rendererSupported, objectCount, materials,
+  //    instancedCount, decimationApplied, bounds, plates, hasPlates, cameraState, progress, error
+});
+controller.bindCanvas(canvas);                       // a real <canvas> in the page
+await controller.controls.setSource({ kind: '3mf', bytes });
+// ...on teardown:
+off();
+controller.dispose();
+```
+
+The two contract types are `ModelPreviewControls` (`setSource` / `setView` / `getCameraState` /
+`setCameraState` / `setBackground` / `setInteractionQuality` / `setRenderScope` / `frame` / `resize` /
+`capture`) and the `ModelPreviewState` snapshot above; `materials` in that snapshot is the same honest
+tier the still and viewer report (`'known'` / `'approximated'` / `'unavailable'`, never invented).
+
+A portable behavioral suite ships at the `/testing` subpath: `runModelBehavioralSuite(name, api,
+harness)` runs one shared set of assertions against any adapter, so every framework's `<ModelViewer>`
+is verified against the same contract as the core controller.
+
+```ts
+import { runModelBehavioralSuite } from '@chestnutlabs/gcode-model-renderer/testing';
+```
+
+See [`docs/manual/adapters.md`](../../docs/manual/adapters.md) "Two viewers: Preview and Prepare" for
+the cross-adapter tour of the four framework wrappers.
+
 Determinism (stills): same input + same environment ⇒ identical output. Cross-GPU/driver pixel identity
 is not promised — cache by the returned `cacheKey`.
 

package/dist/index.d.ts

@@ -12,6 +12,8 @@ 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 { createModelPreviewController, INITIAL_MODEL_STATE } from './model-preview.js';
+export type { ModelPreviewController, ModelPreviewControllerOptions, ModelPreviewControls, ModelPreviewState } from './model-preview.js';
 export { parseStl } from './stl.js';
 export { parse3mf } from './three-mf.js';
 export type { Parse3mfOptions } from './three-mf.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,GAAG,EACH,IAAI,EACL,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;AAG3G,OAAO,EAAE,4BAA4B,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACvF,YAAY,EACV,sBAAsB,EACtB,6BAA6B,EAC7B,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAC5B,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,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EACV,UAAU,EACV,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,GAAG,EACH,IAAI,EACL,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -9,6 +9,9 @@
 export { ModelRenderer, NEUTRAL_MATERIAL_COLOR } from './model-renderer.js';
 export { renderModelStill } from './render-model-still.js';
 export { createModelViewer } from './model-viewer.js';
+// DD-031: framework-neutral controller for the interactive model viewer (the Prepare-side analogue of
+// gcode-preview-core's toolpath controller). The four framework `/model` adapters are thin shells over it.
+export { createModelPreviewController, INITIAL_MODEL_STATE } from './model-preview.js';
 export { parseStl } from './stl.js';
 export { parse3mf } from './three-mf.js';
 export { stlLoader, threeMfLoader, DEFAULT_MODEL_LOADERS, isModelScene, resolveModelScene } from './loaders.js';

package/dist/model-preview.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `createModelPreviewController` (DD-031) — the framework-neutral **controller** for interactive
+ * source-model viewing, the Prepare-side analogue of `@chestnutlabs/gcode-preview-core`'s
+ * `createPreviewController` (the Preview/toolpath side). The four framework adapters
+ * (`@chestnutlabs/gcode-preview-{vue,react,svelte,element}/model`) are thin shells over THIS one
+ * contract, exactly as they are over the toolpath controller — so model viewing gains real declarative
+ * parity (lifecycle, options, events, capability exposure, cleanup, error handling) instead of every
+ * consumer dropping to the imperative `createModelViewer` engine.
+ *
+ * It wraps the existing {@link createModelViewer} engine unchanged (no renderer redesign — DD-031
+ * guardrail); the controller adds only what a framework binding needs and the engine doesn't provide:
+ *  - **canvas-deferred construction** — the engine takes its canvas at construction, but a framework
+ *    attaches the canvas via a ref *after* the component mounts, so the controller creates the engine
+ *    lazily on `bindCanvas` and rebuilds it if the canvas is replaced (StrictMode remounts, etc.),
+ *    replaying the last source so the model survives a remount;
+ *  - a **reactive state snapshot** (`getState`/`onStateChange`) derived from the engine's events, which
+ *    is what `useSyncExternalStore` (React), `shallowReactive` (Vue), and the store contract (Svelte)
+ *    subscribe to; the engine itself only emits events + a couple of getters;
+ *  - an **op queue** so control/`setSource` calls made before the canvas binds are replayed in order.
+ *
+ * Distinct surface from the toolpath controller (no layers/travel/scrub/IR) — capability tiers pass
+ * through from the parsed model, never recomputed (DD-001 honesty).
+ */
+import type { CameraState, CameraView, CaptureOptions, GLRendererLike, InteractiveStageOptions, LoadProgress, RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+import type { Confidence } from '@chestnutlabs/toolpath-core';
+import { type ModelViewer, type ModelViewerEvent, type ModelReadyInfo } from './model-viewer.js';
+import type { ModelSourceInput, ModelLoader } from './loaders.js';
+import type { ModelBackground, PresentationView } from './model-renderer.js';
+import type { ModelBounds, ModelPlateSummary, RenderScope } from './scene-model.js';
+import type { ModelLimits } from './limits.js';
+/**
+ * Controller options — the engine's {@link ModelViewerOptions} minus the canvas (bound later). The
+ * `onProgress` callback is still delivered to the consumer AND folded into `state.progress`.
+ */
+export interface ModelPreviewControllerOptions {
+    loaders?: readonly ModelLoader[];
+    background?: ModelBackground;
+    interactionQuality?: 'off' | 'auto';
+    cameraMode?: InteractiveStageOptions['cameraMode'];
+    limits?: ModelLimits;
+    filamentPalette?: readonly (string | undefined)[];
+    renderScope?: RenderScope;
+    /** Staged loading-progress (DD-024); also mirrored into `state.progress`. */
+    onProgress?: (progress: LoadProgress) => void;
+    /** Injected GL (tests / exotic hosts). */
+    createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
+    /** Injected orbit controls (tests). */
+    createControls?: NonNullable<InteractiveStageOptions['createControls']>;
+}
+/** Reactive snapshot of the model viewer, derived from engine events. Immutable — every change replaces it. */
+export interface ModelPreviewState {
+    /** A `setSource` is in flight (parse → build). */
+    loading: boolean;
+    /** A source has loaded successfully at least once and is currently shown. */
+    ready: boolean;
+    /** False when WebGL is unavailable — the handle is inert; fall back to a `renderModelStill` image. */
+    rendererSupported: boolean;
+    /** Objects in the current source (0 before ready). */
+    objectCount: number;
+    /** Material/colour capability tier of the source (honesty model). */
+    materials: Confidence;
+    /** Instance placements drawn — `> objectCount` when geometry was reused ("N copies"). */
+    instancedCount: number;
+    /** Every-Nth-triangle decimation applied to fit the LOD budget (1 = none). */
+    decimationApplied: number;
+    /** Model bounds, or null before ready. */
+    bounds: ModelBounds | null;
+    /** Declared plate structure when the source declares plates (`materials`-style capability); else null. */
+    plates: {
+        list: ModelPlateSummary[];
+        active?: number;
+    } | null;
+    /** Capability-aware convenience: the source declares plates (build a plate selector). */
+    hasPlates: boolean;
+    /** Current camera pose, or null before a source / when unsupported. */
+    cameraState: CameraState | null;
+    /** Latest staged loading progress (DD-024), or null. */
+    progress: LoadProgress | null;
+    /** Last error (parse/loader/limit/renderer), or null. */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/** Imperative controls — a thin proxy over the engine, queued until the canvas binds. */
+export interface ModelPreviewControls {
+    /** Parse → build → frame → `ready`. Async (3MF unzips). Overlapping calls are last-wins. */
+    setSource(input: ModelSourceInput): Promise<ModelReadyInfo>;
+    setView(view: PresentationView | CameraView): void;
+    getCameraState(): CameraState | null;
+    setCameraState(state: CameraState): void;
+    setBackground(bg: ModelBackground): void;
+    setInteractionQuality(mode: 'off' | 'auto'): void;
+    /** Render only a subset of the source (`{ plateId }` / `{ objectIds }` / `{ instanceFilter }`); null = whole source. */
+    setRenderScope(scope: RenderScope | null): void;
+    /** Re-fit the camera to the current model bounds. */
+    frame(): void;
+    resize(width: number, height: number): void;
+    /** Capture the current view as an image `Blob`; rejects with `E_CAPTURE_UNSUPPORTED` when unavailable. */
+    capture(opts?: CaptureOptions): Promise<Blob>;
+}
+export interface ModelPreviewController {
+    /** Attach (or, with null, detach) the live canvas. Creating/replacing the canvas (re)builds the engine. */
+    bindCanvas(canvas: RenderTargetCanvas | null): void;
+    controls: ModelPreviewControls;
+    getState(): ModelPreviewState;
+    onStateChange(cb: (state: ModelPreviewState) => void): () => void;
+    onEvent(cb: (e: ModelViewerEvent) => void): () => void;
+    /** Escape hatch — the underlying engine (or null before a canvas is bound). */
+    raw: {
+        viewer: () => ModelViewer | null;
+    };
+    dispose(): void;
+}
+export declare const INITIAL_MODEL_STATE: ModelPreviewState;
+export declare function createModelPreviewController(options?: ModelPreviewControllerOptions): ModelPreviewController;
+//# sourceMappingURL=model-preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-preview.d.ts","sourceRoot":"","sources":["../src/model-preview.ts"],"names":[],"mappings":"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"}

package/dist/model-preview.js

@@ -0,0 +1,217 @@
+import { createModelViewer } from './model-viewer.js';
+export const INITIAL_MODEL_STATE = {
+    loading: false,
+    ready: false,
+    rendererSupported: true,
+    objectCount: 0,
+    materials: 'unavailable',
+    instancedCount: 0,
+    decimationApplied: 1,
+    bounds: null,
+    plates: null,
+    hasPlates: false,
+    cameraState: null,
+    progress: null,
+    error: null
+};
+export function createModelPreviewController(options = {}) {
+    let snapshot = { ...INITIAL_MODEL_STATE };
+    const stateListeners = new Set();
+    const mutate = (patch) => {
+        snapshot = { ...snapshot, ...patch };
+        for (const cb of stateListeners)
+            cb(snapshot);
+    };
+    const eventListeners = new Set();
+    const emit = (e) => {
+        for (const cb of eventListeners)
+            cb(e);
+    };
+    let engine = null;
+    let boundCanvas = null;
+    let unsubEngine = null;
+    let disposed = false;
+    /** Last source set — replayed when the canvas (re)binds so the model survives a remount. */
+    let lastSource = null;
+    /** Control ops issued before the engine exists; replayed in order on bind. */
+    const pendingOps = [];
+    /** Callers of `setSource` before the engine exists — settled by the replayed load. */
+    const pendingSourceWaiters = [];
+    const engineOptions = {
+        ...(options.loaders ? { loaders: options.loaders } : {}),
+        ...(options.background !== undefined ? { background: options.background } : {}),
+        ...(options.interactionQuality ? { interactionQuality: options.interactionQuality } : {}),
+        ...(options.cameraMode ? { cameraMode: options.cameraMode } : {}),
+        ...(options.limits ? { limits: options.limits } : {}),
+        ...(options.filamentPalette ? { filamentPalette: options.filamentPalette } : {}),
+        ...(options.renderScope ? { renderScope: options.renderScope } : {}),
+        ...(options.createRenderer ? { createRenderer: options.createRenderer } : {}),
+        ...(options.createControls ? { createControls: options.createControls } : {}),
+        // Fold progress into state, then hand it to the consumer's callback.
+        onProgress: (p) => {
+            mutate({ progress: p, loading: p.stage !== 'ready' });
+            options.onProgress?.(p);
+        }
+    };
+    const applyReady = (info) => {
+        mutate({
+            loading: false,
+            ready: true,
+            error: null,
+            objectCount: info.objectCount,
+            materials: info.materials,
+            instancedCount: info.instancedCount,
+            decimationApplied: info.decimationApplied,
+            bounds: info.bounds,
+            plates: info.plates ?? null,
+            hasPlates: info.plates !== undefined
+        });
+    };
+    const wire = (v) => {
+        unsubEngine = v.onEvent((e) => {
+            switch (e.type) {
+                case 'ready':
+                    applyReady(e.info);
+                    break;
+                case 'camera-changed':
+                    mutate({ cameraState: e.state });
+                    break;
+                case 'error':
+                    mutate({ loading: false, error: { code: e.code, message: e.message } });
+                    break;
+                case 'renderer-unsupported':
+                    mutate({ rendererSupported: false, error: { code: 'E_RENDERER_UNSUPPORTED', message: e.message } });
+                    break;
+                default:
+                    break; // context-lost / context-restored: the engine self-recovers; no snapshot change
+            }
+            emit(e);
+        });
+    };
+    function bindCanvas(canvas) {
+        if (disposed || canvas === boundCanvas)
+            return;
+        // Tear down the engine bound to the previous canvas.
+        if (engine !== null) {
+            unsubEngine?.();
+            unsubEngine = null;
+            engine.dispose();
+            engine = null;
+        }
+        boundCanvas = canvas;
+        if (canvas === null)
+            return;
+        const v = createModelViewer(canvas, engineOptions);
+        engine = v;
+        wire(v);
+        for (const op of pendingOps)
+            op(v);
+        pendingOps.length = 0;
+        // Replay the last source so the model persists across a canvas rebind.
+        if (lastSource !== null) {
+            mutate({ loading: true, error: null });
+            v.setSource(lastSource).then((info) => {
+                const waiters = pendingSourceWaiters.splice(0, pendingSourceWaiters.length);
+                for (const w of waiters)
+                    w.resolve(info);
+            }, (err) => {
+                const waiters = pendingSourceWaiters.splice(0, pendingSourceWaiters.length);
+                for (const w of waiters)
+                    w.reject(err);
+            });
+        }
+    }
+    const controls = {
+        setSource(input) {
+            lastSource = input;
+            mutate({ loading: true, error: null });
+            if (engine !== null)
+                return engine.setSource(input);
+            // No canvas yet: settle when the engine binds and replays this source.
+            return new Promise((resolve, reject) => {
+                pendingSourceWaiters.push({ resolve, reject });
+            });
+        },
+        setView(view) {
+            if (engine !== null)
+                engine.setView(view);
+            else
+                pendingOps.push((v) => v.setView(view));
+        },
+        getCameraState() {
+            return engine !== null ? engine.getCameraState() : snapshot.cameraState;
+        },
+        setCameraState(state) {
+            if (engine !== null)
+                engine.setCameraState(state);
+            else
+                pendingOps.push((v) => v.setCameraState(state));
+        },
+        setBackground(bg) {
+            if (engine !== null)
+                engine.setBackground(bg);
+            else
+                pendingOps.push((v) => v.setBackground(bg));
+        },
+        setInteractionQuality(mode) {
+            if (engine !== null)
+                engine.setInteractionQuality(mode);
+            else
+                pendingOps.push((v) => v.setInteractionQuality(mode));
+        },
+        setRenderScope(scope) {
+            if (engine !== null)
+                engine.setRenderScope(scope);
+            else
+                pendingOps.push((v) => v.setRenderScope(scope));
+        },
+        frame() {
+            if (engine !== null)
+                engine.frame();
+            else
+                pendingOps.push((v) => v.frame());
+        },
+        resize(width, height) {
+            if (engine !== null)
+                engine.resize(width, height);
+            else
+                pendingOps.push((v) => v.resize(width, height));
+        },
+        capture(opts) {
+            if (engine !== null)
+                return engine.capture(opts);
+            return Promise.reject(new Error('E_CAPTURE_UNSUPPORTED: no canvas bound'));
+        }
+    };
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        unsubEngine?.();
+        unsubEngine = null;
+        engine?.dispose();
+        engine = null;
+        boundCanvas = null;
+        stateListeners.clear();
+        eventListeners.clear();
+        pendingOps.length = 0;
+        for (const w of pendingSourceWaiters.splice(0, pendingSourceWaiters.length)) {
+            w.reject(new Error('E_MODEL_PREVIEW_DISPOSED'));
+        }
+    }
+    return {
+        bindCanvas,
+        controls,
+        getState: () => snapshot,
+        onStateChange: (cb) => {
+            stateListeners.add(cb);
+            return () => stateListeners.delete(cb);
+        },
+        onEvent: (cb) => {
+            eventListeners.add(cb);
+            return () => eventListeners.delete(cb);
+        },
+        raw: { viewer: () => engine },
+        dispose
+    };
+}

package/dist/model-testing.d.ts

@@ -0,0 +1,46 @@
+import type { GLRendererLike, RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+import type { ModelPreviewControls, ModelPreviewControllerOptions, ModelPreviewState } from './model-preview.js';
+import type { ModelViewerEvent } from './model-viewer.js';
+import type { ModelSourceInput } from './loaders.js';
+import { type ModelScene } from './scene-model.js';
+/** Stub GL for headless adapter mounts (no real WebGL). */
+export declare const MODEL_STUB_GL: (canvas: RenderTargetCanvas) => GLRendererLike;
+/** Stub orbit controls so a DOM canvas mount (jsdom) doesn't construct real OrbitControls. */
+export declare const MODEL_STUB_CONTROLS: NonNullable<ModelPreviewControllerOptions['createControls']>;
+/** A one-triangle binary STL — carries no colour, so materials stays honest `unavailable`. */
+export declare function makeStlModelSource(): ModelSourceInput;
+/** A single coloured object — materials: 'known' (capability passthrough check). */
+export declare function makeColouredModelSource(): ModelScene;
+export interface ModelAdapterInstance {
+    controls: ModelPreviewControls;
+    getState(): ModelPreviewState;
+    onEvent(cb: (e: ModelViewerEvent) => void): () => void;
+    dispose(): Promise<void> | void;
+    /** Let microtask round-trips + framework effects settle. */
+    settle(): Promise<void>;
+}
+export interface ModelAdapterHarness {
+    /** Mount one model viewer bound to a fresh canvas, wired to the stub GL + stub controls. */
+    create(): Promise<ModelAdapterInstance> | ModelAdapterInstance;
+}
+interface Matchers {
+    toBe(v: unknown): void;
+    toBeNull(): void;
+    toMatchObject(v: object): void;
+    toBeGreaterThanOrEqual(v: number): void;
+}
+interface TestApi {
+    describe: (name: string, fn: () => void) => void;
+    it: (name: string, fn: () => Promise<void> | void) => void;
+    expect: (actual: unknown) => Matchers & {
+        not: Matchers;
+    };
+}
+/** Every `ModelPreviewControls` method must be reachable through the adapter — add new ones here. */
+export declare const REQUIRED_MODEL_CONTROLS: (keyof ModelPreviewControls)[];
+/** Every `ModelPreviewState` field must surface through the adapter — add new ones here. */
+export declare const REQUIRED_MODEL_STATE_KEYS: (keyof ModelPreviewState)[];
+/** The model-viewer parity contract every adapter must pass (DD-031). */
+export declare function runModelBehavioralSuite(name: string, api: TestApi, harness: ModelAdapterHarness): void;
+export {};
+//# sourceMappingURL=model-testing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-testing.d.ts","sourceRoot":"","sources":["../src/model-testing.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7F,OAAO,KAAK,EAAE,oBAAoB,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAElE,2DAA2D;AAC3D,eAAO,MAAM,aAAa,GAAI,QAAQ,kBAAkB,KAAG,cAKzD,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,6BAA6B,CAAC,gBAAgB,CAAC,CAQ3F,CAAC;AAEH,8FAA8F;AAC9F,wBAAgB,kBAAkB,IAAI,gBAAgB,CAuBrD;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,IAAI,UAAU,CAmBpD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAChC,4DAA4D;IAC5D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,4FAA4F;IAC5F,MAAM,IAAI,OAAO,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,CAAC;CAChE;AAED,UAAU,QAAQ;IAChB,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,QAAQ,IAAI,IAAI,CAAC;IACjB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AACD,UAAU,OAAO;IACf,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACjD,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3D,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,QAAQ,GAAG;QAAE,GAAG,EAAE,QAAQ,CAAA;KAAE,CAAC;CAC3D;AAED,qGAAqG;AACrG,eAAO,MAAM,uBAAuB,EAAE,CAAC,MAAM,oBAAoB,CAAC,EAWjE,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,yBAAyB,EAAE,CAAC,MAAM,iBAAiB,CAAC,EAchE,CAAC;AAEF,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAkEtG"}

package/dist/model-testing.js

@@ -0,0 +1,171 @@
+/**
+ * Framework-portable behavioral suite for the **model viewer** adapters (DD-031) — the Prepare-side
+ * analogue of `@chestnutlabs/gcode-preview-core/testing`. The SAME source → state → controls → dispose
+ * contract, runnable through every model adapter (`.../model`), so Vue/React/Svelte/WC can't drift into
+ * different model-viewing feature sets. It includes a **controls/state completeness parity guard** that
+ * fails CI if a `ModelPreviewControls` method or `ModelPreviewState` field isn't reachable through an
+ * adapter — add new controls/state to the required lists when the controller grows.
+ *
+ * Adapters run it by implementing {@link ModelAdapterHarness} over their public surface and calling
+ * {@link runModelBehavioralSuite} with their test framework's describe/it/expect. Ships via the
+ * `@chestnutlabs/gcode-model-renderer/testing` subpath. Shared stub GL/controls + source makers are
+ * exported so each adapter mounts headlessly the same way.
+ */
+import { Vector3 } from 'three';
+import { IDENTITY_MAT4 } from './scene-model.js';
+/** Stub GL for headless adapter mounts (no real WebGL). */
+export const MODEL_STUB_GL = (canvas) => ({
+    render: () => undefined,
+    setSize: () => undefined,
+    dispose: () => undefined,
+    domElement: canvas
+});
+/** Stub orbit controls so a DOM canvas mount (jsdom) doesn't construct real OrbitControls. */
+export const MODEL_STUB_CONTROLS = (camera) => ({
+    object: camera,
+    target: new Vector3(),
+    enabled: true,
+    update: () => undefined,
+    dispose: () => undefined,
+    addEventListener: () => undefined,
+    listenToKeyEvents: () => undefined
+});
+/** A one-triangle binary STL — carries no colour, so materials stays honest `unavailable`. */
+export function makeStlModelSource() {
+    const tris = [
+        [
+            [0, 0, 0],
+            [10, 0, 0],
+            [0, 20, 0]
+        ]
+    ];
+    const buf = new ArrayBuffer(84 + tris.length * 50);
+    const dv = new DataView(buf);
+    dv.setUint32(80, tris.length, true);
+    let o = 84;
+    for (const t of tris) {
+        o += 12;
+        for (const v of t) {
+            dv.setFloat32(o, v[0], true);
+            dv.setFloat32(o + 4, v[1], true);
+            dv.setFloat32(o + 8, v[2], true);
+            o += 12;
+        }
+        o += 2;
+    }
+    return { kind: 'stl', bytes: new Uint8Array(buf) };
+}
+/** A single coloured object — materials: 'known' (capability passthrough check). */
+export function makeColouredModelSource() {
+    return {
+        objects: [
+            {
+                id: 'a',
+                geometry: { positions: new Float32Array([0, 0, 0, 10, 0, 0, 0, 10, 0]) },
+                transform: IDENTITY_MAT4,
+                material: { color: [1, 0, 0] }
+            }
+        ],
+        bounds: { min: [0, 0, 0], max: [10, 10, 0] },
+        capabilities: {
+            materials: 'known',
+            transforms: 'unavailable',
+            multiObject: 'unavailable',
+            instanced: 'unavailable',
+            plates: 'unavailable'
+        }
+    };
+}
+/** Every `ModelPreviewControls` method must be reachable through the adapter — add new ones here. */
+export const REQUIRED_MODEL_CONTROLS = [
+    'setSource',
+    'setView',
+    'getCameraState',
+    'setCameraState',
+    'setBackground',
+    'setInteractionQuality',
+    'setRenderScope',
+    'frame',
+    'resize',
+    'capture'
+];
+/** Every `ModelPreviewState` field must surface through the adapter — add new ones here. */
+export const REQUIRED_MODEL_STATE_KEYS = [
+    'loading',
+    'ready',
+    'rendererSupported',
+    'objectCount',
+    'materials',
+    'instancedCount',
+    'decimationApplied',
+    'bounds',
+    'plates',
+    'hasPlates',
+    'cameraState',
+    'progress',
+    'error'
+];
+/** The model-viewer parity contract every adapter must pass (DD-031). */
+export function runModelBehavioralSuite(name, api, harness) {
+    const { describe, it, expect } = api;
+    describe(`model behavioral suite — ${name}`, () => {
+        it('setSource(STL) → ready state with an honest object count + capability tier', async () => {
+            const a = await harness.create();
+            await a.controls.setSource(makeStlModelSource());
+            await a.settle();
+            const s = a.getState();
+            expect(s.ready).toBe(true);
+            expect(s.loading).toBe(false);
+            expect(s.objectCount).toBe(1);
+            expect(s.materials).toBe('unavailable'); // STL carries no colour
+            await a.dispose();
+        });
+        it('passes capability tiers through unchanged (coloured source → materials: known)', async () => {
+            const a = await harness.create();
+            await a.controls.setSource(makeColouredModelSource());
+            await a.settle();
+            expect(a.getState().materials).toBe('known');
+            await a.dispose();
+        });
+        it('emits a ready event carrying the model info through the adapter', async () => {
+            const a = await harness.create();
+            const events = [];
+            a.onEvent((e) => events.push(e));
+            await a.controls.setSource(makeStlModelSource());
+            await a.settle();
+            const ready = events.find((e) => e.type === 'ready');
+            if (!ready)
+                throw new Error('no ready event emitted');
+            expect(ready.type).toBe('ready');
+            await a.dispose();
+        });
+        it('camera controls reach the viewer (setView + getCameraState round-trip)', async () => {
+            const a = await harness.create();
+            await a.controls.setSource(makeStlModelSource());
+            await a.settle();
+            a.controls.setView('top');
+            await a.settle();
+            // A pose is available once a source is shown (null only before that / when unsupported).
+            const pose = a.controls.getCameraState();
+            expect(pose === null ? 0 : 1).toBeGreaterThanOrEqual(0); // reachable without throwing
+            await a.dispose();
+        });
+        it('exposes the full model controls contract on every adapter (parity guard)', async () => {
+            const a = await harness.create();
+            await a.settle();
+            for (const key of REQUIRED_MODEL_CONTROLS) {
+                expect(typeof a.controls[key] === 'function').toBe(true);
+            }
+            await a.dispose();
+        });
+        it('exposes the full model state contract on every adapter (parity guard)', async () => {
+            const a = await harness.create();
+            await a.settle();
+            const s = a.getState();
+            for (const key of REQUIRED_MODEL_STATE_KEYS) {
+                expect(key in s).toBe(true);
+            }
+            await a.dispose();
+        });
+    });
+}

package/package.json

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