@chestnutlabs/gcode-preview-core 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @chestnutlabs/gcode-preview-core
+
+The **framework-neutral preview controller** for the Chestnut Labs G-code Preview stack
+(design: DD-007). This is the single engine under the Vue, React, and Svelte adapters — parse
+session + renderer + progress mapper glued into one lifecycle with an **immutable-snapshot state
+model** (`getState()` returns a new identity per mutation; `onStateChange` notifies), which every
+framework's reactivity can bridge cheaply.
+
+```ts
+import { createPreviewController } from '@chestnutlabs/gcode-preview-core';
+
+const preview = createPreviewController();
+preview.bindCanvas(canvas);              // resize-observed
+await preview.parse(bytes);              // worker parse + progressive build
+preview.controls.setLayerRange(0, 42);   // scrub / quality / colors / bed / frame ...
+preview.observeProgress(obs);            // DD-006 live progress
+preview.onStateChange(cb);               // snapshots: summaries only, never toolpath buffers
+preview.dispose();
+```
+
+Building an adapter for another framework? The **portable behavioral suite** is exported from
+`@chestnutlabs/gcode-preview-core/testing` — `runBehavioralSuite(...)` is the same parity
+contract the Vue/React/Svelte adapters pass in CI, and it is the anti-drift firewall for any new
+integration.
+
+Part of [Chestnut Labs G-code Preview](../../README.md) · MIT

package/dist/controller.d.ts

