@chestnutlabs/gcode-preview-vue 0.19.0 → 0.20.0

package/README.md

@@ -34,23 +34,32 @@ const file = shallowRef<File | null>(null);
 </template>
 ```
 
-That is a complete viewer. The full surface is optional props with sensible defaults:
+That is a complete viewer. The full surface is ~24 optional props with sensible defaults — the
+frequently reached-for ones:
 
 | Prop | Purpose |
 |---|---|
 | `source` | `Uint8Array \| ArrayBuffer \| File` — changing it re-parses |
 | `parse-options` | wire options (limits, dialects, containers, plate selection) |
+| `renderer` | `'3d'` (Three.js) or `'2d'` (Canvas fallback) — construction-time |
 | `build-volume` | consumer-configured plate — wins over file-discovered geometry; discovery is then emitted, not applied |
-| `quality` | `'auto' \| 'lines' \| 'tubes'` |
-| `color-mode` | single / by-tool / by-feature (feature coloring is capability-gated — listen for `error`) |
-| `layer-range` / `scrub` / `show-travel` | clipping controls |
+| `quality` / `quality-mode` | `'auto' \| 'lines' \| 'tubes'`; render-quality budget (`'full' \| 'adaptive' \| 'fast'`) |
+| `color-mode` | single / by-tool / by-feature (feature coloring is capability-gated — check `state.availableColorModes` or listen for `error`) |
+| `theme` | viewer theme (background, bed, toolpath palette) |
+| `camera-mode` / `view` / `camera-state` / `frame-content` | perspective/orthographic, named view, saved camera, framing target |
+| `layer-range` / `scrub` / `scrub-time` | clipping / time-based scrub controls |
+| `show-travel` / `show-wipe` / `show-retractions` / `show-volume-cage` | move-class and overlay visibility toggles |
+| `hidden-feature-roles` | hide feature roles (e.g. Skirt, Brim) — declarative form of `controls.setFeatureRoleVisible`; gate on `capabilities.featureRoles` |
 | `progress` | a DD-006 `ProgressObservation` — drives the honest live-progress overlay (marker for byte-exact, uncertainty band for approximate, gray when stale) |
 | `create-worker` | worker factory escape hatch (see below) |
 
-Emits: `ready`, `parse-error`, `parse-cancelled`, `parse-progress`, `build-complete`,
-`quality-fallback`, `machine-geometry-mismatch`, `machine-geometry-discovered`,
+Emits (13): `ready`, `camera-change`, `parse-error`, `parse-cancelled`, `parse-progress`, `stage`,
+`build-complete`, `quality-fallback`, `machine-geometry-mismatch`, `machine-geometry-discovered`,
 `progress-presentation-changed`, `disclosure`, `error`. The underlying handle is exposed for
-template refs (`ref.preview`).
+template refs (`ref.preview`); its `controls` reach the imperative surface — `getRenderStats()`
+(render diagnostics), `pickSegment(ndcX, ndcY, threshold?)` (source-mapping / picking),
+`isColorModeAvailable(mode)`, and `capture(opts?)` (image `Blob`, also `handle.capture`). The handle
+`state` carries capability-aware UI data (`availableColorModes`, `hasRetractions`, `hasColorChanges`).
 
 ## Headless composable (build your own controls)
 
@@ -89,6 +98,48 @@ Linked-workspace development note: Vite consumers using `file:` links should add
 `@chestnutlabs/*` package the worker pulls in to `optimizeDeps.exclude` (installed tarballs/registry
 packages need no configuration).
 
+## Model viewing (Prepare side)
+
+The `/model` subpath ships a `<ModelViewer>` — the **Prepare**-side counterpart to `<GcodePreview>`.
+Where `<GcodePreview>` draws the toolpath (how a print runs), `<ModelViewer>` draws the **source
+model** (an `.stl` / `.3mf` mesh) — the object before slicing.
+
+```vue
+<script setup lang="ts">
+import { ModelViewer } from '@chestnutlabs/gcode-preview-vue/model';
+
+const source = { kind: '3mf' as const, bytes };
+</script>
+
+<template>
+  <div style="height: 70vh">
+    <ModelViewer :source="source" @ready="(info) => console.log(info.objectCount, info.materials)" />
+  </div>
+</template>
+```
+
+`@ready` carries the honest material-colour tier: `info.materials` is `'known'` / `'approximated'`
+when the file declared colours the render used, and `'unavailable'` when it declared none (a neutral
+default, never faked). The kebab props (`:view`, `:background`, `:render-scope`, …), matching emits,
+and the `useModelViewer` composable mirror the toolpath component. See
+[`docs/manual/adapters.md`](../../docs/manual/adapters.md) "Two viewers: Preview and Prepare" for the
+cross-adapter tour, and `tools/example-vue/model.html` for a runnable minimal page.
+
+## Examples
+
+`tools/example-vue` in the repository is a Vite app with two tiers, both driving this published
+package (no raw renderer or parser imports):
+
+- **`minimal.html`** — the smallest real integration: `<GcodePreview :source>` plus a fixture picker
+  and a layer slider. One short component to copy when getting started.
+- **`showcase.html`** — the full declarative surface: capability-gated color modes (a mode greys out
+  with a plain-language reason when the file can't support it), declarative `:hidden-feature-roles`,
+  camera, and `getRenderStats()`/`pickSegment()` diagnostics through the component ref's handle
+  (`viewer.preview.controls`), whose `state` mirror is directly reactive in Vue.
+
+Run it with `npm install --prefix tools/example-vue && npm run dev --prefix tools/example-vue`
+(port 5203).
+
 ## Capability honesty
 
 Everything the engine reports as `inferred`/`approximated`/`unavailable` stays that way at this

package/dist/gcode-preview-component.d.ts

@@ -12,7 +12,7 @@
 import { type PropType } from 'vue';
 import type { BuildVolumeDef, CameraMode, CameraState, CameraView, ColorMode, QualityMode, ProgressivePreview, PreparationStage, QualityPolicy, Theme, TubeOptions } from '@chestnutlabs/gcode-renderer-three';
 import type { Confidence, DialectMetadata, Warning } from '@chestnutlabs/toolpath-core';
-import type { MachineGeometry, ProgressObservation } from '@chestnutlabs/toolpath-core';
+import type { FeatureRoleValue, MachineGeometry, ProgressObservation } from '@chestnutlabs/toolpath-core';
 import type { WireParseOptions, WorkerLike } from '@chestnutlabs/gcode-parser';
 import { type RendererMode, type UseGcodePreviewOptions } from './use-gcode-preview.js';
 export type GcodePreviewSource = Uint8Array | ArrayBuffer | File | null;
@@ -126,6 +126,12 @@ export declare const GcodePreview: import("vue").DefineComponent<import("vue").E
         type: BooleanConstructor;
         default: boolean;
     };
+    /** DD-031 G3: feature roles to hide (e.g. `[FeatureRole.Skirt, FeatureRole.Brim]` to declutter a
+     *  part). Declarative form of `controls.setFeatureRoleVisible`; gate on `capabilities.featureRoles`. */
+    hiddenFeatureRoles: {
+        type: PropType<FeatureRoleValue[]>;
+        default: undefined;
+    };
     /** DD-006 live progress observation; null hides the overlay. */
     progress: {
         type: PropType<ProgressObservation | null>;
@@ -301,6 +307,12 @@ export declare const GcodePreview: import("vue").DefineComponent<import("vue").E
         type: BooleanConstructor;
         default: boolean;
     };
