gemba 0.1.1 → 0.2.0

data/lib/gemba/rom_info.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+
+module Gemba
+  # Immutable snapshot of everything known about a single ROM.
+  #
+  # Aggregates data from multiple sources:
+  #   - RomLibrary entry  (title, path, game_code, platform, rom_id)
+  #   - GameIndex         (has_official_entry — whether libretro knows about it)
+  #   - BoxartFetcher     (cached_boxart_path — auto-fetched cover art)
+  #   - RomOverrides      (custom_boxart_path — user-chosen cover art)
+  #
+  # Use RomInfo.from_rom to construct from a raw library entry hash.
+  # Use #boxart_path to get the effective cover image (custom beats cache).
+  RomInfo = Data.define(
+    :rom_id,             # String  — unique ROM identifier (game_code + CRC32)
+    :title,              # String  — display name
+    :platform,           # String  — uppercased, e.g. "GBA"
+    :game_code,          # String? — 4-char code e.g. "AGB-AXVE", or nil
+    :path,               # String  — absolute path to the ROM file
+    :md5,                # String? — MD5 hex digest of ROM content, or nil (lazy)
+    :has_official_entry, # Boolean — GameIndex has an entry for this game_code
+    :cached_boxart_path, # String? — auto-fetched cover from libretro CDN, or nil
+    :custom_boxart_path  # String? — user-set cover image path, or nil
+  ) do
+    # Effective cover image path: custom override wins, then fetched cache, then nil.
+    def boxart_path
+      return custom_boxart_path if custom_boxart_path && File.exist?(custom_boxart_path)
+      return cached_boxart_path if cached_boxart_path && File.exist?(cached_boxart_path)
+      nil
+    end
+
+    # Build a RomInfo from a raw rom_library entry hash.
+    #
+    # @param rom      [Hash]          entry from RomLibrary#all
+    # @param fetcher  [BoxartFetcher, nil]
+    # @param overrides [RomOverrides, nil]
+    def self.from_rom(rom, fetcher: nil, overrides: nil, game_index: GameIndex)
+      game_code = rom['game_code']
+      rom_id    = rom['rom_id']
+
+      new(
+        rom_id:             rom_id,
+        title:              game_index.lookup(game_code) ||
+                            game_index.lookup_by_md5(rom['md5'], rom['platform'] || 'gba') ||
+                            rom['title'] || rom['rom_id'] || '???',
+        platform:           (rom['platform'] || 'gba').upcase,
+        game_code:          game_code,
+        path:               rom['path'],
+        md5:                rom['md5'],
+        has_official_entry: game_code ? !game_index.lookup(game_code).nil? : false,
+        cached_boxart_path: (fetcher.cached_path(game_code) if fetcher&.cached?(game_code)),
+        custom_boxart_path: overrides&.custom_boxart(rom_id),
+      )
+    end
+  end
+end

data/lib/gemba/rom_info_window.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "child_window"
-require_relative "locale"
 
 module Gemba
   # Displays ROM metadata in a read-only window.
@@ -259,6 +257,21 @@ module Gemba
       hide_window(modal: false)
     end
 
+    # ModalStack protocol (non-modal — no grab)
+    def show_modal(core: nil, rom_path: nil, save_path: nil, **_)
+      build_ui unless @built
+      populate(core, rom_path, save_path) if core
+      position_near_parent
+      top = self.class::TOP
+      @app.command(:wm, 'deiconify', top)
+      @app.command(:raise, top)
+    end
+
+    def withdraw
+      top = self.class::TOP
+      @app.command(:wm, 'withdraw', top)
+    end
+
     private
 
     def build_ui
@@ -318,7 +331,7 @@ module Gemba
       publisher = maker.empty? ? na : "#{self.class.publisher_name(maker)} (#{maker})"
       set_field('publisher', publisher)
 
