cabriolet 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d2875b9afed58332c6e9823f3f383a60d802bac8514cb2015fdbd6a7f1559dc
-  data.tar.gz: 6979ce57ad3d47867bed19330d70b5db483bc33ac8920ee2986faa35828d6cbc
+  metadata.gz: 59d85958b00fa7eb684912e7ec77bfd9ce261a01035ed7ef42c2d6db5b1405a7
+  data.tar.gz: e9fa2123fe7c48778a01018c68f47cdb66f68449fe4fee48074e2b7591d5b9e1
 SHA512:
-  metadata.gz: edd7b1345bee36e75fb5796a3840f087a9dfa51e41c599fa767938e8d64ab0abc985e563b9fb246fc86fc4798eb3f98539f774023eaf613f50a1c9e4a2a6d518
-  data.tar.gz: c5cfc76ae8dc5239efa9e90d0956d2518eab56c669d4b7e4087debc4955f509cc97440296c53084152cb30059b25044b6231cd9a84ee94e85f446a20f3306e08
+  metadata.gz: ddc9ef226ce8359cbe65ac4e80853dbd8e57f25c6e934e48837a163f614bcdbdf94f18609c788c6396f4b87f93d4e12c1fa326c8f291bc1156ec0eaf0387d377
+  data.tar.gz: 20206a2b5011d4a869d0f4d29085b5b874fe1d34daa00ce14f842d55a71722c19329ea75b1f46adaebf88fc43805a467b089e038aa19fe5736010d1a9ca951ad

data/lib/cabriolet/binary/bitstream.rb

@@ -4,7 +4,7 @@ module Cabriolet
   module Binary
     # Bitstream provides bit-level I/O operations for reading compressed data
     class Bitstream
-      attr_reader :io_system, :handle, :buffer_size, :bit_order
+      attr_reader :io_system, :handle, :buffer_size, :bit_order, :bits_left
 
       # Initialize a new bitstream
       #
@@ -29,6 +29,9 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         # For MSB mode, we need to know the bit width of the buffer
         # Ruby integers are arbitrary precision, so we use 32 bits as standard
         @bitbuf_width = 32
+
+        # Cache ENV lookups once at initialization
+        @debug_bitstream = ENV.fetch("DEBUG_BITSTREAM", nil)
       end
 
       # Read specified number of bits from the stream
@@ -83,7 +86,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
           byte = 0 if byte.nil?
 
           # DEBUG
-          if ENV["DEBUG_BITSTREAM"]
+          if @debug_bitstream
             warn "DEBUG LSB read_byte: buffer_pos=#{@buffer_pos} byte=#{byte} (#{byte.to_s(2).rjust(
               8, '0'
             )}) bits_left=#{@bits_left}"
@@ -101,7 +104,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         @bits_left -= num_bits
 
         # DEBUG
-        warn "DEBUG LSB read_bits(#{num_bits}): result=#{result} buffer=#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+        warn "DEBUG LSB read_bits(#{num_bits}): result=#{result} buffer=#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if @debug_bitstream
 
         result
       end
@@ -116,7 +119,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
           word = read_msb_word
 
           # DEBUG
-          warn "DEBUG MSB read_bytes: word=0x#{word.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+          warn "DEBUG MSB read_bytes: word=0x#{word.to_s(16)} bits_left=#{@bits_left}" if @debug_bitstream
 
           # INJECT_BITS (MSB): inject at the left side
           @bit_buffer |= (word << (@bitbuf_width - 16 - @bits_left))
@@ -131,7 +134,7 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         @bits_left -= num_bits
 
         # DEBUG
-        warn "DEBUG MSB read_bits(#{num_bits}) result=#{result} (0x#{result.to_s(16)}) buffer=0x#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+        warn "DEBUG MSB read_bits(#{num_bits}) result=#{result} (0x#{result.to_s(16)}) buffer=0x#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if @debug_bitstream
 
         result
       end
@@ -172,15 +175,62 @@ buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         byte
       end
 
+      # Ensure at least num_bits are available in the bit buffer.
+      # Reads from input if needed. Used for alignment operations.
+      #
+      # @param num_bits [Integer] Minimum number of bits required
+      # @return [void]
+      def ensure_bits(num_bits)
+        if @bit_order == :msb
+          while @bits_left < num_bits
+            word = read_msb_word
+            @bit_buffer |= (word << (@bitbuf_width - 16 - @bits_left))
+            @bits_left += 16
+          end
+        else
+          while @bits_left < num_bits
+            byte = read_byte
+            byte = 0 if byte.nil?
+            @bit_buffer |= (byte << @bits_left)
+            @bits_left += 8
+          end
+        end
+      end
+
       # Align to the next byte boundary
       #
       # @return [void]
       def byte_align
         discard_bits = @bits_left % 8
-        @bit_buffer >>= discard_bits
+        if @bit_order == :msb
+          # MSB mode: valid bits are at the left (high) end, shift left to discard
+          @bit_buffer = (@bit_buffer << discard_bits) & ((1 << @bitbuf_width) - 1)
+        else
+          @bit_buffer >>= discard_bits
+        end
         @bits_left -= discard_bits
       end
 
+      # Flush the bit buffer entirely (discard all remaining bits).
+      # Per libmspack lzxd.c: used when transitioning to raw byte reading
+      # for uncompressed blocks. Sets bits_left=0 and bit_buffer=0.
+      #
+      # @return [void]
+      def flush_bit_buffer
+        @bit_buffer = 0
+        @bits_left = 0
+      end
+
+      # Read a raw byte directly from the input, bypassing the bit buffer.
+      # Per libmspack lzxd.c: uncompressed block headers and data are read
+      # directly from the input pointer (i_ptr), not through the bitstream.
+      # Call flush_bit_buffer first to discard any residual bits.
+      #
+      # @return [Integer] Byte value (0 on EOF)
+      def read_raw_byte
+        read_byte || 0
+      end
+
       # Peek at bits without consuming them
       #
       # @param num_bits [Integer] Number of bits to peek at

data/lib/cabriolet/cab/decompressor.rb

@@ -157,8 +157,11 @@ module Cabriolet
               offset = cab_offset + 4
             end
           else
-            # No cabinet found in this chunk, move to next
-            offset += length
+            # No cabinet found in this chunk, move to next.
+            # Overlap by 20 bytes so MSCF signatures spanning chunk
+            # boundaries are not missed (state machine reads 20 bytes).
+            overlap = length > 20 ? 20 : 0
+            offset += [length - overlap, 1].max
           end
         end
 
@@ -452,7 +455,7 @@ file_length)
                                                         cablen_u32, caboff, file_length)
 
             # Not valid, restart search after "MSCF"
