teek 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbf5c504422362129bd97b61be21e564e0c4fc4eddced045f97320a14d77d999
-  data.tar.gz: 2a2d74b99b040fe345f67ae83f52b7f759b24c5a2b86a644f3673d0539676023
+  metadata.gz: 92cd230fed0f898dcf23f80a0a6058adcf308e14b4a8f7feb6985026be4692e0
+  data.tar.gz: 698f02315ab27973a05490552fbd6aec21447987a726119d583cbc98f197c486
 SHA512:
-  metadata.gz: 7a380c5190906c2537aaca29e7da5c6def0abb727db6ca1137ace00f2fd9f85876753b192cd1ff327108a62123b25c8db2db20dbe98c01ca82dbb8a2de11333d
-  data.tar.gz: c6ed01ff47f5edf05407b3e60bd1108a94461988053e013becaadbed0fa9697990e92e28ceed55341299d7f42a11dcecdc21b8b803cef86ff50538efe6fcee1b
+  metadata.gz: b259a6ed4a721cfe5179d53eacffdd67f9e3213af17e81eb9c8e434a8857456bf55e2d2798ccddf0099bfe001294fae2cf187111f9aafa575e84e90a1528314e
+  data.tar.gz: 20c96ae1cb5f4340737bcd4db2539c01f47f19c7b837bd85fff18ada2d707c4719cabfe0dc14ab1bf986e9b15aee6d61d64883dba4f33f758c3896b9877014c1

data/README.md

@@ -175,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

@@ -107,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')
@@ -119,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"
@@ -178,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'
@@ -272,8 +382,32 @@ namespace :docker do
   Rake::Task['docker:test'].enhance { Rake::Task['docker:prune'].invoke }
 
   namespace :test do
-    desc "Run tests with coverage and generate report"
-    task coverage: 'docker:build' 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)
@@ -282,11 +416,17 @@ namespace :docker do
       FileUtils.rm_rf('coverage')
       FileUtils.mkdir_p('coverage/results')
 
-      # Run tests with coverage enabled
+      # Run both test suites with coverage enabled and distinct COVERAGE_NAMEs
       ENV['COVERAGE'] = '1'
-      ENV['COVERAGE_NAME'] ||= 'main'
+
+      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"
@@ -304,10 +444,26 @@ namespace :docker do
     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

@@ -1481,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 */

data/ext/teek/tkeventsource.c

