@chestnutlabs/gcode-bgcode 0.3.0

package/README.md

@@ -0,0 +1,51 @@
+# @chestnutlabs/gcode-bgcode
+
+Binary G-code (`.bgcode`) **decode** for the Chestnut Labs G-code toolpath stack (DD-011, epic #188).
+
+Prusa's `.bgcode` is a *container* of ordinary G-code, not a new toolpath language. This package walks
+the binary block structure, verifies per-block CRC32, decompresses, decodes, and concatenates the GCode
+blocks into **plain G-code** — which the existing parser / dialect / IR / renderer / progress pipeline
+consumes unchanged. **Decode-only** (it never writes `.bgcode`), **in-memory only** (no filesystem, no
+network), zero runtime dependencies beyond `@chestnutlabs/toolpath-core` and
+`@chestnutlabs/gcode-containers`.
+
+## Licensing (why this is a clean-room decoder)
+
+The reference `libbgcode` and OctoPrint-MeatPack are **AGPL-3.0**; none of their code is used here — the
+block walker is written clean-room from the published format spec ([RR-003](https://github.com/ChestnutLabs/gcode-preview/blob/dev/docs/research/RR-003-bgcode-licensing-and-format-audit.md)).
+The **MeatPack** decoder is a faithful port of the **MIT** [`jamesgopsill/meatpack`](https://github.com/jamesgopsill/meatpack)
+(© 2025 James Gopsill), and the **heatshrink** decoder is a port of the **ISC**
+[`atomicobject/heatshrink`](https://github.com/atomicobject/heatshrink) (© 2013–2015 Scott Vokes) —
+both attributions preserved in their source files. This package is MIT.
+
+## Status — phased (DD-011 §14)
+
+| Capability | Status |
+|---|---|
+| Block walker + CRC32 + `sniff`/`open` | ✅ phase 1 |
+| Compression: None, DEFLATE | ✅ phase 1 |
+| Encoding: None | ✅ phase 1 |
+| Encoding: MeatPack (both variants) | ✅ phase 2 |
+| Compression: heatshrink 11/12 | ✅ phase 3 |
+| DEFLATE zlib-flavor fix + golden-equivalence killer test (real Prusa files) | ✅ phase 4 |
+| Container adapter + batteries-worker registration + metadata/thumbnail surfacing | ✅ phase 4c |
+| Adversarial fuzz corpus + §7 security review + decode benchmark | ✅ phase 5 |
+
+## Usage
+
+```ts
+import { openBgcode, sniffBgcode } from '@chestnutlabs/gcode-bgcode';
+
+if (sniffBgcode(firstBytes, name)) {
+  const { gcode, blocks, checksum } = await openBgcode(bytes, { metadata: true });
+  // `gcode` is plain G-code (Uint8Array) → feed the existing parser.
+}
+```
+
+It also registers as a **container adapter** in the batteries parser worker, so a `.bgcode` file "just
+works" through `GcodeParseSession` (`containers: 'auto'`) — decoded to G-code, with the machine geometry
+(`bed_shape`) and whitelisted slicer settings surfaced as container metadata. Thumbnails are decoded and
+available on `openBgcodeContainer(bytes).thumbnails`.
+
+Every failure — bad magic/version, CRC mismatch, truncation, unknown/unsupported codec, or a
+decompression bomb — is a structured, bounded `ContainerError` (never a crash or an unbounded read).

package/dist/adapter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `.bgcode` container adapter (DD-011 phase 4c, #188) — plugs `.bgcode` into the existing parser
+ * pipeline via the DD-005 §4.4 container-adapter contract (`{ id, sniff, open }`), beside `.gcode.3mf`.
+ * The worker sniffs the input, calls `open`, and parses the single decoded plate; the metadata
+ * (machine geometry + whitelisted settings) rides beside the IR.
+ *
+ * `.bgcode` is single-payload — one plate, no `openPlate` index beyond 0.
+ */
+import type { MachineGeometry } from '@chestnutlabs/toolpath-core';
+import { sniffBgcode, type BgcodeThumbnail } from './bgcode.js';
+/** Minimal readable-stream mirror the parser worker consumes (same shape as gcode-containers). */
+export interface BgcodeStreamLike {
+    getReader(): {
+        read(): Promise<{
+            done: boolean;
+            value?: Uint8Array;
+        }>;
+        releaseLock?(): void;
+    };
+}
+export interface OpenedBgcode {
+    id: 'bgcode';
+    plates: {
+        index: number;
+        name: string;
+        estimatedBytes: number;
+    }[];
+    metadata: {
+        machine?: MachineGeometry;
+        raw: Record<string, string>;
+        warnings: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /** Thumbnails from the container (bgcode carries them as binary blocks, not G-code comments). */
+    thumbnails: BgcodeThumbnail[];
+    openPlate(index: number): BgcodeStreamLike;
+}
+/**
+ * Open a `.bgcode` buffer as a container: decode it to plain G-code (the single plate) and surface its
+ * metadata + thumbnails. Errors are the structured `ContainerError`s from {@link openBgcode}.
+ */
+export declare function openBgcodeContainer(bytes: Uint8Array): Promise<OpenedBgcode>;
+/** Re-export the sniff so a worker entry can register `{ id, sniff, open }` in one import. */
+export { sniffBgcode };
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,eAAe,EAAU,MAAM,6BAA6B,CAAC;AAC3E,OAAO,EAAc,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE5E,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,SAAS,IAAI;QAAE,IAAI,IAAI,OAAO,CAAC;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC;QAAC,WAAW,CAAC,IAAI,IAAI,CAAA;KAAE,CAAC;CAC/F;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,QAAQ,CAAC;IACb,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,eAAe,CAAC;QAC1B,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,iGAAiG;IACjG,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC;CAC5C;AA+DD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CAclF;AAED,8FAA8F;AAC9F,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/adapter.js

@@ -0,0 +1,84 @@
+import { openBgcode, sniffBgcode } from './bgcode.js';
+/** Settings keys copied into `metadata.raw` — a whitelist (feeds dialect detection + provenance), never the whole 390-key config. */
+const RAW_WHITELIST = [
+    'Producer',
+    'printer_model',
+    'printer_settings_id',
+    'print_settings_id',
+    'bed_shape',
+    'max_print_height',
+    'printable_height',
+    'nozzle_diameter',
+    'filament_type',
+    'filament_colour'
+];
+/** Parse a PrusaSlicer `bed_shape` ("0x0,360x0,360x360,0x360") into points. */
+function parseBedShape(value) {
+    const parts = value.split(',');
+    if (parts.length < 3 || parts.length > 64)
+        return null;
+    const points = [];
+    for (const p of parts) {
+        const m = /^\s*(-?\d+(?:\.\d+)?)x(-?\d+(?:\.\d+)?)\s*$/.exec(p);
+        if (m === null)
+            return null;
+        points.push({ x: parseFloat(m[1]), y: parseFloat(m[2]) });
+    }
+    return points;
+}
+/** Build a MachineGeometry from the decoded `.bgcode` settings (bed_shape + max_print_height + model). */
+function machineFrom(settings) {
+    const points = settings.bed_shape ? parseBedShape(settings.bed_shape) : null;
+    if (points === null)
+        return undefined;
+    const xs = points.map((p) => p.x);
+    const ys = points.map((p) => p.y);
+    const min = { x: Math.min(...xs), y: Math.min(...ys) };
+    const max = { x: Math.max(...xs), y: Math.max(...ys) };
+    const rect = points.length === 4 && points.every((p) => (p.x === min.x || p.x === max.x) && (p.y === min.y || p.y === max.y));
+    const h = parseFloat(settings.max_print_height ?? settings.printable_height ?? '');
+    return {
+        bed: rect ? { kind: 'rect', min, max } : { kind: 'polygon', points },
+        origin: { x: 0, y: 0 },
+        heightMm: Number.isFinite(h) ? h : undefined,
+        printerName: settings.printer_model,
+        confidence: 'inferred', // read from the slicer's embedded settings, not machine config
+        source: { adapterId: 'bgcode', evidence: 'bgcode metadata (bed_shape)' }
+    };
+}
+/** A one-shot stream over an in-memory buffer. */
+function streamOf(bytes) {
+    return {
+        getReader() {
+            let done = false;
+            return {
+                read: () => Promise.resolve(done ? { done: true } : ((done = true), { done: false, value: bytes })),
+                releaseLock() { }
+            };
+        }
+    };
+}
+/**
+ * Open a `.bgcode` buffer as a container: decode it to plain G-code (the single plate) and surface its
+ * metadata + thumbnails. Errors are the structured `ContainerError`s from {@link openBgcode}.
+ */
+export async function openBgcodeContainer(bytes) {
+    const { gcode, settings, thumbnails } = await openBgcode(bytes, { metadata: true });
+    const raw = {};
+    for (const key of RAW_WHITELIST)
+        if (settings[key] !== undefined)
+            raw[key] = settings[key];
+    return {
+        id: 'bgcode',
+        plates: [{ index: 0, name: 'bgcode', estimatedBytes: gcode.length }],
+        metadata: { machine: machineFrom(settings), raw, warnings: [] },
+        thumbnails,
+        openPlate(index) {
+            if (index !== 0)
+                throw new Error(`.bgcode has a single plate; requested ${index}`);
+            return streamOf(gcode);
+        }
+    };
+}
+/** Re-export the sniff so a worker entry can register `{ id, sniff, open }` in one import. */
+export { sniffBgcode };

package/dist/bgcode.d.ts

@@ -0,0 +1,74 @@
+/** ASCII magic at the start of every `.bgcode` file: "GCDE". */
+export declare const BGCODE_MAGIC = "GCDE";
+/** The only file format version this decoder accepts (DD-011 pins v1). */
+export declare const BGCODE_VERSION = 1;
+/** Block type IDs (spec §5.2). */
+export declare const BgcodeBlockType: {
+    readonly FileMetadata: 0;
+    readonly GCode: 1;
+    readonly SlicerMetadata: 2;
+    readonly PrinterMetadata: 3;
+    readonly PrintMetadata: 4;
+    readonly Thumbnail: 5;
+};
+/** Compression algorithm IDs (spec §5.2). */
+export declare const BgcodeCompression: {
+    readonly None: 0;
+    readonly Deflate: 1;
+    readonly Heatshrink11: 2;
+    readonly Heatshrink12: 3;
+};
+/** GCode-block encoding IDs (spec §5.2). */
+export declare const BgcodeEncoding: {
+    readonly None: 0;
+    readonly MeatPack: 1;
+    readonly MeatPackComments: 2;
+};
+/** Metadata read off a walked block header (no payload for non-GCode blocks in phase 1). */
+export interface BgcodeBlockInfo {
+    type: number;
+    compression: number;
+    /** GCode/metadata encoding param; 0 for thumbnails. */
+    encoding: number;
+    uncompressedSize: number;
+    compressedSize: number;
+}
+/** A thumbnail decoded from a `.bgcode` Thumbnail block (#188 phase 4c). */
+export interface BgcodeThumbnail {
+    format: 'png' | 'jpg' | 'qoi' | 'unknown';
+    width: number;
+    height: number;
+    bytes: Uint8Array;
+}
+export interface BgcodeDecodeResult {
+    /** The decoded plain G-code (all GCode blocks concatenated in file order). */
+    gcode: Uint8Array;
+    /** Every block walked, in file order (for diagnostics / phase-4 metadata). */
+    blocks: BgcodeBlockInfo[];
+    /** Whether the file declared per-block CRC32. */
+    checksum: 'none' | 'crc32';
+    /**
+     * Merged INI key/values from the File/Printer/Print/Slicer metadata blocks (#188 phase 4c) — only
+     * populated when `metadata: true`. Later blocks win on key conflicts. Empty otherwise.
+     */
+    settings: Record<string, string>;
+    /** Thumbnails from Thumbnail blocks (#188 phase 4c) — only when `metadata: true`. */
+    thumbnails: BgcodeThumbnail[];
+}
+export interface BgcodeDecodeOptions {
+    /** Hard cap on total decoded G-code bytes — decompression-bomb defense (default 512 MiB). */
+    maxOutputBytes?: number;
+    /** Also decode the metadata (INI) + thumbnail blocks into `settings`/`thumbnails` (default false). */
+    metadata?: boolean;
+}
+/** True if `prefix`/`name` look like a `.bgcode` file (magic "GCDE", or a `.bgcode` name). */
+export declare function sniffBgcode(prefix: Uint8Array, name?: string): boolean;
+/**
+ * Decode a `.bgcode` v1 buffer to plain G-code. Walks every block, verifies per-block CRC32 (when the
+ * file declares it), decompresses + decodes the GCode blocks, and concatenates them in file order.
+ * Non-GCode blocks are walked past (their metadata/thumbnails are surfaced in phase 4). Every failure
+ * is a structured, bounded `ContainerError` (from `@chestnutlabs/gcode-containers`) — never a crash or
+ * an unbounded read/allocation.
+ */
+export declare function openBgcode(bytes: Uint8Array, opts?: BgcodeDecodeOptions): Promise<BgcodeDecodeResult>;
+//# sourceMappingURL=bgcode.d.ts.map

package/dist/bgcode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bgcode.d.ts","sourceRoot":"","sources":["../src/bgcode.ts"],"names":[],"mappings":"AAkBA,gEAAgE;AAChE,eAAO,MAAM,YAAY,SAAS,CAAC;AACnC,0EAA0E;AAC1E,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,kCAAkC;AAClC,eAAO,MAAM,eAAe;;;;;;;CAOlB,CAAC;AAEX,6CAA6C;AAC7C,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,4CAA4C;AAC5C,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,KAAK,EAAE,UAAU,CAAC;IAClB,8EAA8E;IAC9E,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qFAAqF;IACrF,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,6FAA6F;IAC7F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sGAAsG;IACtG,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0BD,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAStE;AA0FD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4F/G"}

package/dist/bgcode.js

@@ -0,0 +1,261 @@
+/**
+ * Binary G-code (`.bgcode`) decoder — spec **version 1** (DD-011; format audited in RR-003).
+ *
+ * Clean-room from the published Prusa block-format spec — NO code is derived from the AGPL
+ * `libbgcode` reference or the AGPL OctoPrint-MeatPack (RR-003 §6). In-memory only, no fs/net.
+ *
+ * `.bgcode` is a *container* of ordinary G-code: this walks the block structure, verifies per-block
+ * CRC32, decompresses, decodes, and concatenates the GCode blocks into a plain-G-code buffer the
+ * existing parser consumes unchanged. **Decode-only** — never writes `.bgcode`.
+ *
+ * Phase 1 (this file) implements the walker + CRC + **None/DEFLATE** compression and **None**
+ * encoding. MeatPack (encoding) and heatshrink (compression) are honest, structured "not yet
+ * supported" errors until phases 2 and 3.
+ */
+import { ContainerError, crc32, crc32Final } from '@chestnutlabs/gcode-containers';
+import { meatpackDecode } from './meatpack.js';
+import { heatshrinkDecode } from './heatshrink.js';
+/** ASCII magic at the start of every `.bgcode` file: "GCDE". */
+export const BGCODE_MAGIC = 'GCDE';
+/** The only file format version this decoder accepts (DD-011 pins v1). */
+export const BGCODE_VERSION = 1;
+/** Block type IDs (spec §5.2). */
+export const BgcodeBlockType = {
+    FileMetadata: 0,
+    GCode: 1,
+    SlicerMetadata: 2,
+    PrinterMetadata: 3,
+    PrintMetadata: 4,
+    Thumbnail: 5
+};
+/** Compression algorithm IDs (spec §5.2). */
+export const BgcodeCompression = {
+    None: 0,
+    Deflate: 1,
+    Heatshrink11: 2, // window 11, lookahead 4
+    Heatshrink12: 3 // window 12, lookahead 4
+};
+/** GCode-block encoding IDs (spec §5.2). */
+export const BgcodeEncoding = {
+    None: 0,
+    MeatPack: 1,
+    MeatPackComments: 2
+};
+const THUMB_FORMAT = { 0: 'png', 1: 'jpg', 2: 'qoi' };
+/** Parse a PrusaSlicer-style INI block (`key = value` lines) into a record. */
+function parseIni(text) {
+    const out = {};
+    for (const line of text.split('\n')) {
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (key.length === 0 || key.startsWith(';') || key.startsWith('#') || key.startsWith('['))
+            continue;
+        out[key] = line.slice(eq + 1).trim();
+    }
+    return out;
+}
+const DEFAULT_MAX_OUTPUT = 512 * 1024 * 1024;
+function readU16(b, o) {
+    return b[o] | (b[o + 1] << 8);
+}
+function readU32(b, o) {
+    return (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16) | (b[o + 3] << 24)) >>> 0;
+}
+/** True if `prefix`/`name` look like a `.bgcode` file (magic "GCDE", or a `.bgcode` name). */
+export function sniffBgcode(prefix, name) {
+    if (name !== undefined && /\.bgcode$/i.test(name))
+        return true;
+    return (prefix.length >= 4 &&
+        prefix[0] === 0x47 /* G */ &&
+        prefix[1] === 0x43 /* C */ &&
+        prefix[2] === 0x44 /* D */ &&
+        prefix[3] === 0x45 /* E */);
+}
+/** DEFLATE-decode `data` to at most `limit` bytes via the platform stream (bounded — bomb-safe). */
+async function inflate(data, expected, limit) {
+    // Flavor: zlib-wrapped DEFLATE. Confirmed against a real Prusa XL `.bgcode` (phase 4) — its
+    // DEFLATE metadata blocks decode with the zlib header, and fail as raw. (bgcode GCode blocks use
+    // heatshrink, not DEFLATE; only Slicer/Print metadata blocks are DEFLATE.)
+    const ds = new DecompressionStream('deflate');
+    const writer = ds.writable.getWriter();
+    const reader = ds.readable.getReader();
+    // The writer promise must never float unobserved: a corrupt stream errors BOTH ends, and an
+    // unawaited writer rejection crashes the process (the #131 fuzzer lesson from gcode-containers).
+    let writeError;
+    const writeAll = (async () => {
+        await writer.write(data);
+        await writer.close();
+    })().catch((e) => {
+        writeError = e;
+    });
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value !== undefined && value.byteLength > 0) {
+                total += value.byteLength;
+                if (total > expected || total > limit) {
+                    throw new ContainerError('E_BGCODE_BOMB', `deflate output exceeds the declared/limit size (${total})`);
+                }
+                chunks.push(value);
+            }
+        }
+        await writeAll;
+        if (writeError !== undefined)
+            throw writeError;
+    }
+    catch (err) {
+        await writeAll; // settled by construction; never rejects
+        if (err instanceof ContainerError)
+            throw err;
+        throw new ContainerError('E_BGCODE_INFLATE', `deflate failed: ${err instanceof Error ? err.message : err}`);
+    }
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const c of chunks) {
+        out.set(c, o);
+        o += c.byteLength;
+    }
+    return out;
+}
+/** Decompress one block's data by its compression ID, clamped to the declared/limit size. */
+async function decompress(compression, data, uncompressed, limit) {
+    if (compression === BgcodeCompression.None) {
+        if (data.length !== uncompressed) {
+            throw new ContainerError('E_BGCODE_SIZE', `stored block size disagreement (${data.length} vs ${uncompressed})`);
+        }
+        return data;
+    }
+    if (compression === BgcodeCompression.Deflate) {
+        const out = await inflate(data, uncompressed, limit);
+        if (out.length !== uncompressed) {
+            throw new ContainerError('E_BGCODE_SIZE', `deflate size disagreement (${out.length} vs ${uncompressed})`);
+        }
+        return out;
+    }
+    if (compression === BgcodeCompression.Heatshrink11 || compression === BgcodeCompression.Heatshrink12) {
+        const windowBits = compression === BgcodeCompression.Heatshrink11 ? 11 : 12;
+        const out = heatshrinkDecode(data, windowBits, 4, limit);
+        if (out.length !== uncompressed) {
+            throw new ContainerError('E_BGCODE_SIZE', `heatshrink size disagreement (${out.length} vs ${uncompressed})`);
+        }
+        return out;
+    }
+    throw new ContainerError('E_BGCODE_UNSUPPORTED_COMPRESSION', `unknown compression id ${compression}`);
+}
+/** Decode a GCode block's post-decompression bytes by its encoding ID, bounded to `limit` output bytes. */
+function decode(encoding, bytes, limit) {
+    if (encoding === BgcodeEncoding.None)
+        return bytes;
+    // Both MeatPack variants decode identically — comment stripping is an encoder choice (#188 phase 2).
+    if (encoding === BgcodeEncoding.MeatPack || encoding === BgcodeEncoding.MeatPackComments) {
+        return meatpackDecode(bytes, limit);
+    }
+    throw new ContainerError('E_BGCODE_UNSUPPORTED_ENCODING', `unknown gcode encoding id ${encoding}`);
+}
+/**
+ * Decode a `.bgcode` v1 buffer to plain G-code. Walks every block, verifies per-block CRC32 (when the
+ * file declares it), decompresses + decodes the GCode blocks, and concatenates them in file order.
+ * Non-GCode blocks are walked past (their metadata/thumbnails are surfaced in phase 4). Every failure
+ * is a structured, bounded `ContainerError` (from `@chestnutlabs/gcode-containers`) — never a crash or
+ * an unbounded read/allocation.
+ */
+export async function openBgcode(bytes, opts = {}) {
+    const limit = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT;
+    const len = bytes.length;
+    if (len < 10)
+        throw new ContainerError('E_BGCODE_TRUNCATED', 'file shorter than the 10-byte header');
+    if (!sniffBgcode(bytes))
+        throw new ContainerError('E_BGCODE_MAGIC', 'missing "GCDE" magic');
+    const version = readU32(bytes, 4);
+    if (version !== BGCODE_VERSION)
+        throw new ContainerError('E_BGCODE_VERSION', `unsupported file version ${version} (expected 1)`);
+    const checksumType = readU16(bytes, 8);
+    if (checksumType > 1)
+        throw new ContainerError('E_BGCODE_CHECKSUM', `unknown checksum type ${checksumType}`);
+    const hasCrc = checksumType === 1;
+    const wantMeta = opts.metadata === true;
+    const blocks = [];
+    const gcodeParts = [];
+    const settings = {};
+    const thumbnails = [];
+    let totalOut = 0;
+    let off = 10;
+    while (off < len) {
+        const blockStart = off;
+        if (off + 8 > len)
+            throw new ContainerError('E_BGCODE_TRUNCATED', 'truncated block header');
+        const type = readU16(bytes, off);
+        const compression = readU16(bytes, off + 2);
+        const uncompressedSize = readU32(bytes, off + 4);
+        off += 8;
+        let compressedSize = uncompressedSize;
+        if (compression !== BgcodeCompression.None) {
+            if (off + 4 > len)
+                throw new ContainerError('E_BGCODE_TRUNCATED', 'truncated block header (compressed size)');
+            compressedSize = readU32(bytes, off);
+            off += 4;
+        }
+        // Block parameters: 2 bytes (encoding u16) for metadata/GCode; 6 bytes (format+w+h) for thumbnails.
+        const isThumb = type === BgcodeBlockType.Thumbnail;
+        const paramLen = isThumb ? 6 : 2;
+        if (off + paramLen > len)
+            throw new ContainerError('E_BGCODE_TRUNCATED', 'truncated block parameters');
+        const encoding = isThumb ? 0 : readU16(bytes, off);
+        const thumbFormat = isThumb ? readU16(bytes, off) : 0;
+        const thumbWidth = isThumb ? readU16(bytes, off + 2) : 0;
+        const thumbHeight = isThumb ? readU16(bytes, off + 4) : 0;
+        off += paramLen;
+        const dataLen = compression === BgcodeCompression.None ? uncompressedSize : compressedSize;
+        if (off + dataLen > len)
+            throw new ContainerError('E_BGCODE_TRUNCATED', 'truncated block data');
+        const data = bytes.subarray(off, off + dataLen);
+        off += dataLen;
+        if (hasCrc) {
+            if (off + 4 > len)
+                throw new ContainerError('E_BGCODE_TRUNCATED', 'truncated block checksum');
+            const stored = readU32(bytes, off);
+            const calc = crc32Final(crc32(bytes.subarray(blockStart, off))); // over header + params + data
+            if (stored !== calc) {
+                throw new ContainerError('E_BGCODE_CRC', `block CRC32 mismatch at offset ${blockStart}`);
+            }
+            off += 4;
+        }
+        blocks.push({ type, compression, encoding, uncompressedSize, compressedSize });
+        if (type === BgcodeBlockType.GCode) {
+            const decompressed = await decompress(compression, data, uncompressedSize, limit - totalOut);
+            const decoded = decode(encoding, decompressed, limit - totalOut);
+            totalOut += decoded.length;
+            if (totalOut > limit)
+                throw new ContainerError('E_BGCODE_BOMB', `decoded G-code exceeds the output limit (${totalOut})`);
+            gcodeParts.push(decoded);
+        }
+        else if (wantMeta && isThumb) {
+            // Thumbnails are stored as image bytes (PrusaSlicer uses None compression); decompress if flagged.
+            const raw = await decompress(compression, data, uncompressedSize, limit);
+            thumbnails.push({
+                format: THUMB_FORMAT[thumbFormat] ?? 'unknown',
+                width: thumbWidth,
+                height: thumbHeight,
+                bytes: raw.slice()
+            });
+        }
+        else if (wantMeta && (type === 0 || type === 2 || type === 3 || type === 4)) {
+            // File/Printer/Print/Slicer metadata: an INI block (encoding 0), maybe DEFLATE-compressed.
+            const ini = await decompress(compression, data, uncompressedSize, limit);
+            Object.assign(settings, parseIni(new TextDecoder().decode(ini)));
+        }
+    }
+    const gcode = new Uint8Array(totalOut);
+    let o = 0;
+    for (const part of gcodeParts) {
+        gcode.set(part, o);
+        o += part.length;
+    }
+    return { gcode, blocks, checksum: hasCrc ? 'crc32' : 'none', settings, thumbnails };
+}

package/dist/heatshrink.d.ts

@@ -0,0 +1,3 @@
+/** Decode a heatshrink stream. `windowBits`/`lookaheadBits` come from the bgcode compression id. */
+export declare function heatshrinkDecode(data: Uint8Array, windowBits: number, lookaheadBits: number, limit: number): Uint8Array;
+//# sourceMappingURL=heatshrink.d.ts.map

package/dist/heatshrink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatshrink.d.ts","sourceRoot":"","sources":["../src/heatshrink.ts"],"names":[],"mappings":"AAeA,oGAAoG;AACpG,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,GACZ,UAAU,CAyDZ"}

package/dist/heatshrink.js

@@ -0,0 +1,77 @@
+/**
+ * heatshrink LZSS decoder (DD-011 phase 3, #188).
+ *
+ * A TypeScript port of the decoder from **atomicobject/heatshrink** (ISC, © 2013–2015 Scott Vokes —
+ * https://github.com/atomicobject/heatshrink). ISC is permissive and MIT-compatible; porting with the
+ * attribution preserved is the sanctioned path (RR-003 §8) — the AGPL `libbgcode` is never copied.
+ *
+ * Wire format (whole-buffer form of the reference's streaming state machine): a big-endian (MSB-first)
+ * bit stream of tokens. Each token starts with a tag bit — `1` = an 8-bit literal byte; `0` = a
+ * back-reference: `windowBits` of index then `lookaheadBits` of count (both stored as value−1). A
+ * back-reference copies `count+1` bytes from `index+1` bytes back in a circular window, re-emitting
+ * each into the window (so runs can reference themselves). bgcode uses window 11 or 12, lookahead 4.
+ */
+import { ContainerError } from '@chestnutlabs/gcode-containers';
+/** Decode a heatshrink stream. `windowBits`/`lookaheadBits` come from the bgcode compression id. */
+export function heatshrinkDecode(data, windowBits, lookaheadBits, limit) {
+    const windowSize = 1 << windowBits;
+    const mask = windowSize - 1;
+    const window = new Uint8Array(windowSize);
+    let head = 0; // write cursor into the circular window (monotonic; masked on access)
+    let out = new Uint8Array(Math.max(64, Math.min(limit, data.length * 4)));
+    let pos = 0;
+    const emit = (c) => {
+        if (pos >= limit)
+            throw new ContainerError('E_BGCODE_BOMB', `heatshrink output exceeds the limit (${pos})`);
+        if (pos >= out.length) {
+            const bigger = new Uint8Array(Math.min(limit, Math.max(out.length * 2, pos + 1)));
+            bigger.set(out.subarray(0, pos));
+            out = bigger;
+        }
+        out[pos++] = c;
+        window[head++ & mask] = c;
+    };
+    // MSB-first bit reader over `data`. Returns null when fewer than `count` bits remain (end of input).
+    let bytePos = 0;
+    let bitIndex = 0; // 0 means "load next byte"; otherwise a single-bit mask (0x80..0x01)
+    let currentByte = 0;
+    const getBits = (count) => {
+        let acc = 0;
+        for (let i = 0; i < count; i++) {
+            if (bitIndex === 0) {
+                if (bytePos >= data.length)
+                    return null;
+                currentByte = data[bytePos++];
+                bitIndex = 0x80;
+            }
+            acc = (acc << 1) | (currentByte & bitIndex ? 1 : 0);
+            bitIndex >>= 1;
+        }
+        return acc;
+    };
+    for (;;) {
+        const tag = getBits(1);
+        if (tag === null)
+            break; // end of input (trailing byte-padding can never form a full token)
+        if (tag === 1) {
+            const byte = getBits(8);
+            if (byte === null)
+                break;
+            emit(byte & 0xff);
+        }
+        else {
+            const index = getBits(windowBits);
+            if (index === null)
+                break;
+            const count = getBits(lookaheadBits);
+            if (count === null)
+                break;
+            const negOffset = index + 1;
+            const copyCount = count + 1;
+            for (let i = 0; i < copyCount; i++) {
+                emit(window[(head - negOffset) & mask]);
+            }
+        }
+    }
+    return out.subarray(0, pos);
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @chestnutlabs/gcode-bgcode — Binary G-code (`.bgcode`) decode adapter (DD-011, epic #188).
+ *
+ * A license-clean, in-memory decoder for Prusa's binary G-code container. `.bgcode` is a container
+ * of ordinary G-code, so decoding it (block walk → CRC verify → decompress → decode → concatenate)
+ * yields plain G-code the existing parser/dialect/IR/renderer stack consumes unchanged. **Decode-only.**
+ *
+ * Clean-room from the published spec (RR-003) — no AGPL `libbgcode`/MeatPack code. Depends only on
+ * `@chestnutlabs/toolpath-core` and `@chestnutlabs/gcode-containers` (for `crc32`/`ContainerError`);
+ * no `three`, framework, filesystem, or network.
+ *
+ * All spec codecs are decoded (None/DEFLATE/heatshrink × None/MeatPack), validated against real Prusa
+ * files (golden-equivalence). Phase 4c registers a **container adapter** so `.bgcode` flows through the
+ * parser pipeline via `containers: 'auto'`, surfacing machine geometry + settings + thumbnails.
+ */
+export { BGCODE_MAGIC, BGCODE_VERSION, BgcodeBlockType, BgcodeCompression, BgcodeEncoding, sniffBgcode, openBgcode } from './bgcode.js';
+export type { BgcodeBlockInfo, BgcodeDecodeResult, BgcodeDecodeOptions, BgcodeThumbnail } from './bgcode.js';
+export { meatpackDecode } from './meatpack.js';
+export { heatshrinkDecode } from './heatshrink.js';
+export { openBgcodeContainer } from './adapter.js';
+export type { OpenedBgcode, BgcodeStreamLike } from './adapter.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;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @chestnutlabs/gcode-bgcode — Binary G-code (`.bgcode`) decode adapter (DD-011, epic #188).
+ *
+ * A license-clean, in-memory decoder for Prusa's binary G-code container. `.bgcode` is a container
+ * of ordinary G-code, so decoding it (block walk → CRC verify → decompress → decode → concatenate)
+ * yields plain G-code the existing parser/dialect/IR/renderer stack consumes unchanged. **Decode-only.**
+ *
+ * Clean-room from the published spec (RR-003) — no AGPL `libbgcode`/MeatPack code. Depends only on
+ * `@chestnutlabs/toolpath-core` and `@chestnutlabs/gcode-containers` (for `crc32`/`ContainerError`);
+ * no `three`, framework, filesystem, or network.
+ *
+ * All spec codecs are decoded (None/DEFLATE/heatshrink × None/MeatPack), validated against real Prusa
+ * files (golden-equivalence). Phase 4c registers a **container adapter** so `.bgcode` flows through the
+ * parser pipeline via `containers: 'auto'`, surfacing machine geometry + settings + thumbnails.
+ */
+export { BGCODE_MAGIC, BGCODE_VERSION, BgcodeBlockType, BgcodeCompression, BgcodeEncoding, sniffBgcode, openBgcode } from './bgcode.js';
+export { meatpackDecode } from './meatpack.js';
+export { heatshrinkDecode } from './heatshrink.js';
+// Container-adapter integration (DD-005 §4.4, #188 phase 4c).
+export { openBgcodeContainer } from './adapter.js';

package/dist/meatpack.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Decode a MeatPack byte stream to plain G-code, bounded to `limit` output bytes (decompression-bomb
+ * defense). Both bgcode GCode encodings (MeatPack, MeatPack-comments) decode through this identically —
+ * comment preservation is an *encoder* choice; the decoder simply reproduces the packed bytes.
+ */
+export declare function meatpackDecode(data: Uint8Array, limit: number): Uint8Array;
+//# sourceMappingURL=meatpack.d.ts.map

package/dist/meatpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meatpack.d.ts","sourceRoot":"","sources":["../src/meatpack.ts"],"names":[],"mappings":"AAkDA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAgG1E"}

package/dist/meatpack.js

@@ -0,0 +1,154 @@
+/**
+ * MeatPack G-code decoder (DD-011 phase 2, #188).
+ *
+ * A faithful TypeScript reimplementation of the MeatPack unpacker state machine from
+ * **jamesgopsill/meatpack** (MIT, © 2025 James Gopsill — https://github.com/jamesgopsill/meatpack),
+ * which is itself derived from the published Prusa spec (`libbgcode/binarize/meatpack.cpp`). Porting
+ * from an MIT source with attribution is the sanctioned path (RR-003 §8) — the AGPL `libbgcode` and
+ * OctoPrint-MeatPack are never copied.
+ *
+ * MeatPack packs the 15 most common G-code characters into 4-bit nibbles (two per byte); a nibble of
+ * `0b1111` escapes a full literal byte, and a `0xFF 0xFF <cmd>` sequence toggles packing / no-spaces
+ * state. The stream begins in the *disabled* state; the encoder emits `FF FF FB` (enable packing) up
+ * front (the `MEATPACK_HEADER`). The first character of a packed byte is the LOW nibble.
+ */
+import { ContainerError } from '@chestnutlabs/gcode-containers';
+const SIGNAL = 0xff;
+// Command bytes (spec §meatpack; the two 0xFF signal bytes precede one of these).
+const CMD_NO_SPACES_DISABLED = 246;
+const CMD_NO_SPACES_ENABLED = 247;
+const CMD_QUERY_CONFIG = 248;
+const CMD_RESET_ALL = 249;
+const CMD_PACKING_DISABLED = 250;
+const CMD_PACKING_ENABLED = 251;
+/**
+ * 4-bit code → byte. Codes 0..14 are the packable characters; `0b1011` is space (or `'E'` when
+ * no-spaces is active). Code `0b1111` (15) is the full-width escape marker — returned here as `0`,
+ * which callers treat as "a full literal byte follows".
+ */
+function reverseLookup(nibble, noSpaces) {
+    if (nibble <= 9)
+        return 0x30 + nibble; // '0'..'9'
+    switch (nibble) {
+        case 10:
+            return 0x2e; // '.'
+        case 11:
+            return noSpaces ? 0x45 : 0x20; // 'E' or ' '
+        case 12:
+            return 0x0a; // '\n'
+        case 13:
+            return 0x47; // 'G'
+        case 14:
+            return 0x58; // 'X'
+        default:
+            return 0; // 0b1111 → NUL: full-width escape marker
+    }
+}
+/**
+ * Decode a MeatPack byte stream to plain G-code, bounded to `limit` output bytes (decompression-bomb
+ * defense). Both bgcode GCode encodings (MeatPack, MeatPack-comments) decode through this identically —
+ * comment preservation is an *encoder* choice; the decoder simply reproduces the packed bytes.
+ */
+export function meatpackDecode(data, limit) {
+    let out = new Uint8Array(Math.max(64, Math.min(limit, data.length * 2)));
+    let pos = 0;
+    const push = (b) => {
+        if (pos >= limit)
+            throw new ContainerError('E_BGCODE_BOMB', `MeatPack output exceeds the limit (${pos})`);
+        if (pos >= out.length) {
+            const bigger = new Uint8Array(Math.min(limit, Math.max(out.length * 2, pos + 1)));
+            bigger.set(out.subarray(0, pos));
+            out = bigger;
+        }
+        out[pos++] = b;
+    };
+    let state = 'disabled';
+    let noSpaces = false;
+    for (let i = 0; i < data.length; i++) {
+        const byte = data[i];
+        if (byte === SIGNAL) {
+            if (state === 'first')
+                state = 'second';
+            else if (state === 'disabled' || state === 'enabled')
+                state = 'first';
+            else
+                throw new ContainerError('E_BGCODE_MEATPACK', `invalid MeatPack state at byte ${i}`);
+            continue;
+        }
+        switch (state) {
+            case 'disabled':
+                push(byte);
+                break;
+            case 'enabled': {
+                const most = reverseLookup(byte >> 4, noSpaces); // high nibble → 2nd char
+                const least = reverseLookup(byte & 0x0f, noSpaces); // low nibble → 1st char
+                if (most === 10 && least === 10) {
+                    push(10); // a packed (\n, \n) collapses to a single newline
+                }
+                else if (most === 0 && least !== 0) {
+                    // 2nd char is full-width (follows in the stream); 1st char is real.
+                    push(least);
+                    state = 'rightFull';
+                }
+                else if (most !== 0 && least === 0) {
+                    // 1st char is full-width (follows); place a placeholder, then the real 2nd char.
+                    push(least);
+                    push(most);
+                    state = 'leftFull';
+                }
+                else if (most === 0 && least === 0) {
+                    // byte 0xFF — a signal, intercepted above; never reachable here.
+                    throw new ContainerError('E_BGCODE_MEATPACK', `unexpected 0xFF in packed data at byte ${i}`);
+                }
+                else {
+                    push(least); // 1st char (low nibble)
+                    push(most); // 2nd char (high nibble)
+                }
+                break;
+            }
+            case 'second': {
+                switch (byte) {
+                    case CMD_PACKING_ENABLED:
+                        state = 'enabled';
+                        break;
+                    case CMD_PACKING_DISABLED:
+                        state = 'disabled';
+                        break;
+                    case CMD_RESET_ALL:
+                        state = 'disabled';
+                        noSpaces = false;
+                        break;
+                    case CMD_NO_SPACES_ENABLED:
+                        noSpaces = true;
+                        state = 'enabled';
+                        break;
+                    case CMD_NO_SPACES_DISABLED:
+                        noSpaces = false;
+                        state = 'enabled';
+                        break;
+                    case CMD_QUERY_CONFIG:
+                        // A serial-link query, not expected inside a file — no-op, resume packing.
+                        state = 'enabled';
+                        break;
+                    default:
+                        throw new ContainerError('E_BGCODE_MEATPACK', `invalid MeatPack command ${byte} at byte ${i}`);
+                }
+                break;
+            }
+            case 'first':
+                // A lone 0xFF (not a command) → this byte and the next are two full-width literals.
+                state = 'rightFull';
+                push(byte);
+                break;
+            case 'rightFull':
+                state = 'enabled';
+                push(byte);
+                break;
+            case 'leftFull':
+                state = 'enabled';
+                out[pos - 2] = byte; // overwrite the placeholder with the full-width byte
+                break;
+        }
+    }
+    return out.subarray(0, pos);
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@chestnutlabs/gcode-bgcode",
+  "version": "0.3.0",
+  "description": "Binary G-code (.bgcode) decode adapter for the Chestnut Labs G-code toolpath stack (DD-011): a license-clean, in-memory block walker that decodes Prusa .bgcode to plain G-code for the existing parser/dialect/renderer pipeline. Decode-only.",
+  "keywords": [
+    "gcode",
+    "bgcode",
+    "binary-gcode",
+    "3d-printing",
+    "toolpath",
+    "prusa",
+    "chestnutlabs",
+    "container"
+  ],
+  "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-bgcode"
+  },
+  "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.3.0",
+    "@chestnutlabs/gcode-containers": "0.3.0"
+  }
+}