@chestnutlabs/gcode-preview-element 0.2.0

package/README.md

@@ -0,0 +1,74 @@
+# @chestnutlabs/gcode-preview-element
+
+A framework-free **`<gcode-preview>` Web Component** for the Chestnut Labs G-code viewer — a thin
+custom-element shell over [`@chestnutlabs/gcode-preview-core`](../gcode-preview-core), the same engine
+the Vue/React/Svelte adapters wrap. Use it from plain HTML, Angular, or any framework — **no peer
+framework dependency**.
+
+## Install
+
+```sh
+npm install @chestnutlabs/gcode-preview-element three
+```
+
+`three` is a peer dependency of the underlying renderer.
+
+## Usage
+
+```html
+<script type="module">
+  import '@chestnutlabs/gcode-preview-element/define'; // registers <gcode-preview>
+
+  const el = document.querySelector('gcode-preview');
+  el.addEventListener('ready', (e) => console.log('parsed', e.detail));
+  document.querySelector('input[type=file]').addEventListener('change', (ev) => {
+    el.source = ev.target.files[0]; // a File / Uint8Array / ArrayBuffer
+  });
+</script>
+
+<gcode-preview quality="tubes" show-travel="false" style="width: 100%; height: 70vh"></gcode-preview>
+```
+
+Prefer explicit registration? Import the function instead of the side-effectful entry:
+
+```js
+import { defineGcodePreview } from '@chestnutlabs/gcode-preview-element';
+defineGcodePreview(); // idempotent; defaults to the <gcode-preview> tag
+```
+
+## Surface
+
+Scalar options are **attributes** (also settable as properties); rich options are **properties**.
+
+| Attribute | Property | Type | Default |
+|---|---|---|---|
+| `quality` | `quality` | `'auto' \| 'lines' \| 'tubes'` | `'auto'` |
+| `camera-mode` | `cameraMode` | `'perspective' \| 'orthographic'` | `'perspective'` |
+| `show-travel` | `showTravel` | `"true" \| "false"` | `true` |
+| `show-retractions` | `showRetractions` | `"true" \| "false"` | `false` |
+| `scrub` | `scrub` | integer | — (all) |
+| `layer-range` | `layerRange` | `"start,end"` / `[number, number]` | — (all) |
+| — | `source` | `Uint8Array \| ArrayBuffer \| File` | `null` |
+| — | `colorMode` | `ColorMode` | — |
+| — | `theme` | `Theme` | — |
+| — | `buildVolume` | `BuildVolumeDef \| MachineGeometry` | — |
+| — | `progress` | `ProgressObservation \| null` | `null` |
+| — | `createWorker` | `() => WorkerLike` | batteries default |
+
+> `source` is a **property only** (never a URL attribute) — the element does not fetch.
+
+### DOM events (`CustomEvent`, kebab-case `detail`)
+
+`ready` · `parse-error` · `parse-cancelled` · `parse-progress` · `build-complete` · `disclosure` ·
+`quality-fallback` · `progress-presentation-changed` · `machine-geometry-discovered` ·
+`machine-geometry-mismatch` · `error`.
+
+The underlying handle is also exposed as instance members (`state`, `controls`, `raw`, `onEvent`,
+`parse`, `observeProgress`, `tickProgress`, `clearProgress`) for advanced use — the same neutral
+controller surface the other adapters expose.
+
+## Workers
+
+By default the batteries worker parses off-thread. To supply a custom/slim worker, set the
+`createWorker` factory property (see the [Vue README](../gcode-preview-vue) for the shared worker
+notes). The element passes the same behavioral parity suite as the Vue/React/Svelte adapters.

package/dist/define.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":""}

package/dist/define.js

@@ -0,0 +1,7 @@
+/**
+ * Side-effectful registration entry: `import '@chestnutlabs/gcode-preview-element/define'`
+ * auto-registers `<gcode-preview>`. Kept as a separate subpath so the main `.` entry stays
+ * `sideEffects: false`.
+ */
+import { defineGcodePreview } from './index.js';
+defineGcodePreview();

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

