teek 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a6639b7742fe7c1be6b94ddb2e7ea7e5f65f66d4525931f5a916a92ebe45a90
-  data.tar.gz: 0ef9c6a423201a35123193b951577f6f1aa2e375cbabdd20d5d34a35bdd47335
+  metadata.gz: 92cd230fed0f898dcf23f80a0a6058adcf308e14b4a8f7feb6985026be4692e0
+  data.tar.gz: 698f02315ab27973a05490552fbd6aec21447987a726119d583cbc98f197c486
 SHA512:
-  metadata.gz: 252f099b49231033ba5b59d7108c79f920247e357d80ac236b2ead0772b09e5af9aa023855b91597d73586e1c9d78a16724f8d57d7a1d12cddb082ce35e23de7
-  data.tar.gz: bb50dfed0ede92e95c55a74a047a9382498605579c28c6a874cbd5837ceb5a4e13d94b1360446dca0af22ab556a35c9e9ea7919f10235fb4332f52c7f1529129
+  metadata.gz: b259a6ed4a721cfe5179d53eacffdd67f9e3213af17e81eb9c8e434a8857456bf55e2d2798ccddf0099bfe001294fae2cf187111f9aafa575e84e90a1528314e
+  data.tar.gz: 20c96ae1cb5f4340737bcd4db2539c01f47f19c7b837bd85fff18ada2d707c4719cabfe0dc14ab1bf986e9b15aee6d61d64883dba4f33f758c3896b9877014c1

data/README.md

@@ -12,14 +12,13 @@ require 'teek'
 app = Teek::App.new
 
 app.show
-app.tcl_eval('wm title . "Hello Teek"')
+app.set_window_title('Hello Teek')
 
-# Create widgets with tcl_eval
-app.tcl_eval('ttk::label .lbl -text "Hello, world!"')
-app.tcl_eval('pack .lbl -pady 10')
-
-# Or use the command helper — Ruby values are auto-quoted,
+# Create widgets with the command helper — Ruby values are auto-quoted,
 # symbols pass through bare, and procs become callbacks
+app.command('ttk::label', '.lbl', text: 'Hello, world!')
+app.command(:pack, '.lbl', pady: 10)
+
 app.command('ttk::button', '.btn', text: 'Click me', command: proc {
   app.command('.lbl', :configure, text: 'Clicked!')
 })
@@ -28,17 +27,57 @@ app.command(:pack, '.btn', pady: 10)
 app.mainloop
 ```
 
+## Widgets
+
+`create_widget` returns a `Teek::Widget` — a thin wrapper that holds the widget path and provides convenience methods. Paths are auto-generated from the widget type.
+
+```ruby
+btn = app.create_widget('ttk::button', text: 'Click me')
+btn.pack(pady: 10)
+
+btn.command(:configure, text: 'Updated')  # widget subcommand
+btn.destroy
+```
+
+Nest widgets under a parent:
+
+```ruby
+frame = app.create_widget('ttk::frame')
+frame.pack(fill: :both, expand: 1)
+
+label = app.create_widget('ttk::label', parent: frame, text: 'Hello')
+label.pack(pady: 5)
+```
+
+Widgets work anywhere a path string is expected (via `to_s`):
+
+```ruby
+app.command(:pack, btn, pady: 10)       # equivalent to btn.pack(pady: 10)
+app.tcl_eval("#{btn} configure -text New")  # string interpolation works
+```
+
+The raw `app.command` approach still works for cases where you don't need a wrapper:
+
+```ruby
+app.command('ttk::label', '.mylabel', text: 'Direct')
+app.command(:pack, '.mylabel')
+```
+
 ## Callbacks
 
-Register Ruby procs as Tcl callbacks using `app.register_callback`:
+Pass a `proc` to `command` and it becomes a Tcl callback automatically:
 
 ```ruby
 app = Teek::App.new
 