-            return nil
+            state = 0
           end
         end
 

data/lib/cabriolet/cab/extractor.rb

@@ -22,6 +22,9 @@ module Cabriolet
         @current_decomp = nil
         @current_input = nil
         @current_offset = 0
+
+        # Cache ENV lookups once at initialization
+        @debug_block = ENV.fetch("DEBUG_BLOCK", nil)
       end
 
       # Extract a single file from the cabinet
@@ -185,7 +188,7 @@ module Cabriolet
       # @param salvage [Boolean] Salvage mode flag
       # @param file_offset [Integer] File offset for reset condition check
       def setup_decompressor_for_folder(folder, salvage, file_offset)
-        if ENV["DEBUG_BLOCK"]
+        if @debug_block
           warn "DEBUG extract_file: Checking reset condition"
           warn "  @current_folder == folder: #{@current_folder == folder}"
           warn "  @current_offset (#{@current_offset}) > file_offset (#{file_offset})"
@@ -193,7 +196,7 @@ module Cabriolet
         end
 
         if @current_folder != folder || @current_offset > file_offset || !@current_decomp
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG extract_file: RESETTING state (creating new BlockReader)"
           end
 
@@ -211,7 +214,20 @@ module Cabriolet
           # Create decompressor ONCE and reuse it
           @current_decomp = @decompressor.create_decompressor(folder,
                                                               @current_input, nil)
-        elsif ENV["DEBUG_BLOCK"]
+
+          # Per libmspack cabd.c: set output_length from the folder's total
+          # uncompressed size (max file.offset + file.length across all files
+          # in the folder). This allows the LZX decompressor to reduce the
+          # last frame's size so it doesn't read past the end of the stream.
+          if @current_decomp.respond_to?(:set_output_length)
+            cab = folder.data&.cabinet
+            if cab&.files
+              folder_files = cab.files.select { |f| f.folder == folder }
+              max_end = folder_files.map { |f| f.offset + f.length }.max
+              @current_decomp.set_output_length(max_end) if max_end&.positive?
+            end
+          end
+        elsif @debug_block
           warn "DEBUG extract_file: NOT resetting (reusing existing BlockReader)"
         end
       end
@@ -228,7 +244,6 @@ module Cabriolet
         null_output = System::MemoryHandle.new("", Constants::MODE_WRITE)
 
         @current_decomp.instance_variable_set(:@output, null_output)
-        @current_decomp.set_output_length(skip_bytes) if @current_decomp.respond_to?(:set_output_length)
 
         begin
           @current_decomp.decompress(skip_bytes)
@@ -248,8 +263,11 @@ module Cabriolet
       # @param output_fh [System::FileHandle] Output file handle
       # @param filelen [Integer] Number of bytes to write
       def write_file_data(output_fh, filelen)
+        unless @current_decomp
+          raise DecompressionError, "Decompressor not available (state was reset)"
+        end
+
         @current_decomp.instance_variable_set(:@output, output_fh)
-        @current_decomp.set_output_length(filelen) if @current_decomp.respond_to?(:set_output_length)
         @current_decomp.decompress(filelen)
         @current_offset += filelen
       end
@@ -311,6 +329,9 @@ module Cabriolet
           @buffer_pos = 0
           @cab_handle = nil
 
+          # Cache ENV lookups once at initialization
+          @debug_block = ENV.fetch("DEBUG_BLOCK", nil)
+
           # Open first cabinet and seek to data offset
           open_current_cabinet
         end
