@chestnutlabs/gcode-preview-core 0.2.0 → 0.3.0

package/dist/controller.d.ts

@@ -10,10 +10,11 @@
  * only (numbers/strings): IR/typed arrays NEVER enter the state model.
  */
 import { GcodeParseSession, type ParseProgress, type ParseResult, type SessionOptions, type WireParseOptions } from '@chestnutlabs/gcode-parser';
-import { ToolpathRenderer, type BuildVolumeDef, type CameraMode, type ColorMode, type GLRendererLike, type ProgressPresentationMode, type QualityMode, type RenderTargetCanvas, type RendererEvent, type Theme, type TubeOptions } from '@chestnutlabs/gcode-renderer-three';
+import type { BuildVolumeDef, CameraMode, ColorMode, GLRendererLike, ProgressPresentationMode, QualityMode, RenderTargetCanvas, Theme, TubeOptions } from '@chestnutlabs/gcode-renderer-three';
+import type { MoveKindToggle, PreviewRenderer, PreviewRendererEvent, RendererMode } from './renderer-interface.js';
 import { type Confidence, type DialectMetadata, type MachineGeometry, type MappedProgress, type ProgressObservation } from '@chestnutlabs/toolpath-core';
 /** Session/renderer events, re-emitted, plus the controller's own lifecycle events. */