+    /** DD-031 G3: feature roles to hide (e.g. `[FeatureRole.Skirt, FeatureRole.Brim]` to declutter a
+     *  part). Declarative form of `controls.setFeatureRoleVisible`; gate on `capabilities.featureRoles`. */
+    hiddenFeatureRoles: {
+        type: PropType<FeatureRoleValue[]>;
+        default: undefined;
+    };
     /** DD-006 live progress observation; null hides the overlay. */
     progress: {
         type: PropType<ProgressObservation | null>;
@@ -388,6 +400,7 @@ export declare const GcodePreview: import("vue").DefineComponent<import("vue").E
     showWipe: boolean;
     showRetractions: boolean;
     showVolumeCage: boolean;
+    hiddenFeatureRoles: FeatureRoleValue[];
     progress: ProgressObservation | null;
     createWorker: () => WorkerLike;
     rendererOptions: Omit<{

package/dist/gcode-preview-component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gcode-preview-component.d.ts","sourceRoot":"","sources":["../src/gcode-preview-component.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gcode-preview-component.d.ts","sourceRoot":"","sources":["../src/gcode-preview-component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAA6C,KAAK,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/E,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,KAAK,EACL,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC1G,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;AAExE,eAAO,MAAM,YAAY;IAGrB,qFAAqF;;cAC1B,QAAQ,CAAC,kBAAkB,CAAC;;;;cACvD,QAAQ,CAAC,gBAAgB,CAAC;;;IAC1D,qGAAqG;;cACzE,QAAQ,CAAC,YAAY,CAAC;;;IAClD,uGAAuG;;cACrE,QAAQ,CAAC,MAAM,CAAC;;;IAClD,2FAA2F;;cAC5D,QAAQ,CAAC,cAAc,GAAG,eAAe,CAAC;;;;cAC9C,QAAQ,CAAC,WAAW,GAAG,MAAM,CAAC;;;;cAC1B,QAAQ,CAAC,aAAa,CAAC;;;IACtD,0GAA0G;;cACpE,QAAQ,CAAC,kBAAkB,CAAC;;;IAClE,2CAA2C;;cACb,QAAQ,CAAC,UAAU,CAAC;;;IAClD,iGAAiG;;cACjE,QAAQ,CAAC,QAAQ,GAAG,KAAK,CAAC;;;IAC1D,oFAAoF;;cAC9C,QAAQ,CAAC,KAAK,GAAG,MAAM,CAAC;;;IAC9D,oEAAoE;;cAC5C,QAAQ,CAAC,UAAU,CAAC;;;IAC5C,mGAAmG;;cACpE,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;;;IAC3D,mDAAmD;;cAC1B,QAAQ,CAAC,KAAK,CAAC;;;;cACX,QAAQ,CAAC,SAAS,CAAC;;;;cACxB,QAAQ,CAAC,WAAW,CAAC;;;IAC7C,sDAAsD;;cACd,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;;;IACzE,iFAAiF;;cACxD,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC;;;IAChD,uEAAuE;;cAC1C,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC;;;;;;;IAEpD,2DAA2D;;;;;IAE3D,gEAAgE;;;;;IAEhE,kGAAkG;;;;;IAElG;4GACwG;;cACnE,QAAQ,CAAC,gBAAgB,EAAE,CAAC;;;IACjE,gEAAgE;;cACpC,QAAQ,CAAC,mBAAmB,GAAG,IAAI,CAAC;;;IAChE;sFACkF;;cAE9D,QAAQ,CAAC,MAAM,UAAU,CAAC;;;IAG9C,mFAAmF;;cAEjE,QAAQ,CACtB,IAAI,CACF,WAAW,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC,EAC7C,aAAa,GACb,SAAS,GACT,aAAa,GACb,oBAAoB,GACpB,YAAY,GACZ,cAAc,GACd,oBAAoB,GACpB,OAAO,GACP,WAAW,GACX,MAAM,CACT,CACF;;;;;;sBAMe;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,OAAO,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACzC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;QAC7B,QAAQ,EAAE,eAAe,GAAG,SAAS,CAAC;KACvC;8BACyB,WAAW;wBACjB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;;2BAE9B;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;gBACzD;QAAE,KAAK,EAAE,gBAAgB,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;2BAC9E;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE;6BACxC;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,EAAE,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;4CACvC,MAAM;8CACJ,eAAe;0CACnB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;wBACnD,MAAM;gBACd;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;;IA5F7C,qFAAqF;;cAC1B,QAAQ,CAAC,kBAAkB,CAAC;;;;cACvD,QAAQ,CAAC,gBAAgB,CAAC;;;IAC1D,qGAAqG;;cACzE,QAAQ,CAAC,YAAY,CAAC;;;IAClD,uGAAuG;;cACrE,QAAQ,CAAC,MAAM,CAAC;;;IAClD,2FAA2F;;cAC5D,QAAQ,CAAC,cAAc,GAAG,eAAe,CAAC;;;;cAC9C,QAAQ,CAAC,WAAW,GAAG,MAAM,CAAC;;;;cAC1B,QAAQ,CAAC,aAAa,CAAC;;;IACtD,0GAA0G;;cACpE,QAAQ,CAAC,kBAAkB,CAAC;;;IAClE,2CAA2C;;cACb,QAAQ,CAAC,UAAU,CAAC;;;IAClD,iGAAiG;;cACjE,QAAQ,CAAC,QAAQ,GAAG,KAAK,CAAC;;;IAC1D,oFAAoF;;cAC9C,QAAQ,CAAC,KAAK,GAAG,MAAM,CAAC;;;IAC9D,oEAAoE;;cAC5C,QAAQ,CAAC,UAAU,CAAC;;;IAC5C,mGAAmG;;cACpE,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;;;IAC3D,mDAAmD;;cAC1B,QAAQ,CAAC,KAAK,CAAC;;;;cACX,QAAQ,CAAC,SAAS,CAAC;;;;cACxB,QAAQ,CAAC,WAAW,CAAC;;;IAC7C,sDAAsD;;cACd,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;;;IACzE,iFAAiF;;cACxD,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC;;;IAChD,uEAAuE;;cAC1C,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC;;;;;;;IAEpD,2DAA2D;;;;;IAE3D,gEAAgE;;;;;IAEhE,kGAAkG;;;;;IAElG;4GACwG;;cACnE,QAAQ,CAAC,gBAAgB,EAAE,CAAC;;;IACjE,gEAAgE;;cACpC,QAAQ,CAAC,mBAAmB,GAAG,IAAI,CAAC;;;IAChE;sFACkF;;cAE9D,QAAQ,CAAC,MAAM,UAAU,CAAC;;;IAG9C,mFAAmF;;cAEjE,QAAQ,CACtB,IAAI,CACF,WAAW,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC,EAC7C,aAAa,GACb,SAAS,GACT,aAAa,GACb,oBAAoB,GACpB,YAAY,GACZ,cAAc,GACd,oBAAoB,GACpB,OAAO,GACP,WAAW,GACX,MAAM,CACT,CACF;;;;;;cAyBiB,MAAM;iBAAW,MAAM;;;kBAlB/B,MAAM;gBACR,MAAM;kBACJ,OAAO;sBACH,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;kBAC9B,SAAS,OAAO,EAAE;kBAClB,eAAe,GAAG,SAAS;;;;cAGX,MAAM;iBAAW,MAAM;;;;wBAEV,MAAM;oBAAc,MAAM;;;eAC9C,gBAAgB;mBAAa,MAAM;iBAAW;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE;;;kBAChE,MAAM;iBAAW,WAAW;;;cAC9B,WAAW;YAAM,WAAW;gBAAU,MAAM;;;;;cAG/B,MAAM;iBAAW,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA1ClC,UAAU;;;;;;;;;;;;;;;;;;;;;4EA4R/C,CAAC"}

package/dist/gcode-preview-component.js

@@ -54,6 +54,9 @@ export const GcodePreview = defineComponent({
         showRetractions: { type: Boolean, default: false },
         /** #306/#6: show the build-volume wireframe cage (independent of the bed/plate). Default true. */
         showVolumeCage: { type: Boolean, default: true },
+        /** DD-031 G3: feature roles to hide (e.g. `[FeatureRole.Skirt, FeatureRole.Brim]` to declutter a
+         *  part). Declarative form of `controls.setFeatureRoleVisible`; gate on `capabilities.featureRoles`. */
+        hiddenFeatureRoles: { type: Array, default: undefined },
         /** DD-006 live progress observation; null hides the overlay. */
         progress: { type: Object, default: null },
         /** Worker factory escape hatch (DD-005 slim/custom entries; D2). Factory form only —
@@ -221,6 +224,19 @@ export const GcodePreview = defineComponent({
             if (volume !== undefined)
                 preview.controls.setBuildVolume(volume);
         });
+        // Feature-role visibility (DD-031 G3): diff prev→next so we only toggle roles this prop owns,
+        // leaving any role hidden imperatively elsewhere untouched.
+        let prevHiddenRoles = [];
+        watch(() => props.hiddenFeatureRoles, (roles) => {
+            const next = roles ?? [];
+            for (const role of prevHiddenRoles)
+                if (!next.includes(role))
+                    preview.controls.setFeatureRoleVisible(role, true);
+            for (const role of next)
+                if (!prevHiddenRoles.includes(role))
+                    preview.controls.setFeatureRoleVisible(role, false);
+            prevHiddenRoles = [...next];
+        }, { immediate: true });
         watch(() => props.progress, (obs) => {
             if (obs === null)
                 preview.clearProgress();

package/dist/model/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @chestnutlabs/gcode-preview-vue/model — the Vue integration for interactive **source-model** viewing
+ * (STL / 3MF), the Prepare-side counterpart to the toolpath `<GcodePreview>` (DD-031). `useModelViewer`
+ * composable + `<ModelViewer>` component, both thin reactivity bridges over `createModelPreviewController`.
+ */
+export { useModelViewer } from './use-model-viewer.js';
+export type { ModelViewerHandle, UseModelViewerOptions, ModelPreviewControls, ModelPreviewState, ModelViewerEvent, ModelReadyInfo } from './use-model-viewer.js';
+export { ModelViewer } from './model-viewer-component.js';
+export type { ModelViewerSource } from './model-viewer-component.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/model/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/model/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,YAAY,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/model/index.js

@@ -0,0 +1,7 @@
+/**
+ * @chestnutlabs/gcode-preview-vue/model — the Vue integration for interactive **source-model** viewing
+ * (STL / 3MF), the Prepare-side counterpart to the toolpath `<GcodePreview>` (DD-031). `useModelViewer`
+ * composable + `<ModelViewer>` component, both thin reactivity bridges over `createModelPreviewController`.
+ */
+export { useModelViewer } from './use-model-viewer.js';
+export { ModelViewer } from './model-viewer-component.js';

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

@@ -0,0 +1,175 @@
+/**
+ * <ModelViewer> — the ready-to-use Vue component for interactive source-model viewing (STL / 3MF),
+ * the Prepare-side counterpart to <GcodePreview> (DD-031). A SHELL over `useModelViewer`: every prop
+ * maps to a composable/controls call, every emit re-fires a controller event, and the handle is
+ * exposed via `defineExpose`. Render-function component (no SFC) — the template is a single <canvas>.
+ */
+import { type PropType } from 'vue';
+import type { CameraMode, CameraState, CameraView, GLRendererLike, InteractiveStageOptions, LoadProgress, RenderTargetCanvas } from '@chestnutlabs/gcode-renderer-three';
+import type { ModelBackground, ModelLimits, ModelLoader, ModelReadyInfo, ModelSourceInput, PresentationView, RenderScope } from '@chestnutlabs/gcode-model-renderer';
+export type ModelViewerSource = ModelSourceInput | null;
+export declare const ModelViewer: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** The one required-in-practice prop: the source model. Changing it re-parses. */
+    source: {
+        type: PropType<ModelViewerSource>;
+        default: null;
+    };
+    /** Snap to a preset orientation (shared vocabulary with the toolpath camera). */
+    view: {
+        type: PropType<PresentationView | CameraView>;
+        default: undefined;
+    };
+    /** Restore a saved camera pose. Pair with `@camera-change` for two-way binding. */
+    cameraState: {
+        type: PropType<CameraState | null>;
+        default: undefined;
+    };
+    /** `'transparent'` (default) | CSS colour | `0xRRGGBB`. */
+    background: {
+        type: PropType<ModelBackground>;
+        default: undefined;
+    };
+    /** DD-020 interaction-aware quality; default `'auto'`. */
+    interactionQuality: {
+        type: PropType<"off" | "auto">;
+        default: undefined;
+    };
+    /** Initial camera projection; default `'perspective'`. */
+    cameraMode: {
+        type: PropType<CameraMode>;
+        default: undefined;
+    };
+    /** Render only a subset: `{ plateId }` / `{ objectIds }` / `{ instanceFilter }`; null = whole source. */
+    renderScope: {
+        type: PropType<RenderScope | null>;
+        default: undefined;
+    };
+    /** Source-model triangle / byte caps. */
+    limits: {
+        type: PropType<ModelLimits>;
+        default: undefined;
+    };
+    /** 3MF `paint_color` palette override (hex per 0-based slot). */
+    filamentPalette: {
+        type: PropType<readonly (string | undefined)[]>;
+        default: undefined;
+    };
+    /** Loader registry (open `kind`). Default: STL + 3MF. */
+    loaders: {
+        type: PropType<readonly ModelLoader[]>;
+        default: undefined;
+    };
+    /** Advanced/test: inject GL / orbit controls. */
+    createRenderer: {
+        type: PropType<(canvas: RenderTargetCanvas) => GLRendererLike>;
+        default: undefined;
+    };
+    createControls: {
+        type: PropType<NonNullable<InteractiveStageOptions["createControls"]>>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: (_info: ModelReadyInfo) => true;
+    'camera-change': (_state: CameraState) => true;
+    error: (_e: {
+        code: string;
+        message: string;
+    }) => true;
+    'renderer-unsupported': (_e: {
+        feature: string;
+        message: string;
+    }) => true;
+    'context-lost': () => true;
+    'context-restored': () => true;
+    progress: (_p: LoadProgress) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** The one required-in-practice prop: the source model. Changing it re-parses. */
+    source: {
+        type: PropType<ModelViewerSource>;
+        default: null;
+    };
+    /** Snap to a preset orientation (shared vocabulary with the toolpath camera). */
+    view: {
+        type: PropType<PresentationView | CameraView>;
+        default: undefined;
+    };
+    /** Restore a saved camera pose. Pair with `@camera-change` for two-way binding. */
+    cameraState: {
+        type: PropType<CameraState | null>;
+        default: undefined;
+    };
+    /** `'transparent'` (default) | CSS colour | `0xRRGGBB`. */
+    background: {
+        type: PropType<ModelBackground>;
+        default: undefined;
+    };
+    /** DD-020 interaction-aware quality; default `'auto'`. */
+    interactionQuality: {
+        type: PropType<"off" | "auto">;
+        default: undefined;
+    };
+    /** Initial camera projection; default `'perspective'`. */
+    cameraMode: {
+        type: PropType<CameraMode>;
+        default: undefined;
+    };
+    /** Render only a subset: `{ plateId }` / `{ objectIds }` / `{ instanceFilter }`; null = whole source. */
+    renderScope: {
+        type: PropType<RenderScope | null>;
+        default: undefined;
+    };
+    /** Source-model triangle / byte caps. */
+    limits: {
+        type: PropType<ModelLimits>;
+        default: undefined;
+    };
+    /** 3MF `paint_color` palette override (hex per 0-based slot). */
+    filamentPalette: {
+        type: PropType<readonly (string | undefined)[]>;
+        default: undefined;
+    };
+    /** Loader registry (open `kind`). Default: STL + 3MF. */
+    loaders: {
+        type: PropType<readonly ModelLoader[]>;
+        default: undefined;
+    };
+    /** Advanced/test: inject GL / orbit controls. */
+    createRenderer: {
+        type: PropType<(canvas: RenderTargetCanvas) => GLRendererLike>;
+        default: undefined;
+    };
+    createControls: {
+        type: PropType<NonNullable<InteractiveStageOptions["createControls"]>>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    onError?: ((_e: {
+        code: string;
+        message: string;
+    }) => any) | undefined;
+    onReady?: ((_info: ModelReadyInfo) => any) | undefined;
+    onProgress?: ((_p: LoadProgress) => any) | undefined;
+    "onCamera-change"?: ((_state: CameraState) => any) | undefined;
+    "onRenderer-unsupported"?: ((_e: {
+        feature: string;
+        message: string;
+    }) => any) | undefined;
+    "onContext-lost"?: (() => any) | undefined;
+    "onContext-restored"?: (() => any) | undefined;
+}>, {
+    source: ModelViewerSource;
+    cameraMode: CameraMode;
+    interactionQuality: "auto" | "off";
+    createRenderer: (canvas: RenderTargetCanvas) => GLRendererLike;
+    view: CameraView;
+    cameraState: CameraState | null;
+    createControls: (camera: import("three").PerspectiveCamera | import("three").OrthographicCamera, domElement: HTMLElement) => import("@chestnutlabs/gcode-renderer-three").ControlsLike;
+    background: ModelBackground;
+    renderScope: RenderScope | null;
+    limits: ModelLimits;
+    filamentPalette: readonly (string | undefined)[];
+    loaders: readonly ModelLoader[];
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//# sourceMappingURL=model-viewer-component.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-viewer-component.d.ts","sourceRoot":"","sources":["../../src/model/model-viewer-component.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,KAAK,CAAC;AACpE,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,uBAAuB,EACvB,YAAY,EACZ,kBAAkB,EACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAG5C,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,IAAI,CAAC;AAExD,eAAO,MAAM,WAAW;IAGpB,kFAAkF;;cAC7B,QAAQ,CAAC,iBAAiB,CAAC;;;IAChF,iFAAiF;;cACzD,QAAQ,CAAC,gBAAgB,GAAG,UAAU,CAAC;;;IAC/D,mFAAmF;;cACpD,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;;;IAC3D,2DAA2D;;cACnB,QAAQ,CAAC,eAAe,CAAC;;;IACjE,0DAA0D;;cACpB,QAAQ,CAAC,KAAK,GAAG,MAAM,CAAC;;;IAC9D,0DAA0D;;cAC5B,QAAQ,CAAC,UAAU,CAAC;;;IAClD,yGAAyG;;cAC1E,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;;;IAC3D,yCAAyC;;cACf,QAAQ,CAAC,WAAW,CAAC;;;IAC/C,iEAAiE;;cAC/B,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;;;IAC3E,yDAAyD;;cAC/B,QAAQ,CAAC,SAAS,WAAW,EAAE,CAAC;;;IAC1D,iDAAiD;;cAE7B,QAAQ,CAAC,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;;;;cAIxD,QAAQ,CAAC,WAAW,CAAC,uBAAuB,CAAC,gBAAgB,CAAC,CAAC,CAAC;;;;;;mBAMrE,cAAc;8BACH,WAAW;gBACzB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;iCAChB;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;;;mBAGlD,YAAY;;IAtC3B,kFAAkF;;cAC7B,QAAQ,CAAC,iBAAiB,CAAC;;;IAChF,iFAAiF;;cACzD,QAAQ,CAAC,gBAAgB,GAAG,UAAU,CAAC;;;IAC/D,mFAAmF;;cACpD,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;;;IAC3D,2DAA2D;;cACnB,QAAQ,CAAC,eAAe,CAAC;;;IACjE,0DAA0D;;cACpB,QAAQ,CAAC,KAAK,GAAG,MAAM,CAAC;;;IAC9D,0DAA0D;;cAC5B,QAAQ,CAAC,UAAU,CAAC;;;IAClD,yGAAyG;;cAC1E,QAAQ,CAAC,WAAW,GAAG,IAAI,CAAC;;;IAC3D,yCAAyC;;cACf,QAAQ,CAAC,WAAW,CAAC;;;IAC/C,iEAAiE;;cAC/B,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;;;IAC3E,yDAAyD;;cAC/B,QAAQ,CAAC,SAAS,WAAW,EAAE,CAAC;;;IAC1D,iDAAiD;;cAE7B,QAAQ,CAAC,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;;;;cAIxD,QAAQ,CAAC,WAAW,CAAC,uBAAuB,CAAC,gBAAgB,CAAC,CAAC,CAAC;;;;;cAQhE,MAAM;iBAAW,MAAM;;;;;;iBACH,MAAM;iBAAW,MAAM;;;;;;;;6BAbzB,kBAAkB,KAAK,cAAc;;;;;;;;;4EAiH7E,CAAC"}

package/dist/model/model-viewer-component.js

@@ -0,0 +1,127 @@
+/**
+ * <ModelViewer> — the ready-to-use Vue component for interactive source-model viewing (STL / 3MF),
+ * the Prepare-side counterpart to <GcodePreview> (DD-031). A SHELL over `useModelViewer`: every prop
+ * maps to a composable/controls call, every emit re-fires a controller event, and the handle is
+ * exposed via `defineExpose`. Render-function component (no SFC) — the template is a single <canvas>.
+ */
+import { defineComponent, h, ref, watch } from 'vue';
+import { useModelViewer } from './use-model-viewer.js';
+export const ModelViewer = defineComponent({
+    name: 'ModelViewer',
+    props: {
+        /** The one required-in-practice prop: the source model. Changing it re-parses. */
+        source: { type: [Object, Uint8Array, ArrayBuffer], default: null },
+        /** Snap to a preset orientation (shared vocabulary with the toolpath camera). */
+        view: { type: String, default: undefined },
+        /** Restore a saved camera pose. Pair with `@camera-change` for two-way binding. */
+        cameraState: { type: Object, default: undefined },
+        /** `'transparent'` (default) | CSS colour | `0xRRGGBB`. */
+        background: { type: [String, Number], default: undefined },
+        /** DD-020 interaction-aware quality; default `'auto'`. */
+        interactionQuality: { type: String, default: undefined },
+        /** Initial camera projection; default `'perspective'`. */
+        cameraMode: { type: String, default: undefined },
+        /** Render only a subset: `{ plateId }` / `{ objectIds }` / `{ instanceFilter }`; null = whole source. */
+        renderScope: { type: Object, default: undefined },
+        /** Source-model triangle / byte caps. */
+        limits: { type: Object, default: undefined },
+        /** 3MF `paint_color` palette override (hex per 0-based slot). */
+        filamentPalette: { type: Array, default: undefined },
+        /** Loader registry (open `kind`). Default: STL + 3MF. */
+        loaders: { type: Array, default: undefined },
+        /** Advanced/test: inject GL / orbit controls. */
+        createRenderer: {
+            type: Function,
+            default: undefined
+        },
+        createControls: {
+            type: Function,
+            default: undefined
+        }
+    },
+    emits: {
+        /* eslint-disable @typescript-eslint/no-unused-vars -- emit validators document payloads */
+        ready: (_info) => true,
+        'camera-change': (_state) => true,
+        error: (_e) => true,
+        'renderer-unsupported': (_e) => true,
+        'context-lost': () => true,
+        'context-restored': () => true,
+        progress: (_p) => true
+        /* eslint-enable @typescript-eslint/no-unused-vars */
+    },
+    setup(props, { emit, expose }) {
+        const viewer = useModelViewer({
+            ...(props.background !== undefined ? { background: props.background } : {}),
+            ...(props.interactionQuality !== undefined ? { interactionQuality: props.interactionQuality } : {}),
+            ...(props.cameraMode !== undefined ? { cameraMode: props.cameraMode } : {}),
+            ...(props.limits !== undefined ? { limits: props.limits } : {}),
+            ...(props.filamentPalette !== undefined ? { filamentPalette: props.filamentPalette } : {}),
+            ...(props.loaders !== undefined ? { loaders: props.loaders } : {}),
+            ...(props.renderScope != null ? { renderScope: props.renderScope } : {}),
+            ...(props.createRenderer !== undefined ? { createRenderer: props.createRenderer } : {}),
+            ...(props.createControls !== undefined ? { createControls: props.createControls } : {}),
+            onProgress: (p) => emit('progress', p)
+        });
+        viewer.onEvent((e) => {
+            switch (e.type) {
+                case 'ready':
+                    emit('ready', e.info);
+                    break;
+                case 'camera-changed':
+                    emit('camera-change', e.state);
+                    break;
+                case 'error':
+                    emit('error', { code: e.code, message: e.message });
+                    break;
+                case 'renderer-unsupported':
+                    emit('renderer-unsupported', { feature: e.feature, message: e.message });
+                    break;
+                case 'context-lost':
+                    emit('context-lost');
+                    break;
+                case 'context-restored':
+                    emit('context-restored');
+                    break;
+                default:
+                    break;
+            }
+        });
+        // Runtime-only props apply immediately on mount (Vue's watch is change-only by default).
+        watch(() => props.source, (source) => {
+            if (source !== null && source !== undefined)
+                void viewer.controls.setSource(source);
+        }, { immediate: true });
+        watch(() => props.view, (view) => {
+            if (view !== undefined)
+                viewer.controls.setView(view);
+        }, { immediate: true });
+        watch(() => props.cameraState, (state) => {
+            if (state !== undefined && state !== null)
+                viewer.controls.setCameraState(state);
+        }, { immediate: true });
+        watch(() => props.background, (bg) => {
+            if (bg !== undefined)
+                viewer.controls.setBackground(bg);
+        });
+        watch(() => props.interactionQuality, (mode) => {
+            if (mode !== undefined)
+                viewer.controls.setInteractionQuality(mode);
+        });
+        watch(() => props.renderScope, (scope) => {
+            if (scope !== undefined)
+                viewer.controls.setRenderScope(scope);
+        });
+        expose({ viewer });
+        const canvasEl = ref(null);
+        watch(canvasEl, (el) => {
+            viewer.canvasRef.value = el;
+        });
+        return () => h('canvas', {
+            ref: canvasEl,
+            style: { width: '100%', height: '100%', display: 'block', touchAction: 'none' },
+            tabindex: '0',
+            'aria-label': '3D source-model preview'
+        });
+    }
+});

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

@@ -0,0 +1,28 @@
+/**
+ * useModelViewer — the Vue reactivity bridge for interactive **source-model** viewing (the Prepare
+ * side), the analogue of `useGcodePreview` for the toolpath/Preview side (DD-031). Owns only the
+ * Vue-isms: a canvas template ref, a shallow-reactive state mirror fed by controller snapshots, and
+ * scope-tied disposal. The engine/state/contracts live in `@chestnutlabs/gcode-model-renderer` and are
+ * re-exported, never redeclared (the D1 drift firewall).
+ */
+import { type Ref } from 'vue';
+import { type ModelPreviewControllerOptions, type ModelPreviewControls, type ModelPreviewState, type ModelViewer, type ModelViewerEvent, type ModelReadyInfo } from '@chestnutlabs/gcode-model-renderer';
+import type { CaptureOptions } from '@chestnutlabs/gcode-renderer-three';
+export type { ModelPreviewControls, ModelPreviewState, ModelViewerEvent, ModelReadyInfo };
+/** Vue-facing options — identical to the controller's (the alias is the public name). */
+export type UseModelViewerOptions = ModelPreviewControllerOptions;
+export interface ModelViewerHandle {
+    /** Bind to a <canvas> template ref; rebinding disposes and rebuilds safely. */
+    canvasRef: Ref<HTMLCanvasElement | null>;
+    setSource: ModelPreviewControls['setSource'];
+    capture(opts?: CaptureOptions): Promise<Blob>;
+    state: Readonly<ModelPreviewState>;
+    controls: ModelPreviewControls;
+    raw: {
+        viewer: () => ModelViewer | null;
+    };
+    onEvent(cb: (e: ModelViewerEvent) => void): () => void;
+    dispose(): void;
+}
+export declare function useModelViewer(options?: UseModelViewerOptions): ModelViewerHandle;
+//# sourceMappingURL=use-model-viewer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-model-viewer.d.ts","sourceRoot":"","sources":["../../src/model/use-model-viewer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAA0E,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AACvG,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC;AAC1F,yFAAyF;AACzF,MAAM,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,SAAS,EAAE,GAAG,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACzC,SAAS,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC7C,OAAO,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,KAAK,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,WAAW,GAAG,IAAI,CAAA;KAAE,CAAC;IAC1C,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACvD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,iBAAiB,CA2BrF"}

package/dist/model/use-model-viewer.js

@@ -0,0 +1,34 @@
+/**
+ * useModelViewer — the Vue reactivity bridge for interactive **source-model** viewing (the Prepare
+ * side), the analogue of `useGcodePreview` for the toolpath/Preview side (DD-031). Owns only the
+ * Vue-isms: a canvas template ref, a shallow-reactive state mirror fed by controller snapshots, and
+ * scope-tied disposal. The engine/state/contracts live in `@chestnutlabs/gcode-model-renderer` and are
+ * re-exported, never redeclared (the D1 drift firewall).
+ */
+import { getCurrentScope, onScopeDispose, readonly, ref, shallowReactive, watch } from 'vue';
+import { createModelPreviewController } from '@chestnutlabs/gcode-model-renderer';
+export function useModelViewer(options = {}) {
+    const controller = createModelPreviewController(options);
+    const state = shallowReactive({ ...controller.getState() });
+    const offState = controller.onStateChange((snap) => {
+        Object.assign(state, snap);
+    });
+    const canvasRef = ref(null);
+    watch(canvasRef, (canvas) => controller.bindCanvas(canvas));
+    function dispose() {
+        offState();
+        controller.dispose();
+    }
+    if (getCurrentScope() !== undefined)
+        onScopeDispose(dispose);
+    return {
+        canvasRef,
+        setSource: controller.controls.setSource,
+        capture: controller.controls.capture,
+        state: readonly(state),
+        controls: controller.controls,
+        raw: controller.raw,
+        onEvent: controller.onEvent,
+        dispose
+    };
+}

package/dist/use-gcode-preview.d.ts

@@ -10,7 +10,7 @@
 import { type Ref } from 'vue';
 import type { GcodeParseSession, WireParseOptions } from '@chestnutlabs/gcode-parser';
 import type { MappedProgress, ProgressObservation } from '@chestnutlabs/toolpath-core';
-import { type GcodePreviewControls, type GcodePreviewState, type ParseOutcome, type PreviewControllerOptions, type PreviewEvent, type PreviewRenderer } from '@chestnutlabs/gcode-preview-core';
+import { type CaptureOptions, type GcodePreviewControls, type GcodePreviewState, type ParseOutcome, type PreviewControllerOptions, type PreviewEvent, type PreviewRenderer } from '@chestnutlabs/gcode-preview-core';
 export type { GcodePreviewControls, GcodePreviewState, ParseOutcome, PreviewEvent, PreviewRenderer, RendererMode } from '@chestnutlabs/gcode-preview-core';
 /** Vue-facing options — identical to the controller's (the alias is the public name). */
 export type UseGcodePreviewOptions = PreviewControllerOptions;
@@ -24,6 +24,9 @@ export interface GcodePreviewHandle {
     /** Recompute staleness (DD-006 §4.4.3) — call at ~1 Hz while telemetry may go quiet. */
     tickProgress(nowMs: number): MappedProgress | null;
     clearProgress(): void;
+    /** Capture the current view as an image `Blob` (DD-030 D1, DD-031 G5) — handle-level parity with the
+     *  Web Component's `capture()`. Also reachable as `controls.capture`. Rejects on the 2D renderer. */
+    capture(opts?: CaptureOptions): Promise<Blob>;
     state: Readonly<GcodePreviewState>;
     controls: GcodePreviewControls;
     /** Escape hatches — the neutral objects themselves (advanced use; not reactive). */

package/dist/use-gcode-preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-gcode-preview.d.ts","sourceRoot":"","sources":["../src/use-gcode-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAA0E,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AACvG,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACb,MAAM,kCAAkC,CAAC;AAE1C,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,SAAS,EAAE,GAAG,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9F,MAAM,IAAI,IAAI,CAAC;IACf,yFAAyF;IACzF,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAAC;IACjE,wFAAwF;IACxF,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IACnD,aAAa,IAAI,IAAI,CAAC;IACtB,KAAK,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,oFAAoF;IACpF,GAAG,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,MAAM,eAAe,GAAG,IAAI,CAAA;KAAE,CAAC;IAC5E,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,kBAAkB,CAiCxF"}
+{"version":3,"file":"use-gcode-preview.d.ts","sourceRoot":"","sources":["../src/use-gcode-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAA0E,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AACvG,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACb,MAAM,kCAAkC,CAAC;AAE1C,yFAAyF;AACzF,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,SAAS,EAAE,GAAG,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9F,MAAM,IAAI,IAAI,CAAC;IACf,yFAAyF;IACzF,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAAC;IACjE,wFAAwF;IACxF,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IACnD,aAAa,IAAI,IAAI,CAAC;IACtB;yGACqG;IACrG,OAAO,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,KAAK,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACnC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,oFAAoF;IACpF,GAAG,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,MAAM,eAAe,GAAG,IAAI,CAAA;KAAE,CAAC;IAC5E,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,kBAAkB,CAkCxF"}

package/dist/use-gcode-preview.js

@@ -33,6 +33,7 @@ export function useGcodePreview(options = {}) {
         observeProgress: controller.observeProgress,
         tickProgress: controller.tickProgress,
         clearProgress: controller.clearProgress,
+        capture: controller.controls.capture,
         state: readonly(state),
         controls: controller.controls,
         raw: controller.raw,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chestnutlabs/gcode-preview-vue",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Thin Vue 3 integration for the Chestnut Labs G-code viewer (DD-007): useGcodePreview composable + GcodePreview component over the framework-neutral parser/renderer/progress packages.",
   "keywords": [
     "gcode",
@@ -36,6 +36,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "import": "./dist/model/index.js"
     }
   },
   "files": [
@@ -50,10 +54,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@chestnutlabs/gcode-parser": "0.19.0",
-    "@chestnutlabs/gcode-renderer-three": "0.19.0",
-    "@chestnutlabs/toolpath-core": "0.19.0",
-    "@chestnutlabs/gcode-preview-core": "0.19.0"
+    "@chestnutlabs/gcode-model-renderer": "0.20.0",
+    "@chestnutlabs/gcode-parser": "0.20.0",
+    "@chestnutlabs/gcode-renderer-three": "0.20.0",
+    "@chestnutlabs/toolpath-core": "0.20.0",
+    "@chestnutlabs/gcode-preview-core": "0.20.0"
   },
   "peerDependencies": {
     "vue": "^3.4.0"