@chestnutlabs/gcode-parser 0.1.0

package/dist/protocol.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Worker protocol v1 (DD-003 §4.3).
+ *
+ * A parse ends in exactly one terminal message:
+ * - `done` — complete AND limit-bounded parses (limit-bounded: `ir.header.complete === false`
+ *   + `stats.stopReason`); the client RESOLVES `parse()` with the ParseResult.
+ * - `error` — failures producing no usable IR; the client REJECTS.
+ * - `cancelled` — client rejects with E_CANCELLED; `partial` attached when requested.
+ */
+import type { DialectMetadata, ToolpathIR } from '@chestnutlabs/toolpath-core';
+import type { ParseOptions, ParseStats } from './parse.js';
+import type { BlobLike, ReadableStreamLike } from './streaming.js';
+export declare const PROTOCOL_VERSION = 1;
+export interface WireParseOptions extends ParseOptions {
+    /** Attach the bounded partial IR to a `cancelled` response (DD-003 §5.2). */
+    partialOnCancel?: boolean;
+    /** Cooperative yield interval override (tests only; default 50 ms). */
+    yieldIntervalMs?: number;
+    /**
+     * Progressive preview (DD-004 §5.4, issue #60). Default 'auto': partial
+     * snapshots stream once bytesProcessed ≥ minInputBytes (default 25 MiB,
+     * provisional until #61 ratifies), at most one per intervalMs (default 1000).
+     * `false` disables; `{ minInputBytes: 0 }` forces immediate previews.
+     */
+    partialPreview?: false | {
+        minInputBytes?: number;
+        intervalMs?: number;
+    };
+    /**
+     * Dialect annotation (DD-005 §4.5): SERIALIZABLE selection only — adapter
+     * implementations live inside the worker entry. 'auto' (default) runs
+     * detection over the entry's registered set; an array restricts by id;
+     * false disables.
+     */
+    dialects?: 'auto' | string[] | false;
+    /** Per-adapter structured-cloneable configuration, keyed by adapter id. */
+    dialectConfig?: Record<string, unknown>;
+    /**
+     * Container extraction (DD-005 §4.4): 'auto' (default) sniffs sliceable
+     * inputs against the worker entry's registered container adapters; an array
+     * restricts by id; false disables.
+     */
+    containers?: 'auto' | string[] | false;
+    /** Plate selection for multi-plate containers (default 0 + a
+     *  `container-multiple-plates` warning carrying the discovered plate list). */
+    plate?: number;
+}
+/** §5.4 provisional progressive-preview threshold (ratified by #61). */
+export declare const PARTIAL_PREVIEW_MIN_BYTES: number;
+/** Blob is structured-cloneable; ReadableStream is transferred (§4.2). */
+export type ParseInputWire = string | Uint8Array | BlobLike | ReadableStreamLike<Uint8Array>;
+export interface ParseRequest {
+    v: number;
+    type: 'parse';
+    id: number;
+    input: ParseInputWire;
+    opts?: WireParseOptions;
+}
+export interface CancelRequest {
+    v: number;
+    type: 'cancel';
+    id: number;
+}
+export type WorkerRequest = ParseRequest | CancelRequest;
+export interface ProgressMessage {
+    v: number;
+    type: 'progress';
+    id: number;
+    bytesProcessed: number;
+    totalBytes: number;
+    phase: 'parsing' | 'finalizing';
+}
+export interface DoneMessage {
+    v: number;
+    type: 'done';
+    id: number;
+    ir: ToolpathIR;
+    stats: ParseStats;
+    /** Dialect/machine metadata beside the IR (DD-005 §4.2); thumbnails transferred. */
+    metadata?: DialectMetadata;
+}
+export interface ErrorMessage {
+    v: number;
+    type: 'error';
+    id: number;
+    error: {
+        code: string;
+        message: string;
+        srcByte?: number;
+    };
+}
+export interface CancelledMessage {
+    v: number;
+    type: 'cancelled';
+    id: number;
+    partial?: {
+        ir: ToolpathIR;
+        stats: ParseStats;
+    };
+}
+/**
+ * Progressive-preview snapshot (#60): a path-aligned DELTA of segments since the
+ * previous partial, transferred zero-copy. `header.complete` is always false;
+ * the terminal `done` IR REPLACES the accumulated preview wholesale.
+ */
+export interface PartialMessage {
+    v: number;
+    type: 'partial';
+    id: number;
+    slice: ToolpathIR;
+    /** Total segments emitted across all partials so far (= end of this delta). */
+    cumulativeSegments: number;
+}
+export type WorkerResponse = ProgressMessage | PartialMessage | DoneMessage | ErrorMessage | CancelledMessage;
+/** Collect every ArrayBuffer backing an IR's typed arrays for zero-copy transfer. */
+export declare function irTransferList(ir: ToolpathIR): ArrayBuffer[];
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

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