-      set_field('platform', core.platform)
+      set_field('platform', Platform.for(core).name)
       set_field('rom_size', format_size(core.rom_size))
       set_field('checksum', "0x%08X" % core.checksum)
       set_field('rom_path', rom_path || na)

data/lib/gemba/rom_library.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'time'
+
+module Gemba
+  # Persistent catalog of known ROMs.
+  #
+  # Stored as JSON at Config.config_dir/rom_library.json. Each entry records
+  # the ROM's path, title, game code, rom_id, platform, and timestamps.
+  # The library is loaded once on boot and updated whenever a ROM is loaded.
+  class RomLibrary
+    FILENAME = 'rom_library.json'
+
+    def initialize(path = self.class.default_path, subscribe: true)
+      @path = path
+      @roms = []
+      load!
+      subscribe_to_bus if subscribe
+    end
+
+    def self.default_path
+      File.join(Config.config_dir, FILENAME)
+    end
+
+    # All known ROMs, sorted by last_played descending (most recent first).
+    # @return [Array<Hash>]
+    def all
+      @roms.sort_by { |r| r['last_played'] || r['added_at'] || '' }.reverse
+    end
+
+    # Add or update a ROM entry. Upserts by rom_id.
+    # @param attrs [Hash] must include 'rom_id'; other keys merged in
+    def add(attrs)
+      rom_id = attrs['rom_id'] || attrs[:rom_id]
+      raise ArgumentError, 'rom_id is required' unless rom_id
+
+      attrs = stringify_keys(attrs)
+      existing = @roms.find { |r| r['rom_id'] == rom_id }
+      if existing
+        existing.merge!(attrs)
+      else
+        attrs['added_at'] ||= Time.now.utc.iso8601
+        @roms << attrs
+      end
+    end
+
+    # Remove a ROM entry by rom_id.
+    def remove(rom_id)
+      @roms.reject! { |r| r['rom_id'] == rom_id }
+    end
+
+    # Update last_played timestamp for a ROM.
+    def touch(rom_id)
+      entry = find(rom_id)
+      entry['last_played'] = Time.now.utc.iso8601 if entry
+    end
+
+    # Find a ROM entry by rom_id.
+    # @return [Hash, nil]
+    def find(rom_id)
+      @roms.find { |r| r['rom_id'] == rom_id }
+    end
+
+    # @return [Integer]
+    def size
+      @roms.size
+    end
+
+    # Persist to disk.
+    def save!
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, JSON.pretty_generate({ 'roms' => @roms }))
+    end
+
+    private
+
+    def subscribe_to_bus
+      Gemba.bus.on(:rom_loaded) do |rom_id:, path:, title:, game_code:, platform:, md5: nil, **|
+        add(
+          'rom_id'    => rom_id,
+          'path'      => path,
+          'title'     => title,
+          'game_code' => game_code,
+          'platform'  => platform.downcase,
+          'md5'       => md5,
+        )
+        touch(rom_id)
+        save!
+      end
+    end
+
+    def load!
+      return unless File.exist?(@path)
+      data = JSON.parse(File.read(@path))
+      @roms = data['roms'] || []
+    rescue JSON::ParserError
+      @roms = []
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+  end
+end

data/lib/gemba/rom_overrides.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Gemba
+  # Persists per-ROM user overrides to config_dir/rom_overrides.json.
+  #
+  # Keyed by rom_id (game_code + CRC32 checksum) — the most stable
+  # identifier for a ROM across renames or moves.
+  #
+  # Currently tracks:
+  #   custom_boxart — absolute path to a user-chosen cover image
+  #
+  # Custom images are copied into config_dir/boxart/{rom_id}/custom.{ext}
+  # so they remain accessible even if the original file is moved or deleted.
+  class RomOverrides
+    def initialize(path = Config.rom_overrides_path)
+      @path = path
+      @data = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+    end
+
+    # @return [String, nil] absolute path to the custom boxart, or nil
+    def custom_boxart(rom_id)
+      @data.dig(rom_id.to_s, 'custom_boxart')
+    end
+
+    # Copies src_path into the gemba boxart cache and records the dest path.
+    # @return [String] the destination path
+    def set_custom_boxart(rom_id, src_path)
+      ext  = File.extname(src_path)
+      dest = File.join(Config.boxart_dir, rom_id.to_s, "custom#{ext}")
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.cp(src_path, dest)
+      (@data[rom_id.to_s] ||= {})['custom_boxart'] = dest
+      save
+      dest
+    end
+
+    private
+
+    def save
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, JSON.pretty_generate(@data))
+    end
+  end
+end