@@ -318,7 +339,7 @@ module Cabriolet
         def read(bytes)
           # Early return if we've already exhausted all blocks and buffer
           if @current_block >= @num_blocks && @buffer_pos >= @buffer.bytesize
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG BlockReader.read(#{bytes}): Already exhausted, returning empty"
             end
             return +""
@@ -326,14 +347,14 @@ module Cabriolet
 
           result = +""
 
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG BlockReader.read(#{bytes}): buffer_size=#{@buffer.bytesize} buffer_pos=#{@buffer_pos} block=#{@current_block}/#{@num_blocks}"
           end
 
           while result.bytesize < bytes
             # Read more data if buffer is empty
             if (@buffer_pos >= @buffer.bytesize) && !read_next_block
-              if ENV["DEBUG_BLOCK"]
+              if @debug_block
                 warn "DEBUG BlockReader.read: EXHAUSTED at result.bytesize=#{result.bytesize} (wanted #{bytes})"
               end
               break
@@ -347,7 +368,7 @@ module Cabriolet
             @buffer_pos += to_copy
           end
 
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG BlockReader.read: returning #{result.bytesize} bytes"
           end
 
@@ -371,12 +392,12 @@ module Cabriolet
         private
 
         def read_next_block
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG read_next_block: current_block=#{@current_block} num_blocks=#{@num_blocks}"
           end
 
           if @current_block >= @num_blocks
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: EXHAUSTED (current_block >= num_blocks)"
             end
             return false
@@ -387,19 +408,19 @@ module Cabriolet
 
           loop do
             # Read CFDATA header
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               handle_pos = @cab_handle.tell
               warn "DEBUG read_next_block: About to read CFDATA header at position #{handle_pos}"
             end
 
             header_data = @cab_handle.read(Constants::CFDATA_SIZE)
 
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: Read #{header_data.bytesize} bytes (expected #{Constants::CFDATA_SIZE})"
             end
 
             if header_data.bytesize != Constants::CFDATA_SIZE
-              if ENV["DEBUG_BLOCK"]
+              if @debug_block
                 warn "DEBUG read_next_block: FAILED - header read returned #{header_data.bytesize} bytes"
               end
               return false
@@ -427,18 +448,18 @@ module Cabriolet
             end
 
             # Read compressed data
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: About to read #{cfdata.compressed_size} bytes of compressed data"
             end
 
             compressed_data = @cab_handle.read(cfdata.compressed_size)
 
-            if ENV["DEBUG_BLOCK"]
+            if @debug_block
               warn "DEBUG read_next_block: Read #{compressed_data.bytesize} bytes of compressed data (expected #{cfdata.compressed_size})"
             end
 
             if compressed_data.bytesize != cfdata.compressed_size
-              if ENV["DEBUG_BLOCK"]
+              if @debug_block
                 warn "DEBUG read_next_block: FAILED - compressed data read returned #{compressed_data.bytesize} bytes"
               end
               return false
@@ -482,7 +503,7 @@ module Cabriolet
         end
 
         def open_current_cabinet
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             warn "DEBUG open_current_cabinet: filename=#{@current_data.cabinet.filename} offset=#{@current_data.offset}"
           end
 
@@ -490,7 +511,7 @@ module Cabriolet
           @cab_handle = @io_system.open(@current_data.cabinet.filename, Constants::MODE_READ)
           @cab_handle.seek(@current_data.offset, Constants::SEEK_START)
 
-          if ENV["DEBUG_BLOCK"]
+          if @debug_block
             actual_pos = @cab_handle.tell
             warn "DEBUG open_current_cabinet: seeked to position #{actual_pos} (expected #{@current_data.offset})"
           end

data/lib/cabriolet/checksum.rb

@@ -28,14 +28,17 @@ module Cabriolet
         ul = 0
         offset = bytes.size - remainder
 
+        # Match libmspack's cabd_checksum remainder handling:
+        # The C fall-through switch processes bytes in decreasing shift
+        # order (first remaining byte gets the highest shift).
         case remainder
         when 3
-          ul |= bytes[offset + 2] << 16
+          ul |= bytes[offset] << 16
           ul |= bytes[offset + 1] << 8
-          ul |= bytes[offset]
+          ul |= bytes[offset + 2]
         when 2
-          ul |= bytes[offset + 1] << 8
-          ul |= bytes[offset]
+          ul |= bytes[offset] << 8
+          ul |= bytes[offset + 1]
         when 1
           ul |= bytes[offset]
         end

data/lib/cabriolet/compressors/lzx.rb

@@ -89,7 +89,7 @@ module Cabriolet
                                                  buffer_size, bit_order: :msb)
 
         # Initialize sliding window for LZ77
-        @window = "\0" * @window_size
+        @window = ("\0" * @window_size).b
         @window_pos = 0
 
         # Initialize R0, R1, R2 (LRU offset registers)
@@ -153,6 +153,11 @@ module Cabriolet
 
       # Compress a single frame (32KB)
       #
+      # Per libmspack lzxd.c: uncompressed blocks write R0/R1/R2 and data
+      # as raw bytes directly to the stream, NOT through the MSB bitstream.
+      # The bitstream is flushed (padded to 16-bit boundary) after the
+      # block header, then raw bytes follow.
+      #
       # @param data [String] Frame data to compress
       # @return [void]
       def compress_frame(data)
@@ -163,12 +168,12 @@ module Cabriolet
         # Write UNCOMPRESSED block header
         write_block_header(BLOCKTYPE_UNCOMPRESSED, block_length)
 
-        # Write offset registers (R0, R1, R2)
+        # Write offset registers (R0, R1, R2) as raw bytes
         write_offset_registers
 
-        # Write raw uncompressed data
+        # Write raw uncompressed data (bypassing MSB bitstream)
         data.each_byte do |byte|
-          @bitstream.write_bits(byte, 8)
+          @bitstream.write_raw_byte(byte)
         end
       end
 
@@ -571,14 +576,17 @@ module Cabriolet
 
       # Write offset registers (R0, R1, R2) for uncompressed blocks
       #
+      # Per libmspack lzxd.c: R0/R1/R2 are written as raw bytes directly
+      # to the stream (not through the MSB bitstream) to avoid byte-swapping.
+      #
       # @return [void]
       def write_offset_registers
-        # Write R0, R1, R2 as 32-bit little-endian values (12 bytes total)
+        # Write R0, R1, R2 as 32-bit little-endian values (12 raw bytes total)
         [@r0, @r1, @r2].each do |offset|
-          @bitstream.write_bits(offset & 0xFF, 8)
-          @bitstream.write_bits((offset >> 8) & 0xFF, 8)
-          @bitstream.write_bits((offset >> 16) & 0xFF, 8)
-          @bitstream.write_bits((offset >> 24) & 0xFF, 8)
+          @bitstream.write_raw_byte(offset & 0xFF)
+          @bitstream.write_raw_byte((offset >> 8) & 0xFF)
+          @bitstream.write_raw_byte((offset >> 16) & 0xFF)
+          @bitstream.write_raw_byte((offset >> 24) & 0xFF)
         end
       end
 

data/lib/cabriolet/compressors/mszip.rb

@@ -66,7 +66,7 @@ module Cabriolet
         @fixed_codes = Huffman::Encoder.build_fixed_codes
 
         # Initialize sliding window for LZ77
-        @window = "\0" * WINDOW_SIZE
+        @window = ("\0" * WINDOW_SIZE).b
         @window_pos = 0
       end
 

data/lib/cabriolet/decompressors/lzss.rb

@@ -31,11 +31,12 @@ module Cabriolet
                      mode = MODE_EXPAND)
         super(io_system, input, output, buffer_size)
         @mode = mode
