konpeito 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6e49cc678968c9afbf41e3483ce19ac9d0f506bf18b31def5de3468fdef18b3
-  data.tar.gz: f6f85c8b6d646c56ace6b35338ea66adeabc53eec3a21b50b0953346145b0d59
+  metadata.gz: 50ad4b5d35d1b8abd26ee9d941a901b99e281eb9cc7d2deed777f3ebf12b2308
+  data.tar.gz: fc91a16a60718a8a910776ab56f01a09d49ec2ee78e71082965392f1dee332e1
 SHA512:
-  metadata.gz: cc766128892195b93c5acf173b7a84c3ee86415932b9d477a952a824cb9167b15c7e63b74ab894dcd7e8213e731b5c6b2dfd1f2ef829c2e380583d7e85f1536b
-  data.tar.gz: 692f32eee6feb583b24b7f468fbd659c784f01c41ecde853272966c13bdda0032c47e8d55d0d0f0d084dd9493f0df50d9f0f483245f7d9f1a8ef98f43bbb6c70
+  metadata.gz: c2efa11a609aba145beef6d2b722028f657a6a4d5469864241cbdde1b43dc494b9cf814379788a8ede8d4715d0aceab76df3d64a1c6b14913a3e2f84d0787f1f
+  data.tar.gz: 77860386e45ac9a5b78ead9b0f02dfc3d759668fe5ffc3d97c72c4932ca297778d27192c6a698ad264f7641a988b07905dbf6a15c32f10320678999e89a604dc

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-14
+
+### Added
+- **KUI declarative UI framework**: Pure Ruby DSL for building GUI/TUI apps with a single codebase. Wraps Clay+Raylib (GUI) or ClayTUI (TUI). Widgets: `vpanel`, `hpanel`, `fixed_panel`, `label`, `label_num`, `button`, `menu_item`, `spacer`, `divider`, `progress_bar`. Theme system and unified key event abstraction.
+- **ClayTUI stdlib**: Terminal UI backend using Clay layout engine + termbox2 rendering. Auto-detected via `ClayTUI` module reference.
+- **KonpeitoShell stdlib**: Shell execution (`exec`, `system`), environment variables (`getenv`, `setenv`), and file I/O (`read_file`, `write_file`, `append_file`, `file_exists`) for mruby backend.
+- **RPG framework stdlib**: Reusable RPG game components (tilemap, sprites, camera, battle system) for raylib-based games.
+- **Stdlib auto-detection expansion**: `KonpeitoJSON`, `KonpeitoHTTP`, `KonpeitoCrypto`, `KonpeitoCompression` added to `STDLIB_MODULE_MAP` for automatic RBS injection when referenced in source code.
+- **KUI auto-path resolution**: `require "kui_gui"` / `require "kui_tui"` works without `-I` flags — KUI stdlib directory is automatically included in compiler search paths.
+- **KUI example apps**: Counter (GUI + TUI), minimal hello, multi-page dashboard with sidebar navigation.
+- **DQ RPG demo with Clay UI**: Battle scenes, shop menus, and status displays using Clay layout integration.
+- Keyword arguments documented as supported in mruby backend.
+
+### Fixed
+- **mruby GC crash in native callbacks**: `rb_block_call` stored raw C stack pointer (`data2`) in proc env — GC tried to dereference it as `RBasic*` causing crash in `gc_mark_children`. Fixed by storing `mrb_nil_value()` instead; the native callback path reads `data2` from a global, not from proc env.
+- **TUI rendering flicker**: Added per-frame string pool to `clay_tui_native.c` (64KB static buffer) to prevent Clay from holding pointers to GC-managed mruby heap memory that could be invalidated between frames.
+- **Documentation references**: Fixed CLAUDE.md referencing non-existent `docs/architecture.md`.
+
+### Changed
+- Tutorials (EN/JA) updated with KUI framework sections and all stdlib module documentation (Shell, JSON, HTTP, Crypto, Compression).
+
 ## [0.6.0] - 2026-03-11
 
 ### Added

data/lib/konpeito/codegen/llvm_generator.rb