@@ -0,0 +1,94 @@
+/**
+ * <gcode-preview> — the framework-free Web Component adapter (DD-007 D1 / DD-009 D5).
+ *
+ * Strictly a SHELL over `createPreviewController` (D1: never a separate implementation),
+ * exactly like the Vue/React/Svelte adapters: attributes and properties map to the same
+ * neutral controller options / `controls.*` calls, and controller events are re-emitted as
+ * DOM `CustomEvent`s (kebab-case). The underlying handle is also exposed as instance members
+ * (`state`/`controls`/`raw`/`onEvent`/`parse`/…) so the shared behavioral suite runs against
+ * it identically to the other three adapters.
+ *
+ * No framework peer dependency — this is the plain-DOM / Angular / vanilla path.
+ */
+import { createPreviewController, type GcodePreviewControls, type GcodePreviewState, type ParseOutcome, type PreviewController, type PreviewEvent } from '@chestnutlabs/gcode-preview-core';
+import type { BuildVolumeDef, ColorMode, Theme, TubeOptions } from '@chestnutlabs/gcode-renderer-three';
+import type { MachineGeometry, MappedProgress, ProgressObservation } from '@chestnutlabs/toolpath-core';
+import type { WireParseOptions, WorkerLike } from '@chestnutlabs/gcode-parser';
+export type GcodePreviewSource = Uint8Array | ArrayBuffer | File | null;
+/** Advanced/test renderer injectables (pass-throughs of the controller's renderer contract). */
+export type ElementRendererOptions = Omit<NonNullable<PreviewControllerRenderer>, 'buildVolume' | 'quality' | 'cameraMode' | 'theme' | 'colorMode' | 'tube'>;
+type PreviewControllerRenderer = NonNullable<Parameters<typeof createPreviewController>[0]>['renderer'];
+/** The default tag name (DD-009 §4.5). */
+export declare const DEFAULT_TAG = "gcode-preview";
+export declare class GcodePreviewElement extends HTMLElement {
+    static get observedAttributes(): string[];
+    private controller;
+    private canvasEl;
+    private _source;
+    private _parseOptions;
+    private _buildVolume;
+    private _colorMode;
+    private _tube;
+    private _theme;
+    private _progress;
+    private _createWorker;
+    private _rendererOptions;
+    get source(): GcodePreviewSource;
+    set source(v: GcodePreviewSource);
+    get parseOptions(): WireParseOptions | undefined;
+    set parseOptions(v: WireParseOptions | undefined);
+    get buildVolume(): BuildVolumeDef | MachineGeometry | undefined;
+    set buildVolume(v: BuildVolumeDef | MachineGeometry | undefined);
+    get colorMode(): ColorMode | undefined;
+    set colorMode(v: ColorMode | undefined);
+    get tube(): TubeOptions | undefined;
+    set tube(v: TubeOptions | undefined);
+    get theme(): Theme | undefined;
+    set theme(v: Theme | undefined);
+    get progress(): ProgressObservation | null;
+    set progress(v: ProgressObservation | null);
+    get createWorker(): (() => WorkerLike) | undefined;
+    set createWorker(v: (() => WorkerLike) | undefined);
+    get rendererOptions(): ElementRendererOptions | undefined;
+    set rendererOptions(v: ElementRendererOptions | undefined);
+    get quality(): string | null;
+    set quality(v: string | null);
+    get cameraMode(): string | null;
+    set cameraMode(v: string | null);
+    /** Default true; only `show-travel="false"` hides travel. */
+    get showTravel(): boolean;
+    set showTravel(v: boolean);
+    /** Default false; only `show-retractions="true"` shows markers. */
+    get showRetractions(): boolean;
+    set showRetractions(v: boolean);
+    get scrub(): number | null;
+    set scrub(v: number | null);
+    get layerRange(): [number, number] | null;
+    set layerRange(v: [number, number] | null);
+    get state(): GcodePreviewState;
+    get controls(): GcodePreviewControls;
+    get raw(): PreviewController['raw'];
+    parse(input: Uint8Array | ArrayBuffer | File, opts?: WireParseOptions): Promise<ParseOutcome>;
+    observeProgress(obs: ProgressObservation): MappedProgress | null;
+    tickProgress(nowMs: number): MappedProgress | null;
+    clearProgress(): void;
+    onEvent(cb: (e: PreviewEvent) => void): () => void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /** Apply the runtime-only controls (the construction options were set at controller creation). */
+    private applyRuntimeState;
+    private applyProgress;
+    private reflect;
+    private requireController;
+    /** Re-emit a controller event as a kebab-case DOM CustomEvent. */
+    private reemit;
+}
+/**
+ * Register `<gcode-preview>` (idempotent — safe to call repeatedly and from multiple
+ * bundles). Kept as a function (not a module side effect) so the package stays
+ * `sideEffects: false`; import `@chestnutlabs/gcode-preview-element/define` for auto-registration.
+ */
+export declare function defineGcodePreview(tag?: string): void;
+export {};
+//# sourceMappingURL=gcode-preview-element.d.ts.map

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

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