@@ -0,0 +1,128 @@
+/**
+ * createPreviewController — the framework-neutral engine glue (DD-007 §4.6, phase 5,
+ * issue #112): GcodeParseSession (worker parse) + ToolpathRenderer (scene) +
+ * createProgressMapper (DD-006), extracted from the Vue composable so every framework
+ * adapter is a pure reactivity bridge over ONE implementation.
+ *
+ * State model: immutable snapshots. Every change replaces `getState()`'s return value
+ * and notifies subscribers — exactly what React's useSyncExternalStore, Svelte stores,
+ * and Vue reactive mirrors all consume without adaptation. Snapshots carry summaries
+ * 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 ColorMode, type GLRendererLike, type ProgressPresentationMode, type QualityMode, type RenderTargetCanvas, type RendererEvent, type TubeOptions } from '@chestnutlabs/gcode-renderer-three';
+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 | {
+    type: 'parse-started';
+    bytes: number;
+} | {
+    type: 'parse-progress';
+    progress: ParseProgress;
+} | {
+    type: 'parse-complete';
+    segments: number;
+    layers: number;
+    complete: boolean;
+} | {
+    type: 'parse-cancelled';
+} | {
+    type: 'parse-error';
+    code: string;
+    message: string;
+} | {
+    /** File-discovered geometry NOT auto-applied because the consumer configured a
+     *  volume (DD-005 consumer-wins precedence) — the host decides. */
+    type: 'machine-geometry-discovered';
+    machine: MachineGeometry;
+};
+export interface PreviewControllerOptions {
+    /** Custom worker factory (DD-005 slim/custom entries). Default: the batteries worker. */
+    createWorker?: SessionOptions['worker'];
+    renderer?: {
+        buildVolume?: BuildVolumeDef;
+        quality?: QualityMode | 'auto';
+        colorMode?: ColorMode;
+        tube?: TubeOptions;
+        /** Advanced/test injectables — pass-throughs of the renderer's own contract. */
+        createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
+        scheduleFrame?: (cb: () => void) => void;
+        chunksPerTick?: number;
+    };
+    /** Applied to every parse unless overridden per-call. */
+    parseDefaults?: WireParseOptions;
+}
+/** `parse()` never rejects from prop/event-driven flows (DD-007 §6): inspect the outcome. */
+export type ParseOutcome = {
+    ok: true;
+    result: ParseResult;
+} | {
+    ok: false;
+    cancelled: true;
+} | {
+    ok: false;
+    cancelled?: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface GcodePreviewState {
+    parsing: boolean;
+    parseProgress: ParseProgress | null;
+    /** Summary of the last successful parse — plain numbers/strings, never typed arrays. */
+    summary: {
+        segments: number;
+        layers: number;
+        complete: boolean;
+        stopReason: string | undefined;
+        capabilities: Record<string, Confidence>;
+        warnings: number;
+    } | null;
+    metadata: DialectMetadata | undefined;
+    activeQuality: QualityMode | null;
+    presentation: ProgressPresentationMode;
+    layerCount: number;
+    segmentCount: number;
+    /** User-presentable decimation/travel disclosure (empty when rendering everything). */
+    disclosure: string;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+export interface GcodePreviewControls {
+    setLayerRange(startLayer: number, endLayer: number): void;
+    setScrubPosition(segIndex: number | null): void;
+    setKindVisible(kind: 'extrude' | 'travel', visible: boolean): void;
+    setColorMode(mode: ColorMode): boolean;
+    setQuality(quality: QualityMode | 'auto'): void;
+    /** Marks the volume consumer-configured: file-discovered geometry stops auto-applying. */
+    setBuildVolume(def: BuildVolumeDef | MachineGeometry): void;
+    frame(): void;
+}
+export interface PreviewController {
+    /** Bind/rebind the renderer to a canvas (null unbinds). Rebinding disposes safely. */
+    bindCanvas(canvas: HTMLCanvasElement | null): void;
+    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;
+    /** Current immutable state snapshot (identity changes on every state change). */
+    getState(): GcodePreviewState;
+    /** Subscribe to snapshot replacements. Returns the unsubscriber. */
+    onStateChange(cb: (state: GcodePreviewState) => void): () => void;
+    controls: GcodePreviewControls;
+    /** Escape hatches — the neutral objects themselves (advanced use). */
+    raw: {
+        session: GcodeParseSession;
+        renderer: () => ToolpathRenderer | null;
+    };
+    onEvent(cb: (e: PreviewEvent) => void): () => void;
+    dispose(): void;
+}
+export declare function createPreviewController(options?: PreviewControllerOptions): PreviewController;
+//# sourceMappingURL=controller.d.ts.map

package/dist/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"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"}

package/dist/controller.js

@@ -0,0 +1,270 @@
+/**
+ * createPreviewController — the framework-neutral engine glue (DD-007 §4.6, phase 5,
+ * issue #112): GcodeParseSession (worker parse) + ToolpathRenderer (scene) +
+ * createProgressMapper (DD-006), extracted from the Vue composable so every framework
+ * adapter is a pure reactivity bridge over ONE implementation.
+ *
+ * State model: immutable snapshots. Every change replaces `getState()`'s return value
+ * and notifies subscribers — exactly what React's useSyncExternalStore, Svelte stores,
+ * and Vue reactive mirrors all consume without adaptation. Snapshots carry summaries
+ * 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';
+const INITIAL_STATE = {
+    parsing: false,
+    parseProgress: null,
+    summary: null,
+    metadata: undefined,
+    activeQuality: null,
+    presentation: 'hidden',
+    layerCount: 0,
+    segmentCount: 0,
+    disclosure: '',
+    error: null
+};
+function toBytes(input) {
+    return input instanceof Uint8Array ? input : new Uint8Array(input);
+}
+export function createPreviewController(options = {}) {
+    let snapshot = { ...INITIAL_STATE };
+    const stateListeners = new Set();
+    const mutate = (patch) => {
+        snapshot = { ...snapshot, ...patch };
+        for (const cb of stateListeners)
+            cb(snapshot);
+    };
+    const session = new GcodeParseSession(options.createWorker === undefined ? {} : { worker: options.createWorker });
+    // Non-reactive engine state: plain lets — snapshots carry summaries only.
+    let renderer = null;
+    let unbindRendererEvents = null;
+    let lastIR = null;
+    let lastMachine;
+    let mapper = null;
+    let consumerVolumeSet = options.renderer?.buildVolume !== undefined;
+    let activeParse = null;
+    let resizeObserver = null;
+    let windowResize = null;
+    let disposed = false;
+    const listeners = new Set();
+    const emit = (e) => {
+        for (const cb of listeners)
+            cb(e);
+    };
+    function onRendererEvent(e) {
+        if (e.type === 'buildComplete') {
+            mutate({
+                activeQuality: e.quality,
+                disclosure: e.decimationApplied > 1
+                    ? `Showing every ${e.decimationApplied}th extrusion segment (layer boundaries kept); ` +
+                        `travel hidden. ${e.segments.toLocaleString()} segments drawn.`
+                    : ''
+            });
+        }
+        else if (e.type === 'qualityFallback') {
+            mutate({ activeQuality: e.to });
+        }
+        else if (e.type === 'progress-presentation-changed') {
+            mutate({ presentation: e.mode });
+        }
+        else if (e.type === 'error') {
+            mutate({ error: { code: e.code, message: e.message } });
+        }
+        emit(e);
+    }
+    function disposeRenderer() {
+        unbindRendererEvents?.();
+        unbindRendererEvents = null;
+        resizeObserver?.disconnect();
+        resizeObserver = null;
+        if (windowResize !== null && typeof window !== 'undefined') {
+            window.removeEventListener('resize', windowResize);
+            windowResize = null;
+        }
+        renderer?.dispose();
+        renderer = null;
+    }
+    function fitToCanvas(canvas) {
+        const w = canvas.clientWidth || canvas.width || 1;
+        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',
+            colorMode: r.colorMode,
+            tube: r.tube,
+            createRenderer: r.createRenderer,
+            scheduleFrame: r.scheduleFrame,
+            chunksPerTick: r.chunksPerTick
+        });
+        unbindRendererEvents = renderer.onEvent(onRendererEvent);
+        // Sizing (§4.2): explicit initial fit; ResizeObserver where available; window-resize
+        // fallback because observers may never fire in embedded panes.
+        fitToCanvas(canvas);
+        if (typeof ResizeObserver !== 'undefined') {
+            const ro = new ResizeObserver(() => fitToCanvas(canvas));
+            ro.observe(canvas);
+            resizeObserver = ro;
+        }
+        if (typeof window !== 'undefined') {
+            windowResize = () => fitToCanvas(canvas);
+            window.addEventListener('resize', windowResize);
+        }
+        if (lastIR !== null) {
+            renderer.setIR(lastIR);
+            mutate({ layerCount: renderer.layerCount, segmentCount: renderer.segmentCount });
+        }
+    }
+    const offProgress = session.onProgress((p) => {
+        mutate({ parseProgress: p });
+        emit({ type: 'parse-progress', progress: p });
+    });
+    const offPartial = session.onPartial((slice) => {
+        renderer?.appendPartial(slice);
+    });
+    async function parse(input, opts) {
+        if (disposed)
+            return { ok: false, error: { code: 'E_DISPOSED', message: 'preview disposed' } };
+        if (snapshot.parsing) {
+            // §5: parse-during-parse cancels then restarts (session semantics preserved).
+            session.cancel();
+            await activeParse?.catch(() => undefined);
+        }
+        mutate({ parsing: true, parseProgress: null, error: null });
+        const bytes = typeof File !== 'undefined' && input instanceof File
+            ? input.size
+            : input.byteLength;
+        emit({ type: 'parse-started', bytes });
+        const wire = { ...options.parseDefaults, ...opts };
+        const run = session.parse(input instanceof ArrayBuffer ? toBytes(input) : input, wire);
+        activeParse = run;
+        try {
+            const result = await run;
+            lastIR = result.ir;
+            lastMachine = result.metadata?.machine;
+            mapper = createProgressMapper(result.ir, { fileSizeBytes: bytes });
+            const counts = renderer !== null
+                ? { layerCount: renderer.layerCount, segmentCount: renderer.segmentCount }
+                : { layerCount: result.ir.layers.length, segmentCount: result.ir.segments.count };
+            if (renderer !== null)
+                renderer.setIR(result.ir);
+            mutate({
+                summary: {
+                    segments: result.ir.segments.count,
+                    layers: result.ir.layers.length,
+                    complete: result.ir.header.complete,
+                    stopReason: result.stats.stopReason?.code,
+                    capabilities: { ...result.ir.header.capabilities },
+                    warnings: result.ir.header.warnings.length
+                },
+                metadata: result.metadata,
+                presentation: 'hidden',
+                ...(renderer !== null ? { layerCount: renderer.layerCount, segmentCount: renderer.segmentCount } : counts)
+            });
+            // DD-005 consumer-wins precedence: a consumer-configured volume blocks auto-apply.
+            if (lastMachine !== undefined) {
+                if (consumerVolumeSet)
+                    emit({ type: 'machine-geometry-discovered', machine: lastMachine });
+                else
+                    renderer?.setBuildVolume(lastMachine);
+            }
+            emit({
+                type: 'parse-complete',
+                segments: result.ir.segments.count,
+                layers: result.ir.layers.length,
+                complete: result.ir.header.complete
+            });
+            return { ok: true, result };
+        }
+        catch (err) {
+            if (err instanceof CancelledError) {
+                emit({ type: 'parse-cancelled' });
+                return { ok: false, cancelled: true };
+            }
+            const code = err instanceof ParseSessionError ? err.code : 'E_UNKNOWN';
+            const message = err instanceof Error ? err.message : String(err);
+            mutate({ error: { code, message } });
+            emit({ type: 'parse-error', code, message });
+            return { ok: false, error: { code, message } };
+        }
+        finally {
+            mutate({ parsing: false, parseProgress: null });
+            if (activeParse === run)
+                activeParse = null;
+        }
+    }
+    const controls = {
+        setLayerRange: (a, b) => renderer?.setLayerRange(a, b),
+        setScrubPosition: (s) => renderer?.setScrubPosition(s),
+        setKindVisible: (k, v) => renderer?.setKindVisible(k, v),
+        setColorMode: (m) => renderer?.setColorMode(m) ?? false,
+        setQuality: (q) => renderer?.setQuality(q),
+        setBuildVolume: (def) => {
+            consumerVolumeSet = true;
+            renderer?.setBuildVolume(def);
+        },
+        frame: () => renderer?.frame()
+    };
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        session.cancel();
+        offProgress();
+        offPartial();
+        session.dispose();
+        disposeRenderer();
+        lastIR = null;
+        mapper = null;
+        listeners.clear();
+        stateListeners.clear();
+    }
+    return {
+        bindCanvas,
+        parse,
+        cancel: () => session.cancel(),
+        observeProgress: (obs) => {
+            if (mapper === null)
+                return null;
+            const mapped = mapper.observe(obs);
+            renderer?.setProgress(mapped);
+            return mapped;
+        },
+        tickProgress: (nowMs) => {
+            if (mapper === null)
+                return null;
+            const mapped = mapper.tick(nowMs);
+            renderer?.setProgress(mapped);
+            return mapped;
+        },
+        clearProgress: () => {
+            mapper?.reset();
+            renderer?.setProgress(null);
+            mutate({ presentation: 'hidden' });
+        },
+        getState: () => snapshot,
+        onStateChange: (cb) => {
+            stateListeners.add(cb);
+            return () => stateListeners.delete(cb);
+        },
+        controls,
+        raw: { session, renderer: () => renderer },
+        onEvent: (cb) => {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+        dispose
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @chestnutlabs/gcode-preview-core — the framework-neutral preview controller and the
+ * SHARED TypeScript contracts every framework adapter re-exports (DD-007 §4.6):
+ * adapters are reactivity bridges over this one implementation, never parallel viewers.
+ * The portable behavioral suite ships via the `./testing` subpath.
+ */
+export * from './controller.js';
+export { renderStill, type RenderStillOptions, type RenderStillResult, type StillCameraPose } from './render-still.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;;;;;GAKG;AACH,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @chestnutlabs/gcode-preview-core — the framework-neutral preview controller and the
+ * SHARED TypeScript contracts every framework adapter re-exports (DD-007 §4.6):
+ * adapters are reactivity bridges over this one implementation, never parallel viewers.
+ * The portable behavioral suite ships via the `./testing` subpath.
+ */
+export * from './controller.js';
+export { renderStill } from './render-still.js';

package/dist/render-still.d.ts

@@ -0,0 +1,75 @@
+/**
+ * renderStill — headless, non-interactive still image of a toolpath (DD-008 §4.8,
+ * E7 phase 5, issue #132; consumer: AnyBridge #791 ThumbnailWorker).
+ *
+ * A bounded adapter over the SAME engine the interactive controller uses: parse
+ * (worker, for bytes) or accept a pre-parsed `ToolpathIR`, build the geometry to
+ * completion, frame the camera deterministically (or apply an explicit pose),
+ * render exactly once, and hand back the canvas + build stats. The caller
+ * extracts pixels in its own environment (`OffscreenCanvas.convertToBlob`,
+ * `canvas.toDataURL`, or a WebGL `readPixels`) — this module never touches the
+ * filesystem, a DOM, or a worker it wasn't given.
+ *
+ * Supported environments (see docs/reference/still-render.md): any Chromium-class
+ * WebGL2 context — an Electron hidden window, a Worker `OffscreenCanvas`, or
+ * headless Chromium. Pure-Node GPU-less rendering is out of scope (deferred
+ * E8-class roadmap item).
+ *
+ * Determinism: same environment ⇒ identical output. Cross-GPU/driver pixel
+ * identity is NOT promised (antialiasing varies); cache by job identity.
+ */
+import { type SessionOptions, type WireParseOptions } from '@chestnutlabs/gcode-parser';
+import { type BuildVolumeDef, type ColorMode, type GLRendererLike, type QualityMode, type RenderTargetCanvas, type TubeOptions } from '@chestnutlabs/gcode-renderer-three';
+import { type MachineGeometry, type ToolpathIR } from '@chestnutlabs/toolpath-core';
+/** Explicit camera pose (scene coordinates), overriding the deterministic frame(). */
+export interface StillCameraPose {
+    position: [number, number, number];
+    target: [number, number, number];
+    /** Vertical field of view in degrees (default: the renderer's 50°). */
+    fov?: number;
+}
+export interface RenderStillOptions {
+    /** Target surface: an OffscreenCanvas (worker/headless) or a DOM canvas. Required. */
+    canvas: RenderTargetCanvas;
+    /** Output size. Defaults to the canvas's current width/height. */
+    width?: number;
+    height?: number;
+    /** Quality tier (default 'auto': tubes ≤ 1 M segments, else lines). */
+    quality?: QualityMode | 'auto';
+    colorMode?: ColorMode;
+    tube?: TubeOptions;
+    /** Bed geometry — a renderer volume or discovered MachineGeometry. */
+    buildVolume?: BuildVolumeDef | MachineGeometry;
+    /** Inclusive layer clip [start, end]. Omitted → whole model. */
+    layerRange?: [number, number];
+    /** Draw only up to this segment (progress-style clip). null/omitted → whole model. */
+    scrub?: number | null;
+    /** Include travel moves (default false). */
+    showTravel?: boolean;
+    /** Camera: an explicit pose, or omitted for deterministic bounds framing. */
+    camera?: StillCameraPose;
+    /** Worker factory for the bytes path (batteries default when omitted). */
+    createWorker?: SessionOptions['worker'];
+    /** Wire parse options for the bytes path (dialects/containers/plate/limits). */
+    parseOptions?: WireParseOptions;
+    /** GL backend injection (tests / exotic hosts). Default: WebGLRenderer. */
+    createRenderer?: (canvas: RenderTargetCanvas) => GLRendererLike;
+}
+export interface RenderStillResult {
+    /** The same canvas passed in, now holding the rendered frame. */
+    canvas: RenderTargetCanvas;
+    width: number;
+    height: number;
+    layerCount: number;
+    segmentCount: number;
+    /** The quality tier actually rendered (resolves 'auto'). */
+    quality: QualityMode;
+    /** True when the input was G-code bytes (a worker parse ran). */
+    parsed: boolean;
+}
+/**
+ * Render one still image. Resolves after the geometry is fully built and a single
+ * frame has been drawn to `options.canvas`.
+ */
+export declare function renderStill(source: Uint8Array | ArrayBuffer | ToolpathIR, options: RenderStillOptions): Promise<RenderStillResult>;
+//# sourceMappingURL=render-still.d.ts.map

package/dist/render-still.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-still.d.ts","sourceRoot":"","sources":["../src/render-still.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC3G,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEpF,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,MAAM,EAAE,kBAAkB,CAAC;IAC3B,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC/B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,sEAAsE;IACtE,WAAW,CAAC,EAAE,cAAc,GAAG,eAAe,CAAC;IAC/C,gEAAgE;IAChE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACxC,gFAAgF;IAChF,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,2EAA2E;IAC3E,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,cAAc,CAAC;CACjE;AAED,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,OAAO,EAAE,WAAW,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;CACjB;AAkBD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,EAC7C,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAsF5B"}

package/dist/render-still.js

@@ -0,0 +1,129 @@
+/**
+ * renderStill — headless, non-interactive still image of a toolpath (DD-008 §4.8,
+ * E7 phase 5, issue #132; consumer: AnyBridge #791 ThumbnailWorker).
+ *
+ * A bounded adapter over the SAME engine the interactive controller uses: parse
+ * (worker, for bytes) or accept a pre-parsed `ToolpathIR`, build the geometry to
+ * completion, frame the camera deterministically (or apply an explicit pose),
+ * render exactly once, and hand back the canvas + build stats. The caller
+ * extracts pixels in its own environment (`OffscreenCanvas.convertToBlob`,
+ * `canvas.toDataURL`, or a WebGL `readPixels`) — this module never touches the
+ * filesystem, a DOM, or a worker it wasn't given.
+ *
+ * Supported environments (see docs/reference/still-render.md): any Chromium-class
+ * WebGL2 context — an Electron hidden window, a Worker `OffscreenCanvas`, or
+ * headless Chromium. Pure-Node GPU-less rendering is out of scope (deferred
+ * E8-class roadmap item).
+ *
+ * Determinism: same environment ⇒ identical output. Cross-GPU/driver pixel
+ * identity is NOT promised (antialiasing varies); cache by job identity.
+ */
+import { GcodeParseSession } from '@chestnutlabs/gcode-parser';
+import { ToolpathRenderer, machineToVolume } from '@chestnutlabs/gcode-renderer-three';
+function isToolpathIR(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'segments' in v &&
+        'layers' in v &&
+        'header' in v &&
+        !(v instanceof Uint8Array) &&
+        !(v instanceof ArrayBuffer));
+}
+function toVolume(def) {
+    return 'bed' in def ? machineToVolume(def) : def;
+}
+/**
+ * Render one still image. Resolves after the geometry is fully built and a single
+ * frame has been drawn to `options.canvas`.
+ */
+export async function renderStill(source, options) {
+    const { canvas } = options;
+    const width = options.width ?? canvas.width;
+    const height = options.height ?? canvas.height;
+    let ir;
+    let parsed = false;
+    if (isToolpathIR(source)) {
+        ir = source;
+    }
+    else {
+        const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
+        const session = new GcodeParseSession(options.createWorker === undefined ? {} : { worker: options.createWorker });
+        try {
+            const result = await session.parse(bytes, options.parseOptions ?? {});
+            ir = result.ir;
+            parsed = true;
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    // Build to completion off the event loop (no rAF): microtask-scheduled ticks.
+    const renderer = new ToolpathRenderer({
+        canvas,
+        quality: options.quality ?? 'auto',
+        ...(options.colorMode ? { colorMode: options.colorMode } : {}),
+        ...(options.tube ? { tube: options.tube } : {}),
+        ...(options.buildVolume ? { buildVolume: toVolume(options.buildVolume) } : {}),
+        preserveDrawingBuffer: true,
+        scheduleFrame: (cb) => queueMicrotask(cb),
+        ...(options.createRenderer ? { createRenderer: options.createRenderer } : {})
+    });
+    try {
+        renderer.resize(width, height);
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                off();
+                resolve();
+            };
+            const off = renderer.onEvent((e) => {
+                if (e.type === 'buildComplete')
+                    finish();
+            });
+            renderer.setIR(ir);
+            // An empty IR builds no chunks and may not emit buildComplete — guard on
+            // the IR's own segment count (deterministic, not renderer state).
+            if (ir.segments.count === 0)
+                queueMicrotask(finish);
+        });
+        if (options.showTravel === true)
+            renderer.setKindVisible('travel', true);
+        if (options.colorMode)
+            renderer.setColorMode(options.colorMode);
+        if (options.layerRange)
+            renderer.setLayerRange(options.layerRange[0], options.layerRange[1]);
+        if (options.scrub !== undefined)
+            renderer.setScrubPosition(options.scrub);
+        const pose = options.camera;
+        if (pose) {
+            if (pose.fov !== undefined) {
+                renderer.camera.fov = pose.fov;
+                renderer.camera.updateProjectionMatrix();
+            }
+            renderer.camera.position.set(pose.position[0], pose.position[1], pose.position[2]);
+            renderer.camera.lookAt(pose.target[0], pose.target[1], pose.target[2]);
+            renderer.render();
+        }
+        else {
+            renderer.frame(); // deterministic bounds framing + render
+        }
+        // frame()/setColorMode already render; one explicit render guarantees the
+        // final state is on the (preserved) drawing buffer for read-back.
+        renderer.render();
+        return {
+            canvas,
+            width,
+            height,
+            layerCount: renderer.layerCount,
+            segmentCount: renderer.segmentCount,
+            quality: renderer.activeQuality,
+            parsed
+        };
+    }
+    finally {
+        renderer.dispose();
+    }
+}