-        @window = Array.new(WINDOW_SIZE, WINDOW_FILL)
+        @window = (WINDOW_FILL.chr * WINDOW_SIZE).b
         @window_pos = initialize_window_position
         @input_buffer = ""
         @input_pos = 0
         @invert = mode == MODE_MSHELP ? 0xFF : 0x00
+        @output_buffer = String.new(encoding: Encoding::BINARY, capacity: 4096)
       end
 
       # Decompress LZSS data
@@ -69,8 +70,8 @@ module Cabriolet
               literal = read_input_byte
               break if literal.nil?
 
-              @window[@window_pos] = literal
-              write_output_byte(literal)
+              @window.setbyte(@window_pos, literal)
+              buffer_output_byte(literal)
               bytes_written += 1
 
               @window_pos = (@window_pos + 1) & (WINDOW_SIZE - 1)
@@ -91,9 +92,9 @@ module Cabriolet
                 # Check if we've reached the limit mid-match
                 break if enforce_limit && bytes_written >= bytes
 
-                byte = @window[match_pos]
-                @window[@window_pos] = byte
-                write_output_byte(byte)
+                byte = @window.getbyte(match_pos)
+                @window.setbyte(@window_pos, byte)
+                buffer_output_byte(byte)
                 bytes_written += 1
 
                 @window_pos = (@window_pos + 1) & (WINDOW_SIZE - 1)
@@ -103,6 +104,7 @@ module Cabriolet
           end
         end
 
+        flush_output_buffer
         bytes_written
       end
 
@@ -131,17 +133,23 @@ module Cabriolet
         byte
       end
 
-      # Write a single byte to the output
+      # Buffer an output byte and flush when buffer is full
       #
-      # @param byte [Integer] Byte to write
+      # @param byte [Integer] Byte to buffer
       # @return [void]
-      # @raise [Errors::DecompressionError] if write fails
-      def write_output_byte(byte)
-        data = [byte].pack("C")
-        written = @io_system.write(@output, data)
-        return if written == 1
+      def buffer_output_byte(byte)
+        @output_buffer << byte.chr
+        flush_output_buffer if @output_buffer.bytesize >= 4096
+      end
+
+      # Flush the output buffer to the output stream
+      #
+      # @return [void]
+      def flush_output_buffer
+        return if @output_buffer.empty?
 
-        raise Errors::DecompressionError, "Failed to write output byte"
+        @io_system.write(@output, @output_buffer)
+        @output_buffer.clear
       end
     end
   end

data/lib/cabriolet/decompressors/lzx.rb

@@ -129,8 +129,8 @@ module Cabriolet
         @num_offsets = POSITION_SLOTS[window_bits - 15] << 3
         @maintree_maxsymbols = NUM_CHARS + @num_offsets
 
-        # Initialize window
-        @window = "\0" * @window_size
+        # Initialize window (must be binary to avoid UTF-8 character vs byte mismatch)
+        @window = ("\0" * @window_size).b
         @window_posn = 0
         @frame_posn = 0
         @frame = 0
@@ -149,7 +149,7 @@ module Cabriolet
         # Intel E8 transformation state
         @intel_filesize = 0
         @intel_started = false