@@ -0,0 +1,195 @@
+/*
+ * tkeventsource.c - External event source integration via Tcl_CreateEventSource
+ *
+ * Allows other C extensions (e.g. teek-sdl2) to register poll callbacks
+ * that run inside Tcl's event loop with zero Ruby overhead in the hot path.
+ *
+ * The consumer passes a C function pointer via a Ruby method call at
+ * registration time. The Tcl event source setup/check procs call that
+ * pointer directly — no rb_funcall, no method dispatch.
+ */
+
+#include "tcltkbridge.h"
+#include <stdint.h>
+
+static VALUE cEventSource;
+
+/* ---------------------------------------------------------
+ * Event source struct — wrapped as Ruby TypedData
+ * --------------------------------------------------------- */
+
+typedef void (*event_source_check_fn)(void *client_data);
+
+struct event_source {
+    event_source_check_fn check_fn;  /* C function pointer from consumer */
+    void *client_data;               /* Opaque data from consumer */
+    Tcl_Time max_block;              /* Max block time for setup proc */
+    int registered;                  /* Whether Tcl event source is active */
+};
+
+/* Forward declarations */
+static void es_setup_proc(ClientData cd, int flags);
+static void es_check_proc(ClientData cd, int flags);
+
+/* ---------------------------------------------------------
+ * TypedData functions
+ * --------------------------------------------------------- */
+
+static void
+event_source_free(void *ptr)
+{
+    struct event_source *es = ptr;
+    if (es->registered) {
+        Tcl_DeleteEventSource(es_setup_proc, es_check_proc, (ClientData)es);
+        es->registered = 0;
+    }
+    xfree(es);
+}
+
+static size_t
+event_source_memsize(const void *ptr)
+{
+    return sizeof(struct event_source);
+}
+
+static const rb_data_type_t event_source_type = {
+    .wrap_struct_name = "Teek::EventSource",
+    .function = {
+        .dmark = NULL,  /* No Ruby VALUEs to mark */
+        .dfree = event_source_free,
+        .dsize = event_source_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+/* ---------------------------------------------------------
+ * Tcl event source callbacks (hot path — pure C)
+ * --------------------------------------------------------- */
+
+/*
+ * Setup proc: called before Tcl_WaitForEvent.
+ * Caps the block time so our check proc runs frequently.
+ */
+static void
+es_setup_proc(ClientData cd, int flags)
+{
+    struct event_source *es = (struct event_source *)cd;
+
+    if (!(flags & TCL_FILE_EVENTS) && !(flags & TCL_ALL_EVENTS))
+        return;
+
+    Tcl_SetMaxBlockTime(&es->max_block);
+}
+
+/*
+ * Check proc: called after Tcl_WaitForEvent returns.
+ * Calls the consumer's C function pointer directly.
+ * No rb_funcall, no Ruby method dispatch — just a function pointer call.
+ */
+static void
+es_check_proc(ClientData cd, int flags)
+{
+    struct event_source *es = (struct event_source *)cd;
+
+    if (!(flags & TCL_FILE_EVENTS) && !(flags & TCL_ALL_EVENTS))
+        return;
+
+    es->check_fn(es->client_data);
+}
+
+/* ---------------------------------------------------------
+ * Ruby methods
+ * --------------------------------------------------------- */
+
+/*
+ * Teek._register_event_source(check_fn_ptr, client_data_ptr, interval_ms) -> EventSource
+ *
+ * Registers a C function as a Tcl event source. The function will be called
+ * on every event loop iteration with no Ruby overhead.
+ *
+ * check_fn_ptr:    Integer — address of a C function with signature void(*)(void*)
+ * client_data_ptr: Integer — address passed to check_fn (0 for NULL)
+ * interval_ms:     Integer — max block time in ms (e.g. 16 for ~60fps)
+ *
+ * Returns an opaque EventSource object. Hold a reference to keep it alive.
+ * Call #unregister or let GC collect it to remove the event source.
+ */
+static VALUE
+teek_register_event_source(VALUE self, VALUE fn_ptr, VALUE data_ptr, VALUE interval)
+{
+    struct event_source *es;
+    VALUE obj;
+    int ms;
+
+    /* Validate */
+    event_source_check_fn fn = (event_source_check_fn)(uintptr_t)NUM2ULL(fn_ptr);
+    if (!fn) {
+        rb_raise(rb_eArgError, "check_fn_ptr must not be NULL");
+    }
+
+    ms = NUM2INT(interval);
+    if (ms < 1) ms = 1;
+
+    /* Allocate and populate */
+    obj = TypedData_Make_Struct(cEventSource, struct event_source, &event_source_type, es);
+    es->check_fn = fn;
+    es->client_data = (void *)(uintptr_t)NUM2ULL(data_ptr);
+    es->max_block.sec = ms / 1000;
+    es->max_block.usec = (ms % 1000) * 1000;
+    es->registered = 0;
+
+    /* Register with Tcl */
+    Tcl_CreateEventSource(es_setup_proc, es_check_proc, (ClientData)es);
+    es->registered = 1;
+
+    return obj;
+}
+
+/*
+ * EventSource#unregister -> nil
+ *
+ * Explicitly removes the event source from Tcl's notifier.
+ * Safe to call multiple times.
+ */
+static VALUE
+event_source_unregister(VALUE self)
+{
+    struct event_source *es;
+    TypedData_Get_Struct(self, struct event_source, &event_source_type, es);
+
+    if (es->registered) {
+        Tcl_DeleteEventSource(es_setup_proc, es_check_proc, (ClientData)es);
+        es->registered = 0;
+    }
+    return Qnil;
+}
+
+/*
+ * EventSource#registered? -> true/false
+ */
+static VALUE
+event_source_registered_p(VALUE self)
+{
+    struct event_source *es;
+    TypedData_Get_Struct(self, struct event_source, &event_source_type, es);
+    return es->registered ? Qtrue : Qfalse;
+}
+
+/* ---------------------------------------------------------
+ * Init — called from Init_tcltklib
+ * --------------------------------------------------------- */
+
+static VALUE cEventSource;
+
+void
+Init_tkeventsource(VALUE mTeek)
+{
+    cEventSource = rb_define_class_under(mTeek, "EventSource", rb_cObject);
+    rb_undef_alloc_func(cEventSource);  /* No Ruby-side new */
+
+    rb_define_method(cEventSource, "unregister", event_source_unregister, 0);
+    rb_define_method(cEventSource, "registered?", event_source_registered_p, 0);
+
+    rb_define_module_function(mTeek, "_register_event_source",
+                             teek_register_event_source, 3);
+}