teek 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92cd230fed0f898dcf23f80a0a6058adcf308e14b4a8f7feb6985026be4692e0
-  data.tar.gz: 698f02315ab27973a05490552fbd6aec21447987a726119d583cbc98f197c486
+  metadata.gz: 8fe2f5c480c472d6479ac1b92088a748e1216cb1a15472e9e98fbd3c2e4fd347
+  data.tar.gz: c4d2da92180136ca756955258ea59402b27b9019e9d492f0969a7c346dcc053a
 SHA512:
-  metadata.gz: b259a6ed4a721cfe5179d53eacffdd67f9e3213af17e81eb9c8e434a8857456bf55e2d2798ccddf0099bfe001294fae2cf187111f9aafa575e84e90a1528314e
-  data.tar.gz: 20c96ae1cb5f4340737bcd4db2539c01f47f19c7b837bd85fff18ada2d707c4719cabfe0dc14ab1bf986e9b15aee6d61d64883dba4f33f758c3896b9877014c1
+  metadata.gz: 6a10e7f92ca08b1385288829cf0188beb408c90cdf52aecb30a36652f2b299954318c4b3a64434ea0158950f05e105db5a289c115dab4506fa91b7ab6e70f26e
+  data.tar.gz: 7cd908cf513d6f92cad5c89d04cb49f7bf3fb3e9d7868af4d0d0fbb7db04e2a7a712c3e6e1e2fd107fd4df4b84140b49d720b2357cc9b9452067a8f5b7bfe2f6

data/Rakefile

@@ -505,6 +505,7 @@ namespace :docker do
       puts "Recording #{sample} (#{codec})..."
       env = "CODEC=#{codec}"
       env += " NAME=#{name}" if name
+      env += " AUDIO=1" if demo['audio']
       sh "#{env} ./scripts/docker-record.sh #{sample}"
     end
 

data/ext/teek/tcltkbridge.c

@@ -336,6 +336,12 @@ interp_initialize(int argc, VALUE *argv, VALUE self)
         rb_raise(eTclError, "Tk_Init failed: %s", err);
     }
 
