citrine-native 0.1.0 → 0.2.0

data/lib/citrine/native/painter.rb

@@ -2,20 +2,20 @@
 
 module Citrine
   module Native
-    # 自绘面板的绘制薄层（冻结接口见 docs/design/native-area.md 2.2）。
+    # 自绘面板的绘制协议（冻结接口见 docs/design/native-area.md 2.2，文档在后端包）。
     #
-    # 三个部分各司其职，参数归一只有一份，两个实现不会漂移：
+    # 三个部分各司其职，参数归一只有一份，各后端实现不会漂移：
     #   Primitives —— 图元签名 + 颜色/字重/对齐/圆角归一 + "未支持用法"的提醒收集（纯 Ruby）
-    #   Painter    —— 真 libui 绘制（Primitives 的平台实现；坐标是面板本地像素，左上角原点）
     #   Recording  —— 只记录图元调用序列的桩实现（Memory 后端与"画了什么"的断言用）
+    #   各后端     —— 真绘制实现（libui 包：ctx 版 Painter + TextCache；
+    #                 GTK 包：GtkDrawingArea + Cairo，规划中）
     #
-    # 生命周期：**一个面板一次 on_draw 一个 Painter 实例，不跨帧复用**。
-    # 跨帧复用的只有文本布局（TextCache）：它由适配层按面板持有、随面板销毁释放——
-    # libui 的 text layout / attributed string / font descriptor 不归 Ruby GC 管，
-    # 漏 free 就是每帧漏一段 C 内存（每帧每格新建 layout 还会明显掉帧）。
-    class Painter
+    # 生命周期：**一个面板一次 on_draw 一个 painter 实例，不跨帧复用**。
+    # 跨帧复用的只有文本布局（libui 包的 TextCache 按面板持有、随面板销毁释放——
+    # text layout / attributed string 不归 Ruby GC 管，漏 free 就是每帧漏 C 内存）。
+    module Painter
       # ── "未支持用法/无效值"的提醒收集 ────────────────────────
-      # Painter 每帧新建（见上），自己 warn 会每帧刷屏；这里只按 key 收集，
+      # painter 每帧新建（见上），自己 warn 会每帧刷屏；这里只按 key 收集，
       # 交给渲染器按 dev_mode 去重后输出（Renderer#report_painter_warnings）。
       module Warnings
         # key => message（同一 key 只留第一条）
@@ -42,7 +42,7 @@ module Citrine
         DEFAULT_LINE_COLOR = "#000000"
         DEFAULT_TEXT_SIZE = 13
 
-        # libui 的约定：宽度为负 = 不换行（uiDrawNewTextLayout 里 Width < 0 → CGFLOAT_MAX）
+        # 各后端的约定：宽度为负 = 不换行（libui：Width < 0 → CGFLOAT_MAX）
         NO_WRAP = -1.0
 
         # 对齐只在给定宽度内生效（布局的 Width 决定外接矩形），没有 width 时按左对齐
@@ -102,7 +102,7 @@ module Citrine
           [entry.measured_width, entry.measured_height]
         end
 
-        # 块内裁剪（libui 的 save/clip/restore）：块里照常画，矩形外的部分被裁掉
+        # 块内裁剪（后端的 save/clip/restore）：块里照常画，矩形外的部分被裁掉
         def clip(x, y, w, h, &block)
           raise ArgumentError, "clip 需要块：p.clip(x, y, w, h) { … }" unless block
 
@@ -229,7 +229,7 @@ module Citrine
           if key != :left && width.nil?
             note_warning(:align_without_width,
                          "[citrine-native] text 的 align: #{key.inspect} 需要同时给 width:" \
-                         "（libui 的对齐是在给定宽度内对齐），本次按左对齐绘制")
+                         "（对齐是在给定宽度内对齐），本次按左对齐绘制")
             return :left
           end
           key
@@ -249,7 +249,7 @@ module Citrine
         end
 
         # ── 平台实现（emit_*）与文本布局入口 ──────────────────
