gemba 0.1.0

data/lib/gemba/tip_service.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Click-to-show tooltip service for Tk widgets.
+  #
+  # Labels registered with {#register} get an underlined font (like HTML
+  # <abbr>). Clicking them shows a tooltip popup below the label. Only one
+  # tooltip is visible at a time; it auto-dismisses after {#dismiss_ms}
+  # unless the mouse hovers over the tip or its label.
+  #
+  # The tooltip is rendered as a frame inside the parent window (not a
+  # toplevel), so it draws as a true rectangle on all platforms.
+  #
+  # @example
+  #   tips = TipService.new(app, parent: '.settings')
+  #   tips.register('.settings.nb.video.lbl_color', 'Adjusts GBA LCD colors')
+  class TipService
+    DEFAULT_DISMISS_MS = 4000
+
+    # Tooltip colors (pale yellow with gray border, dark text)
+    TIP_BG      = '#FFFFEE'
+    TIP_FG      = '#333333'
+    TIP_BORDER  = '#999999'
+
+    # @param app [Teek::App]
+    # @param parent [String] parent Toplevel path (for unique tooltip path)
+    # @param dismiss_ms [Integer] auto-dismiss delay in milliseconds
+    def initialize(app, parent: '.', dismiss_ms: DEFAULT_DISMISS_MS)
+      @app = app
+      @parent = parent
+      @tip_path = parent == '.' ? '.__tip' : "#{parent}.__tip"
+      @dismiss_ms = dismiss_ms
+      @target = nil
+      @timer = nil
+      @click_guard = false
+
+      # Underlined font for registered labels
+      @font_name = "__tip_font_#{parent.tr('.', '_')}"
+      @app.tcl_eval("catch {font create #{@font_name} {*}[font actual TkDefaultFont] -underline 1}")
+
+      # Click anywhere in the parent window dismisses the tooltip,
+      # unless the click was on a registered label (guard prevents that).
+      @app.command(:bind, @parent, '<Button-1>', proc {
+        if @click_guard
+          @click_guard = false
+        elsif showing?
+          hide
+        end
+      })
+    end
+
+    # @return [Integer] auto-dismiss delay in milliseconds
+    attr_accessor :dismiss_ms
+
+    # @return [String, nil] widget path of the currently showing tip's label
+    attr_reader :target
+
+    # Register a widget for click-to-show tooltip.
+    # @param widget_path [String] Tk widget path (typically a label)
+    # @param text [String] tooltip text (may contain \n for line breaks)
+    def register(widget_path, text)
+      @app.command(widget_path, 'configure', font: @font_name)
+      @app.command(:bind, widget_path, '<Button-1>', proc { toggle(widget_path, text) })
+      @app.command(:bind, widget_path, '<Enter>', proc { cancel_dismiss })
+      @app.command(:bind, widget_path, '<Leave>', proc { schedule_dismiss })
+    end
+
+    # Show a tooltip below the given widget. Hides any existing tip first.
+    # @param widget_path [String]
+    # @param text [String]
+    def show(widget_path, text)
+      hide
+
+      @target = widget_path
+
+      # Position relative to the parent toplevel
+      lx, ly, _lw, lh = @app.interp.window_geometry(widget_path)
+      px, py, _pw, _ph = @app.interp.window_geometry(@parent)
+      rel_x = lx - px
+      rel_y = ly - py + lh + 4
+
+      # Border frame (1px border effect via padding)
+      @app.command(:frame, @tip_path, background: TIP_BORDER, borderwidth: 0)
+
+      @app.command(:label, "#{@tip_path}.l",
+        text: text, background: TIP_BG, foreground: TIP_FG,
+        padx: 8, pady: 6, justify: :left)
+      @app.command(:pack, "#{@tip_path}.l", padx: 1, pady: 1)
+
+      @app.command(:place, @tip_path, x: rel_x, y: rel_y)
+      @app.command(:raise, @tip_path)
+
+      # Pause auto-dismiss while hovering the tooltip itself
+      @app.command(:bind, @tip_path, '<Enter>', proc { cancel_dismiss })
+      @app.command(:bind, @tip_path, '<Leave>', proc { schedule_dismiss })
+    end
+
+    # Hide the current tooltip.
+    def hide
+      cancel_dismiss
+      @target = nil
+      @app.tcl_eval("catch {destroy #{@tip_path}}")
+    end
+
+    # @return [Boolean] true if a tooltip is currently visible
+    def showing?
+      !!@target
+    end
+
+    private
+
+    def toggle(widget_path, text)
+      @click_guard = true
+      if @target == widget_path
+        hide
+      else
+        show(widget_path, text)
+      end
+    end
+
+    def schedule_dismiss
+      cancel_dismiss
+      @timer = @app.after(@dismiss_ms) { hide }
+    end
+
+    def cancel_dismiss
+      if @timer
+        @app.command(:after, :cancel, @timer)
+        @timer = nil
+      end
+    end
+  end
+end