-export type PreviewEvent = RendererEvent | {
+export type PreviewEvent = PreviewRendererEvent | {
     type: 'parse-started';
     bytes: number;
 } | {
@@ -40,15 +41,25 @@ export interface PreviewControllerOptions {
     /** Custom worker factory (DD-005 slim/custom entries). Default: the batteries worker. */
     createWorker?: SessionOptions['worker'];
     renderer?: {
+        /**
+         * Renderer implementation (DD-014 D5): `'3d'` (default) is the Three.js renderer; `'2d'` is the
+         * low-resource Canvas 2D layer view. The 3D renderer is loaded on demand, so a `'2d'` consumer's
+         * bundle never pulls Three.js. 3D-only options below are ignored (and disclosed) in `'2d'`.
+         */
+        mode?: RendererMode;
         buildVolume?: BuildVolumeDef;
         quality?: QualityMode | 'auto';
-        /** Camera projection (#150, DD-009 D3); default 'perspective'. */
+        /** Camera projection (#150, DD-009 D3); default 'perspective'. 3D only. */
         cameraMode?: CameraMode;
         colorMode?: ColorMode;
         tube?: TubeOptions;
-        /** Bounded declarative theme (#153, DD-009 D4). */
+        /** Bounded declarative theme (#153, DD-009 D4). 3D only. */
         theme?: Theme;
-        /** Advanced/test injectables — pass-throughs of the renderer's own contract. */
+        /** 2D only: preceding "ghost" layers drawn beneath the active one (default 1, floor 0). */
+        adjacentLayers?: number;
+        /** 2D only: ghost-layer opacity (default 0.25). */
+        ghostOpacity?: number;
+        /** Advanced/test injectables — pass-throughs of the renderer's own contract (3D only). */
         createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
         scheduleFrame?: (cb: () => void) => void;
         chunksPerTick?: number;
@@ -90,6 +101,13 @@ export interface GcodePreviewState {
     segmentCount: number;
     /** User-presentable decimation/travel disclosure (empty when rendering everything). */
     disclosure: string;
+    /**
+     * Estimated total print time in ms (#181), or null before a parse. `timeEstimateSource` says whether
+     * it's the slicer's own estimate (`'slicer'`, trustworthy) or a kinematic approximation
+     * (`'kinematic'`, constant-velocity, slightly low — disclose when shown).
+     */
+    totalTimeMs: number | null;
+    timeEstimateSource: 'slicer' | 'kinematic' | null;
     error: {
         code: string;
         message: string;
@@ -98,7 +116,12 @@ export interface GcodePreviewState {
 export interface GcodePreviewControls {
     setLayerRange(startLayer: number, endLayer: number): void;
     setScrubPosition(segIndex: number | null): void;
-    setKindVisible(kind: 'extrude' | 'travel', visible: boolean): void;
+    /**
+     * Time-based scrub (#181): cut the toolpath at print time `ms` (kinematic axis). null clears the
+     * cut. Resolves to a segment-index scrub; no-op before a successful parse.
+     */
+    setScrubTime(ms: number | null): void;
+    setKindVisible(kind: MoveKindToggle, visible: boolean): void;
     /** Opt-in retraction/deretraction markers (DD-009 D1, #148). Off by default. */
     setShowRetractions(visible: boolean): void;
     setColorMode(mode: ColorMode): boolean;
@@ -126,10 +149,14 @@ export interface PreviewController {
     /** Subscribe to snapshot replacements. Returns the unsubscriber. */
     onStateChange(cb: (state: GcodePreviewState) => void): () => void;
     controls: GcodePreviewControls;
-    /** Escape hatches — the neutral objects themselves (advanced use). */
+    /**
+     * Escape hatches — the neutral objects themselves (advanced use). `renderer()` returns the active
+     * {@link PreviewRenderer} (the 3D `ToolpathRenderer` or the 2D `LayerView2DRenderer`), or null
+     * before bind / during the 3D renderer's on-demand load.
+     */
     raw: {
         session: GcodeParseSession;
-        renderer: () => ToolpathRenderer | null;
+        renderer: () => PreviewRenderer | null;
     };
     onEvent(cb: (e: PreviewEvent) => void): () => void;
     dispose(): void;

package/dist/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EACL,iBAAiB,EAGjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,cAAc,EACd,wBAAwB,EACxB,WAAW,EACX,kBAAkB,EAClB,KAAK,EACL,WAAW,EACZ,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACnH,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,KAAK,mBAAmB,EAGzB,MAAM,6BAA6B,CAAC;AAErC,uFAAuF;AACvF,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC3B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtD;IACE;uEACmE;IACnE,IAAI,EAAE,6BAA6B,CAAC;IACpC,OAAO,EAAE,eAAe,CAAC;CAC1B,CAAC;AAEN,MAAM,WAAW,wBAAwB;IACvC,yFAAyF;IACzF,YAAY,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE;QACT;;;;WAIG;QACH,IAAI,CAAC,EAAE,YAAY,CAAC;QACpB,WAAW,CAAC,EAAE,cAAc,CAAC;QAC7B,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;QAC/B,2EAA2E;QAC3E,UAAU,CAAC,EAAE,UAAU,CAAC;QACxB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,IAAI,CAAC,EAAE,WAAW,CAAC;QACnB,4DAA4D;QAC5D,KAAK,CAAC,EAAE,KAAK,CAAC;QACd,2FAA2F;QAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,mDAAmD;QACnD,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,0FAA0F;QAC1F,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;QAChE,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;QACzC,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,yDAAyD;IACzD,aAAa,CAAC,EAAE,gBAAgB,CAAC;CAClC;AAED,6FAA6F;AAC7F,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,wFAAwF;IACxF,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACzC,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI,CAAC;IACT,QAAQ,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,YAAY,EAAE,wBAAwB,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kBAAkB,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI,CAAC;IAClD,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAChD;;;OAGG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACtC,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7D,gFAAgF;IAChF,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3C,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IACvC,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,kDAAkD;IAClD,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACtC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,0FAA0F;IAC1F,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,GAAG,IAAI,CAAC;IAC5D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,UAAU,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IACnD,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,iFAAiF;IACjF,QAAQ,IAAI,iBAAiB,CAAC;IAC9B,oEAAoE;IACpE,aAAa,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAClE,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;OAIG;IACH,GAAG,EAAE;QAAE,OAAO,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,MAAM,eAAe,GAAG,IAAI,CAAA;KAAE,CAAC;IAC5E,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnD,OAAO,IAAI,IAAI,CAAC;CACjB;AAqBD,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,iBAAiB,CAmTjG"}

package/dist/controller.js

@@ -10,8 +10,8 @@
  * only (numbers/strings): IR/typed arrays NEVER enter the state model.
  */
 import { GcodeParseSession, CancelledError, ParseSessionError } from '@chestnutlabs/gcode-parser';
-import { ToolpathRenderer } from '@chestnutlabs/gcode-renderer-three';
-import { createProgressMapper } from '@chestnutlabs/toolpath-core';
+import { LayerView2DRenderer } from './renderer-2d-adapter.js';
+import { createProgressMapper, computeToolpathTime, segmentsCompletedAtTime } from '@chestnutlabs/toolpath-core';
 const INITIAL_STATE = {
     parsing: false,
     parseProgress: null,
@@ -22,6 +22,8 @@ const INITIAL_STATE = {
     layerCount: 0,
     segmentCount: 0,
     disclosure: '',
+    totalTimeMs: null,
+    timeEstimateSource: null,
     error: null
 };
 function toBytes(input) {
@@ -40,6 +42,7 @@ export function createPreviewController(options = {}) {
     let renderer = null;
     let unbindRendererEvents = null;
     let lastIR = null;
+    let timeAxis = null;
     let lastMachine;
     let mapper = null;
     let consumerVolumeSet = options.renderer?.buildVolume !== undefined;
@@ -47,6 +50,17 @@ export function createPreviewController(options = {}) {
     let resizeObserver = null;
     let windowResize = null;
     let disposed = false;
+    // The 3D renderer is loaded on demand (DD-014: a 2D-only bundle never pulls Three.js), so binding
+    // can resolve asynchronously. `bindGen` invalidates a slow load superseded by rebind/dispose;
+    // `pendingOps` replays control calls made before the renderer is ready.
+    let bindGen = 0;
+    const pendingOps = [];
+    const withRenderer = (fn) => {
+        if (renderer !== null)
+            fn(renderer);
+        else
+            pendingOps.push(fn);
+    };
     const listeners = new Set();
     const emit = (e) => {
         for (const cb of listeners)
@@ -90,28 +104,10 @@ export function createPreviewController(options = {}) {
         const h = canvas.clientHeight || canvas.height || 1;
         renderer?.resize(w, h);
     }
-    function bindCanvas(canvas) {
-        if (disposed)
-            return;
-        if (canvas === null) {
-            disposeRenderer();
-            return;
-        }
-        disposeRenderer();
-        const r = options.renderer ?? {};
-        renderer = new ToolpathRenderer({
-            canvas,
-            buildVolume: r.buildVolume,
-            quality: r.quality ?? 'auto',
-            cameraMode: r.cameraMode,
-            colorMode: r.colorMode,
-            tube: r.tube,
-            theme: r.theme,
-            createRenderer: r.createRenderer,
-            scheduleFrame: r.scheduleFrame,
-            chunksPerTick: r.chunksPerTick
-        });
-        unbindRendererEvents = renderer.onEvent(onRendererEvent);
+    /** Wire a freshly-constructed renderer: events, sizing, replay of IR + queued control ops. */
+    function applyRendererReady(canvas, r) {
+        renderer = r;
+        unbindRendererEvents = r.onEvent(onRendererEvent);
         // Sizing (§4.2): explicit initial fit; ResizeObserver where available; window-resize
         // fallback because observers may never fire in embedded panes.
         fitToCanvas(canvas);
@@ -125,9 +121,61 @@ export function createPreviewController(options = {}) {
             window.addEventListener('resize', windowResize);
         }
         if (lastIR !== null) {
-            renderer.setIR(lastIR);
-            mutate({ layerCount: renderer.layerCount, segmentCount: renderer.segmentCount });
+            r.setIR(lastIR);
+            // DD-005 consumer-wins: only auto-apply file geometry when the consumer set no volume.
+            if (lastMachine !== undefined && !consumerVolumeSet)
+                r.setBuildVolume(lastMachine);
+        }
+        // Replay control calls made during the (async) load, in order.
+        for (const op of pendingOps)
+            op(r);
+        pendingOps.length = 0;
+        if (lastIR !== null)
+            mutate({ layerCount: r.layerCount, segmentCount: r.segmentCount });
+    }
+    function bindCanvas(canvas) {
+        if (disposed)
+            return;
+        disposeRenderer();
+        if (canvas === null)
+            return;
+        const gen = ++bindGen;
+        const r = options.renderer ?? {};
+        if ((r.mode ?? '3d') === '2d') {
+            // The 2D renderer is a static (three-free) import — construct synchronously.
+            applyRendererReady(canvas, new LayerView2DRenderer(canvas, {
+                colorMode: r.colorMode,
+                adjacentLayers: r.adjacentLayers,
+                ghostOpacity: r.ghostOpacity
+            }));
+            return;
         }
+        // 3D: load Three.js on demand so a 2D-only bundle never ships it (DD-014 D4).
+        import('@chestnutlabs/gcode-renderer-three')
+            .then((mod) => {
+            if (disposed || gen !== bindGen)
+                return; // superseded by a rebind/dispose during the load
+            const r3d = new mod.ToolpathRenderer({
+                canvas,
+                buildVolume: r.buildVolume,
+                quality: r.quality ?? 'auto',
+                cameraMode: r.cameraMode,
+                colorMode: r.colorMode,
+                tube: r.tube,
+                theme: r.theme,
+                createRenderer: r.createRenderer,
+                scheduleFrame: r.scheduleFrame,
+                chunksPerTick: r.chunksPerTick
+            });
+            applyRendererReady(canvas, r3d);
+        })
+            .catch((err) => {
+            if (disposed || gen !== bindGen)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            mutate({ error: { code: 'E_RENDERER_LOAD', message } });
+            emit({ type: 'error', code: 'E_RENDERER_LOAD', message });
+        });
     }
     const offProgress = session.onProgress((p) => {
         mutate({ parseProgress: p });
@@ -157,6 +205,12 @@ export function createPreviewController(options = {}) {
             lastIR = result.ir;
             lastMachine = result.metadata?.machine;
             mapper = createProgressMapper(result.ir, { fileSizeBytes: bytes });
+            // Time axis (#181): prefer the slicer's own estimate (#183) for the total; the kinematic axis
+            // always backs time-scrub. `hasUnknownFeedrate` means the kinematic total is a lower bound.
+            timeAxis = computeToolpathTime(result.ir);
+            const slicerSeconds = result.metadata?.printEstimate?.seconds;
+            const totalTimeMs = slicerSeconds !== undefined ? slicerSeconds * 1000 : timeAxis.totalMs;
+            const timeEstimateSource = slicerSeconds !== undefined ? 'slicer' : 'kinematic';
             const counts = renderer !== null
                 ? { layerCount: renderer.layerCount, segmentCount: renderer.segmentCount }
                 : { layerCount: result.ir.layers.length, segmentCount: result.ir.segments.count };
@@ -173,6 +227,8 @@ export function createPreviewController(options = {}) {
                 },
                 metadata: result.metadata,
                 presentation: 'hidden',
+                totalTimeMs,
+                timeEstimateSource,
                 ...(renderer !== null ? { layerCount: renderer.layerCount, segmentCount: renderer.segmentCount } : counts)
             });
             // DD-005 consumer-wins precedence: a consumer-configured volume blocks auto-apply.
@@ -208,19 +264,32 @@ export function createPreviewController(options = {}) {
         }
     }
     const controls = {
-        setLayerRange: (a, b) => renderer?.setLayerRange(a, b),
-        setScrubPosition: (s) => renderer?.setScrubPosition(s),
-        setKindVisible: (k, v) => renderer?.setKindVisible(k, v),
-        setShowRetractions: (v) => renderer?.setShowRetractions(v),
-        setColorMode: (m) => renderer?.setColorMode(m) ?? false,
-        setQuality: (q) => renderer?.setQuality(q),
-        setCameraMode: (m) => renderer?.setCameraMode(m),
-        setTheme: (t) => renderer?.setTheme(t),
+        // Controls queue when the (async) renderer isn't ready yet, then replay in order on bind.
+        setLayerRange: (a, b) => withRenderer((r) => r.setLayerRange(a, b)),
+        setScrubPosition: (s) => withRenderer((r) => r.setScrubPosition(s)),
+        setScrubTime: (ms) => {
+            // Resolve a print time to a segment-index scrub cut via the kinematic axis (#181).
+            const seg = ms === null || timeAxis === null ? null : segmentsCompletedAtTime(timeAxis.cumulativeMs, ms);
+            withRenderer((r) => r.setScrubPosition(seg));
+        },
+        setKindVisible: (k, v) => withRenderer((r) => r.setKindVisible(k, v)),
+        setShowRetractions: (v) => withRenderer((r) => r.setShowRetractions(v)),
+        // Availability is IR/renderer-dependent; before the renderer is ready we optimistically queue
+        // and report true (the mode applies once bound). Callers can re-check after `parse-complete`.
+        setColorMode: (m) => {
+            if (renderer !== null)
+                return renderer.setColorMode(m);
+            pendingOps.push((r) => r.setColorMode(m));
+            return true;
+        },
+        setQuality: (q) => withRenderer((r) => r.setQuality(q)),
+        setCameraMode: (m) => withRenderer((r) => r.setCameraMode(m)),
+        setTheme: (t) => withRenderer((r) => r.setTheme(t)),
         setBuildVolume: (def) => {
             consumerVolumeSet = true;
-            renderer?.setBuildVolume(def);
+            withRenderer((r) => r.setBuildVolume(def));
         },
-        frame: () => renderer?.frame()
+        frame: () => withRenderer((r) => r.frame())
     };
     function dispose() {
         if (disposed)
@@ -231,7 +300,9 @@ export function createPreviewController(options = {}) {
         offPartial();
         session.dispose();
         disposeRenderer();
+        pendingOps.length = 0;
         lastIR = null;
+        timeAxis = null;
         mapper = null;
         listeners.clear();
         stateListeners.clear();

package/dist/index.d.ts

@@ -5,6 +5,8 @@
  * The portable behavioral suite ships via the `./testing` subpath.
  */
 export * from './controller.js';
+export type { PreviewRenderer, PreviewRendererEvent, RendererMode } from './renderer-interface.js';
+export { LayerView2DRenderer, type LayerView2DRendererOptions } from './renderer-2d-adapter.js';
 export { renderStill, type RenderStillOptions, type RenderStillResult, type StillCameraPose } from './render-still.js';
 export type { Theme, MaterialPreset, ThemeColor } from '@chestnutlabs/gcode-renderer-three';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEvH,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,iBAAiB,CAAC;AAEhC,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACnG,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEvH,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC"}

package/dist/index.js

@@ -5,4 +5,5 @@
  * The portable behavioral suite ships via the `./testing` subpath.
  */
 export * from './controller.js';
+export { LayerView2DRenderer } from './renderer-2d-adapter.js';
 export { renderStill } from './render-still.js';

package/dist/renderer-2d-adapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `LayerView2DRenderer` — adapts the low-resource Canvas 2D renderer
+ * (`@chestnutlabs/gcode-renderer-2d`) to the controller's {@link PreviewRenderer} interface
+ * (DD-014 D5), so `renderer.mode: '2d'` slots in behind the same seam as the 3D renderer.
+ *
+ * This is a **static** import of the (tiny, three-free) 2D package. The 3D renderer is loaded
+ * on demand in the controller, so a 2D-only bundle never pulls Three.js.
+ *
+ * Honesty (DD-014 §6/§11): a flat per-layer view cannot represent 3D-only options. Genuine
+ * 3D-only requests (camera projection, quality modes) are disclosed via `renderer-unsupported`
+ * — never silently faked. Coarser-granularity requests (segment scrub, retraction point markers)
+ * are documented no-ops. Nothing is ever drawn that the IR does not contain.
+ */
+import { type ColorMode, type TravelStyle } from '@chestnutlabs/gcode-renderer-2d';
+import type { BuildVolumeDef, CameraMode, QualityMode, Theme } from '@chestnutlabs/gcode-renderer-three';
+import type { MachineGeometry, MappedProgress, ToolpathIR } from '@chestnutlabs/toolpath-core';
+import type { MoveKindToggle, PreviewRenderer, PreviewRendererEvent } from './renderer-interface.js';
+export interface LayerView2DRendererOptions {
+    colorMode?: ColorMode;
+    /** Preceding "ghost" layers drawn beneath the active one (default 1, floor 0). */
+    adjacentLayers?: number;
+    /** Ghost-layer opacity (default 0.25). */
+    ghostOpacity?: number;
+    /** Extrusion stroke width in device px (default 1). */
+    lineWidth?: number;
+    /** Travel style, or false to hide travel (default hidden). */
+    travel?: TravelStyle | false;
+}
+export declare class LayerView2DRenderer implements PreviewRenderer {
+    private readonly canvas;
+    private readonly view;
+    private ir;
+    private readonly listeners;
+    constructor(canvas: HTMLCanvasElement, opts?: LayerView2DRendererOptions);
+    private emit;
+    private disclose;
+    onEvent(cb: (e: PreviewRendererEvent) => void): () => void;
+    resize(width: number, height: number): void;
+    setIR(ir: ToolpathIR): void;
+    /** 3D-only progressive preview; the 2D view draws on the final IR (§3 non-goal). */
+    appendPartial(): void;
+    get layerCount(): number;
+    get segmentCount(): number;
+    setBuildVolume(_def: BuildVolumeDef | MachineGeometry): void;
+    setLayerRange(_startLayer: number, endLayer: number): void;
+    setScrubPosition(_segIndex: number | null): void;
+    setKindVisible(kind: MoveKindToggle, visible: boolean): void;
+    setShowRetractions(visible: boolean): void;
+    setColorMode(mode: ColorMode): boolean;
+    /** Capability gate mirroring the 3D renderer (DD-001 honesty): unknown channel → unavailable. */
+    private isColorModeAvailable;
+    setQuality(_quality: QualityMode | 'auto'): void;
+    setCameraMode(_mode: CameraMode): void;
+    setTheme(_theme: Theme): void;
+    setProgress(p: MappedProgress | null): void;
+    pickSegment(): number | null;
+    frame(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=renderer-2d-adapter.d.ts.map

package/dist/renderer-2d-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-2d-adapter.d.ts","sourceRoot":"","sources":["../src/renderer-2d-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAGL,KAAK,SAAS,EAEd,KAAK,WAAW,EACjB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oCAAoC,CAAC;AACzG,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAErG,MAAM,WAAW,0BAA0B;IACzC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC9B;AAED,qBAAa,mBAAoB,YAAW,eAAe;IAMvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,EAAE,CAA2B;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgD;gBAGvD,MAAM,EAAE,iBAAiB,EAC1C,IAAI,GAAE,0BAA+B;IAWvC,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI;IAK1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAM3C,KAAK,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI;IAS3B,oFAAoF;IACpF,aAAa,IAAI,IAAI;IAIrB,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,GAAG,IAAI;IAI5D,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM1D,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIhD,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAQ5D,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI1C,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAOtC,iGAAiG;IACjG,OAAO,CAAC,oBAAoB;IAS5B,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAIhD,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAItC,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI;IAI7B,WAAW,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI;IAM3C,WAAW,IAAI,MAAM,GAAG,IAAI;IAK5B,KAAK,IAAI,IAAI;IAKb,OAAO,IAAI,IAAI;CAKhB"}

package/dist/renderer-2d-adapter.js

@@ -0,0 +1,135 @@
+/**
+ * `LayerView2DRenderer` — adapts the low-resource Canvas 2D renderer
+ * (`@chestnutlabs/gcode-renderer-2d`) to the controller's {@link PreviewRenderer} interface
+ * (DD-014 D5), so `renderer.mode: '2d'` slots in behind the same seam as the 3D renderer.
+ *
+ * This is a **static** import of the (tiny, three-free) 2D package. The 3D renderer is loaded
+ * on demand in the controller, so a 2D-only bundle never pulls Three.js.
+ *
+ * Honesty (DD-014 §6/§11): a flat per-layer view cannot represent 3D-only options. Genuine
+ * 3D-only requests (camera projection, quality modes) are disclosed via `renderer-unsupported`
+ * — never silently faked. Coarser-granularity requests (segment scrub, retraction point markers)
+ * are documented no-ops. Nothing is ever drawn that the IR does not contain.
+ */
+import { LayerView2D, describe2DDisclosures } from '@chestnutlabs/gcode-renderer-2d';
+export class LayerView2DRenderer {
+    canvas;
+    view;
+    ir = null;
+    listeners = new Set();
+    constructor(canvas, opts = {}) {
+        this.canvas = canvas;
+        this.view = new LayerView2D(canvas, {
+            colorMode: opts.colorMode,
+            adjacentLayers: opts.adjacentLayers,
+            ghostOpacity: opts.ghostOpacity,
+            lineWidth: opts.lineWidth,
+            travel: opts.travel
+        });
+    }
+    emit(e) {
+        for (const cb of this.listeners)
+            cb(e);
+    }
+    disclose(feature, message) {
+        this.emit({ type: 'renderer-unsupported', feature, message });
+    }
+    onEvent(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    resize(width, height) {
+        this.canvas.width = Math.max(1, Math.round(width));
+        this.canvas.height = Math.max(1, Math.round(height));
+        this.view.render();
+    }
+    setIR(ir) {
+        this.ir = ir;
+        this.view.setToolpath(ir);
+        this.view.render();
+        // Disclose what a flat 2D view cannot faithfully represent (non-planar/CNC), never silently
+        // (DD-014 §6/§11) — an honest capability signal on the same channel as 3D-only-option notices.
+        for (const message of describe2DDisclosures(ir))
+            this.disclose('layers', message);
+    }
+    /** 3D-only progressive preview; the 2D view draws on the final IR (§3 non-goal). */
+    appendPartial() {
+        // Intentional no-op — 2D renders once on setIR; no fabricated partial geometry.
+    }
+    get layerCount() {
+        return this.ir?.layers.length ?? 0;
+    }
+    get segmentCount() {
+        return this.ir?.segments.count ?? 0;
+    }
+    setBuildVolume(_def) {
+        // No bed chrome in the 2D layer view (phase 1–3); not an error, simply not drawn.
+    }
+    setLayerRange(_startLayer, endLayer) {
+        // A single-layer 2D view shows the TOP of the requested range (the current layer).
+        this.view.setLayer(endLayer);
+        this.view.render();
+    }
+    setScrubPosition(_segIndex) {
+        // Segment-granular scrub is a 3D-clip feature; the 2D view is layer-granular. Documented no-op.
+    }
+    setKindVisible(kind, visible) {
+        // extrusion is the point of the 2D view (never hidden); wipe is a 3D-line concern with no
+        // distinct 2D representation, so only the travel toggle is meaningful here.
+        if (kind !== 'travel')
+            return;
+        this.view.setTravel(visible ? { color: 'rgba(120,120,120,0.9)', lineWidth: 0.5 } : false);
+        this.view.render();
+    }
+    setShowRetractions(visible) {
+        if (visible)
+            this.disclose('retractions', 'Retraction markers are only shown in the 3D renderer.');
+    }
+    setColorMode(mode) {
+        if (!this.isColorModeAvailable(mode.mode))
+            return false;
+        this.view.setColorMode(mode);
+        this.view.render();
+        return true;
+    }
+    /** Capability gate mirroring the 3D renderer (DD-001 honesty): unknown channel → unavailable. */
+    isColorModeAvailable(mode) {
+        const caps = this.ir?.header.capabilities;
+        if (mode === 'feature')
+            return caps?.['featureRoles'] !== undefined && caps['featureRoles'] !== 'unavailable';
+        if (mode === 'colorChange')
+            return caps?.['colorChanges'] !== undefined && caps['colorChanges'] !== 'unavailable';
+        if (mode === 'object')
+            return caps?.['objects'] !== undefined && caps['objects'] !== 'unavailable';
+        if (mode === 'feedrate')
+            return caps?.['feedrate'] !== 'unavailable';
+        return true;
+    }
+    setQuality(_quality) {
+        this.disclose('quality', 'Quality/geometry modes apply only to the 3D renderer; the 2D view has none.');
+    }
+    setCameraMode(_mode) {
+        this.disclose('camera', 'Camera projection applies only to the 3D renderer; the 2D view is flat top-down.');
+    }
+    setTheme(_theme) {
+        // The 2D view uses per-segment colors from the color mode; scene theming is a 3D concern.
+    }
+    setProgress(p) {
+        const projected = p === null ? null : { segIndex: p.segIndex, layerIndex: p.layerIndex };
+        this.view.setProgress(projected);
+        this.view.render();
+    }
+    pickSegment() {
+        // Segment picking is a 3D raycast feature; the 2D layer view has none yet (#184).
+        return null;
+    }
+    frame() {
+        // The 2D view always auto-fits the whole-model frame; framing is just a redraw.
+        this.view.render();
+    }
+    dispose() {
+        this.listeners.clear();
+        this.view.setToolpath(null);
+        this.ir = null;
+    }
+}

package/dist/renderer-interface.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The renderer-agnostic seam the controller talks to (DD-014 D5). Both the Three.js
+ * renderer (`@chestnutlabs/gcode-renderer-three`, loaded on demand) and the low-resource
+ * 2D renderer (`@chestnutlabs/gcode-renderer-2d`) satisfy {@link PreviewRenderer}, so the
+ * controller picks one behind this interface from a single `renderer.mode` option.
+ *
+ * The `gcode-renderer-three` imports here are **type-only** (erased at build): they must not
+ * pull Three.js into a 2D-only bundle. The 3D renderer's *values* are reached only through a
+ * dynamic `import()` in the controller, so a bundler drops Three.js when `mode` is `'2d'`.
+ */
+import type { BuildVolumeDef, CameraMode, ColorMode, QualityMode, RendererEvent, Theme } from '@chestnutlabs/gcode-renderer-three';
+import type { MachineGeometry, MappedProgress, ToolpathIR } from '@chestnutlabs/toolpath-core';
+/** Which renderer implementation backs the preview. `'3d'` is the default (Three.js). */
+export type RendererMode = '2d' | '3d';
+/**
+ * Move classes whose visibility can be toggled independently (DD-009 travel toggle + DD-016 wipe).
+ * `'wipe'` is honored by the 3D renderer as its own chunk; the flat 2D view treats it as a no-op.
+ */
+export type MoveKindToggle = 'extrude' | 'travel' | 'wipe';
+/**
+ * Renderer events seen by the controller. The 3D renderer emits {@link RendererEvent}; either
+ * renderer may emit `renderer-unsupported` to disclose a requested option it cannot honor (e.g.
+ * a camera mode on the flat 2D view) — an honest capability signal, never a hard error.
+ */
+export type PreviewRendererEvent = RendererEvent | {
+    type: 'renderer-unsupported';
+    feature: string;
+    message: string;
+};
+/**
+ * The minimal renderer contract the controller drives. 3D-only members are honored by the 2D
+ * renderer as documented no-ops or `renderer-unsupported` disclosures — never fabricated output.
+ */
+export interface PreviewRenderer {
+    onEvent(cb: (e: PreviewRendererEvent) => void): () => void;
+    resize(width: number, height: number): void;
+    setIR(ir: ToolpathIR): void;
+    /** Progressive partial IR (3D only; the 2D renderer draws on the final IR). */
+    appendPartial(slice: ToolpathIR): void;
+    readonly layerCount: number;
+    readonly segmentCount: number;
+    setBuildVolume(def: BuildVolumeDef | MachineGeometry): void;
+    setLayerRange(startLayer: number, endLayer: number): void;
+    setScrubPosition(segIndex: number | null): void;
+    setKindVisible(kind: MoveKindToggle, visible: boolean): void;
+    setShowRetractions(visible: boolean): void;
+    setColorMode(mode: ColorMode): boolean;
+    setQuality(quality: QualityMode | 'auto'): void;
+    setCameraMode(mode: CameraMode): void;
+    setTheme(theme: Theme): void;
+    setProgress(p: MappedProgress | null): void;
+    /**
+     * Pick the IR segment under a pointer (normalized device coords in [-1, 1]), or null (#184). The 3D
+     * renderer raycasts the toolpath; the 2D renderer returns null (no picking yet).
+     */
+    pickSegment(ndcX: number, ndcY: number, threshold?: number): number | null;
+    frame(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=renderer-interface.d.ts.map

package/dist/renderer-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-interface.d.ts","sourceRoot":"","sources":["../src/renderer-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,KAAK,EACN,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE/F,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,EAAE,EAAE,UAAU,GAAG,IAAI,CAAC;IAC5B,+EAA+E;IAC/E,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,GAAG,IAAI,CAAC;IAC5D,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAChD,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7D,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3C,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IACvC,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAAC;IAC5C;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3E,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/renderer-interface.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chestnutlabs/gcode-preview-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-neutral preview controller for the Chestnut Labs G-code viewer (DD-007 §4.6): the shared engine glue, state model, and TypeScript contracts beneath the Vue/React/Svelte adapters.",
   "keywords": [
     "gcode",
@@ -52,8 +52,9 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@chestnutlabs/gcode-parser": "0.2.0",
-    "@chestnutlabs/gcode-renderer-three": "0.2.0",
-    "@chestnutlabs/toolpath-core": "0.2.0"
+    "@chestnutlabs/gcode-parser": "0.3.0",
+    "@chestnutlabs/gcode-renderer-2d": "0.3.0",
+    "@chestnutlabs/gcode-renderer-three": "0.3.0",
+    "@chestnutlabs/toolpath-core": "0.3.0"
   }
 }