-        @e8_buf = "\0" * FRAME_SIZE
+        @e8_buf = ("\0" * FRAME_SIZE).b
 
         # Initialize bitstream (LZX uses MSB-first bit ordering per libmspack lzxd.c)
         @bitstream = Binary::Bitstream.new(io_system, input, buffer_size,
@@ -162,6 +162,12 @@ module Cabriolet
         @offset = 0
         @output_ptr = 0
         @output_end = 0
+
+        # Per libmspack: pending frame data for multi-file extraction.
+        # When a decompress call ends mid-frame, the unwritten portion
+        # of the frame is stored here for the next call to output.
+        @pending_frame_data = nil
+        @pending_frame_offset = 0
       end
 
       # Set output length (for Intel E8 processing)
@@ -174,6 +180,11 @@ module Cabriolet
 
       # Decompress LZX data
       #
+      # Per libmspack lzxd.c: the decompressor always decodes full frames
+      # (32KB) into the window, but may output fewer bytes if the caller
+      # requests less. When multiple files share a folder, decompress is
+      # called per file, so partial-frame data must carry over between calls.
+      #
       # @param bytes [Integer] Number of bytes to decompress
       # @return [Integer] Number of bytes decompressed
       def decompress(bytes)
@@ -183,7 +194,28 @@ module Cabriolet
         read_intel_header unless @header_read
 
         total_written = 0
-        end_frame = ((@offset + bytes) / FRAME_SIZE) + 1
+
+        # Output any pending frame data from the previous partial-frame write.
+        # This handles multi-file extraction where the previous call ended
+        # mid-frame and the next file's data starts in the same frame.
+        if @pending_frame_data
+          avail = @pending_frame_data.bytesize - @pending_frame_offset
+          write_amount = [bytes, avail].min
+          io_system.write(output, @pending_frame_data[@pending_frame_offset, write_amount])
+          total_written += write_amount
+          @offset += write_amount
+          @pending_frame_offset += write_amount
+
+          if @pending_frame_offset >= @pending_frame_data.bytesize
+            @pending_frame_data = nil
+            @pending_frame_offset = 0
+          end
+        end
+
+        remaining = bytes - total_written
+        return total_written if remaining <= 0
+
+        end_frame = ((@offset + remaining) / FRAME_SIZE) + 1
 
         while @frame < end_frame
           # Check reset interval - reset offset registers at frame boundaries
@@ -217,20 +249,47 @@ module Cabriolet
                          @window[@frame_posn, frame_size]
                        end
 
-          # Write frame
+          # Defensive guard: frame_data should never be nil if the >= window
+          # wrap checks below are correct. If it is, the stream is corrupt
+          # or a regression has been introduced.
+          if frame_data.nil?
+            if @salvage
+              warn "Salvage: nil frame data at frame_posn=#{@frame_posn}, frame=#{@frame}"
+              break
+            end
+
+            raise DecompressionError,
+                  "LZX: nil frame data at position #{@frame_posn}, frame_size=#{frame_size}"
+          end
+
+          # Write frame - per libmspack: offset tracks actual output bytes,
+          # not full frame bytes. Save unwritten remainder for next call.
           write_amount = [bytes - total_written, frame_size].min
           io_system.write(output, frame_data[0, write_amount])
           total_written += write_amount
-          @offset += frame_size
+          @offset += write_amount
+
+          # Store pending data if partial frame write
+          if write_amount < frame_size
+            @pending_frame_data = frame_data
+            @pending_frame_offset = write_amount
+          end
 
-          # Advance frame
+          # Advance frame (always by full frame, matching decode position)
           @frame += 1
           @frame_posn += frame_size
-          @frame_posn = 0 if @frame_posn == @window_size
-          @window_posn = 0 if @window_posn == @window_size
-
-          # Re-align bitstream (byte_align is safe to call even if already aligned)
-          @bitstream.byte_align
+          @frame_posn = 0 if @frame_posn >= @window_size
+          @window_posn = 0 if @window_posn >= @window_size
+
+          # Re-align bitstream to 16-bit word boundary between frames.
+          # Per libmspack lzxd.c: LZX frames are padded to 16-bit word
+          # boundaries (not 8-bit byte boundaries) because the bitstream
+          # reads data in 16-bit little-endian words.
+          if @bitstream.bits_left.positive?
+            @bitstream.ensure_bits(16)
+          end
+          remove = @bitstream.bits_left & 15
+          @bitstream.skip_bits(remove) if remove.positive?
         end
 
         total_written
@@ -313,14 +372,27 @@ module Cabriolet
           # Read new block header if needed
           read_block_header if @block_remaining.zero?
 
-          # Decode as much as possible
+          # Decode as much as possible from the current block
           this_run = [@block_remaining, bytes_todo].min
           bytes_todo -= this_run
           @block_remaining -= this_run
 
           case @block_type
           when BLOCKTYPE_VERBATIM, BLOCKTYPE_ALIGNED
-            decode_huffman_block(this_run)
+            remaining = decode_huffman_block(this_run)
+
+            # Per libmspack lzxd.c: if a match caused overrun (this_run
+            # went negative in the inner loop), adjust block_remaining.
+            # This happens when a match crosses a block boundary within
+            # a frame (bytes_todo limited this_run, not block_remaining).
+            if remaining.negative?
+              overrun = -remaining
+              if overrun > @block_remaining
+                raise DecompressionError,
+                      "Match overrun (#{overrun}) exceeds block remaining (#{@block_remaining})"
+              end
+              @block_remaining -= overrun
+            end
           when BLOCKTYPE_UNCOMPRESSED
             decode_uncompressed_block(this_run)
           else
@@ -337,9 +409,11 @@ module Cabriolet
       #
       # @return [void]
       def read_block_header
-        # Align for uncompressed blocks - this ensures correct byte alignment
-        # when reading the R0, R1, R2 values from the block header
-        @bitstream.byte_align if @block_type == BLOCKTYPE_UNCOMPRESSED && @block_length.allbits?(1)
+        # Per libmspack lzxd.c: when transitioning FROM an uncompressed block
+        # with ODD length, skip 1 raw padding byte to maintain 16-bit alignment.
+        if @block_type == BLOCKTYPE_UNCOMPRESSED && @block_length.odd?
+          @bitstream.read_raw_byte
+        end
 
         # Read block type (3 bits)
         @block_type = @bitstream.read_bits(3)
@@ -549,15 +623,23 @@ module Cabriolet
 
       # Read uncompressed block header
       #
+      # Per libmspack lzxd.c: for uncompressed blocks, the bitstream is
+      # flushed (bit_buffer=0, bits_left=0) and R0/R1/R2 are read directly
+      # from the raw input stream (i_ptr), NOT through the MSB bitstream.
+      # Reading through the MSB bitstream would byte-swap each 16-bit word.
+      #
       # @return [void]
       def read_uncompressed_block_header
         @intel_started = true
 
-        # Align to byte boundary
-        @bitstream.byte_align
+        # Per libmspack: if bits_left == 0, ensure we have data available
+        @bitstream.ensure_bits(16) if @bitstream.bits_left.zero?
+
+        # Flush bit buffer - discard any remaining bits (alignment padding)
+        @bitstream.flush_bit_buffer
 
-        # Read R0, R1, R2
-        bytes = Array.new(12) { @bitstream.read_bits(8) }
+        # Read R0, R1, R2 directly from raw input (bypassing bitstream)
+        bytes = Array.new(12) { @bitstream.read_raw_byte }
         @r0 = bytes[0] | (bytes[1] << 8) | (bytes[2] << 16) | (bytes[3] << 24)
         @r1 = bytes[4] | (bytes[5] << 8) | (bytes[6] << 16) | (bytes[7] << 24)
         @r2 = bytes[8] | (bytes[9] << 8) | (bytes[10] << 16) | (bytes[11] << 24)
@@ -565,8 +647,13 @@ module Cabriolet
 
       # Decode Huffman-compressed block
       #
+      # Per libmspack lzxd.c: the inner decode loop uses this_run as its
+      # counter. A match can cause this_run to go negative (overrun past
+      # the planned run length). The caller must adjust block_remaining
+      # for any overrun.
+      #
       # @param run_length [Integer] Number of bytes to decode
-      # @return [void]
+      # @return [Integer] Final run_length (0 or negative if overrun)
       def decode_huffman_block(run_length)
         while run_length.positive?
           # Decode main symbol
@@ -586,6 +673,8 @@ module Cabriolet
             run_length -= match_length
           end
         end
+
+        run_length
       end
 
       # Decode and copy a match
@@ -599,7 +688,7 @@ module Cabriolet
         # Decode match length
         match_length = main_element & NUM_PRIMARY_LENGTHS
         if match_length == NUM_PRIMARY_LENGTHS
-          if @length_empty
+          if @length_empty || @length_tree.nil?
             raise DecompressionError,
                   "Length tree needed but empty"
           end
@@ -747,11 +836,15 @@ module Cabriolet
 
       # Decode uncompressed block
       #
+      # Per libmspack lzxd.c: uncompressed block data is read directly from
+      # the raw input stream (i_ptr), NOT through the MSB bitstream. The bit
+      # buffer was already flushed when the uncompressed block header was read.
+      #
       # @param run_length [Integer] Number of bytes to decode
       # @return [void]
       def decode_uncompressed_block(run_length)
         run_length.times do
-          byte = @bitstream.read_bits(8)
+          byte = @bitstream.read_raw_byte
           @window.setbyte(@window_posn, byte)
           @window_posn += 1
         end

data/lib/cabriolet/decompressors/mszip.rb

@@ -62,8 +62,8 @@ salvage: false, **_kwargs)
         super(io_system, input, output, buffer_size)
         @fix_mszip = fix_mszip
 