data/lib/gemba/toast_overlay.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Gemba
+  # Renders timed notification toasts at the bottom of the game viewport.
+  #
+  # One toast at a time; showing a new one replaces the old. The background
+  # is a pre-rendered anti-aliased rounded rectangle (generated in C).
+  #
+  # All SDL2 objects (renderer, font, textures) are injected or created
+  # internally, so the class can be tested with lightweight mocks.
+  #
+  # @example
+  #   toast = ToastOverlay.new(renderer: vp.renderer, font: font, duration: 1.5)
+  #   toast.show("State saved to slot 1")
+  #   # inside render loop:
+  #   toast.draw(r, dest_rect)
+  class ToastOverlay
+    PAD_X  = 14
+    PAD_Y  = 8
+    RADIUS = 8
+
+    # @param renderer [Teek::SDL2::Renderer] creates background textures
+    # @param font [Teek::SDL2::Font] renders toast text
+    # @param duration [Float] default display time in seconds
+    # @param bg_fn [#call] generates ARGB pixel data for the rounded-rect
+    #   background; signature: bg_fn.call(w, h, radius) → String.
+    #   Defaults to the C-implemented {Gemba.toast_background}.
+    def initialize(renderer:, font:, duration: 1.5, bg_fn: Gemba.method(:toast_background))
+      @renderer = renderer
+      @font = font
+      @duration = duration
+      @bg_fn = bg_fn
+      @crop_h = compute_crop_h(font)
+      @bg_tex = nil
+      @text_tex = nil
+    end
+
+    # @return [Float] default display duration in seconds
+    attr_accessor :duration
+
+    # Whether a toast is currently visible.
+    # @return [Boolean]
+    def visible?
+      !!@bg_tex
+    end
+
+    # Display a toast message. Replaces any existing toast.
+    #
+    # @param message [String]
+    # @param duration [Float, nil] seconds; nil uses the default
+    # @param permanent [Boolean] stays until {#destroy} is called
+    def show(message, duration: nil, permanent: false)
+      destroy
+
+      @text_tex = @font.render_text(message, 255, 255, 255)
+      tw = @text_tex.width
+      th = @crop_h || @text_tex.height
+
+      box_w = tw + PAD_X * 2
+      box_h = th + PAD_Y * 2
+
+      bg_pixels = @bg_fn.call(box_w, box_h, RADIUS)
+      @bg_tex = @renderer.create_texture(box_w, box_h, :streaming)
+      @bg_tex.update(bg_pixels)
+      @bg_tex.blend_mode = :blend
+
+      @box_w = box_w
+      @box_h = box_h
+      @text_w = tw
+      @text_h = th
+      @permanent = permanent
+      @expires = permanent ? nil : Process.clock_gettime(Process::CLOCK_MONOTONIC) + (duration || @duration)
+    end
+
+    # Draw the toast centered at the bottom of the game area.
+    #
+    # @param r [Teek::SDL2::Renderer]
+    # @param dest [Array(Integer,Integer,Integer,Integer), nil] game area rect
+    def draw(r, dest)
+      return unless @bg_tex
+      unless @permanent
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        if now >= @expires
+          destroy
+          return
+        end
+      end
+
+      # Position: bottom-center of game area, 12px from bottom
+      if dest
+        cx = dest[0] + dest[2] / 2
+        by = dest[1] + dest[3] - 12 - @box_h
+      else
+        out_w, out_h = r.output_size
+        cx = out_w / 2
+        by = out_h - 12 - @box_h
+      end
+      bx = cx - @box_w / 2
+
+      # Background (pre-rendered with AA rounded corners)
+      r.copy(@bg_tex, nil, [bx, by, @box_w, @box_h])
+      # White text centered in the box
+      tx = bx + (@box_w - @text_w) / 2
+      ty = by + (@box_h - @text_h) / 2
+      r.copy(@text_tex, [0, 0, @text_w, @text_h],
+             [tx, ty, @text_w, @text_h])
+    end
+
+    # Remove the current toast and free textures.
+    def destroy
+      @bg_tex&.destroy
+      @bg_tex = nil
+      @text_tex&.destroy
+      @text_tex = nil
+    end
+
+    private
+
+    # Crop height: ascent + partial descender. Excludes the very bottom
+    # rows where TTF anti-alias residue causes visible white-line artifacts.
+    def compute_crop_h(font)
+      return nil unless font
+      ascent = font.ascent
+      full_h = font.measure('p')[1]
+      [ascent + (full_h - ascent) / 2, full_h - 1].min
+    end
+  end
+end

