@chestnutlabs/gcode-preview-vue 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @chestnutlabs/gcode-preview-vue
+
+Thin Vue 3 integration for the Chestnut Labs G-code viewer: parse `.gcode` / `.gcode.3mf` off the
+main thread, render an interactive Three.js toolpath (layers, scrub, per-file build plates, honest
+live progress), and never block your UI. This package is glue only — the engine lives in
+`@chestnutlabs/gcode-parser`, `@chestnutlabs/gcode-renderer-three`, and
+`@chestnutlabs/toolpath-core` (design: DD-007).
+
+```sh
+npm install @chestnutlabs/gcode-preview-vue three
+```
+
+(`three` is a peerDependency of the renderer, supported range `^0.178.0` — npm ≥ 7 installs it
+automatically; pnpm/yarn users add it explicitly. See the
+[support policy](../../docs/reference/support-policy.md).)
+
+Two adoption levels, one implementation (the component is a shell over the composable):
+
+## Ready-to-use component
+
+```vue
+<script setup lang="ts">
+import { GcodePreview } from '@chestnutlabs/gcode-preview-vue';
+import { shallowRef } from 'vue';
+
+const file = shallowRef<File | null>(null);
+</script>
+
+<template>
+  <input type="file" accept=".gcode,.3mf" @change="file = ($event.target as HTMLInputElement).files?.[0] ?? null" />
+  <div style="height: 70vh">
+    <GcodePreview :source="file" @ready="(s) => console.log(`${s.segments} segments`)" />
+  </div>
+</template>
+```
+
+That is a complete viewer. The full surface is optional props with sensible defaults:
+
+| Prop | Purpose |
+|---|---|
+| `source` | `Uint8Array \| ArrayBuffer \| File` — changing it re-parses |
+| `parse-options` | wire options (limits, dialects, containers, plate selection) |
+| `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 |
+| `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`,
+`progress-presentation-changed`, `disclosure`, `error`. The underlying handle is exposed for
+template refs (`ref.preview`).
+
+## Headless composable (build your own controls)
+
+```ts
+import { useGcodePreview } from '@chestnutlabs/gcode-preview-vue';
+
+const preview = useGcodePreview();          // in setup(); auto-disposes with the scope
+// bind: <canvas :ref="(el) => (preview.canvasRef.value = el as HTMLCanvasElement)" />
+await preview.parse(bytes);                 // worker parse + progressive preview
+preview.controls.setLayerRange(0, 42);      // scrub / colors / quality / bed / frame ...
+preview.observeProgress(obs);               // DD-006 live progress (tick ~1 Hz for staleness)
+preview.state;                              // shallow read-only reactive summaries
+preview.raw.session; preview.raw.renderer();// escape hatches (non-reactive)
+```
+
+The composable owns the sharp edges: dispose-on-unmount/HMR, SSR-import safety, canvas resize
+(ResizeObserver + fallback), and a strict reactivity boundary (toolpath buffers are never proxied).
+
+## Workers: default and custom (both first-class)
+
+**Default (zero setup):** the batteries worker — all supported slicer/firmware dialect adapters
+plus `.gcode.3mf` container support — is created automatically via the bundler-native
+`new Worker(new URL(...))` pattern. Vite resolves this out of the box (this path is exercised by
+the repo's Vite demo and consumer fixture).
+
+**Custom (smaller builds / custom adapters / strict CSP / other bundlers):**
+
+```ts
+useGcodePreview({
+  createWorker: () => new Worker(new URL('@chestnutlabs/gcode-parser/dist/worker-slim.js', import.meta.url), { type: 'module' })
+});
+// or your own worker built with createWorkerHandler(...) — see the parser package docs
+```
+
+Linked-workspace development note: Vite consumers using `file:` links should add every
+`@chestnutlabs/*` package the worker pulls in to `optimizeDeps.exclude` (installed tarballs/registry
+packages need no configuration).
+
+## Capability honesty
+
+Everything the engine reports as `inferred`/`approximated`/`unavailable` stays that way at this
+layer: feature coloring refuses rather than fabricates, live progress shows a band instead of a
+fake-precise marker, and decimation is disclosed via the `disclosure` emit — surface it.
+
+## Support
+
+`.gcode` (Marlin/Klipper/RepRap-flavor; PrusaSlicer, Orca/Bambu, Cura annotations),
+`.gcode.3mf` (sliced-plate export; multi-plate via `parse-options.plate`), per-file build plates,
+multi-tool/AMS color, object exclusion, arcs. See the repository's
+`docs/compatibility/dialects-and-containers.md` for the evidence-dated matrix and
+`docs/reference/progress-signal-contract.md` for the live-progress contract.

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

@@ -0,0 +1,226 @@
+/**
+ * <GcodePreview> — the ready-to-use component (DD-007 §4.1 D1/D4, phase 2, issue #105).
+ *
+ * Strictly a SHELL over `useGcodePreview` (D1: never a separate implementation): every prop
+ * maps to a composable call, every emit re-fires a composable event, and the underlying handle
+ * is exposed for template-ref access. Advanced props are optional with sensible defaults, so
+ * `<GcodePreview :source="file" />` alone is a working viewer (D4).
+ *
+ * Render-function component on purpose (no SFC): the template is a single full-size <canvas>,
+ * and staying pure TypeScript keeps the package on the plain tsc build with typed props/emits.
+ */
+import { type PropType } from 'vue';
+import type { BuildVolumeDef, ColorMode, QualityMode, TubeOptions } from '@chestnutlabs/gcode-renderer-three';
+import type { MachineGeometry, ProgressObservation } from '@chestnutlabs/toolpath-core';
+import type { WireParseOptions, WorkerLike } from '@chestnutlabs/gcode-parser';
+import { type UseGcodePreviewOptions } from './use-gcode-preview.js';
+export type GcodePreviewSource = Uint8Array | ArrayBuffer | File | null;
+export declare const GcodePreview: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    /** The one required-in-practice prop: bytes/File to parse. Changing it re-parses. */
+    source: {
+        type: PropType<GcodePreviewSource>;
+        default: null;
+    };
+    parseOptions: {
+        type: PropType<WireParseOptions>;
+        default: undefined;
+    };
+    /** Consumer-configured volume — wins over file-discovered geometry (DD-005 precedence). */
+    buildVolume: {
+        type: PropType<BuildVolumeDef | MachineGeometry>;
+        default: undefined;
+    };
+    quality: {
+        type: PropType<QualityMode | "auto">;
+        default: string;
+    };
+    colorMode: {
+        type: PropType<ColorMode>;
+        default: undefined;
+    };
+    tube: {
+        type: PropType<TubeOptions>;
+        default: undefined;
+    };
+    /** Inclusive [start, end]; null shows every layer. */
+    layerRange: {
+        type: PropType<[number, number] | null>;
+        default: null;
+    };
+    /** Scrub cut (IR segment index); null shows everything up to the layer range. */
+    scrub: {
+        type: PropType<number | null>;
+        default: null;
+    };
+    showTravel: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** DD-006 live progress observation; null hides the overlay. */
+    progress: {
+        type: PropType<ProgressObservation | null>;
+        default: null;
+    };
+    /** Worker factory escape hatch (DD-005 slim/custom entries; D2). Factory form only —
+     *  a worker INSTANCE cannot survive re-parse lifecycles the way a factory can. */
+    createWorker: {
+        type: PropType<() => WorkerLike>;
+        default: undefined;
+    };
+    /** Advanced/test renderer injectables (pass-throughs of the renderer contract). */
+    rendererOptions: {
+        type: PropType<Omit<NonNullable<UseGcodePreviewOptions["renderer"]>, "buildVolume" | "quality" | "colorMode" | "tube">>;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    ready: (_summary: {
+        segments: number;
+        layers: number;
+        complete: boolean;
+    }) => true;
+    'parse-error': (_e: {
+        code: string;
+        message: string;
+    }) => true;
+    'parse-cancelled': () => true;
+    'parse-progress': (_p: {
+        bytesProcessed: number;
+        totalBytes: number;
+    }) => true;
+    'build-complete': (_e: {
+        segments: number;
+        quality: QualityMode;
+    }) => true;
+    'quality-fallback': (_e: {
+        from: QualityMode;
+        to: QualityMode;
+        reason: string;
+    }) => true;
+    'machine-geometry-mismatch': (_message: string) => true;
+    'machine-geometry-discovered': (_machine: MachineGeometry) => true;
+    'progress-presentation-changed': (_e: {
+        mode: string;
+        reason?: string;
+    }) => true;
+    disclosure: (_text: string) => true;
+    error: (_e: {
+        code: string;
+        message: string;
+    }) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    /** The one required-in-practice prop: bytes/File to parse. Changing it re-parses. */
+    source: {
+        type: PropType<GcodePreviewSource>;
+        default: null;
+    };
+    parseOptions: {
+        type: PropType<WireParseOptions>;
+        default: undefined;
+    };
+    /** Consumer-configured volume — wins over file-discovered geometry (DD-005 precedence). */
+    buildVolume: {
+        type: PropType<BuildVolumeDef | MachineGeometry>;
+        default: undefined;
+    };
+    quality: {
+        type: PropType<QualityMode | "auto">;
+        default: string;
+    };
+    colorMode: {
+        type: PropType<ColorMode>;
+        default: undefined;
+    };
+    tube: {
+        type: PropType<TubeOptions>;
+        default: undefined;
+    };
+    /** Inclusive [start, end]; null shows every layer. */
+    layerRange: {
+        type: PropType<[number, number] | null>;
+        default: null;
+    };
+    /** Scrub cut (IR segment index); null shows everything up to the layer range. */
+    scrub: {
+        type: PropType<number | null>;
+        default: null;
+    };
+    showTravel: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** DD-006 live progress observation; null hides the overlay. */
+    progress: {
+        type: PropType<ProgressObservation | null>;
+        default: null;
+    };
+    /** Worker factory escape hatch (DD-005 slim/custom entries; D2). Factory form only —
+     *  a worker INSTANCE cannot survive re-parse lifecycles the way a factory can. */
+    createWorker: {
+        type: PropType<() => WorkerLike>;
+        default: undefined;
+    };
+    /** Advanced/test renderer injectables (pass-throughs of the renderer contract). */
+    rendererOptions: {
+        type: PropType<Omit<NonNullable<UseGcodePreviewOptions["renderer"]>, "buildVolume" | "quality" | "colorMode" | "tube">>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    onDisclosure?: ((_text: string) => any) | undefined;
+    onError?: ((_e: {
+        code: string;
+        message: string;
+    }) => any) | undefined;
+    onReady?: ((_summary: {
+        segments: number;
+        layers: number;
+        complete: boolean;
+    }) => any) | undefined;
+    "onParse-error"?: ((_e: {
+        code: string;
+        message: string;
+    }) => any) | undefined;
+    "onParse-cancelled"?: (() => any) | undefined;
+    "onParse-progress"?: ((_p: {
+        bytesProcessed: number;
+        totalBytes: number;
+    }) => any) | undefined;
+    "onBuild-complete"?: ((_e: {
+        segments: number;
+        quality: QualityMode;
+    }) => any) | undefined;
+    "onQuality-fallback"?: ((_e: {
+        from: QualityMode;
+        to: QualityMode;
+        reason: string;
+    }) => any) | undefined;
+    "onMachine-geometry-mismatch"?: ((_message: string) => any) | undefined;
+    "onMachine-geometry-discovered"?: ((_machine: MachineGeometry) => any) | undefined;
+    "onProgress-presentation-changed"?: ((_e: {
+        mode: string;
+        reason?: string;
+    }) => any) | undefined;
+}>, {
+    source: GcodePreviewSource;
+    buildVolume: BuildVolumeDef | MachineGeometry;
+    quality: QualityMode | "auto";
+    colorMode: ColorMode;
+    tube: TubeOptions;
+    parseOptions: WireParseOptions;
+    layerRange: [number, number] | null;
+    scrub: number | null;
+    showTravel: boolean;
+    progress: ProgressObservation | null;
+    createWorker: () => WorkerLike;
+    rendererOptions: Omit<{
+        buildVolume?: BuildVolumeDef;
+        quality?: QualityMode | "auto";
+        colorMode?: ColorMode;
+        tube?: TubeOptions;
+        createRenderer?: (canvas: import("@chestnutlabs/gcode-renderer-three").RenderTargetCanvas) => import("@chestnutlabs/gcode-renderer-three").GLRendererLike;
+        scheduleFrame?: (cb: () => void) => void;
+        chunksPerTick?: number;
+    }, "buildVolume" | "quality" | "colorMode" | "tube">;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//# sourceMappingURL=gcode-preview-component.d.ts.map

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

@@ -0,0 +1 @@
+{"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,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAC9G,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAsC,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEzG,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,2FAA2F;;cAC5D,QAAQ,CAAC,cAAc,GAAG,eAAe,CAAC;;;;cAC9C,QAAQ,CAAC,WAAW,GAAG,MAAM,CAAC;;;;cAC5B,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;;;;;;;IAEhD,gEAAgE;;cACpC,QAAQ,CAAC,mBAAmB,GAAG,IAAI,CAAC;;;IAChE;sFACkF;;cAE9D,QAAQ,CAAC,MAAM,UAAU,CAAC;;;IAG9C,mFAAmF;;cAEjE,QAAQ,CACtB,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC,CACxG;;;;;;sBAMe;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE;wBACrD;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;;2BAE9B;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;2BAC9C;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;;IAzC7C,qFAAqF;;cAC1B,QAAQ,CAAC,kBAAkB,CAAC;;;;cACvD,QAAQ,CAAC,gBAAgB,CAAC;;;IAC1D,2FAA2F;;cAC5D,QAAQ,CAAC,cAAc,GAAG,eAAe,CAAC;;;;cAC9C,QAAQ,CAAC,WAAW,GAAG,MAAM,CAAC;;;;cAC5B,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;;;;;;;IAEhD,gEAAgE;;cACpC,QAAQ,CAAC,mBAAmB,GAAG,IAAI,CAAC;;;IAChE;sFACkF;;cAE9D,QAAQ,CAAC,MAAM,UAAU,CAAC;;;IAG9C,mFAAmF;;cAEjE,QAAQ,CACtB,IAAI,CAAC,WAAW,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC,CACxG;;;;;;cAgBiB,MAAM;iBAAW,MAAM;;;kBAVb,MAAM;gBAAU,MAAM;kBAAY,OAAO;;;cAC3C,MAAM;iBAAW,MAAM;;;;wBAEV,MAAM;oBAAc,MAAM;;;kBAChC,MAAM;iBAAW,WAAW;;;cAC9B,WAAW;YAAM,WAAW;gBAAU,MAAM;;;;;cAG/B,MAAM;iBAAW,MAAM;;;;;;;;;;;;;wBArBlC,UAAU;;;;;;;;;;4EAkJ/C,CAAC"}

package/dist/gcode-preview-component.js

@@ -0,0 +1,154 @@
+/**
+ * <GcodePreview> — the ready-to-use component (DD-007 §4.1 D1/D4, phase 2, issue #105).
+ *
+ * Strictly a SHELL over `useGcodePreview` (D1: never a separate implementation): every prop
+ * maps to a composable call, every emit re-fires a composable event, and the underlying handle
+ * is exposed for template-ref access. Advanced props are optional with sensible defaults, so
+ * `<GcodePreview :source="file" />` alone is a working viewer (D4).
+ *
+ * Render-function component on purpose (no SFC): the template is a single full-size <canvas>,
+ * and staying pure TypeScript keeps the package on the plain tsc build with typed props/emits.
+ */
+import { defineComponent, h, onMounted, ref, watch } from 'vue';
+import { useGcodePreview } from './use-gcode-preview.js';
+export const GcodePreview = defineComponent({
+    name: 'GcodePreview',
+    props: {
+        /** The one required-in-practice prop: bytes/File to parse. Changing it re-parses. */
+        source: { type: [Object, Uint8Array, ArrayBuffer, File], default: null },
+        parseOptions: { type: Object, default: undefined },
+        /** Consumer-configured volume — wins over file-discovered geometry (DD-005 precedence). */
+        buildVolume: { type: Object, default: undefined },
+        quality: { type: String, default: 'auto' },
+        colorMode: { type: Object, default: undefined },
+        tube: { type: Object, default: undefined },
+        /** Inclusive [start, end]; null shows every layer. */
+        layerRange: { type: Array, default: null },
+        /** Scrub cut (IR segment index); null shows everything up to the layer range. */
+        scrub: { type: Number, default: null },
+        showTravel: { type: Boolean, default: true },
+        /** 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 —
+         *  a worker INSTANCE cannot survive re-parse lifecycles the way a factory can. */
+        createWorker: {
+            type: Function,
+            default: undefined
+        },
+        /** Advanced/test renderer injectables (pass-throughs of the renderer contract). */
+        rendererOptions: {
+            type: Object,
+            default: undefined
+        }
+    },
+    emits: {
+        /* eslint-disable @typescript-eslint/no-unused-vars -- emit validators document payloads */
+        ready: (_summary) => true,
+        'parse-error': (_e) => true,
+        'parse-cancelled': () => true,
+        'parse-progress': (_p) => true,
+        'build-complete': (_e) => true,
+        'quality-fallback': (_e) => true,
+        'machine-geometry-mismatch': (_message) => true,
+        'machine-geometry-discovered': (_machine) => true,
+        'progress-presentation-changed': (_e) => true,
+        disclosure: (_text) => true,
+        error: (_e) => true
+        /* eslint-enable @typescript-eslint/no-unused-vars */
+    },
+    setup(props, { emit, expose }) {
+        const preview = useGcodePreview({
+            createWorker: props.createWorker,
+            renderer: {
+                buildVolume: 'bed' in (props.buildVolume ?? {}) ? undefined : props.buildVolume,
+                quality: props.quality,
+                colorMode: props.colorMode,
+                tube: props.tube,
+                ...props.rendererOptions
+            },
+            parseDefaults: props.parseOptions
+        });
+        // A MachineGeometry buildVolume prop applies post-construction (same consumer-wins effect).
+        onMounted(() => {
+            if (props.buildVolume !== undefined && 'bed' in props.buildVolume) {
+                preview.controls.setBuildVolume(props.buildVolume);
+            }
+        });
+        preview.onEvent((e) => {
+            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', preview.state.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', e.machine);
+                    break;
+                case 'error':
+                    if (e.code === 'machine-geometry-mismatch')
+                        emit('machine-geometry-mismatch', e.message);
+                    else
+                        emit('error', { code: e.code, message: e.message });
+                    break;
+                default:
+                    break;
+            }
+        });
+        // ---- prop wiring: each prop is a thin call into the composable (D1 shell rule) ----
+        watch(() => props.source, (source) => {
+            if (source !== null)
+                void preview.parse(source, props.parseOptions);
+        }, { immediate: true });
+        watch(() => props.layerRange, (range) => {
+            if (range === null)
+                preview.controls.setLayerRange(0, Number.POSITIVE_INFINITY);
+            else
+                preview.controls.setLayerRange(range[0], range[1]);
+        });
+        watch(() => props.scrub, (scrub) => preview.controls.setScrubPosition(scrub));
+        watch(() => props.showTravel, (visible) => preview.controls.setKindVisible('travel', visible));
+        watch(() => props.colorMode, (mode) => {
+            if (mode !== undefined)
+                preview.controls.setColorMode(mode);
+        });
+        watch(() => props.quality, (quality) => preview.controls.setQuality(quality));
+        watch(() => props.buildVolume, (volume) => {
+            if (volume !== undefined)
+                preview.controls.setBuildVolume(volume);
+        });
+        watch(() => props.progress, (obs) => {
+            if (obs === null)
+                preview.clearProgress();
+            else
+                preview.observeProgress(obs);
+        });
+        // Template-ref access to the full handle (defineExpose per §4.1).
+        expose({ preview });
+        const canvasEl = ref(null);
+        watch(canvasEl, (el) => {
+            preview.canvasRef.value = el;
+        });
+        return () => h('canvas', {
+            ref: canvasEl,
+            style: { width: '100%', height: '100%', display: 'block', touchAction: 'none' },
+            'aria-label': '3D G-code toolpath preview'
+        });
+    }
+});

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @chestnutlabs/gcode-preview-vue — thin Vue 3 integration (DD-007).
+ *
+ * Phase 1 (issue #104): the headless `useGcodePreview` composable. Phase 2 adds the
+ * `<GcodePreview>` component, which is strictly a shell over this composable (D1).
+ * This package owns Vue-glue mechanics only — no parsing/rendering capability lives
+ * here, and no VueKit/Pinia/router/AnyBridge code may ever enter (DD-002 §4).
+ */
+export * from './use-gcode-preview.js';
+export { GcodePreview, type GcodePreviewSource } from './gcode-preview-component.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @chestnutlabs/gcode-preview-vue — thin Vue 3 integration (DD-007).
+ *
+ * Phase 1 (issue #104): the headless `useGcodePreview` composable. Phase 2 adds the
+ * `<GcodePreview>` component, which is strictly a shell over this composable (D1).
+ * This package owns Vue-glue mechanics only — no parsing/rendering capability lives
+ * here, and no VueKit/Pinia/router/AnyBridge code may ever enter (DD-002 §4).
+ */
+export * from './use-gcode-preview.js';
+export { GcodePreview } from './gcode-preview-component.js';

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

@@ -0,0 +1,39 @@
+/**
+ * useGcodePreview — the Vue reactivity bridge over the framework-neutral controller
+ * (DD-007 §4.6, refactored in phase 5/issue #112; original glue extracted to
+ * @chestnutlabs/gcode-preview-core). This file owns ONLY the Vue-isms: a canvas
+ * template ref, a shallow-reactive state mirror fed by controller snapshots, and
+ * scope-tied disposal. The engine mechanics, state model, and TypeScript contracts
+ * live in the core package and are RE-EXPORTED, never redeclared (the D1-amendment
+ * drift firewall). Public API is unchanged from phase 1.
+ */
+import { type Ref } from 'vue';
+import type { GcodeParseSession, WireParseOptions } from '@chestnutlabs/gcode-parser';
+import type { ToolpathRenderer } from '@chestnutlabs/gcode-renderer-three';
+import type { MappedProgress, ProgressObservation } from '@chestnutlabs/toolpath-core';
+import { type GcodePreviewControls, type GcodePreviewState, type ParseOutcome, type PreviewControllerOptions, type PreviewEvent } from '@chestnutlabs/gcode-preview-core';
+export type { GcodePreviewControls, GcodePreviewState, ParseOutcome, PreviewEvent } from '@chestnutlabs/gcode-preview-core';
+/** Vue-facing options — identical to the controller's (the alias is the public name). */
+export type UseGcodePreviewOptions = PreviewControllerOptions;
+export interface GcodePreviewHandle {
+    /** Bind to a <canvas> template ref; rebinding disposes and rebuilds safely. */
+    canvasRef: Ref<HTMLCanvasElement | null>;
+    parse(input: Uint8Array | ArrayBuffer | File, opts?: WireParseOptions): Promise<ParseOutcome>;
+    cancel(): void;
+    /** DD-006: map one observation and drive the overlay. Null before a successful parse. */
+    observeProgress(obs: ProgressObservation): MappedProgress | null;
+    /** Recompute staleness (DD-006 §4.4.3) — call at ~1 Hz while telemetry may go quiet. */
+    tickProgress(nowMs: number): MappedProgress | null;
+    clearProgress(): void;
+    state: Readonly<GcodePreviewState>;
+    controls: GcodePreviewControls;
+    /** Escape hatches — the neutral objects themselves (advanced use; not reactive). */
+    raw: {
+        session: GcodeParseSession;
+        renderer: () => ToolpathRenderer | null;
+    };
+    onEvent(cb: (e: PreviewEvent) => void): () => void;
+    dispose(): void;
+}
+export declare function useGcodePreview(options?: UseGcodePreviewOptions): GcodePreviewHandle;
+//# sourceMappingURL=use-gcode-preview.d.ts.map

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

@@ -0,0 +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,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,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,EAClB,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,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,gBAAgB,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7E,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"}

package/dist/use-gcode-preview.js

@@ -0,0 +1,42 @@
+/**
+ * useGcodePreview — the Vue reactivity bridge over the framework-neutral controller
+ * (DD-007 §4.6, refactored in phase 5/issue #112; original glue extracted to
+ * @chestnutlabs/gcode-preview-core). This file owns ONLY the Vue-isms: a canvas
+ * template ref, a shallow-reactive state mirror fed by controller snapshots, and
+ * scope-tied disposal. The engine mechanics, state model, and TypeScript contracts
+ * live in the core package and are RE-EXPORTED, never redeclared (the D1-amendment
+ * drift firewall). Public API is unchanged from phase 1.
+ */
+import { getCurrentScope, onScopeDispose, readonly, ref, shallowReactive, watch } from 'vue';
+import { createPreviewController } from '@chestnutlabs/gcode-preview-core';
+export function useGcodePreview(options = {}) {
+    const controller = createPreviewController(options);
+    // Reactivity bridge: controller snapshots → a shallow-reactive mirror. Snapshots
+    // carry summaries only, so a shallow field copy is the whole bridge (§4.2 boundary).
+    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();
+    }
+    // Unmount/HMR safety (§4.2): auto-dispose with the owning effect scope, when there is one.
+    if (getCurrentScope() !== undefined)
+        onScopeDispose(dispose);
+    return {
+        canvasRef,
+        parse: controller.parse,
+        cancel: controller.cancel,
+        observeProgress: controller.observeProgress,
+        tickProgress: controller.tickProgress,
+        clearProgress: controller.clearProgress,
+        state: readonly(state),
+        controls: controller.controls,
+        raw: controller.raw,
+        onEvent: controller.onEvent,
+        dispose
+    };
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@chestnutlabs/gcode-preview-vue",
+  "version": "0.1.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",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "vue",
+    "vue3",
+    "component",
+    "composable",
+    "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-vue"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/gcode-parser": "0.1.0",
+    "@chestnutlabs/gcode-renderer-three": "0.1.0",
+    "@chestnutlabs/toolpath-core": "0.1.0",
+    "@chestnutlabs/gcode-preview-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "vue": "^3.4.0"
+  }
+}