@chestnutlabs/gcode-parser 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @chestnutlabs/gcode-parser
+
+Worker-safe G-code parse core and session client for the Chestnut Labs G-code Preview stack
+(design: DD-003). Parses `.gcode` / `.gcode.3mf` **off the main thread** into
+[`ToolpathIR`](../toolpath-core), with streaming input, progressive partial previews for large
+files, resource limits, cancellation, and an adversarial-input corpus behind it.
+
+```ts
+import { GcodeParseSession } from '@chestnutlabs/gcode-parser';
+
+const session = new GcodeParseSession(); // batteries worker: all dialects + .gcode.3mf
+const result = await session.parse(bytes, {
+  onPartial: (ir) => render(ir), // progressive preview
+  onProgress: (p) => bar(p)
+});
+render(result.ir);
+session.dispose();
+```
+
+## Workers
+
+- **Batteries default (zero setup):** the session creates its own worker via the bundler-native
+  `new Worker(new URL('./worker.js', import.meta.url))` pattern — all supported dialect adapters
+  plus `.gcode.3mf` container support. Vite resolves it out of the box (CI-tested).
+- **Slim / custom:** pass a worker factory for the slim build (no dialects/containers), your own
+  adapter set via `createWorkerHandler(...)`, other bundlers, or strict-CSP environments.
+
+Wire options accept dialect selection, container/plate selection (`plate` for multi-plate
+`.gcode.3mf`), and resource limits. Most applications should consume this through
+[`@chestnutlabs/gcode-preview-core`](../gcode-preview-core) or a framework adapter rather than
+directly.
+
+Part of [Chestnut Labs G-code Preview](../../README.md) · MIT

package/dist/growable.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Budget-aware growable SoA segment writer (DD-003 §7.2/§7.3).
+ *
+ * Accumulates segments directly into growable typed arrays (no intermediate object
+ * graphs) and keeps a byte-accurate account of every live working allocation. Any
+ * projected allocation — growth steps and the final right-size compaction, during
+ * which old and new capacity coexist — is checked against `maxBufferBytes` BEFORE
+ * it is performed. On budget exhaustion the writer reports failure and the parse
+ * stops at the current command boundary with a structured bounded result; it never
+ * throws an unhandled allocation error.
+ */
+export declare class BudgetExceededError extends Error {
+    readonly requestedBytes: number;
+    readonly accountedBytes: number;
+    readonly maxBufferBytes: number;
+    constructor(requestedBytes: number, accountedBytes: number, maxBufferBytes: number);
+}
+export interface SegmentRecord {
+    x0: number;
+    y0: number;
+    z0: number;
+    x1: number;
+    y1: number;
+    z1: number;
+    e: number;
+    feedrate: number;
+    kind: number;
+    tool: number;
+    layer: number;
+    srcByte: number;
+}
+export interface FinalChannels {
+    count: number;
+    x0: Float32Array;
+    y0: Float32Array;
+    z0: Float32Array;
+    x1: Float32Array;
+    y1: Float32Array;
+    z1: Float32Array;
+    e: Float32Array;
+    feedrate: Float32Array;
+    kind: Uint8Array;
+    tool: Uint16Array;
+    layer: Uint32Array;
+    feature: Uint8Array;
+    object: Uint32Array;
+    srcByte: Uint32Array;
+}
+export declare class SegmentWriter {
+    private readonly maxBufferBytes;
+    private capacity;
+    private _count;
+    private x0;
+    private y0;
+    private z0;
+    private x1;
+    private y1;
+    private z1;
+    private e;
+    private feedrate;
+    private kind;
+    private tool;
+    private layer;
+    private feature;
+    private object;
+    private srcByte;
+    /** Bytes of live typed-array capacity currently held by this writer. */
+    private accountedBytes;
+    /** Extra live bytes the caller wants included in the budget (line buffer, warnings). */
+    private externalBytes;
+    constructor(maxBufferBytes: number);
+    get count(): number;
+    get accounted(): number;
+    /** Report additional live working bytes (e.g., the line-drain buffer) into the budget. */
+    setExternalBytes(bytes: number): void;
+    /** Throws BudgetExceededError if `requested` more bytes would break the budget. */
+    private ensureBudget;
+    private allocate;
+    /** Append one segment. Throws BudgetExceededError when growth would break the budget. */
+    push(s: SegmentRecord): void;
+    /** Overwrite the layer channel for a segment range (used for post-hoc layer resolution). */
+    setLayerRange(start: number, end: number, layerIndex: number): void;
+    /** Zero the whole layer channel (non-planar clearing semantics). */
+    clearLayers(): void;
+    /**
+     * Copy a segment range into fresh right-sized arrays (progressive-preview
+     * snapshots, DD-004 §5.4 / issue #60). Budget-checked: the copies coexist with
+     * the live buffers until they are transferred away, so they count against
+     * `maxBufferBytes` at creation time. Throws BudgetExceededError when the copy
+     * would break the budget — callers skip the snapshot, never the parse.
+     */
+    snapshotRange(start: number, end: number): FinalChannels;
+    /** Right-size to exact count. Budget-checked (old + new coexist during the copy). */
+    finalize(): FinalChannels;
+}
+//# sourceMappingURL=growable.d.ts.map

