Priority: this epic comes before the CNC/laser/plotter epic. It's a bounded, high-leverage
container addition that reuses ~2/3 of the E4 machinery; CNC/laser is a larger IR-model concern.
Problem / outcome
Modern PrusaSlicer defaults to binary G-code (.bgcode) for Prusa printers, so a growing share
of real files — including 2026 ColorMix color prints — are currently undecodable by our
stack. .bgcode is a container format, not a new toolpath language: decode it to plain G-code and
the entire existing pipeline works unchanged (parser, dialects, IR, renderer, live progress,
multi-tool/color). It fits as a new container adapter beside .gcode.3mf.
Scope (this repo)
- New
@chestnutlabs/gcode-bgcode package: block walker, CRC32 verify, codec dispatch, sniff/open
via the existing container-adapter contract ({ id, sniff, open }), worker registration
(batteries + optional slim). No multi-plate (simpler than .gcode.3mf).
- Two new decode codecs: heatshrink (LZSS — the one real new algorithm; bounded-output guard) and
meatpack (nibble unpacking). deflate + ASCII reuse existing primitives.
- Optional: surface metadata (printer settings →
MachineGeometry) and thumbnails.
Reuse vs. new
Reuse (confirmed): container-adapter contract, crc32/crc32Final, bounded-decompression limits,
DecompressionStream deflate, no-fs/net lint discipline, adversarial-corpus testing pattern, the
whole downstream parser/renderer stack. New: heatshrink decoder, meatpack decoder, block walker,
fixtures.
Non-goals
- No bgcode encoding/writing (decode/read only).
- Unsupported spec versions rejected honestly (pin supported versions).
- Not a new toolpath model.
DD / RR / ADR gate
Gate: RR-NNN (licensing + format audit) → DD-NNN — Binary G-code Decode Adapter accepted,
plus a §7.3-style security review signed off (as DD-005 required). The licensing audit is the
founding-docs prerequisite (".bgcode decoding after licensing, format, and architecture research")
— we must never copy AGPL (libbgcode) or GPL (Marlin meatpack) code into MIT packages;
clean-room from spec, or port only from MIT/BSD/ISC with attribution.
Phased child-issue plan
- RR gate — licensing + format audit; pin spec version(s); confirm deflate flavor; catalog blocks.
- Block walker + CRC + codec dispatch (deflate + ASCII end-to-end → parser).
- meatpack decoder + unit vectors.
- heatshrink decoder + bounded-output guard + unit vectors.
- Container-adapter integration; golden-equivalence vs plain-gcode; optional metadata/thumbnails.
- Adversarial security corpus + §7.3 review + decode benchmark + matrix/README.
- Epic exit.
Tests / fixtures / benchmarks
Killer test: slice one trivial model two ways (plain .gcode and .bgcode) and assert the
decoded-bgcode IR equals the plain-gcode IR — decode correctness by golden-equivalence against the
trusted path. Plus codec vectors (heatshrink/meatpack) and an adversarial corpus (truncated blocks,
bad CRC, unknown compression/version, decompression bombs). Decode-throughput / TTFP benchmark.
Risks & deferred work
- Licensing contamination (AGPL/GPL) → clean-room-from-spec mandate + license audit gate.
- heatshrink correctness/security → published vectors + golden-equivalence + bounded output.
- Spec/version drift → pin + reject unknown.
Acceptance & exit criteria
A real .bgcode (deflate/heatshrink × ASCII/meatpack) decodes to an IR equal to the plain-.gcode
IR of the same model; adversarial corpus all structured-rejected; §7.3 signed off; matrix + README
published; decode benchmark met.
Milestone: Future / post-1.0 · Depends on: E2 (parser), E4 (container-adapter contract +
security discipline) · Blocking: none · Unlocks: all modern Prusa output incl. ColorMix.
Problem / outcome
Modern PrusaSlicer defaults to binary G-code (
.bgcode) for Prusa printers, so a growing shareof real files — including 2026 ColorMix color prints — are currently undecodable by our
stack.
.bgcodeis a container format, not a new toolpath language: decode it to plain G-code andthe entire existing pipeline works unchanged (parser, dialects, IR, renderer, live progress,
multi-tool/color). It fits as a new container adapter beside
.gcode.3mf.Scope (this repo)
@chestnutlabs/gcode-bgcodepackage: block walker, CRC32 verify, codec dispatch,sniff/openvia the existing container-adapter contract (
{ id, sniff, open }), worker registration(batteries + optional slim). No multi-plate (simpler than
.gcode.3mf).meatpack (nibble unpacking). deflate + ASCII reuse existing primitives.
MachineGeometry) and thumbnails.Reuse vs. new
Reuse (confirmed): container-adapter contract,
crc32/crc32Final, bounded-decompression limits,DecompressionStreamdeflate, no-fs/net lint discipline, adversarial-corpus testing pattern, thewhole downstream parser/renderer stack. New: heatshrink decoder, meatpack decoder, block walker,
fixtures.
Non-goals
DD / RR / ADR gate
Gate:
RR-NNN (licensing + format audit)→DD-NNN — Binary G-code Decode Adapteraccepted,plus a §7.3-style security review signed off (as DD-005 required). The licensing audit is the
founding-docs prerequisite ("
.bgcodedecoding after licensing, format, and architecture research")— we must never copy AGPL (
libbgcode) or GPL (Marlin meatpack) code into MIT packages;clean-room from spec, or port only from MIT/BSD/ISC with attribution.
Phased child-issue plan
Tests / fixtures / benchmarks
Killer test: slice one trivial model two ways (plain
.gcodeand.bgcode) and assert thedecoded-bgcode IR equals the plain-gcode IR — decode correctness by golden-equivalence against the
trusted path. Plus codec vectors (heatshrink/meatpack) and an adversarial corpus (truncated blocks,
bad CRC, unknown compression/version, decompression bombs). Decode-throughput / TTFP benchmark.
Risks & deferred work
Acceptance & exit criteria
A real
.bgcode(deflate/heatshrink × ASCII/meatpack) decodes to an IR equal to the plain-.gcodeIR of the same model; adversarial corpus all structured-rejected; §7.3 signed off; matrix + README
published; decode benchmark met.
Milestone: Future / post-1.0 · Depends on: E2 (parser), E4 (container-adapter contract +
security discipline) · Blocking: none · Unlocks: all modern Prusa output incl. ColorMix.