-        # 两个实现：Painter（libui 调用）/ Recording（记录调用序列）。
+        # 各后端实现：libui 包（ctx 调用）/ GTK 包（Cairo，规划中）/ Recording（记录）。
 
         def emit_rect(_x, _y, _w, _h, _fill, _stroke, _line_width, _radius)
           raise NotImplementedError, "#{self.class}#emit_rect 未实现"
@@ -284,265 +284,18 @@ module Citrine
         end
       end
 
-      # 一条文本布局缓存项：绘制对象 + 度量结果 + 释放所需的 libui 对象。
+      # 一条文本布局缓存项：绘制对象 + 度量结果 + 释放所需的平台对象。
       # 不是冻结接口的一部分（应用只拿到绘制方法，拿不到它）。
       TextEntry = Struct.new(:text, :size, :weight, :family, :color, :wrap_width, :align,
                              :layout, :attr_string, :font, :measured_width, :measured_height,
                              keyword_init: true)
 
-      include Primitives
-
-      attr_reader :width, :height
-
-      # @param ctx   [Fiddle::Pointer] uiDrawContext（只在本次 Draw 回调内有效）
-      # @param cache [TextCache] 文本布局缓存：跨帧复用，由适配层按面板持有（随面板销毁 clear!）
-      # @param clip  [Array, nil] 当前可见区 [x, y, w, h]（内容坐标；nil = 整块面板可见）
-      def initialize(ctx:, width:, height:, cache:, clip: nil)
-        self.class.libui!
-        @ctx = ctx
-        @width = width.to_f
-        @height = height.to_f
-        @cache = cache
-        @clip = clip || [0.0, 0.0, @width, @height]
-        @brush = ::LibUI::FFI::DrawBrush.malloc
-        @brush.Type = ::LibUI::DrawBrushTypeSolid
-        @stroke = ::LibUI::FFI::DrawStrokeParams.malloc
-        @stroke.Cap = ::LibUI::DrawLineCapFlat
-        @stroke.Join = ::LibUI::DrawLineJoinMiter
-        @stroke.MiterLimit = ::LibUI::DrawDefaultMiterLimit
-      end
-
-      private
-
-      # ── 平台实现：真 libui 调用 ──────────────────────────────
-      # 路径（uiDrawPath）是"一次性"对象：画完立刻 uiDrawFreePath，不能跨图元复用
-      # （libui 没有 reset API，且路径不归 Ruby GC 管——漏 free 就是每帧漏一段 C 内存）。
-
-      def emit_rect(x, y, w, h, fill, stroke, line_width, radius)
-        with_path do |path|
-          if radius.positive?
-            round_rect(path, x, y, w, h, radius)
-          else
-            ::LibUI.draw_path_add_rectangle(path, x, y, w, h)
-          end
-          ::LibUI.draw_path_end(path)
-          fill_path(path, fill)
-          stroke_path(path, stroke, line_width)
-        end
-      end
-
-      def emit_line(x1, y1, x2, y2, color, width)
-        with_path do |path|
-          ::LibUI.draw_path_new_figure(path, x1, y1)
-          ::LibUI.draw_path_line_to(path, x2, y2)
-          ::LibUI.draw_path_end(path)
-          stroke_path(path, color, width)
-        end
-      end
-
-      def emit_polyline(points, color, width)
-        with_path do |path|
-          trace(path, points)
-          ::LibUI.draw_path_end(path)
-          stroke_path(path, color, width)
-        end
-      end
-
-      def emit_polygon(points, fill, stroke, line_width)
-        with_path do |path|
-          trace(path, points)
-          ::LibUI.draw_path_close_figure(path)
-          ::LibUI.draw_path_end(path)
-          fill_path(path, fill)
-          stroke_path(path, stroke, line_width)
-        end
-      end
-
-      def emit_text(entry, x, y)
-        # (x, y) 是整段文本外接矩形的**左上角**（libui 的语义），不是基线
-        ::LibUI.draw_text(@ctx, entry.layout, x, y)
-        self
-      end
-
-      def emit_clip_begin(x, y, w, h)
-        ::LibUI.draw_save(@ctx)
-        with_path do |path|
-          ::LibUI.draw_path_add_rectangle(path, x, y, w, h)
-          ::LibUI.draw_path_end(path)
-          ::LibUI.draw_clip(@ctx, path)
-        end
-      end
-
-      def emit_clip_end
-        ::LibUI.draw_restore(@ctx)
-        self
-      end
-
-      def text_entry(text, size:, weight:, family:, color:, wrap_width:, align:)
-        @cache.entry(string: text, size: size, weight: weight, family: family, color: color,
-                     wrap_width: wrap_width, align: align)
-      end
-
-      def with_path
-        path = ::LibUI.draw_new_path(::LibUI::DrawFillModeWinding)
-        begin
-          yield path
-        ensure
-          ::LibUI.draw_free_path(path)
-        end
-        self
-      end
-
-      def trace(path, points)
-        points.each_with_index do |(x, y), index|
-          index.zero? ? ::LibUI.draw_path_new_figure(path, x, y)
-                      : ::LibUI.draw_path_line_to(path, x, y)
-        end
-      end
-
-      # 圆角矩形：四角各一段 90° 圆弧（y 轴向下，角度从 +x 往 +y 增长即顺时针）
-      def round_rect(path, x, y, w, h, radius)
-        half_pi = Math::PI / 2
-        ::LibUI.draw_path_new_figure_with_arc(path, x + radius, y + radius, radius, Math::PI, half_pi, 0)
-        ::LibUI.draw_path_line_to(path, x + w - radius, y)
-        ::LibUI.draw_path_arc_to(path, x + w - radius, y + radius, radius, -half_pi, half_pi, 0)
-        ::LibUI.draw_path_line_to(path, x + w, y + h - radius)
-        ::LibUI.draw_path_arc_to(path, x + w - radius, y + h - radius, radius, 0.0, half_pi, 0)
-        ::LibUI.draw_path_line_to(path, x + radius, y + h)
-        ::LibUI.draw_path_arc_to(path, x + radius, y + h - radius, radius, half_pi, half_pi, 0)
-        ::LibUI.draw_path_close_figure(path)
-      end
-
-      def fill_path(path, color)
-        return if color.nil?
-
-        @brush.R = color[0]
-        @brush.G = color[1]
-        @brush.B = color[2]
-        @brush.A = color[3]
-        ::LibUI.draw_fill(@ctx, path, @brush)
-      end
-
-      def stroke_path(path, color, width)
-        return if color.nil? || width <= 0
-
-        @brush.R = color[0]
-        @brush.G = color[1]
-        @brush.B = color[2]
-        @brush.A = color[3]
-        @stroke.Thickness = width
-        ::LibUI.draw_stroke(@ctx, path, @brush, @stroke)
-      end
-
-      # 文本布局缓存（每个面板一份，见类注释）。面板销毁时必须 clear!。
-      #
-      # 键除设计里写的 (string, size, weight, family) 还带上 color / wrap_width / align：
-      # 颜色是烘进 attributed string 的属性（涨跌红绿靠它），宽度与对齐决定换行与外接
-      # 矩形——少任何一项，缓存命中都会拿到"另一段文本"的布局。
-      class TextCache
-        ALIGN_CODES = { left: :DrawTextAlignLeft, center: :DrawTextAlignCenter,
-                        right: :DrawTextAlignRight }.freeze
-
-        def initialize
-          Painter.libui!
-          @entries = {}
-          @fonts = {}
-        end
-
-        # 取（或建）一条布局缓存
-        def entry(string:, size:, weight:, family:, color:, wrap_width:, align:)
-          @entries[[string, size, weight, family, color, wrap_width, align]] ||=
-            build(string, size, weight, family, color, wrap_width, align)
-        end
-
-        # 释放全部 libui 对象（顺序：layout → 它引用的 attributed string / 字体描述符）
-        def clear!
-          @entries.each_value do |cached|
-            ::LibUI.draw_free_text_layout(cached.layout)
-            ::LibUI.free_attributed_string(cached.attr_string)
-          end
-          @entries.clear
-          @fonts.each_value do |font|
-            # 只有 uiLoadControlFont 填过的描述符能交给 uiFreeFontDescriptor；
-            # 自建 family 的（Family 指向我们自己的 buffer）交给它会被 free 掉
-            # 不该 free 的内存——实测直接 abort 进程（GOALS 变更日志 NA-1）
-            ::LibUI.free_font_descriptor(font[:descriptor]) if font[:libui_owned]
-          end
-          @fonts.clear
-          self
-        end
-
-        # 缓存条目数（测试断言"布局真的被复用"用：画 100 帧，条目数不该跟着涨）
-        def entry_count = @entries.size
-
-        def font_count = @fonts.size
-
-        private
-
-        def build(string, size, weight, family, color, wrap_width, align)
-          font = font_for(size, weight, family)
-          attr_string = attributed_string(string, color)
-          params = ::LibUI::FFI::DrawTextLayoutParams.malloc
-          params.String = attr_string
-          params.DefaultFont = font[:descriptor]
-          params.Width = wrap_width
-          params.Align = ::LibUI.const_get(ALIGN_CODES.fetch(align))
-          layout = ::LibUI.draw_new_text_layout(params)
-
-          width_ptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_DOUBLE, Fiddle::RUBY_FREE)
-          height_ptr = Fiddle::Pointer.malloc(Fiddle::SIZEOF_DOUBLE, Fiddle::RUBY_FREE)
-          ::LibUI.draw_text_layout_extents(layout, width_ptr, height_ptr)
-          TextEntry.new(text: string, size: size, weight: weight, family: family, color: color,
-                        wrap_width: wrap_width, align: align, layout: layout,
-                        attr_string: attr_string, font: font,
-                        measured_width: double_at(width_ptr), measured_height: double_at(height_ptr))
-        end
-
-        # 字号与字重都写在**字体描述符**上（libui 用 params.DefaultFont 铺满整段文本），
-        # 颜色作为属性烘进 attributed string（涨跌红绿）
-        def attributed_string(string, color)
-          attr_string = ::LibUI.new_attributed_string(string)
-          bytes = string.bytesize
-          return attr_string if bytes.zero? || color.nil?
-
-          # uiAttributedStringSetAttribute 接管属性所有权（uiFreeAttributedString 连它们一起释放），
-          # 因此这里**不能**再 uiFreeAttribute——那是 double free
-          ::LibUI.attributed_string_set_attribute(attr_string, ::LibUI.new_color_attribute(*color), 0, bytes)
-          attr_string
-        end
-
-        # 字体描述符缓存：默认走 uiLoadControlFont（系统控制字体，Family 由 libui 分配），
-        # 显式给了 family 就自己填——那条路的 Family 指向我们 malloc 的 buffer，
-        # 结构体与 buffer 都交给 Fiddle 的 RUBY_FREE 释放（见 clear! 的说明）
-        def font_for(size, weight, family)
-          @fonts[[size, weight, family]] ||= if family.nil?
-                                               descriptor = ::LibUI::FFI::FontDescriptor.malloc
-                                               ::LibUI.load_control_font(descriptor)
-                                               descriptor.Size = size
-                                               descriptor.Weight = weight
-                                               { descriptor: descriptor, buffer: nil, libui_owned: true }
-                                             else
-                                               buffer = Fiddle::Pointer.malloc(family.bytesize + 1, Fiddle::RUBY_FREE)
-                                               buffer[0, family.bytesize + 1] = "#{family}\0"
-                                               descriptor = ::LibUI::FFI::FontDescriptor.malloc
-                                               descriptor.Family = buffer
-                                               descriptor.Size = size
-                                               descriptor.Weight = weight
-                                               descriptor.Italic = ::LibUI::TextItalicNormal
-                                               descriptor.Stretch = ::LibUI::TextStretchNormal
-                                               { descriptor: descriptor, buffer: buffer, libui_owned: false }
-                                             end
-        end
-
-        def double_at(pointer) = pointer[0, Fiddle::SIZEOF_DOUBLE].unpack1("d")
-      end
-
       # 记录图元调用序列（Memory 后端与 demo 的绘制断言用；不画任何东西）。