package/dist/protocol.js

@@ -0,0 +1,29 @@
+export const PROTOCOL_VERSION = 1;
+/** §5.4 provisional progressive-preview threshold (ratified by #61). */
+export const PARTIAL_PREVIEW_MIN_BYTES = 25 * 1024 * 1024;
+/** Collect every ArrayBuffer backing an IR's typed arrays for zero-copy transfer. */
+export function irTransferList(ir) {
+    const s = ir.segments;
+    const buffers = new Set();
+    for (const view of [
+        s.x0,
+        s.y0,
+        s.z0,
+        s.x1,
+        s.y1,
+        s.z1,
+        s.e,
+        s.feedrate,
+        s.kind,
+        s.tool,
+        s.layer,
+        s.feature,
+        s.object,
+        s.srcByte,
+        ir.sourceIndex.byteOffsets,
+        ir.sourceIndex.segmentIndices
+    ]) {
+        buffers.add(view.buffer);
+    }
+    return [...buffers];
+}

package/dist/session.d.ts

@@ -0,0 +1,73 @@
+/**
+ * GcodeParseSession — the worker client (DD-003 §4.1/§4.4/§5, issue #45).
+ *
+ * Terminal contract (§4.3): `done` RESOLVES `parse()` (including limit-bounded
+ * results — check `result.ir.header.complete` / `result.stats.stopReason`);
+ * `error` REJECTS with ParseSessionError; `cancelled` REJECTS with
+ * CancelledError (optional bounded partial attached when `partialOnCancel`).
+ *
+ * Cancellation (§5.2): cooperative via the worker's yield loop. If the worker
+ * fails to acknowledge within TERMINATE_FALLBACK_MS the session terminates it —
+ * strictly a last-resort backstop, asserted against in tests.
+ */
+import type { ParseResult } from './parse.js';
+import type { ToolpathIR } from '@chestnutlabs/toolpath-core';
+import { type ParseInputWire, type WireParseOptions } from './protocol.js';
+export interface WorkerLike {
+    /** Transfer list may carry ArrayBuffers and (in browsers) transferable streams. */
+    postMessage(msg: unknown, transfer?: unknown[]): void;
+    terminate(): void;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((err: unknown) => void) | null;
+}
+export interface SessionOptions {
+    /** Escape hatch (DD-003 §4.4 option c): supply a Worker instance or factory. */
+    worker?: WorkerLike | (() => WorkerLike);
+    /** Cancel-acknowledgement backstop before terminate() (default 2000 ms). */
+    terminateFallbackMs?: number;
+}
+export interface ParseProgress {
+    bytesProcessed: number;
+    totalBytes: number;
+    phase: 'parsing' | 'finalizing';
+}
+export declare class ParseSessionError extends Error {
+    readonly code: string;
+    readonly srcByte?: number | undefined;
+    constructor(code: string, message: string, srcByte?: number | undefined);
+}
+export declare class CancelledError extends ParseSessionError {
+    readonly partial?: ParseResult | undefined;
+    /** True only when the terminate() backstop fired (cooperative path failed). */
+    readonly terminated: boolean;
+    constructor(message: string, partial?: ParseResult | undefined, 
+    /** True only when the terminate() backstop fired (cooperative path failed). */
+    terminated?: boolean);
+}
+export declare class GcodeParseSession {
+    private readonly factory;
+    private readonly terminateFallbackMs;
+    private worker;
+    private active;
+    private nextId;
+    private progressListeners;
+    private partialListeners;
+    constructor(opts?: SessionOptions);
+    onProgress(cb: (p: ParseProgress) => void): () => void;
+    /**
+     * Progressive-preview deltas (#60): path-aligned IR slices streamed while a
+     * large parse runs (`partialPreview` wire option; on by default ≥ 25 MiB).
+     * The resolved `done` IR REPLACES everything the partials showed.
+     */
+    onPartial(cb: (slice: ToolpathIR, cumulativeSegments: number) => void): () => void;
+    parse(input: ParseInputWire, opts?: WireParseOptions): Promise<ParseResult>;
+    cancel(): void;
+    dispose(): void;
+    private ensureWorker;
+    private teardownWorker;
+    private settle;
+    private onMessage;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAoB,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAuB,MAAM,eAAe,CAAC;AAElH,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACtD,SAAS,IAAI,IAAI,CAAC;IAClB,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,MAAM,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,CAAC;IACzC,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC;CACjC;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,IAAI,EAAE,MAAM;aAEZ,OAAO,CAAC,EAAE,MAAM;gBAFhB,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC;AAED,qBAAa,cAAe,SAAQ,iBAAiB;aAGjC,OAAO,CAAC,EAAE,WAAW;IACrC,+EAA+E;aAC/D,UAAU;gBAH1B,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,WAAW,YAAA;IACrC,+EAA+E;IAC/D,UAAU,UAAQ;CAKrC;AAeD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,gBAAgB,CAAsE;gBAElF,IAAI,GAAE,cAAmB;IAOrC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAKtD;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlF,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAiB/E,MAAM,IAAI,IAAI;IAed,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,YAAY;IAuBpB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,SAAS;CAmClB"}

package/dist/session.js

@@ -0,0 +1,156 @@
+import { isReadableStreamLike } from './streaming.js';
+import { PROTOCOL_VERSION } from './protocol.js';
+export class ParseSessionError extends Error {
+    code;
+    srcByte;
+    constructor(code, message, srcByte) {
+        super(message);
+        this.code = code;
+        this.srcByte = srcByte;
+        this.name = 'ParseSessionError';
+    }
+}
+export class CancelledError extends ParseSessionError {
+    partial;
+    terminated;
+    constructor(message, partial, 
+    /** True only when the terminate() backstop fired (cooperative path failed). */
+    terminated = false) {
+        super('E_CANCELLED', message);
+        this.partial = partial;
+        this.terminated = terminated;
+        this.name = 'CancelledError';
+    }
+}
+/** Default worker path (DD-003 §4.4 option a): bundler-native module worker. */
+function defaultWorkerFactory() {
+    return new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
+}
+export class GcodeParseSession {
+    factory;
+    terminateFallbackMs;
+    worker = null;
+    active = null;
+    nextId = 1;
+    progressListeners = new Set();
+    partialListeners = new Set();
+    constructor(opts = {}) {
+        const supplied = opts.worker;
+        this.factory =
+            supplied === undefined ? defaultWorkerFactory : typeof supplied === 'function' ? supplied : () => supplied;
+        this.terminateFallbackMs = opts.terminateFallbackMs ?? 2000;
+    }
+    onProgress(cb) {
+        this.progressListeners.add(cb);
+        return () => this.progressListeners.delete(cb);
+    }
+    /**
+     * Progressive-preview deltas (#60): path-aligned IR slices streamed while a
+     * large parse runs (`partialPreview` wire option; on by default ≥ 25 MiB).
+     * The resolved `done` IR REPLACES everything the partials showed.
+     */
+    onPartial(cb) {
+        this.partialListeners.add(cb);
+        return () => this.partialListeners.delete(cb);
+    }
+    parse(input, opts = {}) {
+        if (this.active !== null) {
+            return Promise.reject(new ParseSessionError('E_BUSY', 'a parse is already in progress on this session'));
+        }
+        const worker = this.ensureWorker();
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.active = { id, resolve, reject, partialOnCancel: opts.partialOnCancel === true };
+            // §4.2 wire strategy: Uint8Array transfers its buffer (zero-copy); a
+            // ReadableStream is transferred; a Blob is a cheap cloneable handle.
+            let transfer;
+            if (input instanceof Uint8Array)
+                transfer = [input.buffer];
+            else if (isReadableStreamLike(input) && typeof input !== 'string')
+                transfer = [input];
+            worker.postMessage({ v: PROTOCOL_VERSION, type: 'parse', id, input, opts }, transfer);
+        });
+    }
+    cancel() {
+        const active = this.active;
+        if (active === null || this.worker === null)
+            return;
+        this.worker.postMessage({ v: PROTOCOL_VERSION, type: 'cancel', id: active.id });
+        active.cancelTimer = setTimeout(() => {
+            // Last-resort backstop (§5.2): the cooperative path failed to acknowledge.
+            this.teardownWorker();
+            this.settle(active, undefined, new CancelledError('cancelled (worker terminated after timeout)', undefined, true));
+        }, this.terminateFallbackMs);
+    }
+    dispose() {
+        const active = this.active;
+        if (active !== null) {
+            this.settle(active, undefined, new ParseSessionError('E_DISPOSED', 'session disposed'));
+        }
+        this.teardownWorker();
+        this.progressListeners.clear();
+        this.partialListeners.clear();
+    }
+    ensureWorker() {
+        if (this.worker === null) {
+            const w = this.factory();
+            w.onmessage = (ev) => this.onMessage(ev.data);
+            w.onerror = (err) => {
+                const active = this.active;
+                this.teardownWorker();
+                if (active !== null) {
+                    this.settle(active, undefined, new ParseSessionError('E_WORKER_CRASHED', `worker crashed: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            };
+            this.worker = w;
+        }
+        return this.worker;
+    }
+    teardownWorker() {
+        if (this.worker !== null) {
+            this.worker.onmessage = null;
+            this.worker.onerror = null;
+            this.worker.terminate();
+            this.worker = null;
+        }
+    }
+    settle(active, result, error) {
+        if (active.cancelTimer !== undefined)
+            clearTimeout(active.cancelTimer);
+        if (this.active === active)
+            this.active = null;
+        if (error !== undefined)
+            active.reject(error);
+        else if (result !== undefined)
+            active.resolve(result);
+    }
+    onMessage(msg) {
+        const active = this.active;
+        if (active === null || msg.id !== active.id) {
+            if (msg.type === 'progress')
+                return; // stale progress after settle — ignore
+            return;
+        }
+        switch (msg.type) {
+            case 'progress':
+                for (const cb of this.progressListeners) {
+                    cb({ bytesProcessed: msg.bytesProcessed, totalBytes: msg.totalBytes, phase: msg.phase });
+                }
+                return;
+            case 'partial':
+                for (const cb of this.partialListeners) {
+                    cb(msg.slice, msg.cumulativeSegments);
+                }
+                return;
+            case 'done':
+                this.settle(active, { ir: msg.ir, stats: msg.stats, metadata: msg.metadata });
+                return;
+            case 'cancelled':
+                this.settle(active, undefined, new CancelledError('parse cancelled', msg.partial ? { ir: msg.partial.ir, stats: msg.partial.stats } : undefined));
+                return;
+            case 'error':
+                this.settle(active, undefined, new ParseSessionError(msg.error.code, msg.error.message, msg.error.srcByte));
+                return;
+        }
+    }
+}

package/dist/streaming.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Streaming inputs (DD-003 §4.2, phase 3, issue #46).
+ *
+ * Worker-side line-drain streaming: bytes → TextDecoder{stream:true} → a rolling
+ * buffer bounded by `maxLineLength` → complete lines fed to the shared engine.
+ * Yields happen naturally at every chunk `read()` plus the same §5.2 time-slice
+ * yield between lines of a large chunk, so cancellation stays cooperative.
+ *
+ * Limits on unknown-size streams are enforced INCREMENTALLY: `maxInputBytes` is
+ * checked as bytes arrive (a `Blob`'s known size is still checked upfront), and an
+ * overlong line cannot grow the rolling buffer beyond `maxLineLength` — the
+ * remainder of the line is discarded with a `line-too-long` warning, exactly like
+ * the in-memory path, so hostile input cannot balloon memory.
+ *
+ * Byte offsets use the same single-byte (ASCII/UTF-8) accounting as the in-memory
+ * drivers so stream and sync parses of the same file produce identical IR.
+ */
+import { type AsyncParseHooks, type AsyncParseResult, type ParseOptions } from './parse.js';
+/** Anything that can hand us chunks of bytes. */
+export type StreamInput = BlobLike | ReadableStreamLike<Uint8Array>;
+export interface BlobLike {
+    readonly size: number;
+    stream(): ReadableStreamLike<Uint8Array>;
+}
+export interface ReadableStreamLike<T> {
+    getReader(): {
+        read(): Promise<{
+            done: boolean;
+            value?: T;
+        }>;
+        releaseLock?(): void;
+        cancel?(): Promise<void>;
+    };
+}
+export declare function isBlobLike(v: unknown): v is BlobLike;
+export declare function isReadableStreamLike(v: unknown): v is ReadableStreamLike<Uint8Array>;
+/**
+ * Parse a byte stream into a ToolpathIR with the same semantics (and identical
+ * output) as the in-memory drivers. Cooperative and cancellable throughout.
+ */
+export declare function parseGcodeStreamToIR(input: StreamInput, opts?: ParseOptions, hooks?: AsyncParseHooks): Promise<AsyncParseResult>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,iDAAiD;AACjD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;AAEpE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,IAAI,kBAAkB,CAAC,UAAU,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,SAAS,IAAI;QAAE,IAAI,IAAI,OAAO,CAAC;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,CAAC,CAAA;SAAE,CAAC,CAAC;QAAC,WAAW,CAAC,IAAI,IAAI,CAAC;QAAC,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAChH;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,QAAQ,CAOpD;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,kBAAkB,CAAC,UAAU,CAAC,CAEpF;AAcD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE,YAAiB,EACvB,KAAK,GAAE,eAAoB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CA4H3B"}

package/dist/streaming.js

@@ -0,0 +1,162 @@
+/**
+ * Streaming inputs (DD-003 §4.2, phase 3, issue #46).
+ *
+ * Worker-side line-drain streaming: bytes → TextDecoder{stream:true} → a rolling
+ * buffer bounded by `maxLineLength` → complete lines fed to the shared engine.
+ * Yields happen naturally at every chunk `read()` plus the same §5.2 time-slice
+ * yield between lines of a large chunk, so cancellation stays cooperative.
+ *
+ * Limits on unknown-size streams are enforced INCREMENTALLY: `maxInputBytes` is
+ * checked as bytes arrive (a `Blob`'s known size is still checked upfront), and an
+ * overlong line cannot grow the rolling buffer beyond `maxLineLength` — the
+ * remainder of the line is discarded with a `line-too-long` warning, exactly like
+ * the in-memory path, so hostile input cannot balloon memory.
+ *
+ * Byte offsets use the same single-byte (ASCII/UTF-8) accounting as the in-memory
+ * drivers so stream and sync parses of the same file produce identical IR.
+ */
+import { createEngine, makePartialEmitter } from './parse.js';
+export function isBlobLike(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        typeof v.stream === 'function' &&
+        typeof v.size === 'number');
+}
+export function isReadableStreamLike(v) {
+    return typeof v === 'object' && v !== null && typeof v.getReader === 'function';
+}
+function yieldMacrotask() {
+    return new Promise((resolve) => {
+        const ch = new MessageChannel();
+        ch.port1.onmessage = () => {
+            ch.port1.close();
+            ch.port2.close();
+            resolve();
+        };
+        ch.port2.postMessage(null);
+    });
+}
+/**
+ * Parse a byte stream into a ToolpathIR with the same semantics (and identical
+ * output) as the in-memory drivers. Cooperative and cancellable throughout.
+ */
+export async function parseGcodeStreamToIR(input, opts = {}, hooks = {}) {
+    const engine = createEngine('', opts);
+    const limits = engine.limits;
+    const yieldEvery = hooks.yieldIntervalMs ?? 50;
+    const knownSize = isBlobLike(input) ? input.size : undefined;
+    if (knownSize !== undefined && knownSize > limits.maxInputBytes) {
+        engine.setSourceBytes(knownSize);
+        engine.markInputTooBig();
+        return { ...engine.finish(), cancelled: false };
+    }
+    const stream = isBlobLike(input) ? input.stream() : input;
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let lineStartOffset = 0;
+    let bytesRead = 0;
+    /** True while discarding the remainder of a line that exceeded maxLineLength. */
+    let skippingOverlongLine = false;
+    let overlongWarned = false;
+    let cancelled = false;
+    let sliceStart = Date.now();
+    const partial = makePartialEmitter(engine, hooks);
+    const drainCompleteLines = async () => {
+        for (;;) {
+            const nl = buffer.indexOf('\n');
+            if (nl === -1)
+                return;
+            const line = buffer.slice(0, nl);
+            buffer = buffer.slice(nl + 1);
+            if (skippingOverlongLine) {
+                // The discarded prefix of this line already tripped the limit; count the
+                // full line (prefix included) into offsets and resume normal processing.
+                skippingOverlongLine = false;
+                overlongWarned = false;
+                lineStartOffset += line.length + 1;
+                continue;
+            }
+            engine.processLine(line, lineStartOffset);
+            lineStartOffset += line.length + 1;
+            if (engine.stopped())
+                return;
+            if (Date.now() - sliceStart >= yieldEvery) {
+                hooks.onProgress?.(bytesRead, knownSize ?? 0, 0);
+                partial(bytesRead);
+                await yieldMacrotask();
+                if (hooks.shouldCancel?.()) {
+                    cancelled = true;
+                    return;
+                }
+                sliceStart = Date.now();
+            }
+        }
+    };
+    const boundBuffer = () => {
+        if (buffer.length > limits.maxLineLength && buffer.indexOf('\n') === -1) {
+            if (!overlongWarned) {
+                // Route the warning through the engine by feeding an overlong marker line:
+                // processLine's own maxLineLength branch records `line-too-long` (bounded).
+                engine.processLine('x'.repeat(limits.maxLineLength + 1), lineStartOffset);
+                overlongWarned = true;
+            }
+            // Discard the buffered prefix but keep offset accounting for the final line cut.
+            lineStartOffset += buffer.length;
+            buffer = '';
+            skippingOverlongLine = true;
+        }
+    };
+    try {
+        for (;;) {
+            if (engine.stopped() || cancelled)
+                break;
+            const { done, value } = await reader.read();
+            if (hooks.shouldCancel?.()) {
+                cancelled = true;
+                break;
+            }
+            if (done)
+                break;
+            if (value === undefined || value.byteLength === 0)
+                continue;
+            bytesRead += value.byteLength;
+            engine.setSourceBytes(bytesRead);
+            if (bytesRead > limits.maxInputBytes) {
+                engine.markInputTooBig();
+                break;
+            }
+            const decoded = decoder.decode(value, { stream: true });
+            // §4.5 stream detection windows: bounded head + rolling tail capture.
+            const windows = hooks.captureWindows;
+            if (windows !== undefined) {
+                if (windows.head.length < 64 * 1024) {
+                    windows.head = (windows.head + decoded).slice(0, 64 * 1024);
+                }
+                windows.tail = (windows.tail + decoded).slice(-16 * 1024);
+            }
+            buffer += decoded;
+            boundBuffer();
+            await drainCompleteLines();
+        }
+        // Flush the decoder tail and any final unterminated line.
+        if (!engine.stopped() && !cancelled) {
+            buffer += decoder.decode();
+            boundBuffer();
+            await drainCompleteLines();
+            if (!engine.stopped() && !cancelled && !skippingOverlongLine && buffer.length > 0) {
+                engine.processLine(buffer, lineStartOffset);
+                buffer = '';
+            }
+        }
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+    hooks.onProgress?.(bytesRead, knownSize ?? bytesRead, 0);
+    engine.setSourceBytes(bytesRead);
+    if (cancelled) {
+        return { ...engine.finish(lineStartOffset), cancelled: true };
+    }
+    return { ...engine.finish(), cancelled: false };
+}

package/dist/worker-core.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Transport-agnostic worker handler (DD-003 §4.3/§5.2, issue #45).
+ *
+ * Contains the entire worker-side protocol logic without referencing any Worker
+ * global, so it is directly testable in Node: the host supplies `post` and feeds
+ * inbound messages to the returned handler. The Web Worker entry (`worker.ts`)
+ * is a two-line shim over this.
+ */
+import type { DialectMetadata, ToolpathIR, Warning } from '@chestnutlabs/toolpath-core';
+import { type CommandEvent } from './parse.js';
+import { type ReadableStreamLike } from './streaming.js';
+import { type WorkerRequest, type WorkerResponse } from './protocol.js';
+export type PostFn = (msg: WorkerResponse, transfer?: ArrayBuffer[]) => void;
+/**
+ * Structural mirror of @chestnutlabs/gcode-dialects' runner factory (DD-005
+ * §4.5): the parser never imports the dialects package — worker ENTRIES
+ * compose the two (`worker.ts` batteries-included, `worker-slim.ts` none,
+ * custom workers their own set).
+ */
+export interface DialectRunLike {
+    onComment: (text: string, srcByte: number) => void;
+    onCommand: (event: CommandEvent) => void;
+    finalize(ir: ToolpathIR): {
+        metadata?: DialectMetadata;
+        warnings: Warning[];
+    };
+}
+export interface DialectRunnerFactoryLike {
+    adapterIds: string[];
+    createRun(input: {
+        selection: 'auto' | string[];
+        config?: Record<string, unknown>;
+        headText: string;
+        tailText: string;
+        containerMeta?: Record<string, string>;
+    }): DialectRunLike | null;
+}
+/** Structural mirror of gcode-containers' adapter (DD-005 §4.4) — same composition rule as dialects. */
+export interface OpenedContainerLike {
+    id: string;
+    plates: {
+        index: number;
+        name: string;
+        estimatedBytes: number;
+    }[];
+    metadata: {
+        machine?: import('@chestnutlabs/toolpath-core').MachineGeometry;
+        filaments?: import('@chestnutlabs/toolpath-core').FilamentInfo[];
+        raw: Record<string, string>;
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
+    openPlate(index: number): ReadableStreamLike<Uint8Array>;
+}
+export interface ContainerAdapterLike {
+    id: string;
+    sniff(prefix: Uint8Array): boolean;
+    open(bytes: Uint8Array): Promise<OpenedContainerLike>;
+}
+export interface WorkerHandlerOptions {
+    /** Dialect runner composed by the worker entry (absent in worker-slim). */
+    dialects?: DialectRunnerFactoryLike;
+    /** Container adapters composed by the worker entry (absent in worker-slim). */
+    containers?: ContainerAdapterLike[];
+}
+export declare function createWorkerHandler(post: PostFn, handlerOpts?: WorkerHandlerOptions): (msg: WorkerRequest) => void;
+//# sourceMappingURL=worker-core.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker-core.d.ts","sourceRoot":"","sources":["../src/worker-core.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,YAAY,CAAC;AACpB,OAAO,EAA0D,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACjH,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,EAAE,EAAE,UAAU,GAAG;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,KAAK,EAAE;QACf,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACxC,GAAG,cAAc,GAAG,IAAI,CAAC;CAC3B;AAED,wGAAwG;AACxG,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClE,QAAQ,EAAE;QACR,OAAO,CAAC,EAAE,OAAO,6BAA6B,EAAE,eAAe,CAAC;QAChE,SAAS,CAAC,EAAE,OAAO,6BAA6B,EAAE,YAAY,EAAE,CAAC;QACjE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAC/C,CAAC;IACF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC;AA+CD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,oBAAyB,GACrC,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAgS9B"}