konpeito 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50ad4b5d35d1b8abd26ee9d941a901b99e281eb9cc7d2deed777f3ebf12b2308
-  data.tar.gz: fc91a16a60718a8a910776ab56f01a09d49ec2ee78e71082965392f1dee332e1
+  metadata.gz: ed1949148547cf4716d3405d71d9d79413d84201a699fefe98512ddb4202808e
+  data.tar.gz: cbcc7ecbea2a4c6edeab12fd5f20d5221e9dca2e379906c728d37e16b0168bea
 SHA512:
-  metadata.gz: c2efa11a609aba145beef6d2b722028f657a6a4d5469864241cbdde1b43dc494b9cf814379788a8ede8d4715d0aceab76df3d64a1c6b14913a3e2f84d0787f1f
-  data.tar.gz: 77860386e45ac9a5b78ead9b0f02dfc3d759668fe5ffc3d97c72c4932ca297778d27192c6a698ad264f7641a988b07905dbf6a15c32f10320678999e89a604dc
+  metadata.gz: 8ad8a635a74b09378cacf342e14a9fdba84434d29d3657071a72fb42d800dd8cfe84bc5a9f66ca81fd48852b880f6896c8a4aff5d83c12be03a8cbf8208b5b5d
+  data.tar.gz: f1635c6083bd97079fff23d07e3fe5232eadaffc21aeccdc6718689569da8afe50eba3252a188eb2aff42318317ed0ec18e5d2e1b190ac63679c0b354a27c11d

data/CHANGELOG.md

@@ -7,13 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-03-14
+
+### Added
+- **KUI widget expansion**: text_input, checkbox, radio, toggle, spinner, status_bar,
+  selectable_list, list_item, table (header/row/cell), modal, tab_bar, tab_button,
+  tab_content — all with keyboard focus support and click-to-focus
+- **KUI focus system**: Tab/arrow key navigation across all interactive widgets with
+  focus highlight and Enter key activation
+- **KUI extended key input**: `kui_char_pressed()`, `kui_mod_pressed()`,
+  Delete/Home/End/PgUp/PgDn/F1-F12 key constants
+- **KUI text buffer API**: `kui_textbuf_copy`, `kui_textbuf_render` for dynamic content
+- **KUI GUI backend**: Full GUI implementations for all new widgets (Clay+Raylib)
+- **Game framework expansion**: tween/easing (linear, quad, cubic, bounce, elastic),
+  screen shake, scene transitions (fade), FSM, timer system, parallax scrolling,
+  simple physics (AABB, gravity, friction), particle system, object pool, grid/tile
+  utilities, debug overlay (FPS, collision rects), gamepad abstraction, save/load
+- **Game showcase demo**: "Coin Dash" score-attack platformer demonstrating
+  game framework API (physics, particles, tween, FSM, parallax, Camera2D)
+- **Physics demo**: Platformer demo showcasing NativeArray-based physics
+- **KUI form demo**: Text input, checkbox, radio, toggle showcase
+- **KUI tabs demo**: Tab bar, table, modal dialog, selectable list, status bar showcase
+- **KUI showcase demo**: Rich GUI app demonstrating all v0.8.0 widgets in a 4-tab layout
+
+### Fixed
+- **NativeArray SEGV as function argument**: `convert_value()` lacked
+  `[:native_array, :value]` case, causing raw LLVM pointers where Ruby VALUEs
+  were expected
+- **NativeArray SEGV in compound expressions**: `get_effective_unboxed_type()`
+  only checked `@variable_types` for LoadLocal nodes, causing incorrect float path
+  for integer arithmetic in if conditions
+- **KUI text input isolation**: Only focused text_input processes keyboard input
+- **KUI toggle flip-back**: Filter out termbox2 mouse release events (key 65509)
+- **KUI modal layout**: Reduced TUI padding from 16 to 1 char cells
+- **mruby keyword argument handling**: Optional keyword hash with `MRB_ARGS_ARG`
+- **KUI scroll containers not scrolling**: `Clay_GetScrollOffset()` was not called
+  in `konpeito_clay_scroll` / `konpeito_clay_tui_scroll`, so `childOffset` remained
+  zero and scroll position was never visually applied
+
+## [0.7.1] - 2026-03-14
+
+### Fixed
+- **rescue handler callback crash**: `generate_rescue_handler_with_global_flag_callback` was restoring `@mruby_gc_arena_alloca` without saving it first, causing `NameError` in begin/rescue/else code generation.
+
 ## [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.