data/lib/gemba/rom_patcher/bps.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require 'stringio'
+
+module Gemba
+  class RomPatcher
+    # Applies a BPS (Beat Patch System) patch.
+    #
+    # File layout:
+    #
+    #   ┌──────────────────────────────────────────────────────┐
+    #   │  "BPS1"  (4 bytes, magic)                           │
+    #   ├──────────────────────────────────────────────────────┤
+    #   │  source_size    (varint)                            │
+    #   │  target_size    (varint)                            │
+    #   │  metadata_size  (varint)                            │
+    #   │  metadata       (<metadata_size> bytes, skipped)   │
+    #   ├──────────────────────────────────────────────────────┤
+    #   │  actions …  (repeated until patch.size - 12)        │
+    #   ├──────────────────────────────────────────────────────┤
+    #   │  src_crc32    4B LE  │  tgt_crc32  4B LE  │ patch  │ ← footer
+    #   └──────────────────────────────────────────────────────┘
+    #
+    # Each action word (varint):  word = (length - 1) << 2 | mode
+    #
+    #   mode 0  SourceRead   ┌────────┐  copy `length` bytes from source
+    #                        │  word  │  at current output offset
+    #                        └────────┘
+    #
+    #   mode 1  TargetRead   ┌────────┬──────────────────────┐
+    #                        │  word  │  data  (<length> B)  │
+    #                        └────────┴──────────────────────┘
+    #
+    #   mode 2  SourceCopy   ┌────────┬───────────┐  seek src by signed delta,
+    #                        │  word  │  delta(v) │  copy `length` bytes
+    #                        └────────┴───────────┘
+    #
+    #   mode 3  TargetCopy   ┌────────┬───────────┐  seek already-written target
+    #                        │  word  │  delta(v) │  by signed delta, copy
+    #                        └────────┴───────────┘
+    #
+    # BPS varint encoding (7-bit groups, additive-shift, differs from UPS):
+    #   Each byte holds 7 data bits (b & 0x7f = 0b01111111) and one flag bit
+    #   (b & 0x80).  Flag=1 means last byte; flag=0 means more follow.
+    #   Unlike UPS (bitwise OR + left-shift), BPS uses multiplication and adds
+    #   an extra `shift` after each non-terminal byte so that 0x00 is never a
+    #   valid single-byte encoding — this lets the format distinguish "no data"
+    #   from an actual zero value.
+    #   value = 0, shift = 1
+    #   per byte:  value += (b & 0x7f) * shift
+    #              if bit7 set → done;  else shift <<= 7; value += shift
+    #
+    #   Example: value 300 decoded from bytes [0x2C, 0x81]
+    #   raw byte  │  & 0x7f  │  shift  │  value after        │  bit7  │  action
+    #   ──────────┼──────────┼─────────┼─────────────────────┼────────┼───────────────────────────
+    #   0x2C      │    44    │    1    │  0 + 44×1    =  44  │   0    │  shift<<=7 (→128); value+=128 (→172)
+    #   0x81      │     1    │  128    │  172 + 1×128 = 300  │   1    │  break
+    class BPS
+      # @param rom   [String] binary ROM data
+      # @param patch [String] binary BPS patch data
+      # @return [String] patched ROM (binary)
+      # @raise [RuntimeError] on CRC32 mismatch
+      def self.apply(rom, patch, on_progress: nil)
+        raise "BPS patch too small to be valid" if patch.bytesize < 16
+        rom   = rom.b
+        patch = patch.b
+        io = StringIO.new(patch)
+        io.read(4) # "BPS1"
+
+        read_varint(io) # source_size — not used; target_size drives allocation
+        target_size   = read_varint(io)
+        metadata_size = read_varint(io)
+        skip = io.read(metadata_size)
+        raise "Truncated BPS metadata" if skip&.bytesize != metadata_size
+
+        target     = "\x00".b * target_size
+        out_offset = 0
+        src_offset = 0
+        tgt_offset = 0
+        patch_end  = patch.bytesize - 12
+
+        last_pct = -1
+
+        while io.pos < patch_end
+          if on_progress
+            pct = (io.pos / patch_end.to_f * 100).floor
+            if pct != last_pct
+              on_progress.call(pct / 100.0)
+              last_pct = pct
+            end
+          end
+
+          word   = read_varint(io)
+          mode   = word & 3
+          length = (word >> 2) + 1
+
+          case mode
+          when 0 # SourceRead — copy from rom at current out position
+            length.times do
+              target.setbyte(out_offset, rom.getbyte(out_offset) || 0)
+              out_offset += 1
+            end
+          when 1 # TargetRead — literal data
+            data = io.read(length)
+            target[out_offset, length] = data
+            out_offset += length
+          when 2 # SourceCopy — relative seek in source
+            src_offset += read_signed_varint(io)
+            length.times do
+              target.setbyte(out_offset, rom.getbyte(src_offset) || 0)
+              out_offset += 1
+              src_offset += 1
+            end
+          when 3 # TargetCopy — relative seek in target
+            tgt_offset += read_signed_varint(io)
+            length.times do
+              target.setbyte(out_offset, target.getbyte(tgt_offset) || 0)
+              out_offset += 1
+              tgt_offset += 1
+            end
+          end
+        end
+
+        raise "BPS patch too small to contain footer" if patch.bytesize < 12
+        src_crc, tgt_crc = patch[-12..].unpack("VV")
+        raise "BPS source CRC32 mismatch" unless Zlib.crc32(rom)    == src_crc
+        raise "BPS target CRC32 mismatch" unless Zlib.crc32(target) == tgt_crc
+
+        target
+      end
+
+      # BPS varint: low 7 bits per byte; bit7=1 terminates; additive shift encoding.
+      # Decoder: value = 0, shift = 1; per byte: value += (b & 0x7f) * shift;
+      #          if bit7: break; else: shift <<= 7; value += shift.
+      def self.read_varint(io)
+        value = 0
+        shift = 1
+        loop do
+          byte = io.read(1)
+          raise "Truncated BPS patch (varint read past end)" if byte.nil?
+          b      = byte.getbyte(0)
+          value += (b & 0x7f) * shift
+          break if (b & 0x80) != 0
+          shift <<= 7
+          value += shift
+        end
+        value
+      end
+      private_class_method :read_varint
+
+      def self.read_signed_varint(io)
+        v        = read_varint(io)
+        negative = (v & 1) != 0
+        v >>= 1
+        negative ? -v : v
+      end
+      private_class_method :read_signed_varint
+    end
+  end
+end