package/dist/gcode-preview-element.js

@@ -0,0 +1,330 @@
+/**
+ * <gcode-preview> — the framework-free Web Component adapter (DD-007 D1 / DD-009 D5).
+ *
+ * Strictly a SHELL over `createPreviewController` (D1: never a separate implementation),
+ * exactly like the Vue/React/Svelte adapters: attributes and properties map to the same
+ * neutral controller options / `controls.*` calls, and controller events are re-emitted as
+ * DOM `CustomEvent`s (kebab-case). The underlying handle is also exposed as instance members
+ * (`state`/`controls`/`raw`/`onEvent`/`parse`/…) so the shared behavioral suite runs against
+ * it identically to the other three adapters.
+ *
+ * No framework peer dependency — this is the plain-DOM / Angular / vanilla path.
+ */
+import { createPreviewController } from '@chestnutlabs/gcode-preview-core';
+/** Observed scalar/boolean/number attributes; rich options are property-only. */
+const OBSERVED = ['quality', 'camera-mode', 'show-travel', 'show-retractions', 'scrub', 'layer-range'];
+/** The default tag name (DD-009 §4.5). */
+export const DEFAULT_TAG = 'gcode-preview';
+export class GcodePreviewElement extends HTMLElement {
+    static get observedAttributes() {
+        return [...OBSERVED];
+    }
+    controller = null;
+    canvasEl = null;
+    // Rich options — objects/functions can't be attributes, so they are property-only.
+    _source = null;
+    _parseOptions;
+    _buildVolume;
+    _colorMode;
+    _tube;
+    _theme;
+    _progress = null;
+    _createWorker;
+    _rendererOptions;
+    // ---- rich-option property accessors ----
+    get source() {
+        return this._source;
+    }
+    set source(v) {
+        this._source = v;
+        if (this.controller !== null && v !== null)
+            void this.controller.parse(v, this._parseOptions);
+    }
+    get parseOptions() {
+        return this._parseOptions;
+    }
+    set parseOptions(v) {
+        this._parseOptions = v;
+    }
+    get buildVolume() {
+        return this._buildVolume;
+    }
+    set buildVolume(v) {
+        this._buildVolume = v;
+        if (this.controller !== null && v !== undefined && 'bed' in v)
+            this.controller.controls.setBuildVolume(v);
+    }
+    get colorMode() {
+        return this._colorMode;
+    }
+    set colorMode(v) {
+        this._colorMode = v;
+        if (this.controller !== null && v !== undefined)
+            this.controller.controls.setColorMode(v);
+    }
+    get tube() {
+        return this._tube;
+    }
+    set tube(v) {
+        this._tube = v; // construction-only (tube profile is fixed per renderer)
+    }
+    get theme() {
+        return this._theme;
+    }
+    set theme(v) {
+        this._theme = v;
+        if (this.controller !== null && v !== undefined)
+            this.controller.controls.setTheme(v);
+    }
+    get progress() {
+        return this._progress;
+    }
+    set progress(v) {
+        this._progress = v;
+        this.applyProgress();
+    }
+    get createWorker() {
+        return this._createWorker;
+    }
+    set createWorker(v) {
+        this._createWorker = v; // construction-only (a worker factory can't change mid-lifecycle)
+    }
+    get rendererOptions() {
+        return this._rendererOptions;
+    }
+    set rendererOptions(v) {
+        this._rendererOptions = v; // construction-only injectables
+    }
+    // ---- scalar-option accessors (reflect to attributes: one source of truth) ----
+    get quality() {
+        return this.getAttribute('quality');
+    }
+    set quality(v) {
+        this.reflect('quality', v);
+    }
+    get cameraMode() {
+        return this.getAttribute('camera-mode');
+    }
+    set cameraMode(v) {
+        this.reflect('camera-mode', v);
+    }
+    /** Default true; only `show-travel="false"` hides travel. */
+    get showTravel() {
+        return this.getAttribute('show-travel') !== 'false';
+    }
+    set showTravel(v) {
+        this.setAttribute('show-travel', v ? 'true' : 'false');
+    }
+    /** Default false; only `show-retractions="true"` shows markers. */
+    get showRetractions() {
+        return this.getAttribute('show-retractions') === 'true';
+    }
+    set showRetractions(v) {
+        this.setAttribute('show-retractions', v ? 'true' : 'false');
+    }
+    get scrub() {
+        const a = this.getAttribute('scrub');
+        return a === null ? null : Number(a);
+    }
+    set scrub(v) {
+        this.reflect('scrub', v);
+    }
+    get layerRange() {
+        return parseLayerRange(this.getAttribute('layer-range'));
+    }
+    set layerRange(v) {
+        this.reflect('layer-range', v === null ? null : `${v[0]},${v[1]}`);
+    }
+    // ---- handle-parity passthrough (advanced/parity surface; DOM events are the ergonomic one) ----
+    get state() {
+        return this.requireController().getState();
+    }
+    get controls() {
+        return this.requireController().controls;
+    }
+    get raw() {
+        return this.requireController().raw;
+    }
+    parse(input, opts) {
+        return this.requireController().parse(input, opts);
+    }
+    observeProgress(obs) {
+        return this.controller?.observeProgress(obs) ?? null;
+    }
+    tickProgress(nowMs) {
+        return this.controller?.tickProgress(nowMs) ?? null;
+    }
+    clearProgress() {
+        this.controller?.clearProgress();
+    }
+    onEvent(cb) {
+        return this.requireController().onEvent(cb);
+    }
+    // ---- lifecycle ----
+    connectedCallback() {
+        if (this.controller !== null)
+            return; // guard double-connect
+        const root = this.shadowRoot ?? this.attachShadow({ mode: 'open' });
+        root.replaceChildren();
+        const style = document.createElement('style');
+        style.textContent = ':host{display:block;width:100%;height:100%}canvas{display:block;width:100%;height:100%}';
+        const canvas = document.createElement('canvas');
+        canvas.setAttribute('aria-label', '3D G-code toolpath preview');
+        root.append(style, canvas);
+        this.canvasEl = canvas;
+        const isMachine = this._buildVolume !== undefined && 'bed' in this._buildVolume;
+        this.controller = createPreviewController({
+            createWorker: this._createWorker,
+            renderer: {
+                buildVolume: isMachine ? undefined : this._buildVolume,
+                quality: this.getAttribute('quality') ?? 'auto',
+                cameraMode: this.getAttribute('camera-mode') ?? undefined,
+                colorMode: this._colorMode,
+                tube: this._tube,
+                theme: this._theme,
+                ...this._rendererOptions
+            },
+            parseDefaults: this._parseOptions
+        });
+        this.controller.onEvent((e) => this.reemit(e));
+        this.controller.bindCanvas(canvas);
+        if (isMachine)
+            this.controller.controls.setBuildVolume(this._buildVolume);
+        this.applyRuntimeState();
+        if (this._source !== null)
+            void this.controller.parse(this._source, this._parseOptions);
+    }
+    disconnectedCallback() {
+        this.controller?.dispose();
+        this.controller = null;
+        this.canvasEl = null;
+        this.shadowRoot?.replaceChildren();
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (this.controller === null)
+            return; // connectedCallback applies the initial state
+        const c = this.controller.controls;
+        switch (name) {
+            case 'quality':
+                c.setQuality(value ?? 'auto');
+                break;
+            case 'camera-mode':
+                if (value !== null)
+                    c.setCameraMode(value);
+                break;
+            case 'show-travel':
+                c.setKindVisible('travel', value !== 'false');
+                break;
+            case 'show-retractions':
+                c.setShowRetractions(value === 'true');
+                break;
+            case 'scrub':
+                c.setScrubPosition(value === null ? null : Number(value));
+                break;
+            case 'layer-range': {
+                const r = parseLayerRange(value);
+                if (r === null)
+                    c.setLayerRange(0, Number.POSITIVE_INFINITY);
+                else
+                    c.setLayerRange(r[0], r[1]);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // ---- internals ----
+    /** Apply the runtime-only controls (the construction options were set at controller creation). */
+    applyRuntimeState() {
+        const c = this.requireController().controls;
+        c.setKindVisible('travel', this.showTravel);
+        c.setShowRetractions(this.showRetractions);
+        const r = this.layerRange;
+        if (r === null)
+            c.setLayerRange(0, Number.POSITIVE_INFINITY);
+        else
+            c.setLayerRange(r[0], r[1]);
+        c.setScrubPosition(this.scrub);
+        this.applyProgress();
+    }
+    applyProgress() {
+        if (this.controller === null)
+            return;
+        if (this._progress === null)
+            this.controller.clearProgress();
+        else
+            this.controller.observeProgress(this._progress);
+    }
+    reflect(attr, v) {
+        if (v === null)
+            this.removeAttribute(attr);
+        else
+            this.setAttribute(attr, String(v));
+    }
+    requireController() {
+        if (this.controller === null) {
+            throw new Error('<gcode-preview>: not connected to the DOM yet (no controller). Append it before use.');
+        }
+        return this.controller;
+    }
+    /** Re-emit a controller event as a kebab-case DOM CustomEvent. */
+    reemit(e) {
+        const emit = (type, detail) => {
+            this.dispatchEvent(new CustomEvent(type, { detail }));
+        };
+        switch (e.type) {
+            case 'parse-complete':
+                emit('ready', { segments: e.segments, layers: e.layers, complete: e.complete });
+                break;
+            case 'parse-error':
+                emit('parse-error', { code: e.code, message: e.message });
+                break;
+            case 'parse-cancelled':
+                emit('parse-cancelled');
+                break;
+            case 'parse-progress':
+                emit('parse-progress', { bytesProcessed: e.progress.bytesProcessed, totalBytes: e.progress.totalBytes });
+                break;
+            case 'buildComplete':
+                emit('build-complete', { segments: e.segments, quality: e.quality });
+                emit('disclosure', { text: this.controller?.getState().disclosure ?? '' });
+                break;
+            case 'qualityFallback':
+                emit('quality-fallback', { from: e.from, to: e.to, reason: e.reason });
+                break;
+            case 'progress-presentation-changed':
+                emit('progress-presentation-changed', e.reason === undefined ? { mode: e.mode } : { mode: e.mode, reason: e.reason });
+                break;
+            case 'machine-geometry-discovered':
+                emit('machine-geometry-discovered', { machine: e.machine });
+                break;
+            case 'error':
+                if (e.code === 'machine-geometry-mismatch')
+                    emit('machine-geometry-mismatch', { message: e.message });
+                else
+                    emit('error', { code: e.code, message: e.message });
+                break;
+            default:
+                break;
+        }
+    }
+}
+function parseLayerRange(value) {
+    if (value === null)
+        return null;
+    const parts = value.split(',').map((s) => Number(s.trim()));
+    if (parts.length !== 2 || parts.some((n) => Number.isNaN(n)))
+        return null;
+    return [parts[0], parts[1]];
+}
+/**
+ * Register `<gcode-preview>` (idempotent — safe to call repeatedly and from multiple
+ * bundles). Kept as a function (not a module side effect) so the package stays
+ * `sideEffects: false`; import `@chestnutlabs/gcode-preview-element/define` for auto-registration.
+ */
+export function defineGcodePreview(tag = DEFAULT_TAG) {
+    if (typeof customElements === 'undefined')
+        return;
+    if (customElements.get(tag) === undefined)
+        customElements.define(tag, GcodePreviewElement);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @chestnutlabs/gcode-preview-element — the framework-free `<gcode-preview>` Web Component
+ * adapter (DD-009 D5), a thin shell over @chestnutlabs/gcode-preview-core. Registration is a
+ * function (`defineGcodePreview`) so the `.` entry stays side-effect-free; import
+ * `@chestnutlabs/gcode-preview-element/define` to auto-register.
+ */
+export { GcodePreviewElement, defineGcodePreview, DEFAULT_TAG, type GcodePreviewSource, type ElementRendererOptions } from './gcode-preview-element.js';
+export type { GcodePreviewControls, GcodePreviewState, ParseOutcome, PreviewEvent } from '@chestnutlabs/gcode-preview-core';
+//# 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,EACL,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAGpC,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACb,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @chestnutlabs/gcode-preview-element — the framework-free `<gcode-preview>` Web Component
+ * adapter (DD-009 D5), a thin shell over @chestnutlabs/gcode-preview-core. Registration is a
+ * function (`defineGcodePreview`) so the `.` entry stays side-effect-free; import
+ * `@chestnutlabs/gcode-preview-element/define` to auto-register.
+ */
+export { GcodePreviewElement, defineGcodePreview, DEFAULT_TAG } from './gcode-preview-element.js';

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@chestnutlabs/gcode-preview-element",
+  "version": "0.2.0",
+  "description": "Framework-free <gcode-preview> Web Component for the Chestnut Labs G-code viewer (DD-007 D1 / DD-009 D5): a custom element bridging @chestnutlabs/gcode-preview-core, no framework peer dependency.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "web-component",
+    "custom-element",
+    "viewer",
+    "preview"
+  ],
+  "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-preview-element"
+  },
+  "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"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/gcode-parser": "0.2.0",
+    "@chestnutlabs/gcode-preview-core": "0.2.0",
+    "@chestnutlabs/gcode-renderer-three": "0.2.0",
+    "@chestnutlabs/toolpath-core": "0.2.0"
+  }
+}