-      # 与真 Painter 共用同一份 Primitives：归一后的参数进 @calls。
+      # 与各后端的真实现共用同一份 Primitives：归一后的参数进 @calls。
       #
-      # 度量是**桩**：没有 libui 就没有真字体度量，measure_text 按字符数粗估
+      # 度量是**桩**：没有平台字体度量，measure_text 按字符数粗估
       # （CJK 按两个字符宽），只保证"量出来是正数、随字号变大"这类弱断言。
-      # 需要真度量的测试跑真控件冒烟（test/support/libui_scenario.rb）。
+      # 需要真度量的测试跑真控件冒烟（后端包的冒烟脚本）。
       class Recording
         include Primitives
 
@@ -610,16 +363,6 @@ module Citrine
           units * size * 0.55
         end
       end
-
-      class << self
-        # libui 只在真要用它时加载：Memory 后端下的单测不碰动态库
-        def libui!
-          require "libui"
-        rescue LoadError => e
-          raise Citrine::Native::ToolkitUnavailableError,
-                "自绘面板需要 libui（#{e.message}）：纯逻辑测试请用 Memory 后端"
-        end
-      end
     end
   end
 end

data/lib/citrine/native/version.rb

@@ -4,6 +4,6 @@ module Citrine
   module Native
     # 首个发布版本（N5）：N0–N4 全部落地后定版。
     # 发布流程见 CHANGELOG.md 与 .github/workflows/release.yml（Trusted Publishing）。
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/citrine/native/widgets.rb