@@ -69,7 +69,7 @@ module Konpeito
         end
       end
 
-      attr_reader :profiler, :variadic_functions, :alias_renamed_methods
+      attr_reader :profiler, :variadic_functions, :keyword_param_functions, :alias_renamed_methods
 
       def generate(hir_program)
         @hir_program = hir_program
@@ -1126,6 +1126,17 @@ module Konpeito
         init_builder.store(init_builder.call(mrb_undef_fn), @mrb_qundef_global)
         init_builder.ret_void
 
+        # GC arena management functions (prevent arena overflow in loops)
+        @konpeito_gc_arena_save = @mod.functions.add(
+          "konpeito_gc_arena_save", [], LLVM::Int32
+        )
+        @konpeito_gc_arena_restore = @mod.functions.add(
+          "konpeito_gc_arena_restore", [LLVM::Int32], LLVM.Void
+        )
+        @konpeito_gc_protect_value = @mod.functions.add(
+          "konpeito_gc_protect_value", [value_type], LLVM.Void
+        )
+
         # Clear @qnil etc. so the accessor methods know to load from globals
         @qnil = nil
         @qtrue = nil
@@ -1728,6 +1739,16 @@ module Konpeito
           end
         end
 
+        # For mruby: save GC arena index so we can restore before return.
+        # This prevents arena overflow when LLVM functions call each other
+        # directly (bypassing mruby dispatch's arena management).
+        @mruby_gc_arena_alloca = nil
+        if @runtime == :mruby
+          @mruby_gc_arena_alloca = @builder.alloca(LLVM::Int32, "_gc_arena")
+          arena_idx = @builder.call(@konpeito_gc_arena_save)
+          @builder.store(arena_idx, @mruby_gc_arena_alloca)
+        end
+
         # Insert profiling entry probe after parameter setup
         insert_profile_entry_probe(hir_func)
 
@@ -1753,6 +1774,21 @@ module Konpeito
         func
       end
 
+      # Emit a return instruction with mruby GC arena management.
+      # For the mruby backend, restores the arena to the saved index and
+      # protects the return value from GC before returning.
+      def emit_ret(value)
+        if @mruby_gc_arena_alloca
+          idx = @builder.load2(LLVM::Int32, @mruby_gc_arena_alloca, "_arena_r")
+          @builder.call(@konpeito_gc_arena_restore, idx)
+          # Protect the return value so it survives the arena restore
+          if value.type == value_type
+            @builder.call(@konpeito_gc_protect_value, value)
+          end
+        end
+        @builder.ret(value)
+      end
+
       # Topologically sort blocks based on phi dependencies
       # Ensures blocks are generated after the blocks their phi nodes reference
       def sort_blocks_by_phi_dependencies(blocks)
@@ -4843,6 +4879,9 @@ module Konpeito
         saved_allocas = @variable_allocas.dup
         saved_in_block_callback = @in_block_callback
         saved_block_callback_self = @block_callback_self
+        saved_mrb_cache = save_mrb_constant_cache
+        saved_current_function = @current_function
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # Create entry block for callback
         entry = callback_func.basic_blocks.append("entry")
@@ -4850,10 +4889,16 @@ module Konpeito
 
         # Reset variable tracking for callback scope.
         # Set @in_block_callback so nested proc creation uses GC-safe escape-cells mode.
+        # Reset mruby constant cache — LLVM values are scoped per function, so
+        # cached %qnil/%qtrue from the parent function are invalid here.
+        # Clear GC arena alloca — callbacks don't own their own arena scope.
         @in_block_callback = true
+        @mruby_gc_arena_alloca = nil
         @variables = {}
         @variable_types = {}
         @variable_allocas = {}
+        reset_mrb_constant_cache
+        @current_function = callback_func
 
         # Setup captured variable access through data2 pointer
         unless captures.empty?
@@ -5132,6 +5177,9 @@ module Konpeito
         @variable_allocas = saved_allocas
         @in_block_callback = saved_in_block_callback
         @block_callback_self = saved_block_callback_self
