Parameters, expressions, if / while / do / repeat control flow, and in-file subroutines all run — bounded (a hostile file can't hang the parser: maxProgramIterations / maxCallDepth) and honest (a clean run reports parametricProgram: 'known'; a limit or unsupported construct drops to approximated with a specific warning). It engages only on files that use # / [ / O-words; every FDM file is byte-for-byte unchanged. See Parametric programs.

Framework integration

Four adapters over one engine, with matching options, events, and TypeScript types — enforced by a shared behavioral test suite (with a controls/state parity guard) that runs against all four in CI. Each adapter exposes both viewers: the toolpath <GcodePreview> from the package root, and the source-model <ModelViewer> from the package's /model subpath (the Prepare side).

Browser & performance architecture

• Off-thread parsing — a GcodeParseSession runs the parser in a Web Worker with streaming input, progressive previews for large files, resource limits, and cancellation.
• Parallel geometry build — a geometry worker pool builds extrusion tubes off the main thread (byte-identical to serial), bounded by a memory budget and degrading gracefully (pool → serial → lines) with every step disclosed. Big plates stay responsive.
• Preparation is staged, the reveal is clean — a stage event walks parsing → classifying → building-geometry → preparing-gpu → ready with a real build percentage, and progressivePreview: 'hold' suppresses the half-built scene so the model appears in one clean reveal instead of visibly growing.
• Render diagnostics — getRenderStats() reports what actually happened: backend and WebGL version, hardware-vs-software GPU (unmasked renderer/vendor), geometry mode, rendered segment and draw-call counts, whether decimation applied, worker count, and a timing breakdown — a ready-made "what am I running on / why is this slow" panel, never fabricated.
• Batteries-included worker — the adapters wire up a worker with every dialect and .gcode.3mf support via the bundler-native new Worker(new URL(...)) pattern (Vite works out of the box); a createWorker hook is the escape hatch for slim builds, custom dialects, or strict-CSP hosts.
• Headless still render — renderStill produces a single non-interactive image from an OffscreenCanvas, an Electron hidden window, or headless Chromium, for server-side thumbnails.

Two views, two jobs: toolpath vs. model

Everything above renders the toolpath — the moves the machine makes. That answers how the job runs: where the seams are, which layer a retraction happens on, how travel threads between islands. But sometimes you don't want the toolpath at all — you want a clean picture of what the object is, the way a slicer's file browser shows a part. Those are two different jobs, so they're two different renderers:

The model renderer is a presentation surface, not a second toolpath viewer. It takes an STL or a 3MF mesh, frames it, lights it with a neutral studio rig, and draws it — nothing about layers, moves, or print order. 3MF brings its own multi-object structure and per-object / per-triangle material colors; a bare STL is a single object with no declared material.

It keeps the same honesty rule as the rest of the library. When the source actually declares colors (3MF basematerials), the render uses them. When it doesn't — a plain STL, or a proprietary paint format the standard doesn't cover — it draws a neutral default and reports materials: 'unavailable' rather than inventing a color. The headless renderModelStill mirrors renderStill: hand it bytes, get back a canvas plus a stable cacheKey and the materials confidence for that render.

import { renderModelStill } from '@chestnutlabs/gcode-model-renderer';

const { canvas, materials, cacheKey } = await renderModelStill(
  { kind: 'stl', bytes },                       // or { kind: '3mf', bytes }
  { canvas: new OffscreenCanvas(512, 512), background: 'transparent' }
);
// materials: 'known' when the source carried colors, 'unavailable' when it didn't.
Copy

Need it live rather than as a thumbnail — a "View in 3D" for the part? Interactive source-model viewing is a first-class, declarative half of the SDK: drop <ModelViewer source={…} /> from any framework's /model subpath (@chestnutlabs/gcode-preview-{react,vue,svelte}/model, or <gcode-model-viewer> from the Web Component) and orbit/zoom/pan the same STL / 3MF (including production multicolor) with camera presets, serializable camera state, per-plate render scope, and the honest materials capability tier — the same parity (props, events, lifecycle, cleanup) as the toolpath component. It wraps the framework-neutral createModelPreviewController over the shared createModelViewer engine. See the adapters guide ("Two viewers: Preview and Prepare") and the model-renderer README.

Multi-plate, multi-object, or just a subset. A 3MF project can hold several plates and many objects. Parse or render one plate at a time (parseOptions.plate), and a render scope ({ plateId }, { objectIds }, or an instance filter) narrows a still or the viewer to exactly the plate or objects you want — a single plate's thumbnail, or one part isolated from the rest — with a stable cache key per scope.

Quick start

Install an adapter plus three (the renderer declares three as a peer dependency, range ^0.178.0; npm ≥ 7 installs it automatically, pnpm/yarn users add it explicitly):

npm install @chestnutlabs/gcode-preview-react three
Copy

import { GcodePreview } from '@chestnutlabs/gcode-preview-react';

function Viewer({ file }) {                 // file: a File from an <input>, or a Uint8Array
  return (
    <div style={{ height: '70vh' }}>
      <GcodePreview source={file} onReady={(s) => console.log(`${s.segments} segments`)} />
    </div>
  );
}
Copy

<GcodePreview source={file} /> is the whole thin path; the full viewer — layer clip, scrub, color modes, cameras, live progress — is reachable through props and the lower-level hook without switching APIs.

<script setup>
import { GcodePreview } from '@chestnutlabs/gcode-preview-vue';
import { shallowRef } from 'vue';
const file = shallowRef(null);
</script>

<template>
  <input type="file" accept=".gcode,.3mf,.bgcode" @change="file = $event.target.files?.[0] ?? null" />
  <div style="height: 70vh">
    <GcodePreview :source="file" @ready="(s) => console.log(`${s.segments} segments`)" />
  </div>
</template>
Copy

<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>
Copy

<script type="module">
  import '@chestnutlabs/gcode-preview-element/define';   // registers <gcode-preview>
</script>

<gcode-preview quality="tubes" style="display:block;height:70vh"></gcode-preview>
<script type="module">
  const el = document.querySelector('gcode-preview');
  el.source = await (await fetch('/model.gcode')).arrayBuffer();  // Uint8Array | ArrayBuffer | File
</script>
Copy

All four adapters share the same option surface — source, parseOptions, buildVolume, quality, colorMode, layerRange, scrub, showTravel, progress, cameraMode, view, cameraState, showVolumeCage, frameContent, interactionQuality, theme, createWorker — with matching events (ready — now carrying parsed slice metadata when the dialect supplied it — parse-progress, build-complete, quality-fallback, error, and more). The cross-adapter guide and each package README are the canonical reference.

Formats & compatibility

Input formats

Slicer & firmware dialects annotate the toolpath with feature roles, objects, bed geometry, and more: PrusaSlicer, OrcaSlicer / Bambu Studio, Cura, Klipper, Marlin, and RepRap-flavor. Every annotation carries a confidence tier (below). See the evidence-dated compatibility matrix and G-code motion coverage for the exact per-dialect state.

The honesty model. Every derived fact is tagged with how sure the parser is:

This is why capability-gated features (a color mode, a live-progress marker, a CNC classification) either work from real data or explain why they can't — they never render something the file didn't contain. Details: ToolpathIR & the capability model.

Documentation

• Manual & getting started, the visual feature gallery (what it does, shown rather than described), and the API reference (generated from source).
• Concepts: workers & performance · IR & capabilities · dialects & containers · progress & motion
• Guides: cross-adapter tour · recipes
• References: progress-signal contract · live-progress consumer notes · headless still render · support & deprecation policy · multiple previews on one page

Try it locally

tools/demo is the showcase: the whole pipeline behind one control panel — corpus picker, dialect annotations, quality/color modes, layer clip + time/segment scrub, camera presets and save/restore, simulated live-progress tiers, themes, and STL export.

cd tools/demo
npm install
npm run dev        # http://localhost:5199
Copy

tools/example-react and tools/example-svelte are complete standalone Vite apps. All three consume the packages exactly as an external consumer would.

How it's built

The stack is a pipeline of small packages, each doing one job:

 G-code  ─▶  parser (Web Worker)  ─▶  ToolpathIR  ─▶  toolpath renderer  ─▶  canvas
             dialects · containers    (neutral,        three / 2d
             · bgcode decode           versioned)      + colors

 STL / 3MF mesh  ─────────────────▶  ModelScene  ─▶  model renderer  ─▶  canvas
                                     (presentation)   (shared render stage)
Copy

The two rows share the render "stage" (framing + GL builder) but are otherwise independent: the top row inspects the toolpath, the bottom row presents the source model (see Two views, two jobs).

• @chestnutlabs/toolpath-core — ToolpathIR (structure-of-arrays geometry + metadata + source index), the capability model, progress mapping, and time estimation. The neutral seam every other package reads or writes.
• @chestnutlabs/gcode-parser — the worker parse core and GcodeParseSession client: streaming input, progressive previews, resource limits, cancellation.
• @chestnutlabs/gcode-dialects — slicer/firmware annotators. They add metadata and optional channels; they can never alter geometry.
• @chestnutlabs/gcode-containers — bounded, in-memory .gcode.3mf / ZIP extraction, hardened against adversarial archives.
• @chestnutlabs/gcode-bgcode — Prusa .bgcode decode (license-clean MeatPack + heatshrink), registered as a container adapter so .bgcode "just works".
• @chestnutlabs/gcode-colors — the renderer-agnostic ColorMode model (feature, speed, tool, object, layer-height, color-change, tool-power, cut-vs-rapid), shared by both toolpath renderers.
• @chestnutlabs/gcode-renderer-three — the Three.js toolpath renderer (peer: three): layer chunks, decimation disclosure, draw-range clip/scrub, cameras, themes, live-progress overlay. Also exports the shared render "stage" (framing pose + GL builder).
• @chestnutlabs/gcode-renderer-2d — the Canvas 2D LayerView2D (no WebGL, no three): current + adjacent "ghost" layers.
• @chestnutlabs/gcode-model-renderer — a separate presentation renderer (peer: three) for the source model — STL and 3MF multi-object/material — with headless renderModelStill. It answers "what object is this?", not "how does the toolpath run?"; see Two views, two jobs.
• @chestnutlabs/gcode-preview-core — the framework-neutral controller, immutable state model, renderStill, and the portable behavioral suite.
• -vue · -react · -svelte · -element — the four framework adapters.

Design rationale, boundaries, and the accepted architecture live in docs/design/; the docs index maps the whole set. Fourteen packages publish to npm in lockstep (currently v0.20.1) with npm provenance.

Development

# Node >= 22
npm ci
npm run build            # legacy engine build (rollup)
npm run test             # root suite (IR goldens, manifest validation, adapters)
npm run test:packages    # all workspace package suites
npm run lint && npm run typeCheck && npm run license:check
npm run docs:links       # verify documentation links
Copy

To rebuild the workspace packages the demo consumes, build them in dependency order (toolpath-core → colors/containers/dialects → bgcode → parser → renderers → core → adapters); see tools/screenshots/README.md for the documentation-media capture harness.

Contributing: CONTRIBUTING.md · security policy: SECURITY.md · documentation standard: docs/USER_FACING_DOCS_STYLE.md.

Origin & attribution

This project began as a fork of xyz-tools/gcode-preview (project identity remcoder/gcode-preview) by Remco Veldkamp and contributors, MIT-licensed. Chestnut Labs has rebuilt it into the worker-based, multi-package browser toolpath toolkit described above. The inherited Git history is preserved, upstream copyright notices are retained in LICENSE, and the full provenance record lives in NOTICE.md, docs/UPSTREAM_PROVENANCE.md, and the upstream & licensing policy. Upstream changes are adopted deliberately through review, never auto-synced.

License

MIT — inherited code © 2017–2025 Remco Veldkamp and the xyz-tools/gcode-preview contributors; Chestnut Labs additions © 2026 Chestnut Labs.