@@ -17,14 +17,18 @@ module Citrine
     #     ——五个回调槽必须在创建时全部装上
     module Widgets
       class << self
-        # 默认后端：libui（决策 N-1）。测试注入 Memory 后端：
+        # 默认后端：核心包不带控件实现，解析交给 Citrine::Native.default_backend
+        # （后端包被 require 时自设，如 -libui 设 :libui）。测试注入 Memory 后端：
         #   Renderer.new(widgets: Widgets::Memory.new)
         def default
-          require_relative "widgets/libui"
-          Libui.new
+          backend = Citrine::Native.default_backend
+          raise Citrine::Native::BackendNotSelectedError,
+                "没有选择后端：请传 backend: / widgets:，或先 require 后端 gem"                 "（citrine-native-libui / citrine-native-gtk）" unless backend
+
+          Citrine::Native.resolve_backend(backend)
         end
 
-        # 内存打桩后端（CRuby 单测用；不加载 libui）
+        # 内存打桩后端（CRuby 单测用；不加载任何 UI 工具包）
         def memory
           Memory.new
         end

data/lib/citrine/native.rb

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
 
-# Citrine::Native — Citrine 组件的 CRuby 原生运行时（Shoes 式：ruby app.rb 直接起窗口）。
+# Citrine::Native —— Citrine 组件的 CRuby 原生运行时**核心**（后端无关）。
 #
