citrine 0.2.0

data/lib/citrine/signal.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Citrine
+  # 批量调度（S1-1）：同一同步窗口内的多次 Signal#set 合并为一轮 Effect 重跑——
+  # 去重后每个受影响的 Effect 只重跑一次，中间态不入 DOM。
+  # 窗口：事件处理器的分发过程自动包裹一次；应用代码也可用 Citrine.batch 显式开启。
+  class Scheduler
+    class << self
+      # 开启合并窗口：块内所有 set 只入队不广播，块返回后 flush 一次跑完。
+      # 可嵌套（内层不 flush）；块抛异常时同样 flush（与同步语义一样保留已写入的状态）。
+      def batch
+        @depth = (@depth || 0) + 1
+        begin
+          yield
+        ensure
+          @depth -= 1
+          if @depth.zero?
+            pending = $! # 用户块抛出的异常（若有）正在传播
+            begin
+              flush
+            rescue StandardError
+              raise if pending.nil? # 无用户异常时调度错误照常抛出
+              # 用户原始异常优先：flush 的错误不替换它（warn 已由 flush 发出）
+            end
+          end
+        end
+      end
+
+      def batching?
+        !@depth.nil? && @depth > 0
+      end
+
+      # 去重入队：同一 Effect 被多个信号命中也只跑一次。
+      # 以 effect 对象本身作 Hash 键（identity）：object_id 会被 GC 复用，
+      # 复用期内同 id 的新 effect 会被误判为"已入队"而静默丢弃更新。
+      def schedule(effect)
+        return if @queued && @queued.key?(effect)
+
+        (@queue ||= []) << effect
+        (@queued ||= {})[effect] = true
+      end
+
+      # 排空队列。重跑期间产生的新写入（depth 已归零）走同步广播——
+      # 与窗口外的既有语义一致，也避免循环依赖时无限排空。
+      # 单个 effect 抛错不中断本轮其余项：逐项 rescue、记档第一个错误，
+      # 队列排空后统一 warn 并重新抛出它——既避免同批更新半途丢弃，
+      # 也不让调度错误从 ensure 路径穿出时替换用户块的原始异常
+      # （batch 的 ensure 依 $! 判定：用户异常在传播时吞掉调度错误，只保留 warn）。
+      def flush
+        first_error = nil
+        while @queue && !@queue.empty?
+          current = @queue
+          @queued = nil
+          @queue = nil
+          current.each do |effect|
+            begin
+              effect.run
+            rescue StandardError => e
+              first_error ||= e
+              warn "[citrine] effect 重跑失败（#{e.class}: #{e.message}），已跳过；" \
+                   "同批其余 effect 不受影响"
+            end
+          end
+        end
+        @queue = nil
+        @queued = nil
+        raise first_error if first_error
+      end
+    end
+  end
+
+  # 细粒度响应信号（决策 #3 核心）：
+  # 读取时向当前 Effect 登记依赖；写入时同步通知订阅者重跑。
+  # 唯一读写通道是 #get / #set——绕过它们（如直接改内部数组）不会触发更新，
+  # v1 集合为整体替换语义。
+  class Signal
+    # 可以给块：块即**惰性初值**，第一次 get 时才求值（只求一次）。
+    # 与 state 宏里 `init:` 的区别：这里块在**定义处**的词法作用域执行（普通 Proc 语义），
+    # 组件的 `state ... do ... end` 则在组件实例上求值。
+    def initialize(value = nil, &init)
+      @value = value
+      @init = init
+      @subs = []
+    end
+
+    def get
+      effect = Effect.current
+      effect&.depend(self)
+      run_init if @init
+      @value
+    end
+
+    # 读值但**不订阅**：只想拿一份快照、不想让当前 Effect 依赖它时用（MobX 的 untracked）。
+    # get 一旦落在块/Effect 里就会建立依赖——"订阅"与"取值"耦合在一起，
+    # 想两者分开时就需要这个显式出口。
+    def peek
+      run_init if @init
+      @value
+    end
+
+    def set(new_value)
+      @init = nil # 显式写入过就不再是"未初始化"
+      return self if new_value == @value
+
+      @value = new_value
+      broadcast
+      self
+    end
+
+    # 强制广播：跳过相等短路（S1-11）。用于"值按引用共享、内容被就地改写"的
+    # 场景——对象还是同一个，相等检查会误判为没变。
+    def set!(new_value)
+      @init = nil
+      @value = new_value
+      broadcast
+      self
+    end
+
+    def broadcast
+      if Scheduler.batching?
+        # 批量窗口（S1-1）：只入队不广播——去重后 flush 一次跑完
+        @subs.dup.each { |effect| Scheduler.schedule(effect) }
+      else
+        @subs.dup.each(&:run)
+      end
+      self
+    end
+
+    private :broadcast # 只经 set / set! 触发，不允许外部绕过值更新手动广播
+
+    # 惰性初值是否还没求过（诊断用）
+    def lazy? = !@init.nil?
+
+    # 静默换值：不广播、不触发任何订阅者。用于"每次重传都是新对象的回调类 prop"
+    # （S1-2）：换引用不算变更，与 keyed 复用忽略 Proc 的口径一致。
+    def replace(new_value)
+      @init = nil
+      @value = new_value
+      self
+    end
+
+    # 以下两个方法供 Effect 内部使用
+
+    def subscribe(effect)
+      @subs << effect unless @subs.include?(effect)
+    end
+
+    def unsubscribe(effect)
+      @subs.delete(effect)
+    end
+
+    private
+
+    def run_init
+      init = @init
+      @init = nil
+      @value = init.call
+    end
+  end
+
+  # Effect：block 内读取的信号自动成为依赖，任一依赖变化时重跑整个 block。
+  # 每次重跑前先解除全部旧依赖、按新一次读取重建（MobX 式追踪），
+  # 因此条件分支切换后，未再读取的信号不再触发本 Effect。
+  class Effect
+    class << self
+      def stack
+        @stack ||= []
+      end
+
+      def current
+        stack.last
+      end
+
+      # track_cleanup: 块返回 Proc 时把它当作 cleanup——每次重跑前与 dispose 时
+      # 各执行一次（S1-8 的 effect 宏用；其余 Effect 不启用，避免把普通返回值误当清理）。
+      def create(track_cleanup: false, &block)
+        effect = new(block, track_cleanup)
+        effect.run
+        effect
+      end
+    end
+
+    def initialize(block, track_cleanup = false)
+      @block = block
+      @track_cleanup = track_cleanup
+      @deps = []
+    end
+
+    def run
+      return self if @deps.nil? # 已 dispose 的 effect 保持惰性（广播快照中可能仍被迭代到）
+
+      call_cleanup # 重跑前先清上一轮申请的资源（订阅还在，清理时读得到新鲜值）
+      release_deps
+      self.class.stack.push(self)
+      begin
+        result = @block.call
+        @cleanup = result if @track_cleanup && result.is_a?(Proc)
+      ensure
+        self.class.stack.pop
+      end
+      self
+    end
+
+    # 永久停用：从所有依赖中移除，block 不再执行（节点销毁时由渲染器调用）。
+    # 幂等：同一 effect 可能被销毁两次（自身重跑中 dispose 兄弟节点后又被快照迭代）。
+    def dispose
+      return if @deps.nil?
+
+      call_cleanup # 卸载路径的清理：跑完才释放订阅（与 computed 释放顺序同口径）
+      release_deps
+      @block = nil
+      @deps = nil
+    end
+
+    def depend(signal)
+      return if @deps.nil? # 块运行中自 dispose：依赖表已清空，不再登记（原 nil.any? 崩溃点）
+      return if @deps.any? { |d| d.equal?(signal) } # 同一信号读多次只记一条依赖边
+
+      @deps << signal
+      signal.subscribe(self)
+    end
+
+    private
+
+    def release_deps
+      @deps.each { |s| s.unsubscribe(self) }
+      @deps.clear
+    end
+
+    def call_cleanup
+      cleanup = @cleanup
+      @cleanup = nil
+      cleanup&.call
+    end
+  end
+end