+        restore_mrb_constant_cache(saved_mrb_cache)
+        @current_function = saved_current_function
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -5583,6 +5631,7 @@ module Konpeito
         saved_block_callback_self = @block_callback_self
         saved_in_thread_callback = @in_thread_callback
         saved_thread_boxed_vars = @thread_boxed_vars
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # Create entry block for callback
         entry = callback_func.basic_blocks.append("entry")
@@ -5599,6 +5648,7 @@ module Konpeito
         @in_block_callback = false
         @block_callback_self = nil
         @in_thread_callback = true
+        @mruby_gc_arena_alloca = nil
 
         unless captures.empty?
           declare_free
@@ -5735,6 +5785,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @in_thread_callback = saved_in_thread_callback
         @thread_boxed_vars = saved_thread_boxed_vars
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -8134,11 +8185,13 @@ module Konpeito
         saved_block_callback_self = @block_callback_self
         saved_rescue_escape_array = @rescue_escape_array
         saved_rescue_escape_indices = @rescue_escape_indices
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # Reset variable tracking for callback scope
         @variables = {}
         @variable_types = {}
         @variable_allocas = {}
+        @mruby_gc_arena_alloca = nil
 
         if try_hir_blocks && !try_hir_blocks.empty?
           # Structured try body: process HIR BasicBlock list (handles control flow inside try).
@@ -8231,6 +8284,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @rescue_escape_array = saved_rescue_escape_array
         @rescue_escape_indices = saved_rescue_escape_indices
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -8252,6 +8306,7 @@ module Konpeito
         saved_block_callback_self = @block_callback_self
         saved_rescue_escape_array = @rescue_escape_array
         saved_rescue_escape_indices = @rescue_escape_indices
+        saved_gc_arena_alloca = @mruby_gc_arena_alloca
 
         # In normal mode: params[0] = self. In escape mode, set @block_callback_self after unpacking.
         @block_callback_self = callback_func.params[0] unless escape_var_names
@@ -8264,6 +8319,7 @@ module Konpeito
         @variables = {}
         @variable_types = {}
         @variable_allocas = {}
+        @mruby_gc_arena_alloca = nil
 
         # CRuby rescue callback: (VALUE data2, VALUE exception)
         exception_val = callback_func.params[1]
@@ -8393,6 +8449,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @rescue_escape_array = saved_rescue_escape_array
         @rescue_escape_indices = saved_rescue_escape_indices
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -8532,6 +8589,7 @@ module Konpeito
         @block_callback_self = saved_block_callback_self
         @rescue_escape_array = saved_rescue_escape_array
         @rescue_escape_indices = saved_rescue_escape_indices
+        @mruby_gc_arena_alloca = saved_gc_arena_alloca
 
         callback_func
       end
@@ -9593,9 +9651,9 @@ module Konpeito
             value, type_tag = get_value_with_type(term.value)
             # Box the value before returning to Ruby
             boxed = convert_value(value, type_tag, :value)
-            @builder.ret(boxed)
+            emit_ret(boxed)
           else
-            @builder.ret(qnil)
+            emit_ret(qnil)
           end
         when HIR::Branch
           condition, cond_type = get_value_with_type(term.condition)

data/lib/konpeito/codegen/mruby_backend.rb

@@ -8,6 +8,10 @@ module Konpeito
   module Codegen
     # Generates standalone executable from LLVM module using mruby runtime
     class MRubyBackend