-# 设计与计划见 GOALS.md。本 gem 实现 `Citrine::Renderer` 的平台钩子（renderer.rb），
-# 把节点树翻译成原生控件树；只依赖 citrine 的平台无关核心，**不引入 Opal**。
+# 这里只有平台无关的部分：Renderer（节点树 → 控件树翻译）、App（窗口生命周期）、
+# StyleMatrix、Painter 协议（Primitives + Recording）、Widgets::Base 协议 +
+# Memory 桩、定时器。具体控件由后端 gem 提供，按名字选择：
 #
-#   require "citrine-native"
+#   require "citrine-native"          # 核心
+#   Citrine::Native.run(Counter, backend: :libui)   # → citrine-native-libui
+#   Citrine::Native.run(Counter, backend: :gtk)     # → citrine-native-gtk
 #
-#   class Counter < Citrine::Component
-#     state :count, 0
-#     def view
-#       stack(gap: 8) do
-#         label { "计数：#{count}" }
-#         button(on_click: -> { self.count += 1 }) { "点我 +1" }
-#       end
-#     end
-#   end
+# 约定：后端 gem 名 = citrine-native-<名字>，控件适配类 =
+# Citrine::Native::Widgets::<CamelCase>(名字)（libui → Libui，gtk → Gtk，qt → Qt）。
+# 非常规命名用 Citrine::Native.register_backend 注册。也可以直接传实例：
+#   Citrine::Native.run(Counter, widgets: SomeBackend.new)
 #