data/lib/citrine/sourcemap.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+
+module Citrine
+  # source map 还原（T-B3 后半）：把 Opal 产物的 JS 抛错位置还原到 .rb 文件与行号。
+  #
+  # 支持两种 map 形态：
+  #   - 普通 map：顶层 mappings/sources
+  #   - indexed map：Opal 产出的 sections 内嵌多段 map
+  #
+  # 用法（拿到未捕获异常的 JS 行号后）：
+  #   map  = Citrine::SourceMap.load("counter.js")
+  #   loc  = Citrine::SourceMap.locate(map, js_line, js_column)
+  #   loc  # => { source: "counter.rb", line: 12, column: 5 }
+  class SourceMap
+    B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+          .chars.each_with_index.to_h.freeze
+
+    attr_reader :raw
+
+    # 从 .js 文件读取内联 base64 map（Opal 默认产物形态）
+    def self.load(js_path)
+      body = File.read(js_path)
+      match = body.match(/sourceMappingURL=data:application\/json;base64,([A-Za-z0-9+\/=]+)/)
+      raise ArgumentError, "#{js_path} 内没有内联 source map" unless match
+
+      new(JSON.parse(Base64.decode64(match[1])))
+    end
+
+    def initialize(raw)
+      @raw = raw
+    end
+
+    # 把生成的 JS 位置（1-based 行）还原到原始 .rb 位置。
+    # 返回 { source:, line:, column: } 或 nil（该位置无映射信息）。
+    def locate(line, column = 0)
+      line0 = line - 1 # 内部统一 0-based 生成行（spec 的 section offset 即 0-based）
+      if raw["sections"]
+        section, offset = find_section(line0, column)
+        return nil unless section
+
+        off_line, off_col = offset
+        locate_in(section["map"], line0 - off_line + 1, column - off_col)
+      else
+        locate_in(raw, line, column)
+      end
+    end
+
+    # map 覆盖的所有原始文件
+    def sources
+      if raw["sections"]
+        raw["sections"].flat_map { |s| s.dig("map", "sources") || [] }.compact
+      else
+        raw["sources"] || []
+      end
+    end
+
+    private
+
+    # 选取起始位置 <= 目标位置的最后一个 section（sections 按 offset 升序）。
+    # offset 兼容规范 hash 形态 {"line":, "column":}（部分工具也用数组）。
+    def find_section(line0, _column0)
+      best = nil
+      best_offset = nil
+      raw["sections"].each do |section|
+        offset = section["offset"]
+        off_line = offset.is_a?(Array) ? offset[0] : offset["line"].to_i
+        off_col = offset.is_a?(Array) ? (offset[1] || 0) : offset["column"].to_i
+        if off_line <= line0
+          best = section
+          best_offset = [off_line, off_col]
+        end
+      end
+      best ? [best, best_offset] : nil
+    end
+
+    def locate_in(map, line, column)
+      decoded = decoded_lines(map)
+      return nil if line <= 0 || line > decoded.size
+
+      segments = decoded[line - 1]
+      seg = segments.reverse.find { |(gen_col, *)| gen_col <= column }
+      return nil if seg.nil? || seg[1].nil?
+
+      sources = map["sources"] || []
+      return nil if sources[seg[1]].nil?
+
+      # src_line/src_col 以 0 计，行号转 1-based
+      { source: sources[seg[1]], line: seg[2] + 1, column: seg[3] }
+    end
+
+    # 全量预解码 mappings：生成列每行重置，源索引/源行/源列跨行累积（spec 语义）。
+    # 每行产出 [gen_col, src_idx, src_line, src_col] 段（1 字段段仅推进 gen_col）。
+    def decoded_lines(map)
+      @decoded_cache ||= {}
+      @decoded_cache[map] ||= begin
+        src_idx = 0
+        src_line = 0
+        src_col = 0
+        (map["mappings"] || "").split(";").map do |line|
+          gen_col = 0
+          line.split(",").filter_map do |segment|
+            next if segment.empty?
+
+            fields = decode_vlq(segment)
+            gen_col += fields[0]
+            if fields.size >= 4
+              src_idx += fields[1]
+              src_line += fields[2]
+              src_col += fields[3]
+              [gen_col, src_idx, src_line, src_col]
+            end
+          end
+        end
+      end
+    end
+
+    # Base64 VLQ 解码
+    def decode_vlq(segment)
+      values = []
+      shift = 0
+      value = 0
+      segment.each_char do |ch|
+        digit = B64[ch] or raise ArgumentError, "非法 base64 VLQ 字符: #{ch.inspect}"
+        cont = (digit & 32) != 0
+        digit &= 31
+        value += digit << shift
+        if cont
+          shift += 5
+        else
+          negative = (value & 1) == 1
+          value >>= 1
+          values << (negative ? -value : value)
+          value = 0
+          shift = 0
+        end
+      end
+      values
+    end
+  end
+end