+      # Stdlib modules that should be auto-defined in mruby init code
+      # even when no ModuleDef exists in HIR (cfunc-only modules).
+      STDLIB_MODULES = %w[Raylib Clay ClayTUI KonpeitoShell].freeze
+
       attr_reader :llvm_generator, :output_file, :module_name, :rbs_loader, :debug
 
       def initialize(llvm_generator, output_file:, module_name: nil, rbs_loader: nil, debug: false, extra_c_files: [],
@@ -62,6 +66,10 @@ module Konpeito
           clay_objs = ensure_clay_compiled
           extra_obj_files.concat(clay_objs)
 
+          # Compile vendored termbox2 library if ClayTUI is used
+          tb2_objs = ensure_termbox_compiled
+          extra_obj_files.concat(tb2_objs)
+
           obj_files = [obj_file, init_obj_file, helpers_obj_file] + extra_obj_files
 
           # Link into standalone executable
@@ -278,7 +286,9 @@ module Konpeito
         lines << ""
 
         # Define modules
+        defined_module_names = []
         hir.modules.each do |module_def|
+          defined_module_names << module_def.name.to_s
           module_var = "m#{module_def.name}"
           lines << "    struct RClass *#{module_var} = mrb_define_module(mrb, \"#{module_def.name}\");"
 
@@ -319,6 +329,18 @@ module Konpeito
           end
         end
 
+        # Auto-define stdlib modules that have cfunc methods but no ModuleDef in HIR.
+        # This ensures that even if a dynamic dispatch fallback occurs (e.g., due to
+        # a method name mismatch), the module constant exists at runtime.
+        if @rbs_loader
+          STDLIB_MODULES.each do |mod_name|
+            next if defined_module_names.include?(mod_name)
+            next unless @rbs_loader.has_cfunc_methods?(mod_name.to_sym)
+
+            lines << "    mrb_define_module(mrb, \"#{mod_name}\");"
+          end
+        end
+
         # Define NativeClasses with mrb_data_type
         native_classes.each do |class_name, class_type|
           lines.concat(generate_native_class_init(class_name, class_type))
@@ -434,8 +456,21 @@ module Konpeito
         else
           arity = llvm_func.params.size - 1  # Subtract self
 
+          # Check if this function has only keyword args (no positional params).
+          # If so, the kwargs hash arg is optional — caller may pass 0 args
+          # when no keywords are specified (e.g., `footer do ... end`).
+          func_base_name = mangled_name.sub(/\Arn_/, "")
+          kw_info = llvm_generator.keyword_param_functions[func_base_name] ||
+                    llvm_generator.keyword_param_functions[func_base_name.to_sym]
+          kwargs_only = kw_info && kw_info[:regular_count] == 0 && arity == 1
+
           lines << "static mrb_value #{wrapper_name}(mrb_state *mrb, mrb_value self) {"
-          if arity > 0
+          if kwargs_only
+            # Single optional kwargs hash arg — default to empty hash
+            lines << "    mrb_value a0 = mrb_nil_value(), _block = mrb_nil_value();"
+            lines << "    mrb_get_args(mrb, \"|o&\", &a0, &_block);"
+            lines << "    if (mrb_nil_p(a0)) a0 = mrb_hash_new(mrb);"
+          elsif arity > 0
             lines << "    mrb_value #{(0...arity).map { |i| "a#{i}" }.join(', ')}, _block;"
             format_str = "o" * arity + "&"
             args_list = (0...arity).map { |i| "&a#{i}" }.join(", ") + ", &_block"
@@ -933,6 +968,36 @@ module Konpeito
           )
         end
 
+        # Include termbox2 if ClayTUI is used
+        clay_tui_used = @extra_c_files.any? { |f| File.basename(f).include?("clay_tui") }
+        if clay_tui_used
+          sections << license_section(
+            "termbox2",
+            "MIT",
+            "Copyright (c) 2021 termbox developers",
+            "https://github.com/termbox/termbox2",
+            <<~MIT
+              Permission is hereby granted, free of charge, to any person obtaining a copy
+              of this software and associated documentation files (the "Software"), to deal
+              in the Software without restriction, including without limitation the rights
+              to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+              copies of the Software, and to permit persons to whom the Software is
+              furnished to do so, subject to the following conditions:
+
+              The above copyright notice and this permission notice shall be included in all
+              copies or substantial portions of the Software.
+
+              THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+              IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+              FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+              AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+              LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+              OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+              SOFTWARE.
+            MIT
+          )
+        end
+
         # Include raylib if linked
         ffi_libs = @rbs_loader&.all_ffi_libraries || []
         if ffi_libs.any? { |lib| lib.to_s.include?("raylib") }
@@ -1220,15 +1285,46 @@ module Konpeito
         [clay_impl_obj]
       end
 