-#   Citrine::Native.run(Counter, title: "计数器", width: 400, height: 300)
+# 后端包（如 citrine-native-libui）被加载时会自登记，并把自己设为
+# default_backend——所以"require 后端 gem 之后不传 backend:"也能跑。
 
 require "citrine"
 
@@ -29,8 +28,11 @@ module Citrine
     # 元素/属性在原生后端没有对应概念（GOALS 4.3：不静默降级）
     class UnsupportedElementError < Error; end
 
-    # 后端工具包不可用（缺少 libui 动态库等）
+    # 后端工具包不可用（缺少 libui/GTK 动态库等）
     class ToolkitUnavailableError < Error; end
+
+    # 未选择后端（core 自己不带控件实现）
+    class BackendNotSelectedError < Error; end
   end
 end
 
@@ -51,6 +53,40 @@ module Citrine
       # 挂载的那个"同口径）。定时器靠它把自己排回主线程，应用一般不用碰。
       attr_accessor :active_widgets
 
+      # 默认后端名（符号）：由后端包在被加载时自设（如 -libui 设 :libui），
+      # 应用也可以显式指定。nil = 未设（run 时不传 backend:/widgets: 会报错）。
+      attr_accessor :default_backend
+
+      # 已登记的后端（名字 → 控件适配类全名）
+      def registry
+        @registry ||= {}
+      end
+
+      # 登记后端（非常规命名的出口；常规命名靠 resolve_backend 的约定即可）
+      def register_backend(name, widgets:)
+        registry[name.to_sym] = widgets.to_s
+        self
+      end
+
+      # 按名字解析并实例化后端：约定 require "citrine-native-<名字>"，
+      # 控件类 = Citrine::Native::Widgets::<Camel>(名字)
+      def resolve_backend(name)
+        name = name.to_sym
+        widgets_class = registry[name] ||
+                        "Citrine::Native::Widgets::#{camelize(name)}"
+        require "citrine-native-#{name}"
+        widgets_class.split("::").inject(Object) { |mod, constant| mod.const_get(constant) }.new
+      rescue LoadError => e
+        raise ToolkitUnavailableError,
+              "后端 #{name} 不可用（#{e.message}）：gem citrine-native-#{name} " \
+              "没有装，或它的运行时依赖缺失"
+      end
+
+      # libui → Libui；gtk → Gtk；windows_font → WindowsFont
+      def camelize(name)
+        name.to_s.split("_").map { |part| part.capitalize }.join
+      end
+
       # 周期定时器（设计 2.5）→ Timer 句柄，可 #stop；块在主线程执行
       #
       #   @ticker = Citrine::Native.every(200) { self.tick }
@@ -62,10 +98,12 @@ module Citrine
 
       # 起一个原生窗口应用（阻塞到窗口关闭）。
       #
-      #   Citrine::Native.run(Counter, title: "计数器", width: 400, height: 300)
+      #   Citrine::Native.run(Counter, backend: :libui, title: "计数器", width: 400, height: 300)
       #
       # component 可以是组件类（无 prop 构造）或已构造的实例。
-      # 其余关键字直接作为窗口描述交给渲染器：title / width / height / margined。
+      # 后端三选一：backend:（名字，按上面的约定解析）／ widgets:（现成实例）／
+      # 都不传则用 default_backend（后端包被 require 时自设）。其余关键字直接
+      # 作为窗口描述交给渲染器：title / width / height / margined。
       #
       # dev_mode 默认开：原生运行时没有构建管线（脚本即应用），开发期提醒
       # （未支持的样式键/属性、未声明方向的 box）应当直接可见；显式传