data/lib/gemba/rom_patcher/ips.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module Gemba
+  class RomPatcher
+    # Applies an IPS (International Patching System) patch.
+    #
+    # File layout:
+    #
+    #   ┌─────────────────────────────────────────────┐
+    #   │  "PATCH"  (5 bytes, magic)                  │
+    #   ├─────────────────────────────────────────────┤
+    #   │  Record 1                                   │
+    #   │  Record 2                                   │
+    #   │  ...                                        │
+    #   ├─────────────────────────────────────────────┤
+    #   │  "EOF"  (3 bytes, terminator)               │
+    #   └─────────────────────────────────────────────┘
+    #
+    # Record formats:
+    #
+    #   Normal record:
+    #   ┌────────────────────┬───────────────────┬─────────────────────┐
+    #   │ offset             │  size             │  data               │
+    #   │ 3 bytes, big-endian│ 2 bytes, big-endian│  <size> bytes      │
+    #   └────────────────────┴───────────────────┴─────────────────────┘
+    #
+    #   RLE record — size field is 0x0000 (zero), which is the signal that
+    #   this is NOT a normal data record. Instead of inline bytes, the next
+    #   two fields say "repeat one byte N times":
+    #   ┌────────────────────┬──────────┬────────────────────┬──────────┐
+    #   │ offset             │  0x0000  │  count             │  value   │
+    #   │ 3 bytes, big-endian│  2 bytes │ 2 bytes, big-endian│  1 byte  │
+    #   └────────────────────┴──────────┴────────────────────┴──────────┘
+    #   Writes `value` repeated `count` times starting at `offset`.
+    #   e.g. offset=0x100, count=8, value=0xFF → fills 8 bytes with 0xFF.
+    #
+    # No checksums — no integrity verification.
+    class IPS
+      EOF_MARKER = "EOF".b.freeze
+
+      # @param rom   [String] binary ROM data
+      # @param patch [String] binary IPS patch data
+      # @return [String] patched ROM (binary)
+      def self.apply(rom, patch, on_progress: nil)
+        rom   = rom.b
+        patch = patch.b
+        result = rom.dup
+        io = StringIO.new(patch)
+        read!(io, 5) # "PATCH"
+
+        total    = patch.bytesize.to_f
+        last_pct = -1
+
+        loop do
+          offset_bytes = io.read(3)
+          break if offset_bytes.nil? || offset_bytes == EOF_MARKER
+          raise "Truncated patch: incomplete offset record" if offset_bytes.bytesize < 3
+
+          offset = (offset_bytes.getbyte(0) << 16) |
+                   (offset_bytes.getbyte(1) << 8)  |
+                    offset_bytes.getbyte(2)
+
+          size = read!(io, 2).unpack1("n")  # "n" = 16-bit unsigned big-endian
+
+          data = if size == 0
+                   count = read!(io, 2).unpack1("n")  # "n" = 16-bit unsigned big-endian
+                   value = read!(io, 1)
+                   value * count
+                 else
+                   read!(io, size)
+                 end
+
+          # Extend ROM if patch writes past current end
+          needed = offset + data.bytesize
+          result << "\x00".b * (needed - result.bytesize) if needed > result.bytesize
+          result[offset, data.bytesize] = data
+
+          if on_progress
+            pct = (io.pos / total * 100).floor
+            if pct != last_pct
+              on_progress.call(pct / 100.0)
+              last_pct = pct
+            end
+          end
+        end
+
+        result
+      end
+
+      def self.read!(io, n)
+        data = io.read(n)
+        raise "Truncated IPS patch (expected #{n} bytes, got #{data&.bytesize || 0})" \
+          if data.nil? || data.bytesize < n
+        data
+      end
+      private_class_method :read!
+    end
+  end
+end