data/lib/citrine/string_renderer.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "citrine"
+require "citrine/renderer"
+
+module Citrine
+  # render-to-string 渲染器：纯 CRuby 可用（SSR / 单测 / 快照）。
+  #
+  # 一次性渲染：不建立 Effect 订阅（reactive? = false）；
+  # 事件处理器不序列化（SSR 交互不在本渲染器范围）。
+  class StringRenderer < Renderer
+    class << self
+      def render(component)
+        new.mount_component(component, nil).children.map(&:dom).join
+      end
+    end
+
+    private
+
+    def reactive?
+      false
+    end
+
+    def setup_root(root, _element)
+      root.dom = ""
+    end
+
+    def create_dom(_node)
+      ""
+    end
+
+    def apply_props(_node); end
+
+    def attach(_node, _parent); end
+
+    def detach(_node); end
+
+    def set_text(node, text)
+      node.text = text
+    end
+
+    def setup_widget(_node); end
+
+    # SSR 无宿主概念：portal 内容按逻辑位置内联输出
+    def resolve_portal_host(_target)
+      ""
+    end
+
+    def finalize(node)
+      if node.type == :fragment || node.type == :portal || node.type == :suspense
+        # 透明容器（S1-4 / S1-5 / S1-10）：SSR 侧都按子根依次拼接
+        #（SSR 无宿主概念，portal 内容按逻辑位置内联输出；suspense 只输出当前分支）
+        node.dom = node.children.map(&:dom).join
+        node.dom += escape_html(node.text) if node.text
+        return
+      end
+      return if node.type == :root
+
+      node.dom = serialize(node)
+    end
+
+    def serialize(node)
+      tag = TAGS[node.type] || node.type.to_s
+      attrs = attributes(node)
+      return "<#{tag}#{attrs}>" if VOID.include?(node.type)
+
+      inner = node.children.map(&:dom).join
+      inner += escape_html(node.text) if node.text
+      "<#{tag}#{attrs}>#{inner}</#{tag}>"
+    end
+
+    def attributes(node)
+      out = []
+      # 响应式属性在 SSR 侧只求值一次（无订阅、无重跑，与 DOM 输出保持一致）
+      css_class = prop_value(node, node.props[:css_class])
+      # A7：数组形式与 DOM className 同口径——空格 join，不再渲染成 Ruby 字面量
+      css_class = css_class.join(" ") if css_class.is_a?(Array)
+      # 属性值必须转义：值里出现引号会提前闭合属性，把数据变成新属性（属性注入）。
+      out << %(class="#{escape_html(css_class)}") if css_class
+      case node.type
+      when :text_input
+        out << %(type="#{escape_html(node.props[:type] || "text")}")
+        if (placeholder = prop_value(node, node.props[:placeholder]))
+          out << %(placeholder="#{escape_html(placeholder)}")
+        end
+        value = node.props[:value]
+        value = value.get if value.is_a?(Signal)
+        out << %(value="#{escape_html(value)}") if value && value != ""
+      when :check_box
+        out << 'type="checkbox"'
+        checked = node.props[:checked]
+        checked = checked.get if checked.is_a?(Signal)
+        out << "checked" if checked
+      end
+      # S2-2：未消费属性原样透传，口径与 DOM 一致（kebab-case；true → 空值属性；
+      # false / nil 不输出）。值同样要转义——理由与 class 相同。
+      passthrough_props(node).each do |name, value|
+        out << (value.empty? ? name : %(#{name}="#{escape_html(value)}"))
+      end
+      style = resolve_style(node)
+      out << %(style="#{style_css(style)}") unless style.empty?
+      out.empty? ? "" : " #{out.join(' ')}"
+    end
+
+    def style_css(style)
+      # 样式键为 snake_case（决策 #10）；内联 CSS 属性必须是 kebab-case。
+      # 值同样要转义——理由与 class 相同：属性值里的引号会提前闭合 style 属性。
+      style.map { |key, value| "#{Style.kebab(key)}:#{escape_html(value)}" }.join(";")
+    end
+
+    def escape_html(text)
+      text.to_s.gsub("&", "&amp;").gsub("<", "&lt;")
+             .gsub(">", "&gt;").gsub('"', "&quot;")
+    end
+  end
+end

data/lib/citrine/style.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Citrine
+  # 样式键归一化（决策 #10）：
+  # - API 层统一 snake_case（Ruby 惯例，与 on_click 等事件命名同风格）
+  # - 兼容 camelCase 输入（fontSize 与 font_size 等价）
+  # - 值中的 Symbol 自动转 CSS 连字符形式（:line_through → "line-through"）
+  # 各渲染器在边界自行编译：DOM → camelCase 属性；CSS 字符串 → kebab-case；
+  # Canvas 直接以 snake_case 消费。
+  module Style
+    module_function
+
+    # 有数值默认补 px 的属性（显式字符串单位不受影响）。
+    # font_size 等排版键在此的原因：CSS 里 `font-size:14` 是非法声明（浏览器整条丢弃），
+    # SSR 按值直拼会输出非法 CSS——数值必须推断成 "14px" 才与 DOM 侧一致。
+    PX_PROPERTIES = %i[
+      width height min_width min_height max_width max_height
+      border_radius top left right bottom inset
+      padding padding_left padding_right padding_top padding_bottom
+      margin margin_left margin_right margin_top margin_bottom
+      font_size letter_spacing word_spacing text_indent
+      gap row_gap column_gap outline_width outline_offset
+    ].freeze
+
+    # 数值语义上无单位的属性
+    UNITLESS_PROPERTIES = %i[
+      flex flex_grow flex_shrink order opacity z_index line_height
+      font_weight column_count zoom
+    ].freeze
+
+    def normalize(style)
+      return {} unless style
+
+      style.each_with_object({}) do |(key, value), out|
+        key = underscore(key)
+        value = resolve_theme_ref(value)
+        value = normalize_value(value)
+        next if value.nil? # F17：nil 值剔除而非输出非法 CSS
+        if value.is_a?(Numeric) && PX_PROPERTIES.include?(key) && !UNITLESS_PROPERTIES.include?(key)
+          value = "#{value}px"
+        end
+        out[key] = value
+      end
+    end
+
+    # 主题 token 引用（S2-5）→ 主题值。token 值还可以再引用 token
+    # （有深度上限防循环引用）；解析后的数值走同一套 px 推断
+    def resolve_theme_ref(value, depth = 0)
+      return value unless value.is_a?(Theme::Ref)
+      raise ArgumentError, "主题 token 嵌套过深（疑似循环引用）" if depth > 8
+
+      resolve_theme_ref(Theme.resolve!(value), depth + 1)
+    end
+
+    # fontSize / font_size / :fontSize → :font_size；kebab-case（"font-size"）同归一。
+    # P2：per-key memo——normalize 对每个键每次渲染都跑转换，缓存后同键零分配。
+    def underscore(key)
+      @underscore_cache ||= {}
+      @underscore_cache[key] ||= key.to_s.gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }
+                              .gsub("-", "_").downcase.to_sym
+    end
+
+    # font_size → fontSize（DOM style 属性赋值用）
+    def camel(key)
+      @camel_cache ||= {}
+      @camel_cache[key] ||= key.to_s.gsub(/_([a-zA-Z0-9])/) { Regexp.last_match(1).upcase }
+    end
+
+    # font_size → font-size（内联 CSS 字符串用）
+    def kebab(key)
+      @kebab_cache ||= {}
+      @kebab_cache[key] ||= key.to_s.tr("_", "-")
+    end
+
+    def normalize_value(value)
+      value.is_a?(Symbol) ? value.to_s.tr("_", "-") : value
+    end
+  end
+end

data/lib/citrine/theme.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Citrine
+  # 主题 token 与全局样式资产（S2-5 后半）：
+  #
+  #   Citrine.theme(color_primary: "#667eea", spacing_md: 12)
+  #   Citrine.css("styles.css")     # 声明样式表：dev server 注入 <link>，打包器随包复制
+  #   Citrine.css_text = <<~CSS     # 媒体查询 / 伪类等内联样式表达不了的逃生舱
+  #     .card:hover { background: #f1f5f9; }
+  #   CSS
+  #
+  # style 里用 Citrine.token(:name) 引用 token，归一化时解析：
+  #   label(style: { background: Citrine.token(:color_primary),
+  #                  padding: Citrine.token(:spacing_md) })
+  # 数值 token 走同一套 px 推断；未定义的 token 当场报错（不静默变成裸字符串）。
+  module Theme
+    # token 引用：Style.normalize 遇到它时查主题注册表
+    class Ref
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.to_sym
+      end
+
+      def inspect = "#<Citrine::Theme::Ref #{@name}>"
+      def to_s = "token(#{@name})"
+    end
+
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      def define(**tokens)
+        registry.merge!(tokens)
+        self
+      end
+
+      # 解析 token 引用；未定义的 token 属于样式错误，当场报
+      def resolve!(ref)
+        raise ArgumentError, "未定义的主题 token: #{ref.name}（先 Citrine.theme(#{ref.name}: ...)）" unless registry.key?(ref.name)
+
+        registry[ref.name]
+      end
+    end
+  end
+
+  class << self
+    # 定义 / 读取主题 token：Citrine.theme(color_primary: "#667eea")；
+    # 无参调用返回注册表快照
+    def theme(**tokens)
+      return Theme.registry.dup if tokens.empty?
+
+      Theme.define(**tokens)
+    end
+
+    # style 里引用主题 token
+    def token(name)
+      Theme::Ref.new(name)
+    end
+
+    # 声明样式表文件（相对应用根）：dev server 注入 <link>、打包器随包复制
+    def css(*files)
+      css_files.concat(files.map(&:to_s))
+      self
+    end
+
+    def css_files
+      @css_files ||= []
+    end
+
+    attr_writer :css_files
+
+    # 自定义 CSS 文本（媒体查询 / 伪类等内联样式表达不了的东西的逃生舱）：
+    # dev server 注入 <style>；SSR / 模板侧经 stylesheet_tags 输出
+    def css_text
+      @css_text
+    end
+
+    def css_text=(text)
+      @css_text = text.to_s
+    end
+
+    # SSR / 模板侧：产出 <link> / <style> 标签串
+    def stylesheet_tags
+      tags = css_files.map { |f| %(<link rel="stylesheet" href="/#{f}">) }
+      tags << "<style>#{css_text}</style>" if css_text && !css_text.empty?
+      tags.join("\n")
+    end
+
+    # 测试与多页面隔离用：清空样式资产与主题
+    def reset_style_assets!
+      @css_files = []
+      @css_text = nil
+      Theme.registry.clear
+      self
+    end
+  end
+end

data/lib/citrine/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Citrine
+  VERSION = "0.2.0"
+end