-cb = app.register_callback(proc { |*args|
-  puts "clicked!"
-})
-app.tcl_eval("button .b -text Click -command {ruby_callback #{cb}}")
+app.command(:button, '.b', text: 'Click', command: proc { puts "clicked!" })
+```
+
+Use `bind` for event bindings with optional substitutions:
+
+```ruby
+app.bind('.b', 'Enter') { puts "hovered" }
+app.bind('.c', 'Button-1', :x, :y) { |x, y| puts "#{x},#{y}" }
 ```
 
 ### Stopping event propagation
@@ -46,11 +85,10 @@ app.tcl_eval("button .b -text Click -command {ruby_callback #{cb}}")
 In `bind` handlers, you can stop an event from propagating to subsequent binding tags by throwing `:teek_break`:
 
 ```ruby
-cb = app.register_callback(proc { |*|
-  puts "handled - stop here"
+app.bind('.entry', 'KeyPress', :keysym) { |key|
+  puts "handled #{key} - stop here"
   throw :teek_break
-})
-app.tcl_eval("bind .entry <Key-Return> {ruby_callback #{cb}}")
+}
 ```
 
 This is equivalent to Tcl's `break` command in a bind script.
@@ -137,3 +175,49 @@ The debugger provides three tabs:
 - **Watches** — right-click or double-click a variable to watch it; tracks last 50 values with timestamps
 
 The debugger runs in the same interpreter as your app (as a [Toplevel](https://www.tcl-lang.org/man/tcl8.6/TkCmd/toplevel.htm) window) and filters its own widgets from `app.widgets`.
+
+## Background Work
+
+Tk applications need to keep the UI responsive while doing CPU-intensive work. The `Teek.background_work` API runs work in a background Ractor with automatic UI integration.
+
+**This API is designed for Ruby 4.x.** Ractors on Ruby 3.x lack shareable procs, making them impractical for our use case. A `:thread` mode exists but is rarely beneficial — Ruby threads share the GVL, so thread-based background work often performs *worse* than running inline unless the work involves non-blocking I/O.
+
+```ruby
+app = Teek::App.new
+app.show
+app.set_variable('::progress', 0)
+
+log = app.create_widget(:text, width: 60, height: 10)
+log.pack(fill: :both, expand: 1, padx: 10, pady: 5)
+
+app.create_widget('ttk::progressbar', variable: '::progress', maximum: 100)
+  .pack(fill: :x, padx: 10, pady: 5)
+
+files = Dir.glob('**/*').select { |f| File.file?(f) }
+
+task = Teek::BackgroundWork.new(app, files) do |t, data|
+  # Background work goes here - this block cannot access Tk
+  data.each_with_index do |file, i|
+    t.check_pause
+    hash = Digest::SHA256.file(file).hexdigest
+    t.yield({ file: file, hash: hash, pct: (i + 1) * 100 / data.size })
+  end
+end.on_progress do |msg|
+  # This block can access Tk
+  log.command(:insert, :end, "#{msg[:file]}: #{msg[:hash]}\n")
+  log.command(:see, :end)
+  app.set_variable('::progress', msg[:pct])
+end.on_done do
+  # This block can also access Tk
+  log.command(:insert, :end, "Done!\n")
+end
+
+# Control the task
+task.pause   # Pause work (resumes at next t.check_pause)
+task.resume  # Resume paused work
+task.stop    # Stop completely
+```
+
+The work block runs in a background Ractor and cannot access Tk directly. Use `t.yield()` to send results to `on_progress`, which runs on the main thread where Tk is available. Callbacks (`on_progress`, `on_done`) can be chained in any order.
+
+See [`sample/threading_demo.rb`](sample/threading_demo.rb) for a complete file hasher example.

data/Rakefile

@@ -26,8 +26,18 @@ namespace :docs do
     end
   end
 
+  desc "Generate per-method coverage JSON from SimpleCov data"
+  task :method_coverage do
+    if Dir.exist?('coverage/results')
+      require_relative 'lib/teek/method_coverage_service'
+      Teek::MethodCoverageService.new(coverage_dir: 'coverage').call
+    else
+      puts "No coverage data found (run tests with COVERAGE=1 first)"
+    end
+  end
+
   desc "Generate API docs (YARD JSON -> HTML)"
-  task yard: :yard_json do
+  task yard: [:yard_json, :method_coverage] do
     Bundler.with_unbundled_env do
       sh 'BUNDLE_GEMFILE=docs_site/Gemfile bundle exec ruby docs_site/build_api_docs.rb'
     end
@@ -97,6 +107,7 @@ task yard: 'docs:yard'
 # Clean up extconf cached config files
 CLEAN.include('ext/teek/config_list')
 CLOBBER.include('tmp', 'lib/*.bundle', 'lib/*.so', 'ext/**/*.o', 'ext/**/*.bundle', 'ext/**/*.bundle.dSYM')
+CLOBBER.include('teek-sdl2/lib/*.bundle', 'teek-sdl2/lib/*.so', 'teek-sdl2/ext/**/*.o', 'teek-sdl2/ext/**/*.bundle')
 
 # Clean coverage artifacts before test runs to prevent accumulation
 CLEAN.include('coverage/.resultset.json', 'coverage/results')
@@ -109,6 +120,45 @@ if Gem::Specification.find_all_by_name('rake-compiler').any?
     ext.ext_dir = 'ext/teek'
     ext.lib_dir = 'lib'
   end
+
+  Rake::ExtensionTask.new do |ext|
+    ext.name = 'teek_sdl2'
+    ext.ext_dir = 'teek-sdl2/ext/teek_sdl2'
+    ext.lib_dir = 'teek-sdl2/lib'
+  end
+end
+
+namespace :screenshots do
+  desc "Bless current unverified screenshots as the new baselines"
+  task :bless do
+    require_relative 'test/screenshot_helper'
+    src = ScreenshotHelper.unverified_dir
+    dst = ScreenshotHelper.blessed_dir
+
+    pngs = Dir.glob(File.join(src, '*.png'))
+    if pngs.empty?
+      puts "No unverified screenshots in #{src}"
+      next
+    end
+
+    FileUtils.mkdir_p(dst)
+    pngs.each do |f|
+      FileUtils.cp(f, dst)
+      puts "  Blessed: #{File.basename(f)}"
+    end
+    puts "#{pngs.size} screenshot(s) blessed to #{dst}"
+  end
+
+  desc "Remove unverified screenshots and diffs"
+  task :clean do
+    require_relative 'test/screenshot_helper'
+    [ScreenshotHelper.unverified_dir, ScreenshotHelper.diffs_dir].each do |dir|
+      if Dir.exist?(dir)
+        FileUtils.rm_rf(dir)
+        puts "  Removed: #{dir}"
+      end
+    end
+  end
 end
 
 desc "Clear stale coverage artifacts"
@@ -168,8 +218,78 @@ def detect_platform
   end
 end
 
+namespace :sdl2 do
+  desc "Compile teek-sdl2 C extension"
+  task compile: 'compile:teek_sdl2'
+
+  Rake::TestTask.new(:test) do |t|
+    t.libs << 'teek-sdl2/test' << 'teek-sdl2/lib'
+    t.test_files = FileList['teek-sdl2/test/**/test_*.rb'] - FileList['teek-sdl2/test/test_helper.rb']
+    t.ruby_opts << '-r test_helper'
+    t.verbose = true
+  end
+  task test: 'compile:teek_sdl2'
+end
+
 task :default => :compile
 
+namespace :release do
+  desc "Build gems, install to temp dir, run smoke test"
+  task :smoke do
+    require 'tmpdir'
+    require 'fileutils'
+
+    Dir.mktmpdir('teek-smoke') do |tmpdir|
+      gem_home = File.join(tmpdir, 'gems')
+
+      # Build both gems
+      puts "Building gems..."
+      sh "gem build teek.gemspec -o #{tmpdir}/teek.gem 2>&1"
+      Dir.chdir('teek-sdl2') { sh "gem build teek-sdl2.gemspec -o #{tmpdir}/teek-sdl2.gem 2>&1" }
+
+      # Install into isolated GEM_HOME
+      puts "\nInstalling gems..."
+      sh "GEM_HOME=#{gem_home} gem install #{tmpdir}/teek.gem --no-document 2>&1"
+      sh "GEM_HOME=#{gem_home} gem install #{tmpdir}/teek-sdl2.gem --no-document 2>&1"
+
+      # Run smoke test using only the installed gems (no -I, no bundle)
+      puts "\nRunning SDL2 smoke test..."
+      smoke = <<~'RUBY'
+        require "teek"
+        require "teek/sdl2"
+
+        app = Teek::App.new
+        app.set_window_title("Release Smoke Test")
+        app.set_window_geometry("320x240")
+        app.show
+        app.update
+
+        vp = Teek::SDL2::Viewport.new(app, width: 300, height: 200)
+        vp.pack
+
+        vp.render do |r|
+          r.clear(30, 30, 30)
+          r.fill(20, 20, 120, 80, r: 200, g: 50, b: 50)
+          r.outline(160, 20, 120, 80, r: 50, g: 200, b: 50)
+          r.line(20, 130, 280, 180, r: 50, g: 50, b: 200)
+        end
+
+        w, h = vp.renderer.output_size
+        pixels = vp.renderer.read_pixels
+        raise "read_pixels size mismatch" unless pixels.bytesize == w * h * 4
+
+        app.after(500) { vp.destroy; app.destroy }
+        app.mainloop
+        puts "Release smoke test passed (teek #{Teek::VERSION}, teek-sdl2 #{Teek::SDL2::VERSION})"
+      RUBY
+
+      smoke_file = File.join(tmpdir, 'smoke.rb')
+      File.write(smoke_file, smoke)
+      sh "GEM_HOME=#{gem_home} GEM_PATH=#{gem_home} ruby #{smoke_file}"
+    end
+  end
+end
+
 # Docker tasks for local testing and CI
 namespace :docker do
   DOCKERFILE = 'Dockerfile.ci-test'
@@ -261,10 +381,89 @@ namespace :docker do
 
   Rake::Task['docker:test'].enhance { Rake::Task['docker:prune'].invoke }
 
+  namespace :test do
+    desc "Run teek-sdl2 tests in Docker"
+    task sdl2: :build do
+      tcl_version = tcl_version_from_env
+      ruby_version = ruby_version_from_env
+      image_name = docker_image_name(tcl_version, ruby_version)
+
+      require 'fileutils'
+      FileUtils.mkdir_p('coverage')
+
+      puts "Running teek-sdl2 tests in Docker (Ruby #{ruby_version}, Tcl #{tcl_version})..."
+      cmd = "docker run --rm --init"
+      cmd += " -v #{Dir.pwd}/coverage:/app/coverage"
+      cmd += " -v #{Dir.pwd}/screenshots:/app/screenshots"
+      cmd += " -e TCL_VERSION=#{tcl_version}"
+      if ENV['COVERAGE'] == '1'
+        cmd += " -e COVERAGE=1"
+        cmd += " -e COVERAGE_NAME=#{ENV['COVERAGE_NAME'] || 'sdl2'}"
+      end
+      cmd += " #{image_name}"
+      cmd += " xvfb-run -a bundle exec rake sdl2:test"
+
+      sh cmd
+    end
+
+    desc "Run all tests (teek + teek-sdl2) with coverage and generate report"
+    task all: 'docker:build' do
+      tcl_version = tcl_version_from_env
+      ruby_version = ruby_version_from_env
+      image_name = docker_image_name(tcl_version, ruby_version)
+
+      require 'fileutils'
+      FileUtils.rm_rf('coverage')
+      FileUtils.mkdir_p('coverage/results')
+
+      # Run both test suites with coverage enabled and distinct COVERAGE_NAMEs
+      ENV['COVERAGE'] = '1'
+
+      ENV['COVERAGE_NAME'] = 'main'
+      Rake::Task['docker:test'].invoke
+
+      ENV['COVERAGE_NAME'] = 'sdl2'
+      Rake::Task['docker:test:sdl2'].reenable
+      Rake::Task['docker:build'].reenable
+      Rake::Task['docker:test:sdl2'].invoke
+
+      # Collate inside Docker (paths match /app/lib/...)
+      puts "Collating coverage results..."
+      cmd = "docker run --rm --init"
+      cmd += " -v #{Dir.pwd}/coverage:/app/coverage"
+      cmd += " #{image_name}"
+      cmd += " bundle exec rake coverage:collate"
+
+      sh cmd
+
+      # Generate per-method coverage (runs locally, just needs Prism)
+      puts "Generating per-method coverage..."
+      Rake::Task['docs:method_coverage'].invoke
+
+      puts "Coverage report: coverage/index.html"
+    end
+  end
+
+  namespace :screenshots do
+    desc "Bless linux screenshots inside Docker (copies unverified/ to blessed/)"
+    task bless: :build do
+      ruby_version = ruby_version_from_env
+      tcl_version = tcl_version_from_env
+      image_name = docker_image_name(tcl_version, ruby_version)
+
+      cmd = "docker run --rm --init"
+      cmd += " -v #{Dir.pwd}/screenshots:/app/screenshots"
+      cmd += " #{image_name}"
+      cmd += " bundle exec rake screenshots:bless"
+
+      sh cmd
+    end
+  end
+
   # Scan sample files for # teek-record magic comment
   # Format: # teek-record: title=My Demo, codec=vp9
   def find_recordable_samples
-    Dir['sample/**/*.rb'].filter_map do |path|
+    Dir['sample/**/*.rb', 'teek-sdl2/sample/**/*.rb'].filter_map do |path|
       first_lines = File.read(path, 500)
       match = first_lines.match(/^#\s*teek-record(?::\s*(.+))?$/)
       next unless match

data/ext/teek/extconf.rb

@@ -74,6 +74,6 @@ end
 find_tcltk
 
 # Source files for the extension
-$srcs = ['tcltkbridge.c', 'tkphoto.c', 'tkfont.c', 'tkwin.c']
+$srcs = ['tcltkbridge.c', 'tkphoto.c', 'tkfont.c', 'tkwin.c', 'tkeventsource.c']
 
 create_makefile('tcltklib')

data/ext/teek/tcltkbridge.c

@@ -130,9 +130,6 @@ static void interp_deleted_callback(ClientData, Tcl_Interp *);
 /* 16ms ≈ 60fps - balances UI responsiveness with scheduler contention */
 #define DEFAULT_TIMER_INTERVAL_MS 16
 
-/* Global timer interval for TclTkLib.mainloop (mutable) */
-static int g_thread_timer_ms = DEFAULT_TIMER_INTERVAL_MS;
-
 /* struct tcltk_interp is defined in tcltkbridge.h */
 
 /* ---------------------------------------------------------
@@ -1066,109 +1063,6 @@ interp_mainloop(VALUE self)
  * yields between events).
  * --------------------------------------------------------- */
 
-/* Global timer handler - re-registers itself using global interval */
-static void
-global_keepalive_timer_proc(ClientData clientData)
-{
-    if (g_thread_timer_ms > 0) {
-        Tcl_CreateTimerHandler(g_thread_timer_ms, global_keepalive_timer_proc, NULL);
-    }
-}
-
-static VALUE
-lib_mainloop(int argc, VALUE *argv, VALUE self)
-{
-    int check_root = 1;  /* default: exit when no windows remain */
-    int event_flags = TCL_ALL_EVENTS;
-
-    /* Optional check_root argument:
-     *   true (default): exit when Tk_GetNumMainWindows() == 0
-     *   false: keep running even with no windows (for timers, traces, etc.)
-     */
-    if (argc > 0 && argv[0] != Qnil) {
-        check_root = RTEST(argv[0]);
-    }
-
-    for (;;) {
-        /* Exit if check_root enabled and no windows remain */
-        if (check_root && Tk_GetNumMainWindows() <= 0) {
-            break;
-        }
-
-        if (rb_thread_alone()) {
-            /* No other threads - simple blocking wait */
-            Tcl_DoOneEvent(event_flags);
-        } else {
-            /* Other threads exist - use polling with brief sleep.
-             *
-             * We tried rb_thread_call_without_gvl() with Tcl_ThreadAlert to
-             * efficiently release GVL during blocking waits, but it proved
-             * unstable - crashes in Digest and other C extensions, UI freezes,
-             * and unreliable notifier wakeup across platforms.
-             *
-             * This polling approach is simple and stable:
-             * - Process any pending events without blocking
-             * - If no events, brief sleep to avoid spinning (uses ~1-3% CPU idle)
-             * - rb_thread_schedule() lets background threads run during sleep
-             */
-            int had_event = Tcl_DoOneEvent(event_flags | TCL_DONT_WAIT);
-            if (!had_event) {
-                rb_thread_schedule();
-#ifdef _WIN32
-                Sleep(5);  /* 5ms */
-#else
-                struct timespec ts = {0, 5000000};  /* 5ms */
-                nanosleep(&ts, NULL);
-#endif
-            }
-        }
-
-        /* Check for Ruby interrupts (Ctrl-C, etc) */
-        rb_thread_check_ints();
-    }
-
-    return Qnil;
-}
-
-static VALUE
-lib_get_thread_timer_ms(VALUE self)
-{
-    return INT2NUM(g_thread_timer_ms);
-}
-
-static VALUE
-lib_set_thread_timer_ms(VALUE self, VALUE val)
-{
-    int ms = NUM2INT(val);
-    if (ms < 0) {
-        rb_raise(rb_eArgError, "thread_timer_ms must be >= 0 (got %d)", ms);
-    }
-    g_thread_timer_ms = ms;
-    return val;
-}
-
-/* ---------------------------------------------------------
- * TclTkLib.do_one_event(flags = ALL_EVENTS) - Process single event
- *
- * Global function - Tcl_DoOneEvent doesn't require an interpreter.
- * Returns true if event was processed, false if nothing to do.
- * --------------------------------------------------------- */
-
-static VALUE
-lib_do_one_event(int argc, VALUE *argv, VALUE self)
-{
-    int flags = TCL_ALL_EVENTS;
-    int result;
-
-    if (argc > 0) {
-        flags = NUM2INT(argv[0]);
-    }
-
-    result = Tcl_DoOneEvent(flags);
-
-    return result ? Qtrue : Qfalse;
-}
-
 /* ---------------------------------------------------------
  * Interp#thread_timer_ms / #thread_timer_ms= - Get/set timer interval
  * --------------------------------------------------------- */
@@ -1539,10 +1433,6 @@ Init_tcltklib(void)
     rb_define_module_function(mTeek, "split_list", teek_split_list, 1);
     rb_define_module_function(mTeek, "tcl_to_bool", teek_tcl_to_bool, 1);
 
-    /* Global thread timer - doesn't require an interpreter */
-    rb_define_module_function(mTeek, "thread_timer_ms", lib_get_thread_timer_ms, 0);
-    rb_define_module_function(mTeek, "thread_timer_ms=", lib_set_thread_timer_ms, 1);
-
     /* Callback depth detection for unsafe operation warnings */
     rb_define_module_function(mTeek, "in_callback?", lib_in_callback_p, 0);
 
@@ -1591,6 +1481,9 @@ Init_tcltklib(void)
     /* Tk window query functions (tkwin.c) */
     Init_tkwin(cInterp);
 
+    /* External event source integration (tkeventsource.c) */
+    Init_tkeventsource(mTeek);
+
     /* Class methods for instance tracking */
     rb_define_singleton_method(cInterp, "instance_count", tcltkip_instance_count, 0);
     rb_define_singleton_method(cInterp, "instances", tcltkip_instances, 0);

data/ext/teek/tcltkbridge.h

@@ -39,4 +39,7 @@ void Init_tkfont(VALUE cInterp);
 /* Tk window query functions - defined in tkwin.c */
 void Init_tkwin(VALUE cInterp);
 
+/* External event source integration - defined in tkeventsource.c */
+void Init_tkeventsource(VALUE mTeek);
+
 #endif /* TCLTKBRIDGE_H */