+- **Game framework stdlib**: Reusable 2D 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.
@@ -336,6 +379,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `%a{extern}` - external C struct wrappers
 - `%a{simd}` - SIMD vectorization
 
+[0.8.0]: https://github.com/i2y/konpeito/compare/v0.7.1...v0.8.0
+[0.7.1]: https://github.com/i2y/konpeito/compare/v0.7.0...v0.7.1
+[0.7.0]: https://github.com/i2y/konpeito/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/i2y/konpeito/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/i2y/konpeito/compare/v0.4.2...v0.5.0
+[0.4.2]: https://github.com/i2y/konpeito/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/i2y/konpeito/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/i2y/konpeito/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/i2y/konpeito/compare/v0.3.0...v0.3.1

data/lib/konpeito/codegen/llvm_generator.rb

@@ -1597,6 +1597,24 @@ module Konpeito
             boxed_value = func.params[i + 1]  # +1 to skip self
           type_tag = @variable_types[param.name]
 
+          if type_tag == :native_array
+            # NativeArray parameter: the VALUE is actually a pointer address (via ptr2int).
+            # Reconstruct the pointer and store directly in @variables (not alloca).
+            # generate_load_local reads NativeArray values from @variables, not allocas.
+            array_ptr = @builder.int2ptr(boxed_value, ptr_type, "#{param.name}_ptr")
+            @variables[param.name] = array_ptr
+            # Propagate element type and length from the parameter's HM type if available
+            if param.type.is_a?(TypeChecker::Types::NativeArrayType)
+              elem_type = param.type.element_type
+              @variables["#{param.name}_len"] = LLVM::Int64.from_i(param.type.size || 0)
+              if elem_type && elem_type != :Int64 && elem_type != :Float64
+                @native_array_class_types ||= {}
+                @native_array_class_types[param.name] = elem_type
+              end
+            end
+            next
+          end
+
           # Unbox parameter if it's a numeric type
           value_to_store = case type_tag
           when :i64
@@ -2004,6 +2022,10 @@ module Konpeito
           [LLVM::Int64, :i64]
         elsif float_type?(ruby_type)
           [LLVM::Double, :double]
+        elsif ruby_type.is_a?(TypeChecker::Types::NativeArrayType)
+          # NativeArray parameters: alloca holds VALUE (i64) but type is :native_array
+          # The actual pointer is reconstructed from the VALUE in parameter setup
+          [value_type, :native_array]
         else
           [value_type, :value]
         end
@@ -3029,6 +3051,9 @@ module Konpeito
         when [:native_class, :value]
           # NativeClass struct pointer to VALUE (i64)
           @builder.ptr2int(value, LLVM::Int64)
+        when [:native_array, :value]
+          # NativeArray pointer to VALUE (i64) — encode pointer address as integer
+          @builder.ptr2int(value, LLVM::Int64)
         when [:i64, :double]
           @builder.si2fp(value, LLVM::Double)
         when [:double, :i64]
@@ -7372,6 +7397,15 @@ module Konpeito
           return type_tag if type_tag == :i64 || type_tag == :double
         end
 
+        # Check @variable_types for any instruction with result_var.
+        # This is critical for sub-expressions (e.g. NativeArrayGet, Call) whose
+        # HIR type may be an unresolved TypeVar but whose actual generated type
+        # is correctly tracked in @variable_types.
+        if hir_value.is_a?(HIR::Instruction) && hir_value.result_var
+          type_tag = @variable_types[hir_value.result_var]
+          return type_tag if type_tag == :i64 || type_tag == :double
+        end
+
         # Check HIR type
         hir_type = get_type(hir_value)
         if integer_type?(hir_type)