data/lib/gemba/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Gemba
+  VERSION = "0.1.0"
+end

data/lib/gemba.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "teek"
+require "teek/sdl2"
+require_relative "gemba/runtime"
+require_relative "gemba/child_window"
+require_relative "gemba/tip_service"
+require_relative "gemba/settings_window"
+require_relative "gemba/rom_info_window"
+require_relative "gemba/save_state_picker"
+require_relative "gemba/save_state_manager"
+require_relative "gemba/toast_overlay"
+require_relative "gemba/overlay_renderer"
+require_relative "gemba/input_mappings"
+require_relative "gemba/hotkey_map"
+require_relative "gemba/recorder"
+require_relative "gemba/player"

data/test/shared/screenshot_helper.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Screenshot comparison helpers for SDL2 visual regression testing.
+#
+# Uses Renderer#read_pixels to capture GPU framebuffer output and
+# ImageMagick to convert raw RGBA to PNG and compare against blessed baselines.
+#
+# Directory layout:
+#   screenshots/blessed/{platform}/    — committed gold images
+#   screenshots/unverified/{platform}/ — generated during test (gitignored)
+#   screenshots/diffs/{platform}/      — diff images on failure (gitignored)
+
+require 'fileutils'
+require 'open3'
+require 'teek/platform'
+
+module ScreenshotHelper
+  SCREENSHOTS_ROOT = File.expand_path('../screenshots', __dir__)
+
+  PLATFORM = Teek.platform.to_s
+
+  # Default pixel difference threshold for ImageMagick compare (AE metric).
+  # GPU drivers may produce minor anti-aliasing variations across runs.
+  THRESHOLD = Integer(ENV.fetch('SCREENSHOT_THRESHOLD', 100))
+
+  def self.blessed_dir
+    File.join(SCREENSHOTS_ROOT, 'blessed', PLATFORM)
+  end
+
+  def self.unverified_dir
+    File.join(SCREENSHOTS_ROOT, 'unverified', PLATFORM)
+  end
+
+  def self.diffs_dir
+    File.join(SCREENSHOTS_ROOT, 'diffs', PLATFORM)
+  end
+
+  def self.setup_dirs
+    FileUtils.mkdir_p(blessed_dir)
+    FileUtils.mkdir_p(unverified_dir)
+    FileUtils.mkdir_p(diffs_dir)
+  end
+
+  # Check if ImageMagick is available.
+  def self.imagemagick?
+    return @imagemagick if defined?(@imagemagick)
+    _, _, status = Open3.capture3('magick', '-version')
+    @imagemagick = status.success?
+  rescue Errno::ENOENT
+    @imagemagick = false
+  end
+
+  # Save raw RGBA pixels as PNG via ImageMagick.
+  def self.save_png(pixels, width, height, path)
+    cmd = ['magick', '-size', "#{width}x#{height}", '-depth', '8', 'rgba:-', path]
+    IO.popen(cmd, 'wb') { |io| io.write(pixels) }
+    raise "magick convert failed for #{path}" unless $?.success?
+  end
+
+  # Compare two PNGs with ImageMagick compare (AE metric).
+  # Returns [passed, pixel_diff, output].
+  def self.compare(expected, actual, diff_output)
+    cmd = ['magick', 'compare', '-metric', 'AE', expected, actual, diff_output]
+    stdout, stderr, status = Open3.capture3(*cmd)
+    output = stdout + stderr
+
+    pixel_diff = output[/(\d+)/]&.to_i
+    passed = pixel_diff ? pixel_diff <= THRESHOLD : status.success?
+
+    [passed, pixel_diff, output.strip]
+  end
+
+  # Assert that the current renderer output matches the blessed screenshot.
+  #
+  # Captures pixels from the renderer, saves to unverified/{platform}/{name}.png,
+  # then compares against blessed/{platform}/{name}.png.
+  #
+  #   assert_sdl2_screenshot(renderer, "red_rect")
+  #
+  def assert_sdl2_screenshot(renderer, name, message: nil)
+    ScreenshotHelper.setup_dirs
+
+    unless ScreenshotHelper.imagemagick?
+      skip "ImageMagick not installed — skipping screenshot comparison"
+    end
+
+    w, h = renderer.output_size
+    pixels = renderer.read_pixels
+
+    unverified = File.join(ScreenshotHelper.unverified_dir, "#{name}.png")
+    ScreenshotHelper.save_png(pixels, w, h, unverified)
+
+    blessed = File.join(ScreenshotHelper.blessed_dir, "#{name}.png")
+
+    unless File.exist?(blessed)
+      flunk "No blessed screenshot for '#{name}'. " \
+            "Inspect #{unverified} and run: rake screenshots:bless"
+    end
+
+    diff = File.join(ScreenshotHelper.diffs_dir, "#{name}_diff.png")
+    passed, pixel_diff, output = ScreenshotHelper.compare(blessed, unverified, diff)
+
+    if passed
+      FileUtils.rm_f(diff)
+    else
+      msg = message || "Screenshot '#{name}' differs by #{pixel_diff} pixels (threshold: #{ScreenshotHelper::THRESHOLD})"
+      msg += "\n  Blessed:    #{blessed}"
+      msg += "\n  Unverified: #{unverified}"
+      msg += "\n  Diff:       #{diff}"
+      flunk msg
+    end
+  end
+end