-        # Initialize sliding window
-        @window = "\0" * FRAME_SIZE
+        # Initialize sliding window (must be binary to avoid UTF-8 character vs byte mismatch)
+        @window = ("\0" * FRAME_SIZE).b
         @window_posn = 0
         @bytes_output = 0
         @window_offset = 0 # Offset into window for unconsumed data (for multi-file CFDATA blocks)
@@ -77,6 +77,10 @@ salvage: false, **_kwargs)
         @distance_lengths = Array.new(DISTANCE_MAXSYMBOLS, 0)
         @literal_tree = nil
         @distance_tree = nil
+
+        # Cache ENV lookups once at initialization
+        @debug_mszip = ENV.fetch("DEBUG_MSZIP", nil)
+        @debug_mszip_symbols = ENV.fetch("DEBUG_MSZIP_SYMBOLS", nil)
       end
 
       # Decompress MSZIP data
@@ -86,14 +90,14 @@ salvage: false, **_kwargs)
       def decompress(bytes)
         total_written = 0
 
-        if ENV["DEBUG_MSZIP"]
+        if @debug_mszip
           warn "DEBUG MSZIP.decompress(#{bytes}): ENTRY bytes_output=#{@bytes_output} window_offset=#{@window_offset} window_posn=#{@window_posn}"
         end
 
         while bytes.positive?
           # Check if we have buffered data from previous inflate
           if @bytes_output.positive?
-            if ENV["DEBUG_MSZIP"]
+            if @debug_mszip
               warn "DEBUG MSZIP: Using buffered data: bytes_output=#{@bytes_output} window_offset=#{@window_offset}"
             end
 
@@ -105,7 +109,7 @@ salvage: false, **_kwargs)
             @bytes_output -= write_amount
             @window_offset += write_amount
 
-            if ENV["DEBUG_MSZIP"]
+            if @debug_mszip
               warn "DEBUG MSZIP: After buffer write: total_written=#{total_written} bytes_remaining=#{bytes} bytes_output=#{@bytes_output}"
             end
 
@@ -120,13 +124,13 @@ salvage: false, **_kwargs)
 
           # Read 'CK' signature (marks start of MSZIP frame)
           # Every MSZIP frame starts with a CK signature
-          if ENV["DEBUG_MSZIP"]
+          if @debug_mszip
             warn "DEBUG MSZIP: Reading CK signature (new MSZIP frame)"
           end
           read_signature
 
           # Inflate the MSZIP frame (processes deflate blocks until last_block or window full)
-          if ENV["DEBUG_MSZIP"]
+          if @debug_mszip
             warn "DEBUG MSZIP: Calling inflate_block"
           end
 
@@ -142,14 +146,14 @@ salvage: false, **_kwargs)
             @bytes_output = FRAME_SIZE
           end
 
-          if ENV["DEBUG_MSZIP"]
+          if @debug_mszip
             warn "DEBUG MSZIP: After inflate_block: bytes_output=#{@bytes_output} window_posn=#{@window_posn}"
           end
 
           # Now we have data in the window buffer - loop back to write from it
         end
 
-        if ENV["DEBUG_MSZIP"]
+        if @debug_mszip
           warn "DEBUG MSZIP.decompress: EXIT total_written=#{total_written}"
         end
 
@@ -160,7 +164,7 @@ salvage: false, **_kwargs)
 
       # Read and verify 'CK' signature
       def read_signature
-        if ENV["DEBUG_MSZIP"]
+        if @debug_mszip
           warn "DEBUG read_signature: Before byte_align"
         end
 
@@ -171,7 +175,7 @@ salvage: false, **_kwargs)
         c = @bitstream.read_bits(8)
         k = @bitstream.read_bits(8)
 
-        if ENV["DEBUG_MSZIP"]
+        if @debug_mszip
           warn "DEBUG read_signature: Read 0x#{c.to_s(16)} 0x#{k.to_s(16)} (expected 'C'=0x43 'K'=0x4B)"
         end
 
@@ -188,7 +192,7 @@ salvage: false, **_kwargs)
 
             if c == SIGNATURE_BYTE_C && k == SIGNATURE_BYTE_K
               found = true
-              if ENV["DEBUG_MSZIP"]
+              if @debug_mszip
                 warn "DEBUG read_signature: Found CK signature after searching"
               end
               break
@@ -211,7 +215,7 @@ salvage: false, **_kwargs)
         last_block = @bitstream.read_bits(1)
         block_type = @bitstream.read_bits(2)
 
-        if ENV["DEBUG_MSZIP"]
+        if @debug_mszip
           warn "DEBUG inflate_block: First block: last_block=#{last_block} block_type=#{block_type}"
         end
 
@@ -230,7 +234,7 @@ salvage: false, **_kwargs)
             raise DecompressionError, "Invalid block type: #{block_type}"
           end
 
-          if ENV["DEBUG_MSZIP"]
+          if @debug_mszip
             warn "DEBUG inflate_block: After block: last_block=#{last_block} window_posn=#{@window_posn}"
           end
 