@@ -8469,6 +8503,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

data/lib/konpeito/codegen/mruby_backend.rb

@@ -78,13 +78,17 @@ module Konpeito
           # Generate license file alongside the executable
           generate_license_file
         ensure
-          # Clean up intermediate files
+          # Clean up intermediate files (keep .ll for debugging if ENV['KONPEITO_KEEP_IR'] is set)
+          keep_ir = ENV['KONPEITO_KEEP_IR']
           all_temps = [ir_file, obj_file, init_c_file, init_obj_file, helpers_obj_file] + extra_obj_files
           all_temps.each do |f|
+            next if keep_ir && f&.end_with?('.ll')
             FileUtils.rm_f(f) if f && File.exist?(f)
           end
           # Also clean optimized IR if it was generated
-          FileUtils.rm_f("#{ir_file}.opt.ll") if File.exist?("#{ir_file}.opt.ll")
+          unless keep_ir
+            FileUtils.rm_f("#{ir_file}.opt.ll") if File.exist?("#{ir_file}.opt.ll")
+          end
         end
       end
 
@@ -302,7 +306,7 @@ module Konpeito
 
             arity = llvm_generator.variadic_functions[mangled_name] ? -1 : func.params.size - 1
             wrapper = "mrb_wrap_#{mangled_name}"
-            mrb_args = arity_to_mrb_args(arity)
+            mrb_args = effective_mrb_args(mangled_name, arity)
             lines << "    mrb_define_method(mrb, #{module_var}, \"#{method_name}\", #{wrapper}, #{mrb_args});"
           end
 
@@ -316,7 +320,7 @@ module Konpeito
 
             arity = llvm_generator.variadic_functions[mangled_name] ? -1 : func.params.size - 1
             wrapper = "mrb_wrap_#{mangled_name}"
-            mrb_args = arity_to_mrb_args(arity)
+            mrb_args = effective_mrb_args(mangled_name, arity)
             lines << "    mrb_define_class_method(mrb, #{module_var}, \"#{method_name}\", #{wrapper}, #{mrb_args});"
           end
 
@@ -372,7 +376,7 @@ module Konpeito
 
             arity = llvm_generator.variadic_functions[mangled_name] ? -1 : func.params.size - 1
             wrapper = "mrb_wrap_#{mangled_name}"
-            mrb_args = arity_to_mrb_args(arity)
+            mrb_args = effective_mrb_args(mangled_name, arity)
             lines << "    mrb_define_method(mrb, #{class_var}, \"#{method_name}\", #{wrapper}, #{mrb_args});"
           end
 
@@ -386,7 +390,7 @@ module Konpeito
 
             arity = llvm_generator.variadic_functions[mangled_name] ? -1 : func.params.size - 1
             wrapper = "mrb_wrap_#{mangled_name}"
-            mrb_args = arity_to_mrb_args(arity)
+            mrb_args = effective_mrb_args(mangled_name, arity)
             lines << "    mrb_define_class_method(mrb, #{class_var}, \"#{method_name}\", #{wrapper}, #{mrb_args});"
           end
 
@@ -408,7 +412,7 @@ module Konpeito
 
           arity = llvm_generator.variadic_functions[mangled_name] ? -1 : func.params.size - 1
           wrapper = "mrb_wrap_#{mangled_name}"
-          mrb_args = arity_to_mrb_args(arity)
+          mrb_args = effective_mrb_args(mangled_name, arity)
           lines << "    mrb_define_method(mrb, mrb->object_class, \"#{func_def.name}\", #{wrapper}, #{mrb_args});"
         end
 