+    /* Hide the Tk console if it was auto-created during Tk_Init.
+     * On macOS/Windows, Tk may create a console window depending on
+     * how the process was launched. "catch" handles Linux where the
+     * console command does not exist. */
+    Tcl_Eval(tip->interp, "catch {console hide}");
+
     /* 7. Initialize Tk stubs - after Tk_Init */
     tk_version = Tk_InitStubs(tip->interp, TK_VERSION, 0);
     if (tk_version == NULL) {

data/lib/teek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teek
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/teek.rb

@@ -48,13 +48,15 @@ module Teek
 
   class App
     attr_reader :interp, :widgets, :debugger
+    attr_writer :_pending_exception # @api private
 
-    def initialize(track_widgets: true, debug: false, &block)
+    def initialize(title: nil, track_widgets: true, debug: false, &block)
       @interp = Teek::Interp.new
       @interp.tcl_eval('package require Tk')
       hide
       @widgets = {}
       @widget_counters = Hash.new(0)
+      @_pending_exception = nil
       debug ||= !!ENV['TEEK_DEBUG']
       track_widgets = true if debug
       setup_widget_tracking if track_widgets
@@ -62,6 +64,7 @@ module Teek
         require_relative 'teek/debugger'
         @debugger = Teek::Debugger.new(self)
       end
+      set_window_title(title) if title
       instance_eval(&block) if block
     end
 
@@ -119,14 +122,24 @@ module Teek
 
     # Schedule a one-shot timer. Calls the block after +ms+ milliseconds.
     # @param ms [Integer] delay in milliseconds
+    # @param on_error [:raise, Proc, nil] error handling strategy:
+    #   - +:raise+ (default) — exception propagates to Tcl background error handler.
+    #   - +Proc+ — called with the exception; error is swallowed.
+    #   - +nil+ — error is silently swallowed.
     # @yield block to call when the timer fires
     # @return [String] timer ID, pass to {#after_cancel} to cancel
     # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/after.htm#M5 after ms
-    def after(ms, &block)
+    def after(ms, on_error: :raise, &block)
       cb_id = nil
       cb_id = @interp.register_callback(proc { |*|
-        block.call
-        @interp.unregister_callback(cb_id)
+        begin
+          block.call
+        rescue => e
+          raise if on_error == :raise
+          on_error.call(e) if on_error.is_a?(Proc)
+        ensure
+          @interp.unregister_callback(cb_id)
+        end
       })
       after_id = @interp.tcl_eval("after #{ms.to_i} {ruby_callback #{cb_id}}")
       after_id.instance_variable_set(:@cb_id, cb_id)
@@ -148,6 +161,33 @@ module Teek
       after_id
     end
 
+    # Schedule a repeating timer. Calls the block every +ms+ milliseconds
+    # until cancelled. The block runs on the main thread in the event loop,
+    # so it must be fast (don't block the UI).
+    #
+    # @param ms [Integer] interval in milliseconds
+    # @param on_error [:raise, Proc, nil] error handling strategy:
+    #   - +:raise+ (default) — cancels the timer and raises the exception
+    #     from the next call to {#update}.
+    #   - +Proc+ — called with the exception; timer keeps running.
+    #   - +nil+ — cancels the timer silently; error stored in {RepeatingTimer#last_error}.
+    # @yield block to call on each tick
+    # @return [RepeatingTimer] cancel handle
+    #
+    # @example Basic polling loop
+    #   timer = app.every(50) { update_display }
+    #   timer.cancel  # stop later
+    #
+    # @example With error handler (timer keeps running)
+    #   timer = app.every(100, on_error: ->(e) { log(e) }) { risky_work }
+    #
+    # @example Silent cancel on error
+    #   timer = app.every(50, on_error: nil) { maybe_fails }
+    #   timer.last_error  # => check later
+    def every(ms, on_error: :raise, &block)
+      RepeatingTimer.new(self, ms, on_error: on_error, &block)
+    end
+
     # Cancel a pending {#after} or {#after_idle} timer.
     # @param after_id [String] timer ID returned by {#after} or {#after_idle}
     # @return [void]
@@ -390,6 +430,10 @@ module Teek
     # @see https://www.tcl-lang.org/man/tcl8.6/TclCmd/update.htm update
     def update
       @interp.tcl_eval('update')
+      if (e = @_pending_exception)
+        @_pending_exception = nil
+        raise e
+      end
     end
 
     # Process only pending idle callbacks (e.g. geometry redraws), then return.
@@ -415,6 +459,44 @@ module Teek
       @interp.tcl_eval("wm withdraw #{window}")
     end
 
+    # Enable the Tk debug console. The console starts hidden and can be
+    # toggled with the given keyboard shortcut (default: F12).
+    #
+    # The Tk console is a built-in interactive Tcl shell — useful for
+    # inspecting variables, running Tcl commands, and debugging widget
+    # layouts at runtime. It is available on macOS and Windows only;
+    # on Linux this method is a no-op (Linux has the real terminal).
+    #
+    # @param keybinding [String] Tk event to toggle the console
+    #   (default: "<F12>")
+    # @return [Boolean] true if the console was created, false if
+    #   unavailable on this platform
+    # @example
+    #   app = Teek::App.new
+    #   app.add_debug_console            # F12 toggles console
+    #   app.add_debug_console("<F11>")   # custom key
+    # @see https://www.tcl-lang.org/man/tcl8.6/TkCmd/console.htm console
+    def add_debug_console(keybinding = '<F12>')
+      @interp.create_console
+      @_console_visible = false
+
+      toggle = proc do |*|
+        if @_console_visible
+          tcl_eval('console hide')
+          @_console_visible = false
+        else
+          tcl_eval('console show')
+          @_console_visible = true
+        end
+      end
+
+      command(:bind, '.', keybinding, toggle)
+      true
+    rescue TclError => e
+      warn "Teek: debug console not available on this platform (#{e.message})"
+      false
+    end
+
     # Set a window's title.
     # @param title [String] new title
     # @param window [String] Tk window path
@@ -675,9 +757,122 @@ module Teek
         "{ruby_callback #{id}}"
       when Symbol
         value.to_s
+      when Array
+        "{#{value.map { |v| tcl_value(v) }.join(' ')}}"
       else
         "{#{value}}"
       end
     end
   end
+
+  # A cancellable repeating timer that fires on the main thread.
+  #
+  # Created via {App#every}. Reschedules itself after each tick using
+  # Tcl's +after+ command. The block runs in the event loop, so it
+  # must complete quickly to avoid blocking the UI.
+  #
+  # Tracks timing drift: if a tick fires significantly late (more than
+  # 2x the interval), a warning is printed to stderr. This helps catch
+  # blocks that are too slow for the requested interval.
+  #
+  # @see App#every
+  class RepeatingTimer
+    # @return [Integer] interval in milliseconds
+    attr_reader :interval
+
+    # @return [Exception, nil] the last error if the timer stopped due to an
+    #   unhandled exception, nil otherwise
+    attr_reader :last_error
+
+    # @return [Integer] number of ticks that fired late (> 2x interval)
+    attr_reader :late_ticks
+
+    # @api private
+    def initialize(app, ms, on_error: nil, &block)
+      raise ArgumentError, "interval must be positive, got #{ms}" if ms <= 0
+
+      @app = app
+      @interval = ms
+      @block = block
+      @on_error = on_error
+      @cancelled = false
+      @after_id = nil
+      @last_error = nil
+      @late_ticks = 0
+      @next_expected = nil
+      schedule
+    end
+
+    # Stop the timer. Safe to call multiple times.
+    # @return [void]
+    def cancel
+      return if @cancelled
+      @cancelled = true
+      @app.after_cancel(@after_id) if @after_id
+      @after_id = nil
+    end
+
+    # @return [Boolean] true if the timer has been cancelled
+    def cancelled?
+      @cancelled
+    end
+
+    # Change the interval. Takes effect on the next tick.
+    # @param ms [Integer] new interval in milliseconds
+    def interval=(ms)
+      raise ArgumentError, "interval must be positive, got #{ms}" if ms <= 0
+      @interval = ms
+    end
+
+    private
+
+    def schedule
+      return if @cancelled
+      @next_expected = now_ms + @interval
+      @after_id = @app.after(@interval) { tick }
+    end
+
+    def tick
+      return if @cancelled
+      check_drift
+      @block.call
+      schedule
+    rescue => e
+      @last_error = e
+      case @on_error
+      when :raise
+        @cancelled = true
+        # Store on App so it raises from the next app.update call.
+        # Don't re-raise here — that would go through rb_protect → bgerror.
+        @app._pending_exception = e
+      when Proc
+        begin
+          @on_error.call(e)
+        rescue => handler_err
+          @last_error = handler_err
+          @cancelled = true
+          @app._pending_exception = handler_err
+          return
+        end
+        schedule
+      when nil
+        @cancelled = true
+      end
+    end
+
+    def check_drift
+      return unless @next_expected
+      actual = now_ms
+      drift = actual - @next_expected
+      if drift > @interval
+        @late_ticks += 1
+        warn "Teek::RepeatingTimer: tick #{@late_ticks} fired #{drift.round}ms late " \
+             "(interval=#{@interval}ms)"
+      end
+    end
+
+    def now_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+    end
+  end
 end

data/sample/gamepad_viewer/gamepad_viewer.rb

@@ -0,0 +1,554 @@
+# frozen_string_literal: true
+#
+# Gamepad Viewer — SDL2 gamepad input visualized with pure Tk widgets.
+#
+# Demonstrates:
+#   - Teek::SDL2::Gamepad for controller input (polling + events)
+#   - Virtual gamepad wired to keyboard for testing without hardware
+#   - Combobox for gamepad selection with hot-plug detection
+#   - Canvas overlay highlights on a controller image
+#   - Tk label indicators for button/axis state
+#   - Periodic polling via app.every (50ms game loop)
+#
+# Controller artwork: "Generic Gamepad Template" by Erratic (CC0)
+# https://opengameart.org/content/generic-gamepad-template
+
+require_relative '../../lib/teek'
+require_relative '../../teek-sdl2/lib/teek/sdl2'
+
+class GamepadViewer
+  GP = Teek::SDL2::Gamepad
+
+  # Approximate pixel coordinates for button highlights on controller.png (479x310)
+  # Format: [center_x, center_y, radius]
+  BUTTON_POS = {
+    a:              [352, 140, 18],
+    b:              [390, 107, 18],
+    x:              [315, 107, 18],
+    y:              [353,  71, 18],
+    dpad_up:        [127,  74, 12],
+    dpad_down:      [127, 143, 12],
+    dpad_left:      [ 93, 111, 12],
+    dpad_right:     [160, 110, 12],
+    left_shoulder:  [ 97,  18, 20],
+    right_shoulder: [383,  21, 20],
+    back:           [215,  93, 10],
+    start:          [262,  95, 10],
+    left_stick:     [165, 200, 16],
+    right_stick:    [313, 200, 16],
+    guide:          [242, 135, 12],
+  }.freeze
+
+  # Center of each analog stick for the position dot
+  STICK_CENTER = {
+    left:  [165, 200],
+    right: [313, 200],
+  }.freeze
+
+  # Keyboard → virtual gamepad button mapping
+  KEY_MAP_BUTTONS = {
+    'space'     => :a,
+    'shift_l'   => :b,
+    'shift_r'   => :b,
+    'z'         => :x,
+    'c'         => :y,
+    'return'    => :start,
+    'tab'       => :back,
+    'q'         => :left_shoulder,
+    'e'         => :right_shoulder,
+    'up'        => :dpad_up,
+    'down'      => :dpad_down,
+    'left'      => :dpad_left,
+    'right'     => :dpad_right,
+    'f'         => :left_stick,
+    'g'         => :right_stick,
+    'escape'    => :guide,
+  }.freeze
+
+  # Keyboard → virtual analog stick mapping
+  # WASD → left stick, IJKL → right stick
+  KEY_MAP_AXES = {
+    'w' => [:left_y,  -GP::AXIS_MAX],
+    's' => [:left_y,   GP::AXIS_MAX],
+    'a' => [:left_x,   GP::AXIS_MIN],
+    'd' => [:left_x,   GP::AXIS_MAX],
+    'i' => [:right_y, -GP::AXIS_MAX],
+    'k' => [:right_y,  GP::AXIS_MAX],
+    'j' => [:right_x,  GP::AXIS_MIN],
+    'l' => [:right_x,  GP::AXIS_MAX],
+  }.freeze
+
+  def initialize(calibrate: false)
+    @calibrate = calibrate
+    @app = Teek::App.new(title: calibrate ? 'Gamepad Viewer — CALIBRATE' : 'Gamepad Viewer')
+    @gamepads = []       # [[display_name, :virtual | device_index], ...]
+    @current_gp = nil    # opened Gamepad instance
+    @current_mode = nil  # :virtual or device index
+    @keys_held = {}      # keysym → true (for virtual stick axes)
+    @var_counter = 0     # unique Tcl variable names
+    @prev_buttons = {}   # btn → pressed (skip UI update when unchanged)
+    @prev_axes = {}      # ax → value
+
+    GP.init_subsystem
+
+    build_ui
+    unless @calibrate
+      refresh_gamepad_list
+      start_poll_loop
+    end
+    @app.show
+  end
+
+  def run
+    @app.mainloop
+  ensure
+    @poll_timer&.cancel
+    @current_gp&.close unless @current_gp&.closed?
+    GP.detach_virtual
+    GP.shutdown_subsystem
+  end
+
+  private
+
+  # ── UI construction ────────────────────────────────────────────────────────
+
+  def build_ui
+    # Top bar: gamepad selector
+    top = @app.create_widget('ttk::frame')
+    top.pack(fill: :x, padx: 8, pady: 4)
+
+    @app.create_widget('ttk::label', parent: top, text: 'Gamepad:')
+        .pack(side: :left)
+
+    # Tcl variable must exist before combobox references it via -textvariable
+    @combo_var = next_var
+    set_var(@combo_var, '')
+    @combo = @app.create_widget('ttk::combobox', parent: top,
+                                textvariable: @combo_var,
+                                state: :readonly, width: 35)
+    @combo.pack(side: :left, padx: 4)
+    @combo.bind('<<ComboboxSelected>>') { on_gamepad_selected }
+
+    @app.create_widget('ttk::button', parent: top, text: 'Refresh',
+                       command: proc { refresh_gamepad_list })
+        .pack(side: :left, padx: 4)
+
+    # Main area: canvas (left) + info panel (right)
+    main = @app.create_widget('ttk::frame')
+    main.pack(fill: :both, expand: true, padx: 8, pady: 4)
+
+    build_canvas(main)
+    build_info_panel(main)
+
+    # Status bar (left = status text, right = mouse coords on canvas)
+    status_frame = @app.create_widget('ttk::frame')
+    status_frame.pack(fill: :x, side: :bottom, padx: 8, pady: 4)
+
+    @status_var = next_var
+    set_var(@status_var, 'Select a gamepad to begin')
+    @app.create_widget('ttk::label', parent: status_frame,
+                       textvariable: @status_var, anchor: :w)
+        .pack(fill: :x, side: :left, expand: true)
+
+    @mouse_var = next_var
+    set_var(@mouse_var, 'x: — y: —')
+    @app.create_widget('ttk::label', parent: status_frame,
+                       textvariable: @mouse_var, anchor: :e,
+                       width: 16, font: 'TkFixedFont')
+        .pack(side: :right, padx: [4, 0])
+
+    # Keyboard bindings for virtual mode (skip in calibrate — it uses its own)
+    unless @calibrate
+      @app.bind('all', 'KeyPress', :keysym)   { |k| on_key_press(k) }
+      @app.bind('all', 'KeyRelease', :keysym) { |k| on_key_release(k) }
+    end
+  end
+
+  def build_canvas(parent)
+    @canvas = @app.create_widget('canvas', parent: parent,
+                                 width: 479, height: 310,
+                                 background: '#2b2b2b', highlightthickness: 0)
+    @canvas.pack(side: :left, padx: [0, 8])
+
+    # Load controller image
+    img_path = File.join(__dir__, 'assets', 'controller.png')
+    @controller_img = "gp_controller"
+    @app.command(:image, :create, :photo, @controller_img, file: img_path)
+    @canvas.command(:create, :image, 0, 0, anchor: :nw, image: @controller_img,
+                    tag: :controller)
+
+    # Mouse coordinate tracking for tweaking button positions
+    @canvas.bind('Motion', :x, :y) do |x, y|
+      set_var(@mouse_var, "x:#{x} y:#{y}")
+    end
+
+    # Create highlight ovals for each button
+    @highlight_items = {}
+    @calibrate_pos = {}  # live positions for calibration mode
+    BUTTON_POS.each do |btn, (cx, cy, r)|
+      color = button_highlight_color(btn)
+      tag = "hl_#{btn}"
+      @canvas.command(:create, :oval, cx - r, cy - r, cx + r, cy + r,
+                      fill: color, outline: '', tag: tag,
+                      state: @calibrate ? :normal : :hidden)
+      @highlight_items[btn] = tag
+      @calibrate_pos[btn] = [cx, cy, r]
+
+      if @calibrate
+        # Label each highlight so you know which is which
+        @canvas.command(:create, :text, cx, cy - r - 8,
+                        text: btn.to_s, fill: '#ffffff',
+                        font: 'TkSmallCaptionFont', tag: "lbl_#{btn}")
+      end
+    end
+
+    if @calibrate
+      setup_calibration_drag
+    end
+
+    # Stick position dots
+    @stick_dots = {}
+    STICK_CENTER.each do |side, (cx, cy)|
+      tag = "stick_#{side}"
+      r = 6
+      @canvas.command(:create, :oval, cx - r, cy - r, cx + r, cy + r,
+                      fill: '#00ff88', outline: '#00cc66', width: 2, tag: tag)
+      @stick_dots[side] = tag
+    end
+  end
+
+  def build_info_panel(parent)
+    info = @app.create_widget('ttk::labelframe', parent: parent, text: 'State')
+    info.pack(side: :right, fill: :both, expand: true)
+
+    # Button indicators
+    btn_frame = @app.create_widget('ttk::labelframe', parent: info, text: 'Buttons')
+    btn_frame.pack(fill: :x, padx: 4, pady: 2)
+
+    @btn_labels = {}
+    GP.buttons.each_slice(4) do |row|
+      rf = @app.create_widget('ttk::frame', parent: btn_frame)
+      rf.pack(fill: :x)
+      row.each do |btn|
+        var = next_var
+        set_var(var, btn.to_s)
+        # Use plain label (not ttk) for background color support
+        lbl = @app.create_widget('label', parent: rf,
+                                 textvariable: var,
+                                 width: 12, relief: :groove,
+                                 anchor: :center, padx: 2, pady: 1)
+        lbl.pack(side: :left, padx: 1, pady: 1)
+        # Store default colors so we can restore them when button is released
+        default_bg = lbl.command(:cget, '-background')
+        default_fg = lbl.command(:cget, '-foreground')
+        @btn_labels[btn] = { var: var, label: lbl,
+                             default_bg: default_bg, default_fg: default_fg }
+      end
+    end
+
+    # Axis readouts
+    axis_frame = @app.create_widget('ttk::labelframe', parent: info, text: 'Axes')
+    axis_frame.pack(fill: :x, padx: 4, pady: 2)
+
+    @axis_labels = {}
+    GP.axes.each do |ax|
+      rf = @app.create_widget('ttk::frame', parent: axis_frame)
+      rf.pack(fill: :x)
+      @app.create_widget('ttk::label', parent: rf, text: "#{ax}:",
+                         width: 14, anchor: :e)
+          .pack(side: :left)
+      var = next_var
+      set_var(var, '0')
+      @app.create_widget('ttk::label', parent: rf, textvariable: var,
+                         width: 8, anchor: :w, font: 'TkFixedFont')
+          .pack(side: :left, padx: 4)
+      @axis_labels[ax] = var
+    end
+
+    # Key help for virtual mode
+    help_frame = @app.create_widget('ttk::labelframe', parent: info,
+                                    text: 'Virtual Keys')
+    help_frame.pack(fill: :x, padx: 4, pady: 2)
+
+    help_text = "WASD: L-stick  IJKL: R-stick\n" \
+                "Arrows: D-pad  Space: A\n" \
+                "Shift: B  Z: X  C: Y\n" \
+                "Enter: Start  Tab: Back\n" \
+                "Q/E: Shoulders  F/G: Sticks"
+    @app.create_widget('ttk::label', parent: help_frame,
+                       text: help_text, justify: :left)
+        .pack(padx: 4, pady: 2)
+  end
+
+  # ── Gamepad selection ──────────────────────────────────────────────────────
+
+  def refresh_gamepad_list
+    @gamepads = [['Virtual (Keyboard)', :virtual]]
+
+    # Probe device indices for connected gamepads
+    8.times do |i|
+      gp = begin; GP.open(i); rescue; nil; end
+      next unless gp
+      @gamepads << [gp.name, i]
+      gp.close
+    end
+
+    values = @gamepads.map(&:first)
+    @combo.command(:configure, values: values)
+
+    # Select first if nothing selected
+    current = get_var(@combo_var)
+    if current.empty? || !values.include?(current)
+      set_var(@combo_var, values.first)
+      on_gamepad_selected
+    end
+  end
+
+  def on_gamepad_selected
+    name = get_var(@combo_var)
+    entry = @gamepads.find { |n, _| n == name }
+    return unless entry
+
+    _, mode = entry
+    switch_gamepad(mode)
+  end
+
+  def switch_gamepad(mode)
+    # Close current
+    @current_gp&.close unless @current_gp&.closed?
+    @current_gp = nil
+    GP.detach_virtual
+
+    @prev_buttons.clear
+    @prev_axes.clear
+
+    if mode == :virtual
+      idx = GP.attach_virtual
+      @current_gp = GP.open(idx)
+      @current_mode = :virtual
+      set_var(@status_var, "Virtual gamepad active \u2014 use keyboard")
+    else
+      begin
+        @current_gp = GP.open(mode)
+        @current_mode = mode
+        set_var(@status_var, "Connected: #{@current_gp.name}")
+      rescue => e
+        set_var(@status_var, "Error: #{e.message}")
+        @current_mode = nil
+      end
+    end
+  end
+
+  # ── Keyboard → Virtual gamepad ─────────────────────────────────────────────
+
+  def on_key_press(keysym)
+    return unless @current_mode == :virtual && @current_gp && !@current_gp.closed?
+
+    key = keysym.downcase
+
+    if (btn = KEY_MAP_BUTTONS[key])
+      @current_gp.set_virtual_button(btn, true)
+    end
+
+    if KEY_MAP_AXES[key]
+      @keys_held[key] = true
+      update_virtual_axes
+    end
+  end
+
+  def on_key_release(keysym)
+    return unless @current_mode == :virtual && @current_gp && !@current_gp.closed?
+
+    key = keysym.downcase
+
+    if (btn = KEY_MAP_BUTTONS[key])
+      @current_gp.set_virtual_button(btn, false)
+    end
+
+    if KEY_MAP_AXES[key]
+      @keys_held.delete(key)
+      update_virtual_axes
+    end
+  end
+
+  def update_virtual_axes
+    return unless @current_gp && !@current_gp.closed?
+
+    # Compute net axis values from held keys
+    axes = Hash.new(0)
+    @keys_held.each_key do |key|
+      ax, val = KEY_MAP_AXES[key]
+      axes[ax] = val
+    end
+
+    # Set each axis — reset to 0 if no key held for that axis
+    %i[left_x left_y right_x right_y].each do |ax|
+      @current_gp.set_virtual_axis(ax, axes[ax])
+    end
+  end
+
+  # ── Poll loop ──────────────────────────────────────────────────────────────
+
+  def start_poll_loop
+    @poll_timer = @app.every(50, on_error: ->(e) {
+      set_var(@status_var, "Poll error: #{e.message}")
+    }) {
+      GP.poll_events
+      if @current_gp && !@current_gp.closed?
+        update_buttons
+        update_axes
+      end
+    }
+  end
+
+  def update_buttons
+    GP.buttons.each do |btn|
+      pressed = @current_gp.button?(btn)
+      next if @prev_buttons[btn] == pressed
+
+      @prev_buttons[btn] = pressed
+      info = @btn_labels[btn]
+      next unless info
+
+      if pressed
+        set_var(info[:var], "[ #{btn} ]")
+        info[:label].command(:configure,
+                             background: button_highlight_color(btn),
+                             foreground: '#ffffff')
+      else
+        set_var(info[:var], btn.to_s)
+        info[:label].command(:configure,
+                             background: info[:default_bg],
+                             foreground: info[:default_fg])
+      end
+
+      tag = @highlight_items[btn]
+      @canvas.command(:itemconfigure, tag, state: pressed ? :normal : :hidden) if tag
+    end
+  end
+
+  def update_axes
+    GP.axes.each do |ax|
+      val = @current_gp.axis(ax)
+      next if @prev_axes[ax] == val
+
+      @prev_axes[ax] = val
+      set_var(@axis_labels[ax], val.to_s.rjust(6))
+    end
+
+    # Only move stick dots when their axes actually changed
+    lx = @current_gp.axis(:left_x);  ly = @current_gp.axis(:left_y)
+    rx = @current_gp.axis(:right_x); ry = @current_gp.axis(:right_y)
+    move_stick_dot(:left,  lx, ly)  if @prev_axes[:left_x]  != lx || @prev_axes[:left_y]  != ly
+    move_stick_dot(:right, rx, ry)  if @prev_axes[:right_x] != rx || @prev_axes[:right_y] != ry
+  end
+
+  def move_stick_dot(side, raw_x, raw_y)
+    cx, cy = STICK_CENTER[side]
+    max_offset = 15.0  # pixels of travel on screen
+    nx = raw_x.to_f / GP::AXIS_MAX
+    ny = raw_y.to_f / GP::AXIS_MAX
+    px = cx + (nx * max_offset)
+    py = cy + (ny * max_offset)
+    r = 6
+    @canvas.command(:coords, @stick_dots[side],
+                    (px - r).round, (py - r).round,
+                    (px + r).round, (py + r).round)
+  end
+
+  # ── Helpers ────────────────────────────────────────────────────────────────
+
+  def button_highlight_color(btn)
+    case btn
+    when :a              then '#22cc44'
+    when :b              then '#dd3333'
+    when :x              then '#3388ee'
+    when :y              then '#ee8822'
+    when :dpad_up, :dpad_down, :dpad_left, :dpad_right then '#44aaff'
+    when :left_shoulder, :right_shoulder then '#aa66dd'
+    when :left_stick, :right_stick       then '#00ff88'
+    when :back, :start, :guide           then '#ffaa22'
+    else '#cccccc'
+    end
+  end
+
+  # ── Calibration mode ────────────────────────────────────────────────────────
+
+  def setup_calibration_drag
+    @drag_btn = nil
+    @drag_offset = [0, 0]
+
+    @canvas.bind('ButtonPress-1', :x, :y) { |x, y| calibrate_press(x.to_i, y.to_i) }
+    @canvas.bind('B1-Motion', :x, :y)     { |x, y| calibrate_drag(x.to_i, y.to_i) }
+    @canvas.bind('ButtonRelease-1')        { @drag_btn = nil }
+
+    # Print final coordinates to console
+    @app.bind('all', 'KeyPress', :keysym) do |k|
+      print_calibrated_positions if k.downcase == 'return'
+    end
+
+    set_var(@status_var, 'Drag circles into position. Press Enter to print coordinates.')
+  end
+
+  def calibrate_press(mx, my)
+    # Find the closest button highlight to the click
+    @drag_btn = nil
+    best_dist = 999
+    @calibrate_pos.each do |btn, (cx, cy, _r)|
+      d = Math.sqrt((mx - cx)**2 + (my - cy)**2)
+      if d < best_dist
+        best_dist = d
+        @drag_btn = btn
+        @drag_offset = [mx - cx, my - cy]
+      end
+    end
+    @drag_btn = nil if best_dist > 40
+  end
+
+  def calibrate_drag(mx, my)
+    return unless @drag_btn
+
+    cx = mx - @drag_offset[0]
+    cy = my - @drag_offset[1]
+    _, _, r = @calibrate_pos[@drag_btn]
+    @calibrate_pos[@drag_btn] = [cx, cy, r]
+
+    tag = @highlight_items[@drag_btn]
+    @canvas.command(:coords, tag, cx - r, cy - r, cx + r, cy + r)
+    @canvas.command(:coords, "lbl_#{@drag_btn}", cx, cy - r - 8)
+    set_var(@mouse_var, "#{@drag_btn}: #{cx},#{cy}")
+  end
+
+  def print_calibrated_positions
+    puts "\n# Updated BUTTON_POS — paste into gamepad_viewer.rb"
+    puts "BUTTON_POS = {"
+    @calibrate_pos.each do |btn, (cx, cy, r)|
+      puts "  %-17s [%3d, %3d, %2d]," % ["#{btn}:", cx, cy, r]
+    end
+    puts "}.freeze"
+
+    # Also print stick centers from the stick buttons
+    ls = @calibrate_pos[:left_stick]
+    rs = @calibrate_pos[:right_stick]
+    puts "\nSTICK_CENTER = {"
+    puts "  left:  [#{ls[0]}, #{ls[1]}],"
+    puts "  right: [#{rs[0]}, #{rs[1]}],"
+    puts "}.freeze"
+  end
+
+  # Tcl variable helpers
+  def next_var
+    @var_counter += 1
+    "::gpv_#{@var_counter}"
+  end
+
+  def set_var(name, value)
+    @app.command(:set, name, value)
+  end
+
+  def get_var(name)
+    @app.command(:set, name)
+  end
+end
+
+GamepadViewer.new(calibrate: ARGV.include?('--calibrate')).run

data/sample/{minesweeper/minesweeper.rb → yam/yam.rb}

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# teek-record: title=Yet Another Minesweeper, audio=1
 #
 # Minesweeper clone built with Teek.
 #
@@ -13,8 +14,14 @@
 #
 # Tile artwork: "Minesweeper Tile Set" by eugeneloza (CC0)
 # https://opengameart.org/content/minesweeper-tile-set
+#
+# Sound effects: generated with jsfxr (https://sfxr.me), public domain
+# Music: "Vaporware" by The Cynic Project (CC0)
+#   https://opengameart.org/content/calm-piano-1-vaporware
+#   cynicmusic.com / pixelsphere.org
 
 require_relative '../../lib/teek'
+require_relative '../../teek-sdl2/lib/teek/sdl2'
 
 class Minesweeper
   # The source PNGs are 216x216. Tk can shrink them with "copy -subsample N N"
@@ -28,15 +35,22 @@ class Minesweeper
     expert:       { cols: 30, rows: 16, mines: 99 }
   }.freeze
 