+      # Compile vendored termbox2 implementation if ClayTUI stdlib is used
+      # Returns array of object file paths
+      def ensure_termbox_compiled
+        clay_tui_used = @extra_c_files.any? { |f| File.basename(f).include?("clay_tui") }
+        return [] unless clay_tui_used
+
+        tb2_dir = File.expand_path("../../../vendor/termbox2", __dir__)
+        tb2_impl_c = File.join(tb2_dir, "termbox2_impl.c")
+        tb2_impl_obj = File.join(tb2_dir, "termbox2_impl.o")
+
+        return [] unless File.exist?(tb2_impl_c)
+
+        cc, cc_flags = cross_cc_with_flags
+
+        # Compile termbox2_impl.c (only if stale)
+        unless File.exist?(tb2_impl_obj) && File.mtime(tb2_impl_obj) > File.mtime(tb2_impl_c)
+          cmd = [*cc, "-c", "-O2"]
+          cmd.concat(cc_flags)
+          cmd += ["-o", tb2_impl_obj, tb2_impl_c]
+          system(*cmd) or return []
+        end
+
+        [tb2_impl_obj]
+      end
+
       def ffi_include_flags
         flags = []
 
-        # Always add vendored Clay include path if Clay stdlib is used
+        # Always add vendored Clay include path if Clay/ClayTUI stdlib is used
         clay_dir = File.expand_path("../../../vendor/clay", __dir__)
         if @extra_c_files.any? { |f| File.basename(f).include?("clay") } && Dir.exist?(clay_dir)
           flags << "-I#{clay_dir}"
         end
 
+        # Add vendored termbox2 include path if ClayTUI stdlib is used
+        tb2_dir = File.expand_path("../../../vendor/termbox2", __dir__)
+        if @extra_c_files.any? { |f| File.basename(f).include?("clay_tui") } && Dir.exist?(tb2_dir)
+          flags << "-I#{tb2_dir}"
+        end
+
         if cross_compiling?
           # When cross-compiling, use cross library include paths
           flags << "-I#{@cross_libs_dir}/../include" if @cross_libs_dir && Dir.exist?("#{@cross_libs_dir}/../include")

data/lib/konpeito/codegen/mruby_helpers.c