@@ -456,13 +460,14 @@ 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`).
+          # Check if this function has keyword args.
+          # The kwargs hash arg should be optional — caller may pass only
+          # positional args when no keywords are specified.
           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
+          has_mixed_kwargs = kw_info && kw_info[:regular_count] > 0 && arity > 1
 
           lines << "static mrb_value #{wrapper_name}(mrb_state *mrb, mrb_value self) {"
           if kwargs_only
@@ -470,6 +475,15 @@ module Konpeito
             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 has_mixed_kwargs
+            # Positional args + optional kwargs hash — last arg defaults to empty hash
+            kw_hash_idx = arity - 1
+            req_count = kw_info[:regular_count]
+            lines << "    mrb_value #{(0...arity).map { |i| "a#{i} = mrb_nil_value()" }.join(', ')}, _block = mrb_nil_value();"
+            format_str = "o" * req_count + "|o&"
+            args_list = (0...arity).map { |i| "&a#{i}" }.join(", ") + ", &_block"
+            lines << "    mrb_get_args(mrb, \"#{format_str}\", #{args_list});"
+            lines << "    if (mrb_nil_p(a#{kw_hash_idx})) a#{kw_hash_idx} = mrb_hash_new(mrb);"
           elsif arity > 0
             lines << "    mrb_value #{(0...arity).map { |i| "a#{i}" }.join(', ')}, _block;"
             format_str = "o" * arity + "&"
@@ -804,6 +818,24 @@ module Konpeito
         end
       end
 
+      # Compute mrb_args for a function, accounting for optional keyword hash.
+      # Functions with keyword params can be called with or without the keyword
+      # hash argument, so the kwargs arg must be registered as optional.
+      def effective_mrb_args(mangled_name, arity)
+        return arity_to_mrb_args(arity) if arity <= 0
+
+        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]
+        if kw_info
+          # Keyword hash is optional — use MRB_ARGS_ARG(required, optional)
+          req = kw_info[:regular_count]
+          "MRB_ARGS_ARG(#{req}, #{arity - req})"
+        else
+          arity_to_mrb_args(arity)
+        end
+      end
+
       def resolve_superclass_mrb_expr(superclass, non_native_classes)
         return "mrb->object_class" unless superclass
 

data/lib/konpeito/stdlib/clay/clay.rb

@@ -63,4 +63,20 @@ module Clay
   def self.sizing_percent() end
   def self.left_to_right() end
   def self.top_to_bottom() end
+
+  # Text Buffer System
+  def self.textbuf_clear(id) end
+  def self.textbuf_copy(dst, src) end
+  def self.textbuf_putchar(id, ch) end
+  def self.textbuf_backspace(id) end
+  def self.textbuf_delete(id) end
+  def self.textbuf_cursor_left(id) end
+  def self.textbuf_cursor_right(id) end
+  def self.textbuf_cursor_home(id) end
+  def self.textbuf_cursor_end(id) end
+  def self.textbuf_len(id) end
+  def self.textbuf_cursor(id) end
+  def self.textbuf_render(id, fid, fsz, r, g, b) end
+  def self.textbuf_render_range(id, start_pos, end_pos, fid, fsz, r, g, b) end
+  def self.text_char(ch, fid, fsz, r, g, b) end
 end

data/lib/konpeito/stdlib/clay/clay.rbs

@@ -166,4 +166,48 @@ module Clay
 
   %a{cfunc: "konpeito_clay_top_to_bottom"}
   def self.top_to_bottom: () -> Integer
+
+  # ── Text Buffer System ──
+
+  %a{cfunc: "konpeito_clay_textbuf_clear"}
+  def self.textbuf_clear: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_copy"}
+  def self.textbuf_copy: (Integer dst, Integer src) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_putchar"}
+  def self.textbuf_putchar: (Integer id, Integer ch) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_backspace"}
+  def self.textbuf_backspace: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_delete"}
+  def self.textbuf_delete: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_cursor_left"}
+  def self.textbuf_cursor_left: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_cursor_right"}
+  def self.textbuf_cursor_right: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_cursor_home"}
+  def self.textbuf_cursor_home: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_cursor_end"}
+  def self.textbuf_cursor_end: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_len"}
+  def self.textbuf_len: (Integer id) -> Integer
+
+  %a{cfunc: "konpeito_clay_textbuf_cursor"}
+  def self.textbuf_cursor: (Integer id) -> Integer
+
+  %a{cfunc: "konpeito_clay_textbuf_render"}
+  def self.textbuf_render: (Integer id, Integer fid, Integer fsz, Float r, Float g, Float b) -> void
+
+  %a{cfunc: "konpeito_clay_textbuf_render_range"}
+  def self.textbuf_render_range: (Integer id, Integer start, Integer end_pos, Integer fid, Integer fsz, Float r, Float g, Float b) -> void
+
+  %a{cfunc: "konpeito_clay_text_char"}
+  def self.text_char: (Integer ch, Integer fid, Integer fsz, Float r, Float g, Float b) -> void
 end

data/lib/konpeito/stdlib/clay/clay_native.c

@@ -275,6 +275,7 @@ void konpeito_clay_border(double r, double g, double b, double a,
 void konpeito_clay_scroll(int horizontal, int vertical) {
     g_decl.clip.horizontal = horizontal != 0;
     g_decl.clip.vertical = vertical != 0;
+    g_decl.clip.childOffset = Clay_GetScrollOffset();
 }
 
 /* Floating element */
@@ -491,3 +492,148 @@ int konpeito_clay_sizing_fixed(void)  { return 2; }
 int konpeito_clay_sizing_percent(void){ return 3; }
 int konpeito_clay_left_to_right(void) { return 0; }
 int konpeito_clay_top_to_bottom(void) { return 1; }
+
+/* ═══════════════════════════════════════════
+ *  Text Buffer System
+ * ═══════════════════════════════════════════
+ * 8 independent text buffers for text_input widgets.
+ * Each buffer holds up to 255 characters (256 bytes including null).
+ * Buffer operations are GC-free — no mruby String allocation.
+ */
+
+#define TEXTBUF_COUNT 8
+#define TEXTBUF_SIZE 256
+
+static char g_textbufs[TEXTBUF_COUNT][TEXTBUF_SIZE];
+static int g_textbuf_lens[TEXTBUF_COUNT];
+static int g_textbuf_cursors[TEXTBUF_COUNT];
+
+void konpeito_clay_textbuf_clear(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    g_textbufs[id][0] = '\0';
+    g_textbuf_lens[id] = 0;
+    g_textbuf_cursors[id] = 0;
+}
+
+void konpeito_clay_textbuf_copy(int dst, int src) {
+    if (dst < 0 || dst >= TEXTBUF_COUNT) return;
+    if (src < 0 || src >= TEXTBUF_COUNT) return;
+    int len = g_textbuf_lens[src];
+    for (int i = 0; i <= len; i++) {
+        g_textbufs[dst][i] = g_textbufs[src][i];
+    }
+    g_textbuf_lens[dst] = len;
+    g_textbuf_cursors[dst] = len;
+}
+
+void konpeito_clay_textbuf_putchar(int id, int ch) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    int len = g_textbuf_lens[id];
+    int cur = g_textbuf_cursors[id];
+    if (len >= TEXTBUF_SIZE - 1) return;
+    for (int i = len; i > cur; i--) {
+        g_textbufs[id][i] = g_textbufs[id][i - 1];
+    }
+    g_textbufs[id][cur] = (char)ch;
+    g_textbuf_lens[id] = len + 1;
+    g_textbuf_cursors[id] = cur + 1;
+    g_textbufs[id][len + 1] = '\0';
+}
+
+void konpeito_clay_textbuf_backspace(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    int cur = g_textbuf_cursors[id];
+    int len = g_textbuf_lens[id];
+    if (cur <= 0) return;
+    for (int i = cur - 1; i < len - 1; i++) {
+        g_textbufs[id][i] = g_textbufs[id][i + 1];
+    }
+    g_textbuf_lens[id] = len - 1;
+    g_textbuf_cursors[id] = cur - 1;
+    g_textbufs[id][len - 1] = '\0';
+}
+
+void konpeito_clay_textbuf_delete(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    int cur = g_textbuf_cursors[id];
+    int len = g_textbuf_lens[id];
+    if (cur >= len) return;
+    for (int i = cur; i < len - 1; i++) {
+        g_textbufs[id][i] = g_textbufs[id][i + 1];
+    }
+    g_textbuf_lens[id] = len - 1;
+    g_textbufs[id][len - 1] = '\0';
+}
+
+void konpeito_clay_textbuf_cursor_left(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    if (g_textbuf_cursors[id] > 0) g_textbuf_cursors[id]--;
+}
+
+void konpeito_clay_textbuf_cursor_right(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    if (g_textbuf_cursors[id] < g_textbuf_lens[id]) g_textbuf_cursors[id]++;
+}
+
+void konpeito_clay_textbuf_cursor_home(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    g_textbuf_cursors[id] = 0;
+}
+
+void konpeito_clay_textbuf_cursor_end(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    g_textbuf_cursors[id] = g_textbuf_lens[id];
+}
+
+int konpeito_clay_textbuf_len(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return 0;
+    return g_textbuf_lens[id];
+}
+
+int konpeito_clay_textbuf_cursor(int id) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return 0;
+    return g_textbuf_cursors[id];
+}
+
+void konpeito_clay_textbuf_render(int id, int fid, int fsz, double r, double g, double b) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    if (g_textbuf_lens[id] == 0) return;
+    flush_config();
+    Clay_TextElementConfig cfg = {
+        .textColor = {(float)r, (float)g, (float)b, 255.0f},
+        .fontId = (uint16_t)fid, .fontSize = (uint16_t)fsz, .wrapMode = 0
+    };
+    Clay_String cs = make_string(g_textbufs[id]);
+    Clay__OpenTextElement(cs, Clay__StoreTextElementConfig(cfg));
+}
+
+void konpeito_clay_textbuf_render_range(int id, int start, int end, int fid, int fsz,
+                                         double r, double g, double b) {
+    if (id < 0 || id >= TEXTBUF_COUNT) return;
+    int len = g_textbuf_lens[id];
+    if (start >= len || start >= end) return;
+    if (end > len) end = len;
+    int range_len = end - start;
+    flush_config();
+    const char *pooled = pool_string(g_textbufs[id] + start, range_len);
+    Clay_String cs = {.isStaticallyAllocated = false, .length = range_len, .chars = pooled};
+    Clay_TextElementConfig cfg = {
+        .textColor = {(float)r, (float)g, (float)b, 255.0f},
+        .fontId = (uint16_t)fid, .fontSize = (uint16_t)fsz, .wrapMode = 0
+    };
+    Clay__OpenTextElement(cs, Clay__StoreTextElementConfig(cfg));
+}
+
+void konpeito_clay_text_char(int ch, int fid, int fsz, double r, double g, double b) {
+    if (ch < 32 || ch > 126) return;
+    char buf[2];
+    buf[0] = (char)ch;
+    buf[1] = '\0';
+    flush_config();
+    Clay_TextElementConfig cfg = {
+        .textColor = {(float)r, (float)g, (float)b, 255.0f},
+        .fontId = (uint16_t)fid, .fontSize = (uint16_t)fsz, .wrapMode = 0
+    };
+    Clay_String cs = make_string(buf);
+    Clay__OpenTextElement(cs, Clay__StoreTextElementConfig(cfg));
+}

data/lib/konpeito/stdlib/clay_tui/clay_tui.rb

@@ -109,4 +109,45 @@ module ClayTUI
 
   # Color Helper
   def self.rgb(r, g, b) end
+
+  # Extended Key Constants
+  def self.key_delete() end
+  def self.key_home() end
+  def self.key_end() end
+  def self.key_pgup() end
+  def self.key_pgdn() end
+  def self.key_f1() end
+  def self.key_f2() end
+  def self.key_f3() end
+  def self.key_f4() end
+  def self.key_f5() end
+  def self.key_f6() end
+  def self.key_f7() end
+  def self.key_f8() end
+  def self.key_f9() end
+  def self.key_f10() end
+  def self.key_f11() end
+  def self.key_f12() end
+
+  # Modifier Keys
+  def self.event_mod() end
+  def self.mod_alt() end
+  def self.mod_ctrl() end
+  def self.mod_shift() end
+
+  # Text Buffer System
+  def self.textbuf_clear(id) end
+  def self.textbuf_copy(dst, src) end
+  def self.textbuf_putchar(id, ch) end
+  def self.textbuf_backspace(id) end
+  def self.textbuf_delete(id) end
+  def self.textbuf_cursor_left(id) end
+  def self.textbuf_cursor_right(id) end
+  def self.textbuf_cursor_home(id) end
+  def self.textbuf_cursor_end(id) end
+  def self.textbuf_len(id) end
+  def self.textbuf_cursor(id) end
+  def self.textbuf_render(id, r, g, b) end
+  def self.textbuf_render_range(id, start_pos, end_pos, r, g, b) end
+  def self.text_char(ch, r, g, b) end
 end

data/lib/konpeito/stdlib/clay_tui/clay_tui.rbs

@@ -255,4 +255,115 @@ module ClayTUI
   # Build a truecolor value from RGB components
   %a{cfunc: "konpeito_clay_tui_rgb"}
   def self.rgb: (Integer r, Integer g, Integer b) -> Integer
+
+  # ── Extended Key Constants ──
+
+  %a{cfunc: "konpeito_clay_tui_key_delete"}
+  def self.key_delete: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_home"}
+  def self.key_home: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_end"}
+  def self.key_end: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_pgup"}
+  def self.key_pgup: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_pgdn"}
+  def self.key_pgdn: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f1"}
+  def self.key_f1: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f2"}
+  def self.key_f2: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f3"}
+  def self.key_f3: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f4"}
+  def self.key_f4: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f5"}
+  def self.key_f5: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f6"}
+  def self.key_f6: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f7"}
+  def self.key_f7: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f8"}
+  def self.key_f8: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f9"}
+  def self.key_f9: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f10"}
+  def self.key_f10: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f11"}
+  def self.key_f11: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_key_f12"}
+  def self.key_f12: () -> Integer
+
+  # ── Modifier Keys ──
+
+  %a{cfunc: "konpeito_clay_tui_event_mod"}
+  def self.event_mod: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_mod_alt"}
+  def self.mod_alt: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_mod_ctrl"}
+  def self.mod_ctrl: () -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_mod_shift"}
+  def self.mod_shift: () -> Integer
+
+  # ── Text Buffer System ──
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_clear"}
+  def self.textbuf_clear: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_copy"}
+  def self.textbuf_copy: (Integer dst, Integer src) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_putchar"}
+  def self.textbuf_putchar: (Integer id, Integer ch) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_backspace"}
+  def self.textbuf_backspace: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_delete"}
+  def self.textbuf_delete: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_cursor_left"}
+  def self.textbuf_cursor_left: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_cursor_right"}
+  def self.textbuf_cursor_right: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_cursor_home"}
+  def self.textbuf_cursor_home: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_cursor_end"}
+  def self.textbuf_cursor_end: (Integer id) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_len"}
+  def self.textbuf_len: (Integer id) -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_cursor"}
+  def self.textbuf_cursor: (Integer id) -> Integer
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_render"}
+  def self.textbuf_render: (Integer id, Integer r, Integer g, Integer b) -> void
+
+  %a{cfunc: "konpeito_clay_tui_textbuf_render_range"}
+  def self.textbuf_render_range: (Integer id, Integer start, Integer end_pos, Integer r, Integer g, Integer b) -> void
+
+  %a{cfunc: "konpeito_clay_tui_text_char"}
+  def self.text_char: (Integer ch, Integer r, Integer g, Integer b) -> void
 end