+  attr_reader :app
+
   def initialize(app, level: :beginner)
     @app = app
     @level = level
     apply_level
     load_images
+    load_sounds
     build_ui
     new_game
   end
 
+  # Simulate press/release on a cell for demo/test automation.
+  def press_cell(r, c) = on_left_press(r, c)
+  def release_cell(r, c) = on_left_release(r, c)
+
   private
 
   # -- Setup ---------------------------------------------------------------
@@ -83,10 +97,21 @@ class Minesweeper
     end
   end
 
+  def load_sounds
+    dir = File.join(__dir__, 'assets')
+    @snd_click     = Teek::SDL2::Sound.new(File.join(dir, 'click.wav'))
+    @snd_sweep     = Teek::SDL2::Sound.new(File.join(dir, 'sweep.wav'))
+    @snd_flag      = Teek::SDL2::Sound.new(File.join(dir, 'flag.wav'))
+    @snd_explosion = Teek::SDL2::Sound.new(File.join(dir, 'explosion.wav'))
+    @music = Teek::SDL2::Music.new(File.join(dir, 'music.mp3'))
+    @music.volume = 48
+    @music_on = true
+  end
+
   def build_ui
     # "wm" commands control the window manager -- title, resizability, etc.
     # "." is the root Tk window (every widget path starts from here).