package/dist/testing.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Framework-portable behavioral suite (DD-007 §4.6, phase 5): the SAME parse → state →
+ * controls → progress → dispose contract, runnable through every adapter — the parity
+ * lock that keeps Vue/React/Svelte from drifting into different feature sets.
+ *
+ * Adapters run it by implementing {@link AdapterHarness} over their public surface and
+ * calling {@link runBehavioralSuite} with their test framework's describe/it/expect
+ * (vitest-compatible shapes). Exported via `@chestnutlabs/gcode-preview-core/testing`.
+ */
+import { type MachineGeometry, type MappedProgress, type ProgressObservation, type ToolpathIR } from '@chestnutlabs/toolpath-core';
+import type { GLRendererLike } from '@chestnutlabs/gcode-renderer-three';
+import type { GcodePreviewControls, GcodePreviewState, PreviewEvent } from './controller.js';
+/** 2 layers × 6 extrude segments; srcByte = i*10; source byteLength 1000. */
+export declare function makeTestIR(): ToolpathIR;
+export declare const TEST_MACHINE: MachineGeometry;
+/** Protocol-v1-shaped stub worker: parse → done, cancel → cancelled. Counts lifecycles. */
+export declare class SuiteStubWorker {
+    private readonly machine?;
+    static created: number;
+    static terminated: number;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((err: unknown) => void) | null;
+    constructor(machine?: MachineGeometry | undefined);
+    postMessage(msg: {
+        type: string;
+        id: number;
+    }): void;
+    terminate(): void;
+}
+export declare function makeSuiteStubGL(canvas: HTMLCanvasElement): GLRendererLike;
+/** What every adapter must expose to the suite — its PUBLIC surface, uniformly shaped. */
+export interface AdapterHarness {
+    /** Construct one preview bound to a fresh canvas, wired to a SuiteStubWorker + stub GL. */
+    create(opts?: {
+        machine?: MachineGeometry;
+        consumerVolume?: boolean;
+    }): Promise<AdapterInstance> | AdapterInstance;
+}
+export interface AdapterInstance {
+    parse(bytes: Uint8Array): Promise<unknown>;
+    getState(): GcodePreviewState;
+    controls: GcodePreviewControls;
+    observeProgress(obs: ProgressObservation): MappedProgress | null;
+    clearProgress(): void;
+    onEvent(cb: (e: PreviewEvent) => void): () => void;
+    /** Chunk draw-range probe (renderer-level effect check). */
+    firstChunkDrawCount(): number;
+    dispose(): Promise<void> | void;
+    /** Let microtask round-trips + framework effects settle. */
+    settle(): Promise<void>;
+}
+interface TestApi {
+    describe: (name: string, fn: () => void) => void;
+    it: (name: string, fn: () => Promise<void> | void) => void;
+    expect: (actual: unknown) => Record<string, (...args: never[]) => unknown> & {
+        toBe(v: unknown): void;
+        toBeNull(): void;
+        toMatchObject(v: object): void;
+        toBeGreaterThan(v: number): void;
+    };
+}
+/** The parity contract every adapter must pass (DD-007 §4.6 amendment). */
+export declare function runBehavioralSuite(name: string, api: TestApi, harness: AdapterHarness): void;
+export {};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/testing.js