@@ -43,18 +43,50 @@ mrb_state *konpeito_get_mrb_state(void) {
 /* ================================================================
  * Block stack for rb_yield / rb_block_given_p / rb_block_proc
  *
- * mruby requires explicit block values, unlike CRuby's implicit
- * "current block" context. We maintain a stack of block values
- * that wrapper functions push/pop around LLVM function calls.
+ * We maintain TWO parallel stacks:
+ *
+ * 1. konpeito_block_stack: mruby Proc VALUE (for rb_block_proc,
+ *    rb_block_given_p, and fallback rb_yield via mrb_funcall).
+ *
+ * 2. konpeito_native_cb_stack: native function pointer + data pairs
+ *    (for rb_yield to call callbacks directly without re-entering
+ *    mrb_vm_exec, which corrupts mruby's callinfo on nested yields).
+ *
+ * rb_block_call pushes both the native callback AND the mruby proc.
+ * The mruby method wrapper pushes only the mruby proc (native_cb=NULL).
+ * rb_yield prefers the native callback when available.
  * ================================================================ */
 
+typedef mrb_value (*cruby_block_callback_t)(mrb_value, mrb_value, int, const mrb_value*);
+
+typedef struct {
+    cruby_block_callback_t func;
+    mrb_value data2;
+} konpeito_native_cb_entry;
+
 #define KONPEITO_MAX_BLOCK_STACK 64
 static mrb_value konpeito_block_stack[KONPEITO_MAX_BLOCK_STACK];
+static konpeito_native_cb_entry konpeito_native_cb_stack[KONPEITO_MAX_BLOCK_STACK];
 static int konpeito_block_stack_depth = 0;
 
+/* Pending native callback: set by rb_block_call before mrb_funcall_with_block,
+ * consumed by konpeito_push_block in the wrapper. */
+static cruby_block_callback_t konpeito_pending_native_func = NULL;
+static mrb_value konpeito_pending_native_data2;
+
 void konpeito_push_block(mrb_value block) {
     if (konpeito_block_stack_depth < KONPEITO_MAX_BLOCK_STACK) {
-        konpeito_block_stack[konpeito_block_stack_depth++] = block;
+        konpeito_block_stack[konpeito_block_stack_depth] = block;
+        /* If rb_block_call set a pending native callback, attach it here.
+         * This ensures the wrapper's push includes the native callback info. */
+        if (konpeito_pending_native_func) {
+            konpeito_native_cb_stack[konpeito_block_stack_depth].func = konpeito_pending_native_func;
+            konpeito_native_cb_stack[konpeito_block_stack_depth].data2 = konpeito_pending_native_data2;
+            konpeito_pending_native_func = NULL;
+        } else {
+            konpeito_native_cb_stack[konpeito_block_stack_depth].func = NULL;
+        }
+        konpeito_block_stack_depth++;
     }
 }
 
@@ -71,6 +103,37 @@ static mrb_value konpeito_get_block(void) {
     return mrb_nil_value();
 }
 
+static konpeito_native_cb_entry *konpeito_get_native_cb(void) {
+    if (konpeito_block_stack_depth > 0) {
+        konpeito_native_cb_entry *entry = &konpeito_native_cb_stack[konpeito_block_stack_depth - 1];
+        if (entry->func) return entry;
+    }
+    return NULL;
+}
+
+/* ================================================================
+ * GC arena management
+ *
+ * mruby objects created in LLVM-generated code live on the C stack,
+ * invisible to mruby's GC. The arena protects them as roots.
+ * Each generated function saves the arena index at entry and restores
+ * it before returning, preventing arena overflow.
+ * ================================================================ */
+
+int konpeito_gc_arena_save(void) {
+    return mrb_gc_arena_save(konpeito_mrb_state);
+}
+
+void konpeito_gc_arena_restore(int idx) {
+    mrb_gc_arena_restore(konpeito_mrb_state, idx);
+}
+
+void konpeito_gc_protect_value(mrb_value val) {
+    if (!mrb_immediate_p(val)) {
+        mrb_gc_protect(konpeito_mrb_state, val);
+    }
+}
+
 /* ================================================================
  * mruby constant values (Qnil, Qtrue, Qfalse, Qundef equivalents)
  * These are stored as mrb_value but exposed as uint64_t (VALUE) to
@@ -141,23 +204,31 @@ double rb_num2dbl(mrb_value v) {
 
 /* CRuby: VALUE rb_str_new(const char *ptr, long len) */
 mrb_value rb_str_new(const char *ptr, long len) {
-    return mrb_str_new(konpeito_mrb_state, ptr, (mrb_int)len);
+    mrb_value s = mrb_str_new(konpeito_mrb_state, ptr, (mrb_int)len);
+    mrb_gc_protect(konpeito_mrb_state, s);
+    return s;
 }
 
 /* CRuby: VALUE rb_utf8_str_new(const char *ptr, long len) */
 /* mruby doesn't distinguish encodings */
 mrb_value rb_utf8_str_new(const char *ptr, long len) {
-    return mrb_str_new(konpeito_mrb_state, ptr, (mrb_int)len);
+    mrb_value s = mrb_str_new(konpeito_mrb_state, ptr, (mrb_int)len);
+    mrb_gc_protect(konpeito_mrb_state, s);
+    return s;
 }
 
 /* CRuby: VALUE rb_str_new_cstr(const char *ptr) */
 mrb_value rb_str_new_cstr(const char *ptr) {
-    return mrb_str_new_cstr(konpeito_mrb_state, ptr);
+    mrb_value s = mrb_str_new_cstr(konpeito_mrb_state, ptr);
+    mrb_gc_protect(konpeito_mrb_state, s);
+    return s;
 }
 
 /* CRuby: VALUE rb_str_dup(VALUE str) */
 mrb_value rb_str_dup(mrb_value str) {
-    return mrb_str_dup(konpeito_mrb_state, str);
+    mrb_value s = mrb_str_dup(konpeito_mrb_state, str);
+    mrb_gc_protect(konpeito_mrb_state, s);
+    return s;
 }
 
 /* CRuby: VALUE rb_str_hash(VALUE str) */
@@ -230,7 +301,9 @@ mrb_value rb_reg_new_str(mrb_value str, int64_t options) {
 
 /* CRuby: VALUE rb_ary_new_capa(long capa) */
 mrb_value rb_ary_new_capa(int64_t capa) {
-    return mrb_ary_new_capa(konpeito_mrb_state, (mrb_int)capa);
+    mrb_value a = mrb_ary_new_capa(konpeito_mrb_state, (mrb_int)capa);
+    mrb_gc_protect(konpeito_mrb_state, a);
+    return a;
 }
 
 /* CRuby: VALUE rb_ary_push(VALUE ary, VALUE item) */
@@ -256,12 +329,16 @@ void rb_ary_store(mrb_value ary, int64_t idx, mrb_value val) {
 
 /* CRuby: VALUE rb_ary_new(void) */
 mrb_value rb_ary_new(void) {
-    return mrb_ary_new(konpeito_mrb_state);
+    mrb_value a = mrb_ary_new(konpeito_mrb_state);
+    mrb_gc_protect(konpeito_mrb_state, a);
+    return a;
 }
 
 /* CRuby: VALUE rb_ary_new_from_values(long n, const VALUE *elts) */
 mrb_value rb_ary_new_from_values(int64_t n, const mrb_value *elts) {
-    return mrb_ary_new_from_values(konpeito_mrb_state, (mrb_int)n, elts);
+    mrb_value a = mrb_ary_new_from_values(konpeito_mrb_state, (mrb_int)n, elts);
+    mrb_gc_protect(konpeito_mrb_state, a);
+    return a;
 }
 
 /* CRuby: VALUE rb_ary_subseq(VALUE ary, long beg, long len) */
@@ -305,7 +382,9 @@ mrb_value rb_ary_delete_at(mrb_value ary, int64_t pos) {
 
 /* CRuby: VALUE rb_hash_new(void) */
 mrb_value rb_hash_new(void) {
-    return mrb_hash_new(konpeito_mrb_state);
+    mrb_value h = mrb_hash_new(konpeito_mrb_state);
+    mrb_gc_protect(konpeito_mrb_state, h);
+    return h;
 }
 
 /* CRuby: VALUE rb_hash_aset(VALUE hash, VALUE key, VALUE val) */
@@ -412,17 +491,33 @@ mrb_value rb_obj_class(mrb_value obj) {
 /* CRuby: VALUE rb_yield(VALUE val) */
 mrb_value rb_yield(mrb_value val) {
     mrb_state *mrb = konpeito_mrb_state;
+
+    /* Prefer direct native callback to avoid mrb_vm_exec re-entry issues */
+    konpeito_native_cb_entry *native = konpeito_get_native_cb();
+    if (native) {
+        mrb_value argv[1];
+        argv[0] = val;
+        return native->func(val, native->data2, 1, argv);
+    }
+
     mrb_value block = konpeito_get_block();
     if (mrb_nil_p(block)) {
         mrb_raise(mrb, E_RUNTIME_ERROR, "no block given (yield)");
         return mrb_nil_value();
     }
-    return mrb_funcall(konpeito_mrb_state, block, "call", 1, val);
+    return mrb_funcall(mrb, block, "call", 1, val);
 }
 
 /* CRuby: VALUE rb_yield_values2(int argc, const VALUE *argv) */
 mrb_value rb_yield_values2(int argc, const mrb_value *argv) {
     mrb_state *mrb = konpeito_mrb_state;
+
+    konpeito_native_cb_entry *native = konpeito_get_native_cb();
+    if (native) {
+        mrb_value yielded = (argc > 0) ? argv[0] : mrb_nil_value();
+        return native->func(yielded, native->data2, argc, argv);
+    }
+
     mrb_value block = konpeito_get_block();
     if (mrb_nil_p(block)) {
         mrb_raise(mrb, E_RUNTIME_ERROR, "no block given (yield)");
@@ -456,8 +551,6 @@ mrb_value rb_block_proc(void) {
  * the original callback pointer and data in the proc's environment.
  * ================================================================ */
 
-typedef mrb_value (*cruby_block_callback_t)(mrb_value, mrb_value, int, const mrb_value*);
-
 /* Adapter: called as mruby cfunc, delegates to CRuby-style callback */
 static mrb_value konpeito_cfunc_adapter(mrb_state *mrb, mrb_value self) {
     mrb_value cb_ptr_val = mrb_proc_cfunc_env_get(mrb, 0);
@@ -481,15 +574,29 @@ mrb_value rb_block_call(mrb_value obj, mrb_sym mid, int argc, const mrb_value *a
         return mrb_funcall_argv(konpeito_mrb_state, obj, mid, argc, argv);
     }
 
-    /* Create a proc that wraps the CRuby callback via environment */
+    /* Create a proc that wraps the CRuby callback via environment.
+     * This is needed for rb_block_proc() and as fallback for rb_yield()
+     * when the block was not pushed via rb_block_call (e.g., mruby Proc). */
     mrb_value env[2];
     env[0] = mrb_cptr_value(konpeito_mrb_state, proc);
-    env[1] = data2;
+    /* Store nil instead of data2 in the proc env.  data2 may be a raw C
+     * stack pointer (pointer-to-alloca capture mode) which is NOT a valid
+     * mrb_value.  If GC marks the proc's env it would try to dereference
+     * that raw pointer as an RBasic* → crash in gc_mark_children.
+     * The native callback path reads data2 from konpeito_pending_native_data2
+     * (set below), so env[1] is never read in practice. */
+    env[1] = mrb_nil_value();
     struct RProc *block_proc = mrb_proc_new_cfunc_with_env(
         konpeito_mrb_state, konpeito_cfunc_adapter, 2, env);
     mrb_value block_val = mrb_obj_value(block_proc);
 
-    return mrb_funcall_with_block(konpeito_mrb_state, obj, mid, argc, argv, block_val);
+    /* Set pending native callback so the wrapper's konpeito_push_block call
+     * will attach the native function pointer. rb_yield will then call the
+     * native callback directly, bypassing mrb_vm_exec re-entry. */
+    konpeito_pending_native_func = (cruby_block_callback_t)proc;
+    konpeito_pending_native_data2 = data2;
+    mrb_value result = mrb_funcall_with_block(konpeito_mrb_state, obj, mid, argc, argv, block_val);
+    return result;
 }
 
 /* CRuby: VALUE rb_block_call_kw(...) */

data/lib/konpeito/compiler.rb

@@ -116,8 +116,14 @@ module Konpeito
 
     def parse
       log "Resolving dependencies for #{source_file}..."
+      # Include KUI stdlib in search paths so `require "kui_gui"` / `require "kui_tui"`
+      # resolves automatically without needing `-I` for the KUI directory.
+      kui_stdlib_dir = File.expand_path("stdlib/kui", __dir__)
+      all_require_paths = @require_paths.dup
+      all_require_paths << kui_stdlib_dir unless all_require_paths.include?(kui_stdlib_dir)
+
       resolver = DependencyResolver.new(
-        base_paths: @require_paths,
+        base_paths: all_require_paths,
         verbose: verbose,
         cache_manager: @cache_manager
       )
@@ -653,7 +659,13 @@ module Konpeito
     # Map of stdlib modules: module name pattern => stdlib directory name
     STDLIB_MODULE_MAP = {
       "Raylib" => "raylib",
-      "Clay" => "clay"
+      "Clay" => "clay",
+      "ClayTUI" => "clay_tui",
+      "KonpeitoShell" => "shell",
+      "KonpeitoJSON" => "json",
+      "KonpeitoHTTP" => "http",
+      "KonpeitoCrypto" => "crypto",
+      "KonpeitoCompression" => "compression"
     }.freeze
 
     # Scan AST for known stdlib module references and auto-add their RBS paths