@chestnutlabs/gcode-parser 0.1.0

package/dist/worker-core.js

@@ -0,0 +1,309 @@
+import { parseGcodeToIRAsync } from './parse.js';
+import { isBlobLike, isReadableStreamLike, parseGcodeStreamToIR } from './streaming.js';
+import { PARTIAL_PREVIEW_MIN_BYTES, PROTOCOL_VERSION, irTransferList } from './protocol.js';
+const PROGRESS_THROTTLE_MS = 100;
+const DETECT_HEAD_BYTES = 64 * 1024;
+const DETECT_TAIL_BYTES = 16 * 1024;
+/** §4.5 stream replay: max recorded hook events before annotation degrades (visibly). */
+const STREAM_EVENT_CAP = 500_000;
+/**
+ * DD-005 §8 (ratified #78): container-extracted plate streams use a LOWER
+ * progressive-preview threshold than direct inputs — extraction adds fixed
+ * latency and a container already implies a substantial file. Measured: 8 MiB
+ * restores container TTFP to ~1.4 s @ a 100 MB plate (vs 3.7 s at 25 MiB) with
+ * zero total-time cost. An explicit consumer `partialPreview` setting wins.
+ */
+const CONTAINER_PARTIAL_MIN_BYTES = 8 * 1024 * 1024;
+/** Detection windows for sliceable inputs (DD-005 §4.5). Non-seekable streams: head/tail arrive in phase 4. */
+async function detectWindows(input) {
+    if (typeof input === 'string') {
+        return { headText: input.slice(0, DETECT_HEAD_BYTES), tailText: input.slice(-DETECT_TAIL_BYTES) };
+    }
+    if (input instanceof Uint8Array) {
+        const dec = new TextDecoder();
+        return {
+            headText: dec.decode(input.subarray(0, DETECT_HEAD_BYTES)),
+            tailText: dec.decode(input.subarray(Math.max(0, input.byteLength - DETECT_TAIL_BYTES)))
+        };
+    }
+    if (isBlobLike(input)) {
+        const blob = input;
+        if (typeof blob.slice === 'function') {
+            const head = await blob.slice(0, DETECT_HEAD_BYTES).text();
+            const tail = await blob.slice(Math.max(0, blob.size - DETECT_TAIL_BYTES)).text();
+            return { headText: head, tailText: tail };
+        }
+    }
+    return { headText: '', tailText: '' };
+}
+/** Route by input form (§4.2): streams/Blobs use the line-drain driver, memory uses the async driver. */
+function dispatchParse(input, opts, hooks) {
+    if (isBlobLike(input) || isReadableStreamLike(input)) {
+        return parseGcodeStreamToIR(input, opts, hooks);
+    }
+    return parseGcodeToIRAsync(input, opts, hooks);
+}
+export function createWorkerHandler(post, handlerOpts = {}) {
+    let activeId = null;
+    let cancelRequested = false;
+    return (msg) => {
+        if (typeof msg !== 'object' || msg === null || msg.v !== PROTOCOL_VERSION) {
+            const id = msg?.id ?? -1;
+            post({
+                v: PROTOCOL_VERSION,
+                type: 'error',
+                id,
+                error: {
+                    code: 'E_PROTOCOL',
+                    message: `unsupported message or protocol version (expected v${PROTOCOL_VERSION})`
+                }
+            });
+            return;
+        }
+        if (msg.type === 'cancel') {
+            if (msg.id === activeId) {
+                cancelRequested = true;
+            }
+            return;
+        }
+        if (msg.type === 'parse') {
+            if (activeId !== null) {
+                post({
+                    v: PROTOCOL_VERSION,
+                    type: 'error',
+                    id: msg.id,
+                    error: { code: 'E_BUSY', message: 'a parse is already in progress on this session' }
+                });
+                return;
+            }
+            activeId = msg.id;
+            cancelRequested = false;
+            const { partialOnCancel, yieldIntervalMs, partialPreview, dialects, dialectConfig, containers, plate, ...parseOpts } = msg.opts ?? {};
+            let lastProgress = 0;
+            const hooks = {
+                yieldIntervalMs,
+                shouldCancel: () => cancelRequested,
+                onProgress: (bytesProcessed, totalBytes) => {
+                    const now = Date.now();
+                    if (now - lastProgress >= PROGRESS_THROTTLE_MS) {
+                        lastProgress = now;
+                        post({ v: PROTOCOL_VERSION, type: 'progress', id: msg.id, bytesProcessed, totalBytes, phase: 'parsing' });
+                    }
+                }
+            };
+            // Progressive preview (#60): on by default with the §5.4 25 MiB threshold;
+            // partials transfer zero-copy like the terminal IR.
+            if (partialPreview !== false) {
+                hooks.partialMinBytes = partialPreview?.minInputBytes ?? PARTIAL_PREVIEW_MIN_BYTES;
+                hooks.partialIntervalMs = partialPreview?.intervalMs ?? 1000;
+                hooks.onPartial = (slice, cumulativeSegments) => {
+                    post({ v: PROTOCOL_VERSION, type: 'partial', id: msg.id, slice, cumulativeSegments }, irTransferList(slice));
+                };
+            }
+            void (async () => {
+                // Container resolution (DD-005 §4.4): sniff sliceable inputs; on a
+                // match the selected plate's stream becomes the parse input and the
+                // container's metadata rides beside the IR.
+                let input = msg.input;
+                let opened = null;
+                const containerSel = containers ?? 'auto';
+                const containerWarnings = [];
+                if (containerSel !== false && (handlerOpts.containers?.length ?? 0) > 0) {
+                    let bytes = null;
+                    if (input instanceof Uint8Array)
+                        bytes = input;
+                    else if (isBlobLike(input)) {
+                        const blob = input;
+                        if (typeof blob.arrayBuffer === 'function')
+                            bytes = new Uint8Array(await blob.arrayBuffer());
+                    }
+                    if (bytes !== null && bytes.byteLength >= 4) {
+                        const adapter = handlerOpts.containers.find((a) => (containerSel === 'auto' || containerSel.includes(a.id)) && a.sniff(bytes.subarray(0, 8)));
+                        if (adapter !== undefined) {
+                            try {
+                                opened = await adapter.open(bytes);
+                            }
+                            catch (err) {
+                                const code = err instanceof Error && 'code' in err && typeof err.code === 'string'
+                                    ? err.code
+                                    : 'E_CONTAINER';
+                                post({
+                                    v: PROTOCOL_VERSION,
+                                    type: 'error',
+                                    id: msg.id,
+                                    error: { code, message: err instanceof Error ? err.message : String(err) }
+                                });
+                                return;
+                            }
+                            const plateIdx = plate ?? 0;
+                            if (plateIdx < 0 || plateIdx >= opened.plates.length) {
+                                post({
+                                    v: PROTOCOL_VERSION,
+                                    type: 'error',
+                                    id: msg.id,
+                                    error: {
+                                        code: 'E_CONTAINER_NO_PAYLOAD',
+                                        message: `plate ${plateIdx} does not exist (container has ${opened.plates.length})`
+                                    }
+                                });
+                                return;
+                            }
+                            if (opened.plates.length > 1 && plate === undefined) {
+                                containerWarnings.push({
+                                    code: 'container-multiple-plates',
+                                    message: `container has ${opened.plates.length} plates ` +
+                                        `(${opened.plates.map((p) => p.name).join(', ')}); parsing plate 0 — pass {plate} to select`,
+                                    severity: 'warn',
+                                    count: 1
+                                });
+                            }
+                            for (const w of opened.metadata.warnings) {
+                                containerWarnings.push({ ...w, severity: 'warn', count: 1 });
+                            }
+                            input = opened.openPlate(plateIdx);
+                            // §8: container path defaults to the lower preview threshold
+                            // unless the consumer configured partialPreview explicitly.
+                            if (partialPreview === undefined && hooks.onPartial !== undefined) {
+                                hooks.partialMinBytes = CONTAINER_PARTIAL_MIN_BYTES;
+                            }
+                        }
+                    }
+                }
+                // Dialect annotation (DD-005 §4.5): composed by the worker entry; the
+                // main thread only ever sent serializable IDs/config.
+                let run = null;
+                const selection = dialects ?? 'auto';
+                let slimRequested = false;
+                if (selection !== false) {
+                    if (handlerOpts.dialects !== undefined) {
+                        const windows = opened === null ? await detectWindows(input) : { headText: '', tailText: '' };
+                        run = handlerOpts.dialects.createRun({
+                            selection,
+                            config: dialectConfig,
+                            headText: windows.headText,
+                            tailText: windows.tailText,
+                            containerMeta: opened?.metadata.raw
+                        });
+                        if (run !== null) {
+                            parseOpts.onComment = run.onComment;
+                            parseOpts.onCommand = run.onCommand;
+                        }
+                    }
+                    else if (Array.isArray(selection)) {
+                        slimRequested = true; // explicit request against a slim worker — degrade VISIBLY
+                    }
+                }
+                let streamReplay = null;
+                if (run === null &&
+                    selection !== false &&
+                    handlerOpts.dialects !== undefined &&
+                    opened === null &&
+                    isReadableStreamLike(input)) {
+                    const rec = { events: [], overflow: false, windows: { head: '', tail: '' } };
+                    streamReplay = rec;
+                    hooks.captureWindows = rec.windows;
+                    parseOpts.onComment = (t, b) => {
+                        if (rec.events.length < STREAM_EVENT_CAP)
+                            rec.events.push({ kind: 'comment', t, b });
+                        else
+                            rec.overflow = true;
+                    };
+                    parseOpts.onCommand = (e) => {
+                        if (rec.events.length < STREAM_EVENT_CAP)
+                            rec.events.push({ kind: 'command', e });
+                        else
+                            rec.overflow = true;
+                    };
+                }
+                const result = await dispatchParse(input, parseOpts, hooks);
+                if (result.cancelled) {
+                    const partial = partialOnCancel ? { ir: result.ir, stats: result.stats } : undefined;
+                    post({ v: PROTOCOL_VERSION, type: 'cancelled', id: msg.id, partial }, partial ? irTransferList(partial.ir) : undefined);
+                    return;
+                }
+                if (streamReplay !== null) {
+                    if (streamReplay.overflow) {
+                        result.ir.header.warnings.push({
+                            code: 'dialect-stream-truncated',
+                            message: 'stream exceeded the dialect replay budget; annotation skipped — ' +
+                                'use Uint8Array/Blob input for full annotation of very large files',
+                            severity: 'warn',
+                            count: 1
+                        });
+                    }
+                    else {
+                        run = handlerOpts.dialects.createRun({
+                            selection: selection,
+                            config: dialectConfig,
+                            headText: streamReplay.windows.head,
+                            tailText: streamReplay.windows.tail
+                        });
+                        if (run !== null) {
+                            for (const ev of streamReplay.events) {
+                                if (ev.kind === 'comment')
+                                    run.onComment(ev.t, ev.b);
+                                else
+                                    run.onCommand(ev.e);
+                            }
+                        }
+                    }
+                }
+                let metadata;
+                if (run !== null) {
+                    metadata = run.finalize(result.ir).metadata;
+                }
+                // Merge container metadata (§4.4): container-config machine data is
+                // 'known' and outranks comment-inferred geometry; ties go to the
+                // container (it is the project's own machine config).
+                if (opened !== null) {
+                    metadata = metadata ?? {};
+                    const cm = opened.metadata.machine;
+                    if (cm !== undefined && (metadata.machine === undefined || cm.confidence === 'known')) {
+                        metadata.machine = cm;
+                    }
+                    if (opened.metadata.filaments !== undefined && opened.metadata.filaments.length > 0) {
+                        metadata.filaments = [...(metadata.filaments ?? []), ...opened.metadata.filaments];
+                    }
+                    if (Object.keys(opened.metadata.raw).length > 0) {
+                        metadata.raw = { ...opened.metadata.raw, ...(metadata.raw ?? {}) };
+                    }
+                }
+                for (const w of containerWarnings) {
+                    result.ir.header.warnings.push(w);
+                }
+                if (slimRequested) {
+                    result.ir.header.warnings.push({
+                        code: 'dialects-unavailable',
+                        message: 'dialect adapters requested but this worker entry bundles none (worker-slim)',
+                        severity: 'warn',
+                        count: 1
+                    });
+                }
+                // Terminal-message contract (§4.3): complete AND limit-bounded parses both
+                // arrive as `done` (limit-bounded: complete:false + stats.stopReason).
+                const transfer = irTransferList(result.ir);
+                for (const t of metadata?.thumbnails ?? []) {
+                    transfer.push(t.bytes.buffer);
+                }
+                post({ v: PROTOCOL_VERSION, type: 'done', id: msg.id, ir: result.ir, stats: result.stats, metadata }, transfer);
+            })()
+                .catch((err) => {
+                // Preserve structured codes (e.g. mid-stream E_CONTAINER_CRC from a
+                // plate stream) instead of collapsing everything into E_INTERNAL.
+                const code = err instanceof Error && 'code' in err && typeof err.code === 'string'
+                    ? err.code
+                    : 'E_INTERNAL';
+                post({
+                    v: PROTOCOL_VERSION,
+                    type: 'error',
+                    id: msg.id,
+                    error: { code, message: err instanceof Error ? err.message : String(err) }
+                });
+            })
+                .finally(() => {
+                activeId = null;
+                cancelRequested = false;
+            });
+        }
+    };
+}

