@chestnutlabs/gcode-preview-svelte 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @chestnutlabs/gcode-preview-svelte
+
+Thin Svelte integration for the Chestnut Labs G-code viewer — a reactivity bridge over
+`@chestnutlabs/gcode-preview-core` with **capability parity** to the Vue and React adapters
+(same engine, same state model, same TypeScript contracts; DD-007 D1 amendment).
+
+```sh
+npm install @chestnutlabs/gcode-preview-svelte 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
+
+```svelte
+<script>
+  import GcodePreview from '@chestnutlabs/gcode-preview-svelte/GcodePreview.svelte';
+  let file = null;
+</script>
+
+<div style="height: 70vh">
+  <GcodePreview source={file} on:ready={(e) => console.log(`${e.detail.segments} segments`)} />
+</div>
+```
+
+That is a complete viewer. The component ships as a **raw `.svelte` file** (standard Svelte
+library packaging — your bundler's svelte plugin compiles it via the `svelte` export condition).
+Full defaulted prop surface: `source`, `parseOptions`, `buildVolume` (consumer-wins bed
+precedence), `quality`, `colorMode`, `layerRange`, `scrub`, `showTravel`, `progress` (DD-006
+observation), `createWorker`. Events: `ready`, `parseerror`, `parsecancelled`, `parseprogress`,
+`buildcomplete`, `qualityfallback`, `machinegeometrymismatch`/`discovered`,
+`progresspresentationchanged`, `disclosure`, `error`. The full handle is exported as `preview`
+(`bind:this` then `.preview`).
+
+## Store/action API (build your own controls)
+
+```svelte
+<script>
+  import { createGcodePreview } from '@chestnutlabs/gcode-preview-svelte';
+  import { onDestroy } from 'svelte';
+
+  const preview = createGcodePreview();
+  onDestroy(() => preview.dispose());
+  // $state store: const state = preview.state;  →  {$state.summary?.segments}
+  // await preview.parse(bytes); preview.controls.setScrubPosition(n);
+  // preview.observeProgress(obs); preview.raw.renderer()
+</script>
+
+<canvas use:preview.canvas style="width: 100%; height: 100%" />
+```
+
+`preview.state` follows the Svelte store contract (immediate emission + every snapshot after),
+so `$`-prefix auto-subscription works. Headless (non-component) users call `dispose()` themselves.
+
+## Workers
+
+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 — options are
+identical across all three framework adapters by design (see the Vue README for the shared worker
+documentation).
+
+## Example
+
+`tools/example-svelte` in the repository is a complete Vite + Svelte app (corpus load,
+layer/scrub, simulated live progress) compiling the raw component through the export condition.

package/dist/GcodePreview.svelte

@@ -0,0 +1,113 @@
+<script>
+  /**
+   * <GcodePreview> — the ready-to-use Svelte component (DD-007 D1 amendment, phase 7).
+   *
+   * Strictly a SHELL over `createGcodePreview` (D1: never a separate implementation):
+   * every prop is a reactive statement into the store/action API, every dispatched event
+   * re-fires a controller event, and the underlying handle is exported for bind:this
+   * access (`preview`). Advanced props are optional with sensible defaults, so
+   * `<GcodePreview source={file} />` alone is a working viewer (D4).
+   *
+   * Svelte-4-style component (compiles under Svelte 5 compat) shipped RAW — the
+   * consumer's bundler compiles it via the "svelte" export condition.
+   */
+  import { createEventDispatcher, onDestroy } from 'svelte';
+  import { createGcodePreview } from './create-gcode-preview.js';
+
+  /** Bytes/File to parse. Changing it re-parses. */
+  export let source = null;
+  export let parseOptions = undefined;
+  /** Consumer-configured volume — wins over file-discovered geometry (DD-005). */
+  export let buildVolume = undefined;
+  export let quality = 'auto';
+  export let colorMode = undefined;
+  export let tube = undefined;
+  /** Inclusive [start, end]; null shows every layer. */
+  export let layerRange = null;
+  /** Scrub cut (IR segment index); null shows everything up to the layer range. */
+  export let scrub = null;
+  export let showTravel = true;
+  /** DD-006 live progress observation; null hides the overlay. */
+  export let progress = null;
+  /** Worker factory escape hatch (DD-005 slim/custom entries; D2). */
+  export let createWorker = undefined;
+  /** Advanced/test renderer injectables (pass-throughs of the renderer contract). */
+  export let rendererOptions = undefined;
+
+  const dispatch = createEventDispatcher();
+  const isMachine = buildVolume !== undefined && 'bed' in buildVolume;
+
+  /** The full store/action handle — reachable via `bind:this={c}` then `c.preview`. */
+  export const preview = createGcodePreview({
+    createWorker,
+    renderer: {
+      buildVolume: isMachine ? undefined : buildVolume,
+      quality,
+      colorMode,
+      tube,
+      ...rendererOptions
+    },
+    parseDefaults: parseOptions
+  });
+
+  if (isMachine) preview.controls.setBuildVolume(buildVolume);
+
+  preview.onEvent((e) => {
+    switch (e.type) {
+      case 'parse-complete':
+        dispatch('ready', { segments: e.segments, layers: e.layers, complete: e.complete });
+        break;
+      case 'parse-error':
+        dispatch('parseerror', { code: e.code, message: e.message });
+        break;
+      case 'parse-cancelled':
+        dispatch('parsecancelled');
+        break;
+      case 'parse-progress':
+        dispatch('parseprogress', { bytesProcessed: e.progress.bytesProcessed, totalBytes: e.progress.totalBytes });
+        break;
+      case 'buildComplete': {
+        dispatch('buildcomplete', { segments: e.segments, quality: e.quality });
+        let disclosure = '';
+        const off = preview.state.subscribe((s) => (disclosure = s.disclosure));
+        off();
+        dispatch('disclosure', disclosure);
+        break;
+      }
+      case 'qualityFallback':
+        dispatch('qualityfallback', { from: e.from, to: e.to, reason: e.reason });
+        break;
+      case 'progress-presentation-changed':
+        dispatch('progresspresentationchanged', e.reason === undefined ? { mode: e.mode } : { mode: e.mode, reason: e.reason });
+        break;
+      case 'machine-geometry-discovered':
+        dispatch('machinegeometrydiscovered', e.machine);
+        break;
+      case 'error':
+        if (e.code === 'machine-geometry-mismatch') dispatch('machinegeometrymismatch', e.message);
+        else dispatch('error', { code: e.code, message: e.message });
+        break;
+      default:
+        break;
+    }
+  });
+
+  // ---- prop wiring: each prop is a thin reactive call into the handle (D1 shell rule) ----
+  $: if (source !== null && source !== undefined) void preview.parse(source, parseOptions);
+  $: if (layerRange === null || layerRange === undefined) preview.controls.setLayerRange(0, Number.POSITIVE_INFINITY);
+  else preview.controls.setLayerRange(layerRange[0], layerRange[1]);
+  $: preview.controls.setScrubPosition(scrub ?? null);
+  $: preview.controls.setKindVisible('travel', showTravel);
+  $: if (colorMode !== undefined) preview.controls.setColorMode(colorMode);
+  $: preview.controls.setQuality(quality);
+  $: if (progress === null || progress === undefined) preview.clearProgress();
+  else preview.observeProgress(progress);
+
+  onDestroy(() => preview.dispose());
+</script>
+
+<canvas
+  use:preview.canvas
+  style="width: 100%; height: 100%; display: block; touch-action: none;"
+  aria-label="3D G-code toolpath preview"
+></canvas>

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

@@ -0,0 +1,47 @@
+/**
+ * createGcodePreview — the Svelte reactivity bridge over the framework-neutral
+ * controller (DD-007 §4.6 D1 amendment, phase 7, issue #114). This file owns ONLY the
+ * Svelte-isms: a store-contract `state` (subscribe receiving controller snapshots) and
+ * a `use:` action for the canvas. Engine mechanics and contracts live in
+ * @chestnutlabs/gcode-preview-core and are RE-EXPORTED, never redeclared.
+ *
+ * Lifecycle: the component wrapper disposes via onDestroy. Headless users (this API
+ * outside a component) call `dispose()` themselves — there is no ambient scope to tie to.
+ */
+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';
+/** Svelte-facing options — identical to the controller's (the alias is the public name). */
+export type CreateGcodePreviewOptions = PreviewControllerOptions;
+/** Minimal svelte/store Readable contract — declared structurally so the shipped JS
+ *  never imports 'svelte' (the component and consumers bring their own). */
+export interface ReadableState {
+    subscribe(run: (state: GcodePreviewState) => void): () => void;
+}
+/** Svelte `use:` action result for the canvas binding. */
+export interface CanvasActionResult {
+    destroy(): void;
+}
+export interface SvelteGcodePreview {
+    /** Store-contract state: subscribers receive the current snapshot immediately,
+     *  then every replacement — `$preview.state` works in components. */
+    state: ReadableState;
+    /** Canvas binding as a Svelte action: `<canvas use:preview.canvas />`. */
+    canvas(el: HTMLCanvasElement): CanvasActionResult;
+    parse(input: Uint8Array | ArrayBuffer | File, opts?: WireParseOptions): Promise<ParseOutcome>;
+    cancel(): void;
+    observeProgress(obs: ProgressObservation): MappedProgress | null;
+    tickProgress(nowMs: number): MappedProgress | null;
+    clearProgress(): void;
+    controls: GcodePreviewControls;
+    raw: {
+        session: GcodeParseSession;
+        renderer: () => ToolpathRenderer | null;
+    };
+    onEvent(cb: (e: PreviewEvent) => void): () => void;
+    dispose(): void;
+}
+export declare function createGcodePreview(options?: CreateGcodePreviewOptions): SvelteGcodePreview;
+//# sourceMappingURL=create-gcode-preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-gcode-preview.d.ts","sourceRoot":"","sources":["../src/create-gcode-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,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,4FAA4F;AAC5F,MAAM,MAAM,yBAAyB,GAAG,wBAAwB,CAAC;AAEjE;4EAC4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAChE;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC;yEACqE;IACrE,KAAK,EAAE,aAAa,CAAC;IACrB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,EAAE,iBAAiB,GAAG,kBAAkB,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,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;AAED,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,kBAAkB,CAuB9F"}

package/dist/create-gcode-preview.js

@@ -0,0 +1,25 @@
+import { createPreviewController } from '@chestnutlabs/gcode-preview-core';
+export function createGcodePreview(options = {}) {
+    const controller = createPreviewController(options);
+    return {
+        state: {
+            subscribe(run) {
+                run(controller.getState()); // store contract: immediate emission
+                return controller.onStateChange(run);
+            }
+        },
+        canvas: (el) => {
+            controller.bindCanvas(el);
+            return { destroy: () => controller.bindCanvas(null) };
+        },
+        parse: controller.parse,
+        cancel: controller.cancel,
+        observeProgress: controller.observeProgress,
+        tickProgress: controller.tickProgress,
+        clearProgress: controller.clearProgress,
+        controls: controller.controls,
+        raw: controller.raw,
+        onEvent: controller.onEvent,
+        dispose: controller.dispose
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @chestnutlabs/gcode-preview-svelte — thin Svelte integration (DD-007 D1 amendment).
+ *
+ * `createGcodePreview` store/action API + the raw `GcodePreview.svelte` component
+ * (import from '@chestnutlabs/gcode-preview-svelte/GcodePreview.svelte' — the consumer's
+ * bundler compiles it via the "svelte" export condition). Both are reactivity bridges
+ * over @chestnutlabs/gcode-preview-core — never a separate viewer implementation.
+ */
+export * from './create-gcode-preview.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,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @chestnutlabs/gcode-preview-svelte — thin Svelte integration (DD-007 D1 amendment).
+ *
+ * `createGcodePreview` store/action API + the raw `GcodePreview.svelte` component
+ * (import from '@chestnutlabs/gcode-preview-svelte/GcodePreview.svelte' — the consumer's
+ * bundler compiles it via the "svelte" export condition). Both are reactivity bridges
+ * over @chestnutlabs/gcode-preview-core — never a separate viewer implementation.
+ */
+export * from './create-gcode-preview.js';

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@chestnutlabs/gcode-preview-svelte",
+  "version": "0.1.0",
+  "description": "Thin Svelte integration for the Chestnut Labs G-code viewer (DD-007 D1 amendment): createGcodePreview store/action API + GcodePreview component as a reactivity bridge over @chestnutlabs/gcode-preview-core.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "svelte",
+    "store",
+    "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-svelte"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "svelte": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./GcodePreview.svelte": {
+      "svelte": "./dist/GcodePreview.svelte",
+      "import": "./dist/GcodePreview.svelte"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node copy-svelte.mjs",
+    "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": {
+    "svelte": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "svelte": "^4.2.0"
+  }
+}