@@ -74,15 +112,27 @@ module Citrine
       # signals 默认 nil（不接管进程级信号）：库不该悄悄覆盖宿主已有的处理器。
       # 把运行脚本当独立进程时传 `signals: :default`，Ctrl+C / SIGTERM 就会走
       # "退出主循环 → 有序拆解"，而不是硬杀（见 App#trap_quit!）。
-      def run(component, dev_mode: true, widgets: nil, **options)
+      def run(component, dev_mode: true, widgets: nil, backend: nil, **options)
         Citrine.dev_mode = dev_mode unless dev_mode.nil?
-        App.new(component, widgets: widgets, **options).run
+        App.new(component, widgets: pick_backend(widgets, backend), **options).run
       end
 
       # 只建窗口挂组件、不进主循环（测试与自管事件循环用）
-      def start(component, dev_mode: nil, widgets: nil, **options)
+      def start(component, dev_mode: nil, widgets: nil, backend: nil, **options)
         Citrine.dev_mode = dev_mode unless dev_mode.nil?
-        App.new(component, widgets: widgets, **options).tap(&:setup)
+        App.new(component, widgets: pick_backend(widgets, backend), **options).tap(&:setup)
+      end
+
+      private
+
+      def pick_backend(widgets, backend)
+        return widgets if widgets
+        return resolve_backend(backend) if backend
+        return Widgets.default if default_backend
+
+        raise BackendNotSelectedError,
+              "没有选择后端：请传 backend: :libui / :gtk（需要安装对应后端 gem），" \
+              "或 widgets: 后端实例；也可以 require 后端 gem（它会自设默认后端）"
       end
     end
   end

data/lib/citrine-native.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
-# gem 入口（RubyGems 命名惯例：require "citrine-native"）
-
+# gem 入口（RubyGems 命名惯例：require "citrine-native"）。
+# 核心 = 后端无关：Renderer / App / StyleMatrix / Painter 协议 / Widgets 协议 +
+# Memory 桩 + 定时器。控件实现按 backend: 选择（libui / gtk / …），
+# 见 lib/citrine/native.rb 头部的说明。
 require_relative "citrine/native"
+
+# 后端 gem（citrine-native-libui / citrine-native-gtk / …）各自提供：
+#   Citrine::Native.register_backend(:名字, widgets: "Citrine::Native::Widgets::类名")
+#   Citrine::Native.default_backend = :名字   # 可选：require 即默认

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: citrine-native
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - ShiningRay
@@ -23,20 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
-- !ruby/object:Gem::Dependency
-  name: libui
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
@@ -51,38 +37,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.2'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-description: citrine-native：Citrine 组件的 CRuby 原生运行时。不经 Opal/JS，同一份信号式组件代码直接用 ruby
-  启动为桌面窗口应用（Shoes 精神）。实现 Citrine::Renderer 协议，首版后端为 libui（原生控件）。
+description: 'citrine-native：Citrine 组件的 CRuby 原生运行时**核心**（后端无关）。Renderer / App /
+  StyleMatrix / Painter 协议 / Widgets 协议 + Memory 桩。控件实现按 backend: 选择：citrine-native-libui（libui）、citrine-native-gtk（GTK3）、以及未来的其它后端。'
 email:
-- shiningray@users.noreply.github.com
+- tsowly@hotmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -102,7 +60,6 @@ files:
 - lib/citrine/native/timer.rb
 - lib/citrine/native/version.rb
 - lib/citrine/native/widgets.rb
-- lib/citrine/native/widgets/libui.rb
 - lib/citrine/native/widgets/memory.rb
 homepage: https://github.com/ShiningRay/citrine-native
 licenses:
@@ -117,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -126,5 +83,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: CRuby native runtime for Citrine components (Shoes-style desktop apps)
+summary: Backend-agnostic native runtime core for Citrine components
 test_files: []