package/dist/growable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"growable.d.ts","sourceRoot":"","sources":["../src/growable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,cAAc,EAAE,MAAM;aACtB,cAAc,EAAE,MAAM;aACtB,cAAc,EAAE,MAAM;gBAFtB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM;CAOzC;AAuBD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,YAAY,CAAC;IACjB,EAAE,EAAE,YAAY,CAAC;IACjB,EAAE,EAAE,YAAY,CAAC;IACjB,EAAE,EAAE,YAAY,CAAC;IACjB,EAAE,EAAE,YAAY,CAAC;IACjB,EAAE,EAAE,YAAY,CAAC;IACjB,CAAC,EAAE,YAAY,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAID,qBAAa,aAAa;IAwBZ,OAAO,CAAC,QAAQ,CAAC,cAAc;IAvB3C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAK;IAEnB,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,CAAC,CAAgB;IACzB,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,IAAI,CAAe;IAC3B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAe;IAE9B,wEAAwE;IACxE,OAAO,CAAC,cAAc,CAAK;IAC3B,wFAAwF;IACxF,OAAO,CAAC,aAAa,CAAK;gBAEG,cAAc,EAAE,MAAM;IAInD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,0FAA0F;IAC1F,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIrC,mFAAmF;IACnF,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,QAAQ;IAwDhB,yFAAyF;IACzF,IAAI,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI;IAsB5B,4FAA4F;IAC5F,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAInE,oEAAoE;IACpE,WAAW,IAAI,IAAI;IAInB;;;;;;OAMG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa;IAsBxD,qFAAqF;IACrF,QAAQ,IAAI,aAAa;CAsB1B"}

package/dist/growable.js