@@ -383,7 +387,7 @@ salvage: false, **_kwargs)
       def inflate_huffman_block
         symbol_count = 0
         loop do
-          if ENV["DEBUG_MSZIP_SYMBOLS"]
+          if @debug_mszip_symbols
             warn "DEBUG inflate_huffman_block: window_posn=#{@window_posn} bytes_output=#{@bytes_output}"
           end
 
@@ -394,7 +398,7 @@ salvage: false, **_kwargs)
           )
           symbol_count += 1
 
-          if ENV["DEBUG_MSZIP_SYMBOLS"] || ENV["DEBUG_MSZIP"]
+          if @debug_mszip || @debug_mszip_symbols
             warn "DEBUG inflate_huffman_block[#{symbol_count}]: decoded code=#{code} (#{'0x%02x' % code if code < 256})"
           end
 
@@ -405,7 +409,7 @@ salvage: false, **_kwargs)
             flush_window if @window_posn == FRAME_SIZE
           elsif code == 256
             # End of block
-            if ENV["DEBUG_MSZIP"] || ENV["DEBUG_MSZIP_SYMBOLS"]
+            if @debug_mszip || @debug_mszip_symbols
               warn "DEBUG inflate_huffman_block: END OF BLOCK (window_posn=#{@window_posn})"
             end
             break

data/lib/cabriolet/decompressors/quantum.rb

@@ -60,12 +60,11 @@ module Cabriolet
         @window_bits = window_bits
         @window_size = 1 << window_bits
 
-        # Initialize window (mutable for Ruby < 3.2 bytesplice compatibility)
+        # Initialize window (must be binary to avoid UTF-8 character vs byte mismatch)
         @window = if String.method_defined?(:bytesplice)
-                    "\0" * @window_size
+                    ("\0" * @window_size).b
                   else
-                    # In Ruby < 3.2, create mutable window using String.new
-                    String.new("\0" * @window_size)
+                    String.new("\0" * @window_size, encoding: Encoding::BINARY)
                   end
         @window_posn = 0
         @frame_todo = FRAME_SIZE

data/lib/cabriolet/huffman/decoder.rb

@@ -52,8 +52,14 @@ num_symbols = nil)
                   "Huffman decode error: code too long"
           end
 
-          # Get the next bit from bit buffer at position idx
-          bit = (bitstream.peek_bits(idx + 1) >> idx) & 1
+          # Get the next bit from bit buffer at position idx.
+          # LSB mode: peek_bits returns bottom n bits; bit idx is at position idx.
+          # MSB mode: peek_bits returns top n bits right-justified; bit idx is the LSB.
+          bit = if bitstream.bit_order == :msb
+                  bitstream.peek_bits(idx + 1) & 1
+                else
+                  (bitstream.peek_bits(idx + 1) >> idx) & 1
+                end
 
           # Follow the tree path: (current_entry << 1) | bit
           next_idx = (sym << 1) | bit

data/lib/cabriolet/plugin_manager.rb

@@ -259,11 +259,11 @@ module Cabriolet
         else
           @plugins.select { |_, entry| entry[:state] == state }
             .transform_values do |entry|
-              {
-                metadata: entry[:metadata],
-                state: entry[:state],
-                error: entry[:error],
-              }
+            {
+              metadata: entry[:metadata],
+              state: entry[:state],
+              error: entry[:error],
+            }
           end
         end
       end

data/lib/cabriolet/system/file_handle.rb

@@ -98,7 +98,7 @@ module Cabriolet
                       raise ArgumentError, "Invalid mode: #{mode}"
                     end
 
-        ::File.open(@filename, file_mode)
+        ::File.open(@filename, file_mode) # rubocop:disable Style/FileOpen -- lifecycle managed by close/closed?
       rescue Errno::ENOENT, Errno::EACCES => e
         raise IOError, "Cannot open file #{@filename}: #{e.message}"
       end

data/lib/cabriolet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cabriolet
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/lib/cabriolet.rb

@@ -65,101 +65,99 @@ module Cabriolet
   # Default buffer size of 64KB - better for modern systems
   # Larger buffers reduce I/O syscall overhead significantly
   self.default_buffer_size = 65_536
-end
 