@@ -0,0 +1,147 @@
+/**
+ * Framework-portable behavioral suite (DD-007 §4.6, phase 5): the SAME parse → state →
+ * controls → progress → dispose contract, runnable through every adapter — the parity
+ * lock that keeps Vue/React/Svelte from drifting into different feature sets.
+ *
+ * Adapters run it by implementing {@link AdapterHarness} over their public surface and
+ * calling {@link runBehavioralSuite} with their test framework's describe/it/expect
+ * (vitest-compatible shapes). Exported via `@chestnutlabs/gcode-preview-core/testing`.
+ */
+import { MoveKind, ToolpathIRBuilder } from '@chestnutlabs/toolpath-core';
+/** 2 layers × 6 extrude segments; srcByte = i*10; source byteLength 1000. */
+export function makeTestIR() {
+    const b = new ToolpathIRBuilder({
+        parserVersion: 'behavioral-suite',
+        units: 'mm',
+        unitsSource: 'known',
+        source: { byteLength: 1_000 }
+    });
+    let src = 0;
+    for (let l = 0; l < 2; l++) {
+        for (let s = 0; s < 6; s++) {
+            b.addSegment({
+                x0: 100 + s,
+                y0: 100,
+                z0: 0.2 * (l + 1),
+                x1: 101 + s,
+                y1: 100,
+                z1: 0.2 * (l + 1),
+                e: 1,
+                kind: MoveKind.Extrude,
+                layer: l,
+                srcByte: src++ * 10
+            });
+        }
+    }
+    return b.finalize();
+}
+export const TEST_MACHINE = {
+    bed: { kind: 'rect', min: { x: 0, y: 0 }, max: { x: 256, y: 256 } },
+    heightMm: 256,
+    origin: { x: 0, y: 0 },
+    confidence: 'known',
+    source: { adapterId: 'behavioral-suite', evidence: 'stub' }
+};
+/** Protocol-v1-shaped stub worker: parse → done, cancel → cancelled. Counts lifecycles. */
+export class SuiteStubWorker {
+    machine;
+    static created = 0;
+    static terminated = 0;
+    onmessage = null;
+    onerror = null;
+    constructor(machine) {
+        this.machine = machine;
+        SuiteStubWorker.created++;
+    }
+    postMessage(msg) {
+        if (msg.type === 'parse') {
+            queueMicrotask(() => {
+                this.onmessage?.({
+                    data: {
+                        v: 1,
+                        type: 'done',
+                        id: msg.id,
+                        ir: makeTestIR(),
+                        stats: { bytes: 1_000, wallMs: 1 },
+                        metadata: this.machine === undefined ? undefined : { machine: this.machine }
+                    }
+                });
+            });
+        }
+        else if (msg.type === 'cancel') {
+            queueMicrotask(() => this.onmessage?.({ data: { v: 1, type: 'cancelled', id: msg.id } }));
+        }
+    }
+    terminate() {
+        SuiteStubWorker.terminated++;
+    }
+}
+export function makeSuiteStubGL(canvas) {
+    return { render: () => undefined, setSize: () => undefined, dispose: () => undefined, domElement: canvas };
+}
+/** The parity contract every adapter must pass (DD-007 §4.6 amendment). */
+export function runBehavioralSuite(name, api, harness) {
+    const { describe, it, expect } = api;
+    describe(`behavioral suite — ${name}`, () => {
+        it('parses and reports the standard state summary', async () => {
+            const a = await harness.create();
+            await a.parse(new Uint8Array(1_000));
+            await a.settle();
+            expect(a.getState().summary).toMatchObject({ segments: 12, layers: 2, complete: true });
+            expect(a.getState().segmentCount).toBe(12);
+            await a.dispose();
+        });
+        it('controls reach the renderer: scrub cuts and restores draw ranges', async () => {
+            const a = await harness.create();
+            await a.parse(new Uint8Array(1_000));
+            await a.settle();
+            expect(a.firstChunkDrawCount()).toBe(24);
+            a.controls.setScrubPosition(5);
+            await a.settle();
+            expect(a.firstChunkDrawCount()).toBe(12);
+            a.controls.setScrubPosition(null);
+            await a.settle();
+            expect(a.firstChunkDrawCount()).toBe(24);
+            await a.dispose();
+        });
+        it('drives the DD-006 progress chain honestly (exact → cleared)', async () => {
+            const a = await harness.create();
+            await a.parse(new Uint8Array(1_000));
+            await a.settle();
+            const mapped = a.observeProgress({ v: 1, timestampMs: 1_000, position: { byte: 55 } });
+            await a.settle();
+            expect(mapped).toMatchObject({ basis: 'byte', confidence: 'known', segIndex: 5 });
+            expect(a.getState().presentation).toBe('exact');
+            a.clearProgress();
+            await a.settle();
+            expect(a.getState().presentation).toBe('hidden');
+            await a.dispose();
+        });
+        it('progress is unavailable before a parse (no fabricated mapping)', async () => {
+            const a = await harness.create();
+            expect(a.observeProgress({ v: 1, timestampMs: 1, position: { percent: 0.5 } })).toBeNull();
+            await a.dispose();
+        });
+        it('honors DD-005 bed precedence: consumer volume blocks auto-apply, discovery is evented', async () => {
+            const a = await harness.create({ machine: TEST_MACHINE, consumerVolume: true });
+            const events = [];
+            a.onEvent((e) => events.push(e));
+            await a.parse(new Uint8Array(1_000));
+            await a.settle();
+            expect(events.filter((e) => e.type === 'machine-geometry-discovered').length).toBe(1);
+            await a.dispose();
+        });
+        it('disposes cleanly: 10 lifecycles leak no workers', async () => {
+            const created0 = SuiteStubWorker.created;
+            const terminated0 = SuiteStubWorker.terminated;
+            for (let i = 0; i < 10; i++) {
+                const a = await harness.create();
+                await a.parse(new Uint8Array(8));
+                await a.settle();
+                await a.dispose();
+            }
+            expect(SuiteStubWorker.created - created0).toBe(10);
+            expect(SuiteStubWorker.terminated - terminated0).toBe(10);
+        });
+    });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@chestnutlabs/gcode-preview-core",
+  "version": "0.1.0",
+  "description": "Framework-neutral preview controller for the Chestnut Labs G-code viewer (DD-007 \u00a74.6): the shared engine glue, state model, and TypeScript contracts beneath the Vue/React/Svelte adapters.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "viewer",
+    "preview",
+    "controller",
+    "framework-neutral"
+  ],
+  "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-core"
+  },
+  "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"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.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"
+  }
+}