@chestnutlabs/gcode-preview-react 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @chestnutlabs/gcode-preview-react
+
+Thin React integration for the Chestnut Labs G-code viewer — a reactivity bridge over
+`@chestnutlabs/gcode-preview-core` with **capability parity** to the Vue and Svelte adapters
+(same engine, same state model, same TypeScript contracts; DD-007 D1 amendment).
+
+```sh
+npm install @chestnutlabs/gcode-preview-react 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).)
+
+## Ready-to-use component
+
+```tsx
+import { GcodePreview } from '@chestnutlabs/gcode-preview-react';
+
+function Viewer({ file }: { file: File | null }) {
+  return (
+    <div style={{ height: '70vh' }}>
+      <GcodePreview source={file} onReady={(s) => console.log(`${s.segments} segments`)} />
+    </div>
+  );
+}
+```
+
+That is a complete viewer (StrictMode-safe). The full surface is optional props with sensible
+defaults — `source`, `parseOptions`, `buildVolume` (consumer-wins bed precedence), `quality`,
+`colorMode`, `layerRange`, `scrub`, `showTravel`, `progress` (DD-006 observation), `createWorker`
+— with matching callbacks (`onReady`, `onParseError`, `onBuildComplete`, `onQualityFallback`,
+`onMachineGeometryMismatch`/`Discovered`, `onProgressPresentationChanged`, `onDisclosure`,
+`onError`). The full handle is reachable via `ref`.
+
+## Headless hook (build your own controls)
+
+```tsx
+import { useGcodePreview } from '@chestnutlabs/gcode-preview-react';
+
+function CustomViewer() {
+  const preview = useGcodePreview();
+  // <canvas ref={preview.canvasRef} /> — bind; unmount disposes automatically
+  // await preview.parse(bytes); preview.controls.setScrubPosition(n);
+  // preview.observeProgress(obs); preview.state (useSyncExternalStore-subscribed)
+  return <canvas ref={preview.canvasRef} style={{ width: '100%', height: '100%' }} />;
+}
+```
+
+## Workers
+
+The batteries default (all dialect adapters + `.gcode.3mf`) needs zero setup under Vite; pass
+`createWorker` for the slim build, custom adapters, other bundlers, or strict CSP. See the
+`@chestnutlabs/gcode-preview-vue` README for the shared worker documentation — the options are
+identical across adapters by design.
+
+## Example
+
+`tools/example-react` in the repository is a complete Vite + React app (corpus load, layer/scrub,
+simulated live progress) running under `<StrictMode>`.

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

@@ -0,0 +1,63 @@
+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 GcodePreviewHandle, type UseGcodePreviewOptions } from './use-gcode-preview.js';
+export type GcodePreviewSource = Uint8Array | ArrayBuffer | File | null;
+export interface GcodePreviewProps {
+    /** The one prop needed in practice: bytes/File to parse. Changing it re-parses. */
+    source?: GcodePreviewSource;
+    parseOptions?: WireParseOptions;
+    /** Consumer-configured volume — wins over file-discovered geometry (DD-005 precedence). */
+    buildVolume?: BuildVolumeDef | MachineGeometry;
+    quality?: QualityMode | 'auto';
+    colorMode?: ColorMode;
+    tube?: TubeOptions;
+    /** Inclusive [start, end]; null/undefined shows every layer. */
+    layerRange?: [number, number] | null;
+    /** Scrub cut (IR segment index); null shows everything up to the layer range. */
+    scrub?: number | null;
+    showTravel?: boolean;
+    /** DD-006 live progress observation; null hides the overlay. */
+    progress?: ProgressObservation | null;
+    /** Worker factory escape hatch (DD-005 slim/custom entries; D2). */
+    createWorker?: () => WorkerLike;
+    /** Advanced/test renderer injectables (pass-throughs of the renderer contract). */
+    rendererOptions?: Omit<NonNullable<UseGcodePreviewOptions['renderer']>, 'buildVolume' | 'quality' | 'colorMode' | 'tube'>;
+    onReady?: (summary: {
+        segments: number;
+        layers: number;
+        complete: boolean;
+    }) => void;
+    onParseError?: (e: {
+        code: string;
+        message: string;
+    }) => void;
+    onParseCancelled?: () => void;
+    onParseProgress?: (p: {
+        bytesProcessed: number;
+        totalBytes: number;
+    }) => void;
+    onBuildComplete?: (e: {
+        segments: number;
+        quality: QualityMode;
+    }) => void;
+    onQualityFallback?: (e: {
+        from: QualityMode;
+        to: QualityMode;
+        reason: string;
+    }) => void;
+    onMachineGeometryMismatch?: (message: string) => void;
+    onMachineGeometryDiscovered?: (machine: MachineGeometry) => void;
+    onProgressPresentationChanged?: (e: {
+        mode: string;
+        reason?: string;
+    }) => void;
+    onDisclosure?: (text: string) => void;
+    onError?: (e: {
+        code: string;
+        message: string;
+    }) => void;
+}
+/** Ready-to-use viewer: `<GcodePreview source={file} />` works alone (D4). */
+export declare const GcodePreview: import("react").ForwardRefExoticComponent<GcodePreviewProps & import("react").RefAttributes<GcodePreviewHandle>>;
+//# 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":"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"}

package/dist/gcode-preview-component.js

@@ -0,0 +1,114 @@
+/**
+ * <GcodePreview> — the ready-to-use React component (DD-007 D1 amendment, phase 6).
+ *
+ * Strictly a SHELL over `useGcodePreview` (D1: never a separate implementation): every
+ * prop maps to a hook/controls call, every callback re-fires a controller event, and the
+ * full handle is reachable via `ref`. Advanced props are optional with sensible defaults,
+ * so `<GcodePreview source={file} />` alone is a working viewer (D4).
+ *
+ * createElement (no JSX) on purpose: the template is a single full-size <canvas>, and
+ * staying pure TypeScript keeps the package on the plain tsc build.
+ */
+import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import { useGcodePreview } from './use-gcode-preview.js';
+function GcodePreviewImpl(props, ref) {
+    const isMachine = props.buildVolume !== undefined && 'bed' in props.buildVolume;
+    const preview = useGcodePreview({
+        createWorker: props.createWorker,
+        renderer: {
+            buildVolume: isMachine ? undefined : props.buildVolume,
+            quality: props.quality ?? 'auto',
+            colorMode: props.colorMode,
+            tube: props.tube,
+            ...props.rendererOptions
+        },
+        parseDefaults: props.parseOptions
+    });
+    useImperativeHandle(ref, () => preview, [preview]);
+    // Callbacks live in a ref so the event subscription is stable across renders.
+    const cbRef = useRef(props);
+    cbRef.current = props;
+    useEffect(() => {
+        return preview.onEvent((e) => {
+            const p = cbRef.current;
+            switch (e.type) {
+                case 'parse-complete':
+                    p.onReady?.({ segments: e.segments, layers: e.layers, complete: e.complete });
+                    break;
+                case 'parse-error':
+                    p.onParseError?.({ code: e.code, message: e.message });
+                    break;
+                case 'parse-cancelled':
+                    p.onParseCancelled?.();
+                    break;
+                case 'parse-progress':
+                    p.onParseProgress?.({ bytesProcessed: e.progress.bytesProcessed, totalBytes: e.progress.totalBytes });
+                    break;
+                case 'buildComplete':
+                    p.onBuildComplete?.({ segments: e.segments, quality: e.quality });
+                    p.onDisclosure?.(preview.state.disclosure);
+                    break;
+                case 'qualityFallback':
+                    p.onQualityFallback?.({ from: e.from, to: e.to, reason: e.reason });
+                    break;
+                case 'progress-presentation-changed':
+                    p.onProgressPresentationChanged?.(e.reason === undefined ? { mode: e.mode } : { mode: e.mode, reason: e.reason });
+                    break;
+                case 'machine-geometry-discovered':
+                    p.onMachineGeometryDiscovered?.(e.machine);
+                    break;
+                case 'error':
+                    if (e.code === 'machine-geometry-mismatch')
+                        p.onMachineGeometryMismatch?.(e.message);
+                    else
+                        p.onError?.({ code: e.code, message: e.message });
+                    break;
+                default:
+                    break;
+            }
+        });
+    }, []);
+    // ---- prop wiring: each prop is a thin call into the hook (D1 shell rule) ----
+    const { source, layerRange, scrub, showTravel, colorMode, quality, buildVolume, progress } = props;
+    useEffect(() => {
+        if (source !== null && source !== undefined)
+            void preview.parse(source, cbRef.current.parseOptions);
+    }, [source]);
+    useEffect(() => {
+        if (layerRange === null || layerRange === undefined)
+            preview.controls.setLayerRange(0, Number.POSITIVE_INFINITY);
+        else
+            preview.controls.setLayerRange(layerRange[0], layerRange[1]);
+    }, [layerRange]);
+    useEffect(() => {
+        preview.controls.setScrubPosition(scrub ?? null);
+    }, [scrub]);
+    useEffect(() => {
+        preview.controls.setKindVisible('travel', showTravel ?? true);
+    }, [showTravel]);
+    useEffect(() => {
+        if (colorMode !== undefined)
+            preview.controls.setColorMode(colorMode);
+    }, [colorMode]);
+    useEffect(() => {
+        if (quality !== undefined)
+            preview.controls.setQuality(quality);
+    }, [quality]);
+    useEffect(() => {
+        if (buildVolume !== undefined && 'bed' in buildVolume)
+            preview.controls.setBuildVolume(buildVolume);
+    }, [buildVolume]);
+    useEffect(() => {
+        if (progress === null || progress === undefined)
+            preview.clearProgress();
+        else
+            preview.observeProgress(progress);
+    }, [progress]);
+    return createElement('canvas', {
+        ref: preview.canvasRef,
+        style: { width: '100%', height: '100%', display: 'block', touchAction: 'none' },
+        'aria-label': '3D G-code toolpath preview'
+    });
+}
+/** Ready-to-use viewer: `<GcodePreview source={file} />` works alone (D4). */
+export const GcodePreview = forwardRef(GcodePreviewImpl);

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @chestnutlabs/gcode-preview-react — thin React integration (DD-007 D1 amendment).
+ *
+ * `useGcodePreview` hook + `<GcodePreview>` component, both reactivity bridges over
+ * @chestnutlabs/gcode-preview-core — never a separate viewer implementation. Shared
+ * contracts are re-exported from core.
+ */
+export * from './use-gcode-preview.js';
+export { GcodePreview, type GcodePreviewProps, 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;;;;;;GAMG;AACH,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @chestnutlabs/gcode-preview-react — thin React integration (DD-007 D1 amendment).
+ *
+ * `useGcodePreview` hook + `<GcodePreview>` component, both reactivity bridges over
+ * @chestnutlabs/gcode-preview-core — never a separate viewer implementation. Shared
+ * contracts are re-exported from core.
+ */
+export * from './use-gcode-preview.js';
+export { GcodePreview } from './gcode-preview-component.js';

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

@@ -0,0 +1,27 @@
+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';
+/** React-facing options — identical to the controller's (the alias is the public name). */
+export type UseGcodePreviewOptions = PreviewControllerOptions;
+export interface GcodePreviewHandle {
+    /** Attach as `<canvas ref={preview.canvasRef} />`; null detaches safely. */
+    canvasRef: (el: HTMLCanvasElement | null) => void;
+    parse(input: Uint8Array | ArrayBuffer | File, opts?: WireParseOptions): Promise<ParseOutcome>;
+    cancel(): void;
+    observeProgress(obs: ProgressObservation): MappedProgress | null;
+    tickProgress(nowMs: number): MappedProgress | null;
+    clearProgress(): void;
+    /** Current state snapshot — render-subscribed via useSyncExternalStore. */
+    state: GcodePreviewState;
+    controls: GcodePreviewControls;
+    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":"AAYA,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,EAEjB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EAClB,MAAM,kCAAkC,CAAC;AAG1C,YAAY,EACV,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACb,MAAM,kCAAkC,CAAC;AAE1C,2FAA2F;AAC3F,MAAM,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,SAAS,EAAE,CAAC,EAAE,EAAE,iBAAiB,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD,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,eAAe,CAAC,GAAG,EAAE,mBAAmB,GAAG,cAAc,GAAG,IAAI,CAAC;IACjE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IACnD,aAAa,IAAI,IAAI,CAAC;IACtB,2EAA2E;IAC3E,KAAK,EAAE,iBAAiB,CAAC;IACzB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,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;AAUD,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,kBAAkB,CAiExF"}

package/dist/use-gcode-preview.js

@@ -0,0 +1,74 @@
+/**
+ * useGcodePreview — the React reactivity bridge over the framework-neutral controller
+ * (DD-007 §4.6 D1 amendment, phase 6, issue #113). This file owns ONLY the React-isms:
+ * a `useSyncExternalStore` subscription to controller snapshots, a callback canvas ref,
+ * and effect-scoped disposal. Engine mechanics and contracts live in
+ * @chestnutlabs/gcode-preview-core and are RE-EXPORTED, never redeclared.
+ *
+ * StrictMode safety: React 18 dev mounts effects twice (setup → cleanup → setup). Every
+ * delegate goes through `ensure()`, which lazily (re)creates the controller after a
+ * cleanup disposed it — the remounted subscription lands on the fresh controller.
+ */
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { createPreviewController } from '@chestnutlabs/gcode-preview-core';
+export function useGcodePreview(options = {}) {
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const slot = useRef({ controller: null, disposed: false, canvas: null });
+    const ensure = useCallback(() => {
+        const s = slot.current;
+        if (s.controller === null || s.disposed) {
+            s.controller = createPreviewController(optionsRef.current);
+            s.disposed = false;
+        }
+        return s.controller;
+    }, []);
+    const subscribe = useCallback((cb) => ensure().onStateChange(() => cb()), [ensure]);
+    const getSnapshot = useCallback(() => ensure().getState(), [ensure]);
+    const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    useEffect(() => {
+        const c = ensure(); // (re)create on mount — StrictMode's second setup lands here
+        // Refs attached BEFORE StrictMode's dispose/recreate cycle: rebind the canvas the
+        // ref delivered so the fresh controller actually renders (refs never re-fire).
+        if (slot.current.canvas !== null && c.raw.renderer() === null) {
+            c.bindCanvas(slot.current.canvas);
+        }
+        return () => {
+            slot.current.controller?.dispose();
+            slot.current.disposed = true;
+        };
+    }, [ensure]);
+    // The handle (incl. canvasRef) must be IDENTITY-STABLE across state changes: a fresh
+    // canvasRef each render would make React detach/reattach the ref, rebuilding the
+    // renderer per snapshot — an infinite loop. `state` reads through a per-render ref.
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    return useMemo(() => ({
+        canvasRef: (el) => {
+            slot.current.canvas = el;
+            if (el === null)
+                slot.current.controller?.bindCanvas(null);
+            else
+                ensure().bindCanvas(el);
+        },
+        parse: (input, opts) => ensure().parse(input, opts),
+        cancel: () => slot.current.controller?.cancel(),
+        observeProgress: (obs) => slot.current.controller?.observeProgress(obs) ?? null,
+        tickProgress: (nowMs) => slot.current.controller?.tickProgress(nowMs) ?? null,
+        clearProgress: () => slot.current.controller?.clearProgress(),
+        get state() {
+            return stateRef.current;
+        },
+        get controls() {
+            return ensure().controls;
+        },
+        get raw() {
+            return ensure().raw;
+        },
+        onEvent: (cb) => ensure().onEvent(cb),
+        dispose: () => {
+            slot.current.controller?.dispose();
+            slot.current.disposed = true;
+        }
+    }), [ensure]);
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@chestnutlabs/gcode-preview-react",
+  "version": "0.1.0",
+  "description": "Thin React integration for the Chestnut Labs G-code viewer (DD-007 D1 amendment): useGcodePreview hook + GcodePreview component as a reactivity bridge over @chestnutlabs/gcode-preview-core.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "react",
+    "hooks",
+    "component",
+    "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-react"
+  },
+  "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-preview-core": "0.1.0",
+    "@chestnutlabs/gcode-renderer-three": "0.1.0",
+    "@chestnutlabs/toolpath-core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  }
+}