@@ -0,0 +1,217 @@
+/**
+ * Budget-aware growable SoA segment writer (DD-003 §7.2/§7.3).
+ *
+ * Accumulates segments directly into growable typed arrays (no intermediate object
+ * graphs) and keeps a byte-accurate account of every live working allocation. Any
+ * projected allocation — growth steps and the final right-size compaction, during
+ * which old and new capacity coexist — is checked against `maxBufferBytes` BEFORE
+ * it is performed. On budget exhaustion the writer reports failure and the parse
+ * stops at the current command boundary with a structured bounded result; it never
+ * throws an unhandled allocation error.
+ */
+export class BudgetExceededError extends Error {
+    requestedBytes;
+    accountedBytes;
+    maxBufferBytes;
+    constructor(requestedBytes, accountedBytes, maxBufferBytes) {
+        super(`allocation of ${requestedBytes} B would exceed maxBufferBytes=${maxBufferBytes} B (accounted: ${accountedBytes} B)`);
+        this.requestedBytes = requestedBytes;
+        this.accountedBytes = accountedBytes;
+        this.maxBufferBytes = maxBufferBytes;
+        this.name = 'BudgetExceededError';
+    }
+}
+const CHANNELS = [
+    { name: 'x0', bytesPerElement: 4 },
+    { name: 'y0', bytesPerElement: 4 },
+    { name: 'z0', bytesPerElement: 4 },
+    { name: 'x1', bytesPerElement: 4 },
+    { name: 'y1', bytesPerElement: 4 },
+    { name: 'z1', bytesPerElement: 4 },
+    { name: 'e', bytesPerElement: 4 },
+    { name: 'feedrate', bytesPerElement: 4 },
+    { name: 'kind', bytesPerElement: 1 },
+    { name: 'tool', bytesPerElement: 2 },
+    { name: 'layer', bytesPerElement: 4 },
+    { name: 'feature', bytesPerElement: 1 },
+    { name: 'object', bytesPerElement: 4 },
+    { name: 'srcByte', bytesPerElement: 4 }
+];
+const BYTES_PER_SEGMENT = CHANNELS.reduce((a, c) => a + c.bytesPerElement, 0); // 40 B core set
+const INITIAL_CAPACITY = 4096;
+export class SegmentWriter {
+    maxBufferBytes;
+    capacity = 0;
+    _count = 0;
+    x0;
+    y0;
+    z0;
+    x1;
+    y1;
+    z1;
+    e;
+    feedrate;
+    kind;
+    tool;
+    layer;
+    feature;
+    object;
+    srcByte;
+    /** Bytes of live typed-array capacity currently held by this writer. */
+    accountedBytes = 0;
+    /** Extra live bytes the caller wants included in the budget (line buffer, warnings). */
+    externalBytes = 0;
+    constructor(maxBufferBytes) {
+        this.maxBufferBytes = maxBufferBytes;
+        this.allocate(INITIAL_CAPACITY);
+    }
+    get count() {
+        return this._count;
+    }
+    get accounted() {
+        return this.accountedBytes + this.externalBytes;
+    }
+    /** Report additional live working bytes (e.g., the line-drain buffer) into the budget. */
+    setExternalBytes(bytes) {
+        this.externalBytes = bytes;
+    }
+    /** Throws BudgetExceededError if `requested` more bytes would break the budget. */
+    ensureBudget(requested) {
+        if (this.accounted + requested > this.maxBufferBytes) {
+            throw new BudgetExceededError(requested, this.accounted, this.maxBufferBytes);
+        }
+    }
+    allocate(newCapacity) {
+        // During a grow/compact, old and new capacity coexist until copies complete.
+        const newBytes = newCapacity * BYTES_PER_SEGMENT;
+        this.ensureBudget(newBytes);
+        const nx0 = new Float32Array(newCapacity);
+        const ny0 = new Float32Array(newCapacity);
+        const nz0 = new Float32Array(newCapacity);
+        const nx1 = new Float32Array(newCapacity);
+        const ny1 = new Float32Array(newCapacity);
+        const nz1 = new Float32Array(newCapacity);
+        const ne = new Float32Array(newCapacity);
+        const nfeed = new Float32Array(newCapacity);
+        const nkind = new Uint8Array(newCapacity);
+        const ntool = new Uint16Array(newCapacity);
+        const nlayer = new Uint32Array(newCapacity);
+        const nfeature = new Uint8Array(newCapacity);
+        const nobject = new Uint32Array(newCapacity);
+        const nsrc = new Uint32Array(newCapacity);
+        if (this.capacity > 0) {
+            nx0.set(this.x0.subarray(0, this._count));
+            ny0.set(this.y0.subarray(0, this._count));
+            nz0.set(this.z0.subarray(0, this._count));
+            nx1.set(this.x1.subarray(0, this._count));
+            ny1.set(this.y1.subarray(0, this._count));
+            nz1.set(this.z1.subarray(0, this._count));
+            ne.set(this.e.subarray(0, this._count));
+            nfeed.set(this.feedrate.subarray(0, this._count));
+            nkind.set(this.kind.subarray(0, this._count));
+            ntool.set(this.tool.subarray(0, this._count));
+            nlayer.set(this.layer.subarray(0, this._count));
+            nfeature.set(this.feature.subarray(0, this._count));
+            nobject.set(this.object.subarray(0, this._count));
+            nsrc.set(this.srcByte.subarray(0, this._count));
+        }
+        const oldBytes = this.capacity * BYTES_PER_SEGMENT;
+        this.x0 = nx0;
+        this.y0 = ny0;
+        this.z0 = nz0;
+        this.x1 = nx1;
+        this.y1 = ny1;
+        this.z1 = nz1;
+        this.e = ne;
+        this.feedrate = nfeed;
+        this.kind = nkind;
+        this.tool = ntool;
+        this.layer = nlayer;
+        this.feature = nfeature;
+        this.object = nobject;
+        this.srcByte = nsrc;
+        this.capacity = newCapacity;
+        this.accountedBytes = this.accountedBytes - oldBytes + newBytes;
+    }
+    /** Append one segment. Throws BudgetExceededError when growth would break the budget. */
+    push(s) {
+        if (this._count === this.capacity) {
+            this.allocate(this.capacity * 2);
+        }
+        const i = this._count;
+        this.x0[i] = s.x0;
+        this.y0[i] = s.y0;
+        this.z0[i] = s.z0;
+        this.x1[i] = s.x1;
+        this.y1[i] = s.y1;
+        this.z1[i] = s.z1;
+        this.e[i] = s.e;
+        this.feedrate[i] = s.feedrate;
+        this.kind[i] = s.kind;
+        this.tool[i] = s.tool;
+        this.layer[i] = s.layer;
+        this.feature[i] = 0;
+        this.object[i] = 0;
+        this.srcByte[i] = s.srcByte;
+        this._count++;
+    }
+    /** Overwrite the layer channel for a segment range (used for post-hoc layer resolution). */
+    setLayerRange(start, end, layerIndex) {
+        this.layer.fill(layerIndex, start, end + 1);
+    }
+    /** Zero the whole layer channel (non-planar clearing semantics). */
+    clearLayers() {
+        this.layer.fill(0, 0, this._count);
+    }
+    /**
+     * Copy a segment range into fresh right-sized arrays (progressive-preview
+     * snapshots, DD-004 §5.4 / issue #60). Budget-checked: the copies coexist with
+     * the live buffers until they are transferred away, so they count against
+     * `maxBufferBytes` at creation time. Throws BudgetExceededError when the copy
+     * would break the budget — callers skip the snapshot, never the parse.
+     */
+    snapshotRange(start, end) {
+        const count = Math.max(0, end - start);
+        this.ensureBudget(count * BYTES_PER_SEGMENT);
+        return {
+            count,
+            x0: this.x0.slice(start, end),
+            y0: this.y0.slice(start, end),
+            z0: this.z0.slice(start, end),
+            x1: this.x1.slice(start, end),
+            y1: this.y1.slice(start, end),
+            z1: this.z1.slice(start, end),
+            e: this.e.slice(start, end),
+            feedrate: this.feedrate.slice(start, end),
+            kind: this.kind.slice(start, end),
+            tool: this.tool.slice(start, end),
+            layer: this.layer.slice(start, end),
+            feature: this.feature.slice(start, end),
+            object: this.object.slice(start, end),
+            srcByte: this.srcByte.slice(start, end)
+        };
+    }
+    /** Right-size to exact count. Budget-checked (old + new coexist during the copy). */
+    finalize() {
+        if (this._count < this.capacity) {
+            this.allocate(Math.max(this._count, 1));
+        }
+        return {
+            count: this._count,
+            x0: this.x0.subarray(0, this._count),
+            y0: this.y0.subarray(0, this._count),
+            z0: this.z0.subarray(0, this._count),
+            x1: this.x1.subarray(0, this._count),
+            y1: this.y1.subarray(0, this._count),
+            z1: this.z1.subarray(0, this._count),
+            e: this.e.subarray(0, this._count),
+            feedrate: this.feedrate.subarray(0, this._count),
+            kind: this.kind.subarray(0, this._count),
+            tool: this.tool.subarray(0, this._count),
+            layer: this.layer.subarray(0, this._count),
+            feature: this.feature.subarray(0, this._count),
+            object: this.object.subarray(0, this._count),
+            srcByte: this.srcByte.subarray(0, this._count)
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @chestnutlabs/gcode-parser — worker-safe G-code parse core (DD-003).
+ *
+ * Phase 1 (#44): pure parse core. Phase 2 (#45): cooperative async driver,
+ * worker protocol v1, and the GcodeParseSession client. Streaming inputs and
+ * full limit wiring land in phase 3 (#46). Depends only on
+ * @chestnutlabs/toolpath-core.
+ */
+export { parseGcodeToIR, parseGcodeToIRAsync, DEFAULT_LIMITS } from './parse.js';
+export type { AsyncParseHooks, AsyncParseResult, CommandEvent, ParseLimits, ParseOptions, ParseResult, ParseStats, StopReason } from './parse.js';
+export { BudgetExceededError } from './growable.js';
+export { parseGcodeStreamToIR, isBlobLike, isReadableStreamLike } from './streaming.js';
+export type { StreamInput, BlobLike, ReadableStreamLike } from './streaming.js';
+export { PROTOCOL_VERSION, PARTIAL_PREVIEW_MIN_BYTES, irTransferList } from './protocol.js';
+export type { WireParseOptions, WorkerRequest, WorkerResponse, PartialMessage } from './protocol.js';
+export { createWorkerHandler } from './worker-core.js';
+export type { PostFn, DialectRunLike, DialectRunnerFactoryLike, WorkerHandlerOptions } from './worker-core.js';
+export { GcodeParseSession, ParseSessionError, CancelledError } from './session.js';
+export type { SessionOptions, WorkerLike, ParseProgress } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjF,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACrG,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC/G,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpF,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @chestnutlabs/gcode-parser — worker-safe G-code parse core (DD-003).
+ *
+ * Phase 1 (#44): pure parse core. Phase 2 (#45): cooperative async driver,
+ * worker protocol v1, and the GcodeParseSession client. Streaming inputs and
+ * full limit wiring land in phase 3 (#46). Depends only on
+ * @chestnutlabs/toolpath-core.
+ */
+export { parseGcodeToIR, parseGcodeToIRAsync, DEFAULT_LIMITS } from './parse.js';
+export { BudgetExceededError } from './growable.js';
+export { parseGcodeStreamToIR, isBlobLike, isReadableStreamLike } from './streaming.js';
+export { PROTOCOL_VERSION, PARTIAL_PREVIEW_MIN_BYTES, irTransferList } from './protocol.js';
+export { createWorkerHandler } from './worker-core.js';
+export { GcodeParseSession, ParseSessionError, CancelledError } from './session.js';

package/dist/parse.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Pure G-code parse core (DD-003 §14 phase 1, issue #44; async driver added in phase 2, #45).
+ *
+ * Ports the inherited xyz-tools interpreter semantics — motion handling (G0/G1),
+ * arc flattening (G2/G3 incl. R-mode and full circles), units (G20/G21), homing
+ * (G28), tool selection (T0–T7), travel/extrusion path splitting, and the
+ * layer-indexing rules (0.05 tolerance, non-planar clearing) — but writes the
+ * DD-001 `ToolpathIR` SoA buffers **directly** through a budget-aware growable
+ * writer, with **real** per-segment `srcByte`, extrusion deltas, and modal
+ * feed rate (the #29 adapter had to report those `unavailable`).
+ *
+ * Provenance: machine-state semantics adapted from the inherited MIT source
+ * (`src/interpreter.ts`, `src/gcode-parser.ts`, `src/indexers.ts` @ the founding
+ * baseline) — recorded in docs/UPSTREAM_PROVENANCE.md. Deliberate quirk-for-quirk
+ * fidelity (e.g. truthy `x || state.x` in arcs, tool captured at path start) is
+ * required by the golden-equivalence gate; do not "fix" behavior here without a
+ * reviewed golden regeneration.
+ *
+ * Two drivers share one engine:
+ * - `parseGcodeToIR` — synchronous (tests, Node tooling).
+ * - `parseGcodeToIRAsync` — the DD-003 §5.2 cooperative driver: processes at most
+ *   `yieldIntervalMs` of CPU work between explicit MessageChannel macrotask yields
+ *   so a queued worker `cancel` message can actually be dispatched; reports
+ *   progress and honors a cancellation hook.
+ *
+ * Byte offsets assume single-byte (ASCII/UTF-8) G-code, which holds for slicer
+ * output; multi-byte comment bytes would skew offsets and are a documented
+ * limitation until the streaming decoder lands (phase 3).
+ */
+import { type ToolpathIR } from '@chestnutlabs/toolpath-core';
+export interface ParseLimits {
+    maxInputBytes: number;
+    maxSegments: number;
+    maxBufferBytes: number;
+    maxLineLength: number;
+    maxWarnings: number;
+}
+export declare const DEFAULT_LIMITS: ParseLimits;
+/**
+ * Read-only normalized command event (DD-005 §4.3, amendment 1): observers see
+ * each lexed command BEFORE dispatch and cannot alter parsing.
+ */
+export interface CommandEvent {
+    /** Normalized lowercase word+number, e.g. 'm486'. */
+    gcode: string;
+    params: Readonly<Record<string, number>>;
+    /** The raw line, for vendor syntaxes the lexer's params don't capture. */
+    rawLine: string;
+    srcByte: number;
+    /** Segment count at event time — maps events to segment ranges. */
+    segIndex: number;
+}
+export interface ParseOptions {
+    parserVersion?: string;
+    sourceId?: string;
+    limits?: Partial<ParseLimits>;
+    /** Layer-detection tolerance (inherited default 0.05). */
+    minLayerThreshold?: number;
+    /**
+     * DD-005 §4.3 read-only hooks: observe comments/commands during the parse.
+     * Inert when unset (one branch per line); they cannot alter lexing, dispatch,
+     * or machine state — the golden-gated semantics are untouched.
+     */
+    onComment?: (text: string, srcByte: number) => void;
+    onCommand?: (event: CommandEvent) => void;
+}
+export interface StopReason {
+    code: 'E_LIMIT_INPUT_BYTES' | 'E_LIMIT_SEGMENTS' | 'E_LIMIT_BUFFER_BYTES';
+    message: string;
+    srcByte?: number;
+}
+export interface ParseStats {
+    bytes: number;
+    lines: number;
+    commands: number;
+    segments: number;
+    points: number;
+    retractions: number;
+    deretractions: number;
+    feedrateChanges: number;
+    others: number;
+    extrusionDistance: number;
+    warningsByCode: Record<string, number>;
+    stopReason?: StopReason;
+}
+export interface ParseResult {
+    ir: ToolpathIR;
+    stats: ParseStats;
+    /** Dialect/machine metadata (DD-005 §4.2) — populated by the worker pipeline
+     *  when dialect adapters are registered and matched; absent otherwise. */
+    metadata?: import('@chestnutlabs/toolpath-core').DialectMetadata;
+}
+export interface AsyncParseHooks {
+    /** Called after each cooperative yield with bytes processed so far. */
+    onProgress?: (bytesProcessed: number, totalBytes: number, segments: number) => void;
+    /** Checked after each yield; returning true stops the parse with a partial result. */
+    shouldCancel?: () => boolean;
+    /** Max CPU ms between yields (DD-003 §5.2 default 50). */
+    yieldIntervalMs?: number;
+    /**
+     * Progressive preview (DD-004 §5.4, issue #60): receives path-aligned delta
+     * snapshots of the IR built so far. Emission starts once bytesProcessed ≥
+     * `partialMinBytes` and repeats at most every `partialIntervalMs`.
+     */
+    onPartial?: (slice: ToolpathIR, cumulativeSegments: number) => void;
+    /** Bytes processed before the first partial may be emitted (default 0 when onPartial set). */
+    partialMinBytes?: number;
+    /** Minimum ms between partial snapshots (default 1000). */
+    partialIntervalMs?: number;
+    /**
+     * DD-005 §4.5 stream detection windows: when set, the STREAMING driver fills
+     * `head` with the first ≤64 KB of decoded text and keeps `tail` as a bounded
+     * rolling window (last ≤16 KB) — read after the parse for late dialect
+     * detection on non-seekable streams. In-memory drivers ignore this (their
+     * windows are sliceable up front).
+     */
+    captureWindows?: {
+        head: string;
+        tail: string;
+    };
+}
+export interface AsyncParseResult extends ParseResult {
+    cancelled: boolean;
+}
+/** Internal engine surface shared by the sync, async, and streaming drivers. Not public API. */
+export interface Engine {
+    text: string;
+    limits: ParseLimits;
+    processLine(rawLine: string, offset: number): void;
+    stopped(): boolean;
+    markInputTooBig(): void;
+    /** Streaming driver: record the true source byte count as it becomes known. */
+    setSourceBytes(bytes: number): void;
+    /**
+     * Progressive-preview delta (issue #60): copy segments [fromSeg, cut) where
+     * `cut` is the current path boundary — every included segment has a resolved
+     * layer. Returns null when nothing new is ready or the copy would break the
+     * §7.2 buffer budget (snapshots are skippable; the parse never is).
+     */
+    snapshot(fromSeg: number): {
+        slice: ToolpathIR;
+        upTo: number;
+    } | null;
+    finish(cancelledAtByte?: number): ParseResult;
+}
+/** Internal: build an engine over decoded text (streaming passes '' and feeds lines itself). */
+export declare function createEngine(input: string | Uint8Array, opts: ParseOptions): Engine;
+/** Parse a whole G-code text into a ToolpathIR. Pure and synchronous. */
+export declare function parseGcodeToIR(input: string | Uint8Array, opts?: ParseOptions): ParseResult;
+/**
+ * Cooperative async driver (DD-003 §5.2): identical parsing semantics, but the
+ * loop processes at most `yieldIntervalMs` (default 50) of CPU work between
+ * explicit macrotask yields so queued `cancel` messages are dispatched. Progress
+ * and cancellation are surfaced through hooks.
+ */
+export declare function parseGcodeToIRAsync(input: string | Uint8Array, opts?: ParseOptions, hooks?: AsyncParseHooks): Promise<AsyncParseResult>;
+/**
+ * Shared partial-snapshot emitter for the async and streaming drivers (#60):
+ * called at cooperative yield points; emits a delta once bytesProcessed passes
+ * `partialMinBytes` and at most every `partialIntervalMs`.
+ */
+export declare function makePartialEmitter(engine: Engine, hooks: AsyncParseHooks): (bytesProcessed: number) => void;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

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