-# Models
-require_relative "cabriolet/models/cabinet"
-require_relative "cabriolet/models/folder"
-require_relative "cabriolet/models/folder_data"
-require_relative "cabriolet/models/file"
-require_relative "cabriolet/models/chm_header"
-require_relative "cabriolet/models/chm_section"
-require_relative "cabriolet/models/chm_file"
-require_relative "cabriolet/models/szdd_header"
-require_relative "cabriolet/models/kwaj_header"
-require_relative "cabriolet/models/hlp_header"
-require_relative "cabriolet/models/hlp_file"
-require_relative "cabriolet/models/winhelp_header"
-require_relative "cabriolet/models/lit_header"
-require_relative "cabriolet/models/oab_header"
-
-# Load errors first (needed by algorithm_factory)
-
-# Load plugin system
-require_relative "cabriolet/plugin"
-require_relative "cabriolet/plugin_validator"
-require_relative "cabriolet/plugin_manager"
-
-# Load algorithm factory
-require_relative "cabriolet/algorithm_factory"
-
-# Load core components
-
-require_relative "cabriolet/quantum_shared"
-
-require_relative "cabriolet/huffman/tree"
-require_relative "cabriolet/huffman/decoder"
-require_relative "cabriolet/huffman/encoder"
-
-require_relative "cabriolet/decompressors/base"
-require_relative "cabriolet/decompressors/none"
-require_relative "cabriolet/decompressors/lzss"
-require_relative "cabriolet/decompressors/mszip"
-require_relative "cabriolet/decompressors/lzx"
-require_relative "cabriolet/decompressors/quantum"
-
-require_relative "cabriolet/compressors/base"
-require_relative "cabriolet/compressors/lzss"
-require_relative "cabriolet/compressors/mszip"
-require_relative "cabriolet/compressors/lzx"
-require_relative "cabriolet/compressors/quantum"
-
-require_relative "cabriolet/cab/parser"
-require_relative "cabriolet/cab/decompressor"
-require_relative "cabriolet/cab/extractor"
-require_relative "cabriolet/cab/compressor"
-
-require_relative "cabriolet/chm/parser"
-require_relative "cabriolet/chm/decompressor"
-require_relative "cabriolet/chm/compressor"
-
-require_relative "cabriolet/szdd/parser"
-require_relative "cabriolet/szdd/decompressor"
-require_relative "cabriolet/szdd/compressor"
-
-require_relative "cabriolet/kwaj/parser"
-require_relative "cabriolet/kwaj/decompressor"
-require_relative "cabriolet/kwaj/compressor"
-
-require_relative "cabriolet/hlp/parser"
-require_relative "cabriolet/hlp/decompressor"
-require_relative "cabriolet/hlp/compressor"
-
-require_relative "cabriolet/hlp/winhelp/parser"
-require_relative "cabriolet/hlp/winhelp/zeck_lz77"
-require_relative "cabriolet/hlp/winhelp/decompressor"
-require_relative "cabriolet/hlp/winhelp/compressor"
-
-require_relative "cabriolet/lit/decompressor"
-require_relative "cabriolet/lit/compressor"
-
-require_relative "cabriolet/oab/decompressor"
-require_relative "cabriolet/oab/compressor"
-
-# Load new advanced features
-require_relative "cabriolet/format_detector"
-require_relative "cabriolet/extraction/base_extractor"
-require_relative "cabriolet/extraction/extractor"
-require_relative "cabriolet/streaming"
-require_relative "cabriolet/validator"
-require_relative "cabriolet/repairer"
-require_relative "cabriolet/modifier"
-
-# Load CLI (optional, for command-line usage)
-require_relative "cabriolet/cli"
-
-# Convenience methods at top level
-module Cabriolet
+  # Models
+  require_relative "cabriolet/models/cabinet"
+  require_relative "cabriolet/models/folder"
+  require_relative "cabriolet/models/folder_data"
+  require_relative "cabriolet/models/file"
+  require_relative "cabriolet/models/chm_header"
+  require_relative "cabriolet/models/chm_section"
+  require_relative "cabriolet/models/chm_file"
+  require_relative "cabriolet/models/szdd_header"
+  require_relative "cabriolet/models/kwaj_header"
+  require_relative "cabriolet/models/hlp_header"
+  require_relative "cabriolet/models/hlp_file"
+  require_relative "cabriolet/models/winhelp_header"
+  require_relative "cabriolet/models/lit_header"
+  require_relative "cabriolet/models/oab_header"
+
+  # Load errors first (needed by algorithm_factory)
+
+  # Load plugin system
+  require_relative "cabriolet/plugin"
+  require_relative "cabriolet/plugin_validator"
+  require_relative "cabriolet/plugin_manager"
+
+  # Load algorithm factory
+  require_relative "cabriolet/algorithm_factory"
+
+  # Load core components
+
+  require_relative "cabriolet/quantum_shared"
+
+  require_relative "cabriolet/huffman/tree"
+  require_relative "cabriolet/huffman/decoder"
+  require_relative "cabriolet/huffman/encoder"
+
+  require_relative "cabriolet/decompressors/base"
+  require_relative "cabriolet/decompressors/none"
+  require_relative "cabriolet/decompressors/lzss"
+  require_relative "cabriolet/decompressors/mszip"
+  require_relative "cabriolet/decompressors/lzx"
+  require_relative "cabriolet/decompressors/quantum"
+
+  require_relative "cabriolet/compressors/base"
+  require_relative "cabriolet/compressors/lzss"
+  require_relative "cabriolet/compressors/mszip"
+  require_relative "cabriolet/compressors/lzx"
+  require_relative "cabriolet/compressors/quantum"
+
+  require_relative "cabriolet/cab/parser"
+  require_relative "cabriolet/cab/decompressor"
+  require_relative "cabriolet/cab/extractor"
+  require_relative "cabriolet/cab/compressor"
+
+  require_relative "cabriolet/chm/parser"
+  require_relative "cabriolet/chm/decompressor"
+  require_relative "cabriolet/chm/compressor"
+
+  require_relative "cabriolet/szdd/parser"
+  require_relative "cabriolet/szdd/decompressor"
+  require_relative "cabriolet/szdd/compressor"
+
+  require_relative "cabriolet/kwaj/parser"
+  require_relative "cabriolet/kwaj/decompressor"
+  require_relative "cabriolet/kwaj/compressor"
+
+  require_relative "cabriolet/hlp/parser"
+  require_relative "cabriolet/hlp/decompressor"
+  require_relative "cabriolet/hlp/compressor"
+
+  require_relative "cabriolet/hlp/winhelp/parser"
+  require_relative "cabriolet/hlp/winhelp/zeck_lz77"
+  require_relative "cabriolet/hlp/winhelp/decompressor"
+  require_relative "cabriolet/hlp/winhelp/compressor"
+
+  require_relative "cabriolet/lit/decompressor"
+  require_relative "cabriolet/lit/compressor"
+
+  require_relative "cabriolet/oab/decompressor"
+  require_relative "cabriolet/oab/compressor"
+
+  # Load new advanced features
+  require_relative "cabriolet/format_detector"
+  require_relative "cabriolet/extraction/base_extractor"
+  require_relative "cabriolet/extraction/extractor"
+  require_relative "cabriolet/streaming"
+  require_relative "cabriolet/validator"
+  require_relative "cabriolet/repairer"
+  require_relative "cabriolet/modifier"
+
+  # Load CLI (optional, for command-line usage)
+  require_relative "cabriolet/cli"
+
+  # Convenience methods
   class << self
     # Open and parse an archive with automatic format detection
     #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cabriolet
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-20 00:00:00.000000000 Z
+date: 2026-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bindata