package/dist/worker-slim.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-slim.d.ts.map

package/dist/worker-slim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-slim.d.ts","sourceRoot":"","sources":["../src/worker-slim.ts"],"names":[],"mappings":""}

package/dist/worker-slim.js

@@ -0,0 +1,14 @@
+/**
+ * Web Worker entry — SLIM (DD-005 §4.5): zero dialect adapters bundled.
+ *
+ * Smallest payload for consumers that never want annotation. Explicit dialect
+ * requests against this entry degrade VISIBLY (`dialects-unavailable` warning
+ * on the result), never silently. Use via the session escape hatch:
+ * `new GcodeParseSession({ worker: () => new Worker(new URL(
+ *   '@chestnutlabs/gcode-parser/dist/worker-slim.js', import.meta.url),
+ *   { type: 'module' }) })`.
+ */
+import { createWorkerHandler } from './worker-core.js';
+const post = (msg, transfer) => self.postMessage(msg, transfer);
+const handle = createWorkerHandler(post);
+self.onmessage = (ev) => handle(ev.data);

package/dist/worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":""}

package/dist/worker.js

@@ -0,0 +1,34 @@
+/**
+ * Web Worker entry — BATTERIES-INCLUDED (DD-003 §4.4 option (a); DD-005 §4.5).
+ *
+ * Consumers' bundlers (Vite/webpack/Rollup) bundle this file automatically via
+ * `new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })`
+ * in `session.ts`. All logic lives in the transport-agnostic `worker-core`;
+ * this entry composes it with the built-in dialect adapter set (currently
+ * empty — vendor adapters land in DD-005 phases 3–5; the wiring is live so
+ * they activate here without API changes). Size-sensitive consumers use
+ * `worker-slim.ts`; custom adapters use a consumer-supplied worker entry
+ * calling `createWorkerHandler(post, { dialects: createDialectRunner([...]) })`.
+ */
+import { createDialectRunner, cura, klipper, marlin, orcaBambu, prusaSlicer, repRap } from '@chestnutlabs/gcode-dialects';
+import { openGcode3mf, sniffGcode3mf } from '@chestnutlabs/gcode-containers';
+import { createWorkerHandler } from './worker-core.js';
+/** Built-in dialect adapter set (DD-005 phases 3–4; phase 5 adds command semantics). */
+const BUILTIN_ADAPTERS = [
+    prusaSlicer(),
+    orcaBambu(),
+    cura(),
+    klipper(),
+    marlin(),
+    repRap()
+];
+/** Built-in container adapters (DD-005 §4.4): .gcode.3mf. */
+const BUILTIN_CONTAINERS = [
+    { id: 'gcode-3mf', sniff: sniffGcode3mf, open: (bytes) => openGcode3mf(bytes) }
+];
+const post = (msg, transfer) => self.postMessage(msg, transfer);
+const handle = createWorkerHandler(post, {
+    dialects: createDialectRunner(BUILTIN_ADAPTERS),
+    containers: BUILTIN_CONTAINERS
+});
+self.onmessage = (ev) => handle(ev.data);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@chestnutlabs/gcode-parser",
+  "version": "0.1.0",
+  "description": "Worker-safe G-code parse core producing ToolpathIR (DD-003).",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "parser",
+    "web-worker",
+    "streaming",
+    "marlin",
+    "klipper"
+  ],
+  "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-parser"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/toolpath-core": "0.1.0",
+    "@chestnutlabs/gcode-dialects": "0.1.0",
+    "@chestnutlabs/gcode-containers": "0.1.0"
+  }
+}