data/test/shared/simplecov_config.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Shared SimpleCov configuration for all test contexts:
+# - Main test process
+# - Teek::TestWorker subprocess
+# - Collation (Rakefile)
+# - Subprocess preamble (tk_test_helper.rb)
+
+module SimpleCovConfig
+  PROJECT_ROOT = File.expand_path('../..', __dir__)
+
+  FILTERS = [
+    '/test/',
+    %r{^/ext/},
+    'lib/teek/method_coverage_service.rb',
+    'lib/teek/background_none.rb',
+    'lib/teek/demo_support.rb',
+    'lib/teek/version.rb',
+  ].freeze
+
+  def self.apply_filters(simplecov_context)
+    FILTERS.each { |f| simplecov_context.add_filter(f) }
+  end
+
+  def self.apply_groups(simplecov_context)
+    simplecov_context.add_group 'Core', 'lib/teek.rb'
+    simplecov_context.add_group 'SDL2', 'lib/teek/sdl2'
+  end
+
+  # Generate add_filter code lines from FILTERS array (for subprocess preamble)
+  def self.filters_as_code
+    FILTERS.map do |f|
+      case f
+      when Regexp then "add_filter #{f.inspect}"
+      when String then "add_filter '#{f}'"
+      end
+    end.join("\n          ")
+  end
+
+  # Ruby code string for subprocess SimpleCov setup
+  def self.subprocess_preamble(project_root: PROJECT_ROOT)
+    <<~RUBY
+      if ENV['COVERAGE']
+        require 'simplecov'
+
+        coverage_name = ENV['COVERAGE_NAME'] || 'default'
+        SimpleCov.coverage_dir "#{project_root}/coverage/results/\#{coverage_name}_sub_\#{Process.pid}"
+        SimpleCov.command_name "subprocess:\#{Process.pid}"
+        SimpleCov.print_error_status = false
+        SimpleCov.formatter SimpleCov::Formatter::SimpleFormatter
+
+        SimpleCov.start do
+          #{filters_as_code}
+          track_files "#{project_root}/lib/**/*.rb"
+        end
+      end
+    RUBY
+  end
+end