data/lib/gemba/rom_patcher/ups.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'zlib'
+require 'stringio'
+
+module Gemba
+  class RomPatcher
+    # Applies a UPS (Universal Patching System) patch.
+    #
+    # File layout:
+    #
+    #   ┌──────────────────────────────────────────────────────┐
+    #   │  "UPS1"  (4 bytes, magic)                           │
+    #   ├──────────────────────────────────────────────────────┤
+    #   │  source_size  (varint)                              │
+    #   │  target_size  (varint)                              │
+    #   ├──────────────────────────────────────────────────────┤
+    #   │  hunks …  (repeated until patch.size - 12)          │
+    #   ├──────────────────────────────────────────────────────┤
+    #   │  src_crc32  4B LE  │  tgt_crc32  4B LE  │  patch   │ ← footer
+    #   └──────────────────────────────────────────────────────┘
+    #
+    # Each hunk:
+    #   ┌──────────────────┬──────────────────────────────────┐
+    #   │  skip  (varint)  │  xor_data …  0x00                │
+    #   └──────────────────┴──────────────────────────────────┘
+    #
+    #   skip     — advance output position by this many bytes (unchanged bytes)
+    #   xor_data — each byte XOR'd with the corresponding output byte; 0x00 ends the run
+    #
+    # Example: source  = [AA BB CC DD EE FF]
+    #          hunk 1:  skip=1, xor=[11 22], 0x00
+    #          result:  [AA (BB^11) (CC^22) DD EE FF]
+    #                        ↑ changed  ↑ changed
+    #
+    # UPS varint encoding (7-bit groups, LSB first):
+    #   Each byte holds 7 data bits (b & 0x7f = 0b01111111) and one flag bit
+    #   (b & 0x80).  Flag=1 means this is the last byte; flag=0 means more follow.
+    #   value = 0, shift = 0
+    #   per byte:  value |= (b & 0x7f) << shift
+    #              if bit7 set → done;  else shift += 7
+    #
+    #   Example: value 300 decoded from bytes [0x2C, 0x82]
+    #   raw byte  │  & 0x7f  │  shift  │  value after          │  bit7  │  action
+    #   ──────────┼──────────┼─────────┼───────────────────────┼────────┼──────────
+    #   0x2C      │   0x2C   │   0     │  0x2C        (44)     │   0    │  shift += 7
+    #   0x82      │   0x02   │   7     │  0x2C│0x100  (300)    │   1    │  break
+    class UPS
+      # @param rom   [String] binary ROM data
+      # @param patch [String] binary UPS patch data
+      # @return [String] patched ROM (binary)
+      # @raise [RuntimeError] on CRC32 mismatch
+      def self.apply(rom, patch, on_progress: nil)
+        rom   = rom.b
+        patch = patch.b
+        io = StringIO.new(patch)
+        io.read(4) # "UPS1"
+
+        read_varint(io) # source_size — not needed; we derive target from target_size
+        target_size  = read_varint(io)
+
+        result = if rom.bytesize >= target_size
+                   rom[0, target_size].dup
+                 else
+                   rom + "\x00".b * (target_size - rom.bytesize)
+                 end
+
+        pos       = 0
+        patch_end = patch.bytesize - 12
+        last_pct  = -1
+
+        while io.pos < patch_end
+          if on_progress
+            pct = (io.pos / patch_end.to_f * 100).floor
+            if pct != last_pct
+              on_progress.call(pct / 100.0)
+              last_pct = pct
+            end
+          end
+
+          pos += read_varint(io)
+
+          while io.pos < patch_end
+            b = io.read(1).getbyte(0)
+            break if b == 0x00
+            result.setbyte(pos, (result.getbyte(pos) || 0) ^ b) if pos < result.bytesize
+            pos += 1
+          end
+          pos += 1 # advance past the matching byte at the hunk boundary
+        end
+
+        src_crc, tgt_crc = patch[-12..].unpack("VV")
+        raise "UPS source CRC32 mismatch" unless Zlib.crc32(rom)    == src_crc
+        raise "UPS target CRC32 mismatch" unless Zlib.crc32(result) == tgt_crc
+
+        result
+      end
+
+      # UPS varint: low 7 bits per byte; bit7=1 terminates; simple bitshift accumulation.
+      # Decoder: value = 0, shift = 0; per byte: value |= (b & 0x7f) << shift;
+      #          if bit7: break; else: shift += 7.
+      def self.read_varint(io)
+        value = 0
+        shift = 0
+        loop do
+          byte = io.read(1)
+          raise "Truncated UPS patch (varint read past end)" if byte.nil?
+          b      = byte.getbyte(0)
+          value |= (b & 0x7f) << shift
+          break if (b & 0x80) != 0
+          shift += 7
+        end
+        value
+      end
+      private_class_method :read_varint
+    end
+  end
+end