-    @app.command(:wm, :title, '.', 'Minesweeper')
+    @app.command(:wm, :title, '.', 'Yet Another Minesweeper')
     @app.command(:wm, :resizable, '.', 0, 0)
 
     build_menu
@@ -165,6 +190,13 @@ class Minesweeper
                  font: 'TkFixedFont 14 bold', fg: :red, bg: :black,
                  relief: :sunken, anchor: :center)
     @app.command(:pack, '.hdr.time', side: :right, padx: 5, pady: 3)
+
+    # Music toggle (right, next to timer)
+    @music_btn = '.hdr.music'
+    @app.command(:button, @music_btn, text: "\u266A", width: 2,
+                 font: 'TkDefaultFont 10',
+                 command: proc { |*| toggle_music })
+    @app.command(:pack, @music_btn, side: :right, padx: 2, pady: 3)
   end
 
   # The game grid is a single Tk canvas filled with image items.
@@ -184,15 +216,27 @@ class Minesweeper
     @app.command(:canvas, @canvas, width: cw, height: ch, highlightthickness: 0)
     @app.command(:pack, @canvas)
 
-    # Left-click: reveal a cell
-    lcb = @app.register_callback(proc { |*|
+    # Left-click: press shows sunken tile + suspense face, release reveals.
+    # This mimics classic Windows Minesweeper's press-and-hold behavior.
+    @pressed_cell = nil
+
+    press_cb = @app.register_callback(proc { |*|
       row, col = canvas_cell
-      on_left_click(row, col) if row
+      on_left_press(row, col) if row
     })
-    @app.tcl_eval("bind #{@canvas} <Button-1> " \
+    @app.tcl_eval("bind #{@canvas} <ButtonPress-1> " \
                   "{set ::_ms_x [#{@canvas} canvasx %x]; " \
                   "set ::_ms_y [#{@canvas} canvasy %y]; " \
-                  "ruby_callback #{lcb}}")
+                  "ruby_callback #{press_cb}}")
+
+    release_cb = @app.register_callback(proc { |*|
+      row, col = canvas_cell
+      on_left_release(row, col) if row
+    })
+    @app.tcl_eval("bind #{@canvas} <ButtonRelease-1> " \
+                  "{set ::_ms_x [#{@canvas} canvasx %x]; " \
+                  "set ::_ms_y [#{@canvas} canvasy %y]; " \
+                  "ruby_callback #{release_cb}}")
 
     # Right-click: toggle flag. Binding all three events covers:
     #   Button-2  -- right-click on macOS
@@ -240,6 +284,7 @@ class Minesweeper
     @app.command(@face, :configure, text: ':)')
 
     draw_board
+    @music.play if @music_on && !@music.playing?
   end
 
   # Changing difficulty resizes the canvas and resets. The window auto-shrinks
@@ -285,7 +330,8 @@ class Minesweeper
 
     candidates = []
     @rows.times { |r| @cols.times { |c| candidates << [r, c] unless safe[[r, c]] } }
-    candidates.shuffle!.first(@num_mines).each { |r, c| @mine[r][c] = true }
+    rng = ENV['SEED'] ? Random.new(ENV['SEED'].to_i) : Random.new
+    candidates.shuffle!(random: rng).first(@num_mines).each { |r, c| @mine[r][c] = true }
 
     # Precompute how many mines neighbor each cell
     @rows.times do |r|
@@ -298,7 +344,29 @@ class Minesweeper
 
   # -- Click handlers ------------------------------------------------------
 
-  def on_left_click(r, c)
+  def on_left_press(r, c)
+    return if @game_over || @flagged[r][c] || @revealed[r][c]
+
+    # Show sunken/pressed tile and suspense face
+    @pressed_cell = [r, c]
+    set_cell_image(r, c, :empty)
+    @app.command(@face, :configure, text: ':o')
+  end
+
+  def on_left_release(r, c)
+    prev = @pressed_cell
+    @pressed_cell = nil
+
+    # Restore face
+    @app.command(@face, :configure, text: ':)') unless @game_over
+
+    # If released on a different cell than pressed, restore the pressed cell
+    if prev && prev != [r, c]
+      pr, pc = prev
+      set_cell_image(pr, pc, :hidden) unless @revealed[pr][pc]
+      return
+    end
+
     return if @game_over || @flagged[r][c] || @revealed[r][c]
 
     if @first_click
@@ -308,8 +376,10 @@ class Minesweeper
     end
 
     if @mine[r][c]
+      @snd_explosion.play
       game_over_lose(r, c)
     else
+      @cascading = false
       reveal(r, c)
       check_win
     end
@@ -318,6 +388,7 @@ class Minesweeper
   def on_right_click(r, c)
     return if @game_over || @revealed[r][c]
 
+    @snd_flag.play
     if @flagged[r][c]
       @flagged[r][c] = false
       @flags_placed -= 1
@@ -344,8 +415,13 @@ class Minesweeper
 
     if count == 0
       set_cell_image(r, c, :empty)
+      unless @cascading
+        @cascading = true
+        @snd_sweep.play
+      end
       neighbors(r, c).each { |nr, nc| reveal(nr, nc) }
     else
+      @snd_click.play unless @cascading
       set_cell_image(r, c, count)
     end
   end
@@ -375,6 +451,7 @@ class Minesweeper
     @game_over = true
     stop_timer
     @app.command(@face, :configure, text: ':(')
+    Teek::SDL2.fade_out_music(1500) if @music_on
 
     @rows.times do |r|
       @cols.times do |c|
@@ -405,6 +482,24 @@ class Minesweeper
     @app.after(1000) { tick_timer }
   end
 
+  # -- Music ---------------------------------------------------------------
+
+  def toggle_music
+    if @music_on
+      @music.pause
+      @music_on = false
+      @app.command(@music_btn, :configure, text: '--')
+    else
+      if @music.paused?
+        @music.resume
+      else
+        @music.play
+      end
+      @music_on = true
+      @app.command(@music_btn, :configure, text: "\u266A")
+    end
+  end
+
   # -- Helpers -------------------------------------------------------------
 
   def in_bounds?(r, c)
@@ -437,16 +532,56 @@ app = Teek::App.new(track_widgets: false)
 # The root window starts withdrawn by default in Teek -- show it.
 app.show
 
-Minesweeper.new(app)
+game = Minesweeper.new(app)
 
 # Automated demo support (for rake docker:test and recording)
 require_relative '../../lib/teek/demo_support'
 TeekDemo.app = app
 
-if TeekDemo.testing?
-  TeekDemo.after_idle do
-    app.after(500) { TeekDemo.finish }
+if TeekDemo.active?
+  ENV['SEED'] = '42'
+  game.send(:new_game) # restart with deterministic layout
+
+  if TeekDemo.recording?
+    app.set_window_geometry('+0+0')
+    app.tcl_eval('. configure -cursor none')
+    TeekDemo.signal_recording_ready
   end
+
+  # Capture all audio output to WAV when TEEK_RECORD_AUDIO is set.
+  # The WAV can be muxed with the screen recording via ffmpeg:
+  #   ffmpeg -i screen.mp4 -i yam_audio.wav -c:v copy -c:a aac -shortest out.mp4
+  audio_capture_path = ENV['TEEK_RECORD_AUDIO']
+  audio_capture_path = nil if audio_capture_path&.empty?
+  Teek::SDL2.start_audio_capture(audio_capture_path) if audio_capture_path
+
+  TeekDemo.after_idle {
+    d = TeekDemo.method(:delay)
+
+    # Click (row=2, col=3) — safe reveal, then (row=0, col=4) — mine. Boom!
+    steps = [
+      -> { game.press_cell(2, 3) },
+      -> { game.release_cell(2, 3) },
+      nil,
+      -> { game.press_cell(0, 4) },
+      -> { game.release_cell(0, 4) },
+      nil, nil,
+      -> {
+        Teek::SDL2.stop_audio_capture if audio_capture_path
+        TeekDemo.finish
+      },
+    ]
+
+    i = 0
+    run_step = proc {
+      steps[i]&.call
+      i += 1
+      if i < steps.length
+        app.after(d.call(test: 50, record: 1500)) { run_step.call }
+      end
+    }
+    run_step.call
+  }
 end
 
 app.mainloop

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teek
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - James Cook
@@ -141,22 +141,12 @@ files:
 - lib/teek/widget.rb
 - sample/calculator.rb
 - sample/debug_demo.rb
+- sample/gamepad_viewer/assets/controller.png
+- sample/gamepad_viewer/gamepad_viewer.rb
 - sample/goldberg.rb
 - sample/goldberg_helpers.rb
-- sample/minesweeper/assets/MINESWEEPER_0.png
-- sample/minesweeper/assets/MINESWEEPER_1.png
-- sample/minesweeper/assets/MINESWEEPER_2.png
-- sample/minesweeper/assets/MINESWEEPER_3.png
-- sample/minesweeper/assets/MINESWEEPER_4.png
-- sample/minesweeper/assets/MINESWEEPER_5.png
-- sample/minesweeper/assets/MINESWEEPER_6.png
-- sample/minesweeper/assets/MINESWEEPER_7.png
-- sample/minesweeper/assets/MINESWEEPER_8.png
-- sample/minesweeper/assets/MINESWEEPER_F.png
-- sample/minesweeper/assets/MINESWEEPER_M.png
-- sample/minesweeper/assets/MINESWEEPER_X.png
-- sample/minesweeper/minesweeper.rb
 - sample/optcarrot.rb
+- sample/optcarrot/thwaite.nes
 - sample/optcarrot/vendor/optcarrot.rb
 - sample/optcarrot/vendor/optcarrot/apu.rb
 - sample/optcarrot/vendor/optcarrot/config.rb
@@ -183,6 +173,24 @@ files:
 - sample/paint/sparse_pixel_buffer.rb
 - sample/sdl2_demo.rb
 - sample/threading_demo.rb
+- sample/yam/assets/MINESWEEPER_0.png
+- sample/yam/assets/MINESWEEPER_1.png
+- sample/yam/assets/MINESWEEPER_2.png
+- sample/yam/assets/MINESWEEPER_3.png
+- sample/yam/assets/MINESWEEPER_4.png
+- sample/yam/assets/MINESWEEPER_5.png
+- sample/yam/assets/MINESWEEPER_6.png
+- sample/yam/assets/MINESWEEPER_7.png
+- sample/yam/assets/MINESWEEPER_8.png
+- sample/yam/assets/MINESWEEPER_F.png
+- sample/yam/assets/MINESWEEPER_M.png
+- sample/yam/assets/MINESWEEPER_X.png
+- sample/yam/assets/click.wav
+- sample/yam/assets/explosion.wav
+- sample/yam/assets/flag.wav
+- sample/yam/assets/music.mp3
+- sample/yam/assets/sweep.wav
+- sample/yam/yam.rb
 - teek.gemspec
 homepage: https://github.com/jamescook/teek
 licenses: