funicular 0.1.0 → 0.2.0

data/mrblib/component.rb

@@ -62,6 +62,25 @@ module Funicular
       {}
     end
 
+    # Merge externally provided state into the component before rendering.
+    # Used by SSR to inject server data, and by client hydration to restore
+    # the same state from window.__FUNICULAR_STATE__ so the first client
+    # render matches the server HTML. Top-level keys are symbolized so they
+    # are reachable via state.foo (StateAccessor uses symbol keys); nested
+    # values are left untouched (components read them with string keys).
+    def seed_state(state_hash)
+      return self if state_hash.nil?
+      return self if state_hash.respond_to?(:empty?) && state_hash.empty?
+
+      symbolized = {} #: Hash[Symbol, untyped]
+      state_hash.each do |key, value|
+        symbolized[key.to_sym] = value
+      end
+      @state = @state.merge(symbolized)
+      @state_accessor = nil
+      self
+    end
+
     # Load all registered suspense data
     # Called automatically in component_mounted if suspense definitions exist
     def load_suspense_data
@@ -173,10 +192,14 @@ module Funicular
     #     div { user.name }
     #   end
     def suspense(fallback:, error: nil, &block)
+      current_children = @current_children
+      child_count_before = current_children&.size
+      result = nil
+
       # Check for any rejected suspense
       rejected_name = self.class.suspense_definitions.keys.find { |name| @suspense_states[name] == :rejected }
       if rejected_name
-        if error
+        result = if error
           error.call(@suspense_errors[rejected_name])
         else
           fallback.call
@@ -184,13 +207,17 @@ module Funicular
       elsif suspense_loading?
         # Check if any suspense is still loading
         # Note: Loading is started in mount(), not here
-        fallback.call
+        result = fallback.call
       else
         # All suspense data loaded, render content
-        block.call
+        result = block.call
+      end
+
+      if current_children && current_children.size == child_count_before
+        add_child(result)
       end
-      # Note: We don't add result to @current_children because
-      # the DSL methods inside fallback/block already do that
+
+      result
     end
 
     # Class methods for styles DSL
@@ -298,6 +325,65 @@ module Funicular
       end
     end
 
+    # Hydrate this component against server-rendered DOM.
+    #
+    # Unlike mount, which builds a fresh DOM tree via VDOM::Renderer, hydrate
+    # reuses the existing DOM produced by the server: it builds the VDOM,
+    # associates it with the existing nodes, and only attaches event listeners
+    # and refs (plus wiring child components). The first client render must
+    # match the server HTML, which is why state is seeded from
+    # window.__FUNICULAR_STATE__ before calling this.
+    def hydrate(dom_element)
+      return if @mounted
+      raise "hydrate: missing server DOM element" unless dom_element
+
+      begin
+        component_will_mount if respond_to?(:component_will_mount)
+
+        # The router/start sets the container; without it, unmount could not
+        # detach this subtree later. Derive it from the existing DOM.
+        @container ||= dom_element.parentNode
+        @dom_element = dom_element
+
+        new_vdom = build_vdom
+
+        if hydration_match?(new_vdom, dom_element)
+          # Wire child components first so their instances exist for collection.
+          hydrate_child_components(new_vdom, dom_element)
+
+          # Reuse the same positional walks as mount: they skip Component vnodes
+          # (children manage their own events/refs during their own hydrate).
+          bind_events(dom_element, new_vdom)
+          collect_refs(dom_element, new_vdom)
+          collect_child_components(new_vdom)
+        else
+          # Server and client disagree on structure (nondeterministic render or
+          # stale state). Recover by discarding the server DOM and rendering a
+          # fresh tree, the same way mount does. The page stays usable; only the
+          # first-paint reuse is lost for this subtree.
+          warn_hydration_mismatch(new_vdom, dom_element)
+          @dom_element = full_render_fallback(new_vdom, dom_element)
+        end
+
+        @vdom = new_vdom
+        @mounted = true
+
+        load_suspense_data if self.class.suspense_definitions.any?
+
+        @child_components.each do |child|
+          unless child.mounted
+            child.mounted = true
+            child.component_mounted if child.respond_to?(:component_mounted)
+          end
+        end
+
+        component_mounted if respond_to?(:component_mounted)
+      rescue => e
+        component_raised(e) if respond_to?(:component_raised)
+        raise e
+      end
+    end
+
     # Unmount component from DOM
     def unmount
       return unless @mounted
@@ -495,42 +581,25 @@ module Funicular
 
     private
 
-    # Normalize state value by converting JS::Object to Ruby native types
+    # Normalize state value for storage. Primitives are already auto-
+    # converted to Ruby native values by picoruby-wasm, so only composite
+    # JS::Object values (array / plain object / function / symbol / bigint)
+    # and nested Ruby collections need handling here.
     def normalize_state_value(value)
-      if value.is_a?(Hash)
-        # Recursively normalize hash values
+      case value
+      when Hash
         normalized = {} #: Hash[untyped, untyped]
-        value.each do |k, v|
-          normalized[k] = normalize_state_value(v)
-        end
+        value.each { |k, v| normalized[k] = normalize_state_value(v) }
         normalized
-      elsif value.is_a?(Array)
-        # Recursively normalize array elements
+      when Array
         value.map { |v| normalize_state_value(v) }
-      elsif value.is_a?(JS::Object)
-        # Convert JS::Object to appropriate Ruby type
-        case value.type
-        when :string
-          value.to_s
-        when :number
-          # Check if it's an integer or float
-          num = value.to_f
-          num == num.to_i ? num.to_i : num
-        when :boolean
-          # JS::Object#== now supports direct comparison with Ruby true/false
-          value == true
-        when :null, :undefined
-          nil
-        when :array
+      when JS::Object
+        if value.typeof == :array
           value.to_a.map { |v| normalize_state_value(v) }
-        when :object
-          # For plain objects, keep as JS::Object or convert to hash if needed
-          value
         else
           value
         end
       else
-        # Return as-is for Ruby native types
         value
       end
     end
@@ -546,7 +615,10 @@ module Funicular
       cleanup_events
 
       unless patches.empty?
-        @dom_element = VDOM::Patcher.new.apply(@dom_element, patches)
+        new_dom_element = VDOM::Patcher.new.apply(@dom_element, patches)
+        # apply returns JS::Object (it must accept text-node patches), but
+        # the component's root is always an Element. Narrow to JS::Element.
+        @dom_element = new_dom_element if new_dom_element.is_a?(JS::Element)
       end
 
       bind_events(@dom_element, new_vdom)
@@ -599,6 +671,64 @@ module Funicular
       end
     end
 
+    # Lightweight structural check: the root tag of the freshly built VDOM
+    # must match the server-rendered element. A mismatch means server and
+    # client disagree (nondeterministic render or stale state); the caller
+    # falls back to a full client render.
+    def hydration_match?(vnode, dom_element)
+      return true unless vnode.is_a?(VDOM::Element)
+      actual = dom_element[:tagName]
+      return true unless actual  # non-element node; let later steps surface issues
+      vnode.tag.to_s.downcase == actual.to_s.downcase
+    end
+
+    # Emit a development-only warning describing a hydration mismatch. Uses
+    # puts so the message reaches the browser console (same idiom as the
+    # ErrorBoundary logger), and is silent in production.
+    def warn_hydration_mismatch(vnode, dom_element)
+      return unless Funicular.env.development?
+      expected = vnode.is_a?(VDOM::Element) ? vnode.tag.to_s.downcase : vnode.class.to_s
+      got = dom_element[:tagName].to_s.downcase
+      puts "[Funicular] Hydration mismatch: expected <#{expected}>, found <#{got}>; " \
+           "falling back to full client render"
+    end
+
+    # Recover from a hydration mismatch by rendering a fresh DOM tree and
+    # swapping it in for the server-rendered node. Mirrors mount, minus the
+    # appendChild: the stale node already has a place in the document, so we
+    # replaceChild instead.
+    def full_render_fallback(new_vdom, server_dom)
+      fresh = VDOM::Renderer.new.render(new_vdom)
+      parent = server_dom.parentNode
+      parent.replaceChild(fresh, server_dom) if parent
+      bind_events(fresh, new_vdom)
+      collect_refs(fresh, new_vdom)
+      collect_child_components(new_vdom)
+      fresh
+    end
+
+    # Walk the VDOM and existing DOM in parallel to hydrate nested components.
+    # Uses the same positional indexing as bind_events/collect_refs so the
+    # three walks agree on which DOM node maps to which vnode.
+    def hydrate_child_components(vnode, dom_element)
+      return unless vnode.is_a?(VDOM::Element)
+      return unless dom_element
+
+      dom_children = dom_element.children.to_a
+      vnode.children.each_with_index do |child, index|
+        child_dom = dom_children[index]
+        next unless child_dom
+
+        if child.is_a?(VDOM::Component)
+          instance = child.component_class.new(child.props)
+          child.instance = instance
+          instance.hydrate(child_dom)
+        elsif child.is_a?(VDOM::Element)
+          hydrate_child_components(child, child_dom)
+        end
+      end
+    end
+
     # Collect child component instances from VDOM tree
     def collect_child_components(vnode)
       @child_components = []
@@ -632,6 +762,13 @@ module Funicular
       br hr
     ]
 
+    # The HTML tag DSL methods are public: besides being called inside render
+    # (implicit self), they are invoked by collaborators such as FormBuilder
+    # with an explicit receiver (@component.div). A private method would forbid
+    # that under CRuby (it is tolerated under mruby), which would break SSR of
+    # any component using form_for. Keep them public on both VMs.
+    public
+
     HTML_TAGS.each do |tag|
       define_method(tag) do |props = {}, &block|
         # @type self: Component
@@ -674,6 +811,8 @@ module Funicular
       end
     end
 
+    private
+
     # Helper to add children in DSL blocks
     def add_child(child)
       return unless @rendering && @current_children

data/mrblib/debug.rb

@@ -4,6 +4,9 @@ module Funicular
       attr_accessor :enabled
 
       def enabled?
+        # Disabled on the server: SSR instantiates components per request and
+        # must not accumulate them in the debug registry.
+        return false if Funicular.server?
         @enabled ||= Funicular.env.development?
       end
 

data/mrblib/differ.rb

@@ -90,9 +90,22 @@ module Funicular
         end
       end
 
+      # Produce a single composite patch describing a keyed-children diff.
+      #
+      # The earlier implementation emitted independent `[index, ...]` patches
+      # for inserts, removes and updates. The patcher consumed them as
+      # `replaceChild`, which is unsafe whenever insert and remove indices
+      # overlap (e.g. switching between two equal-length sets of keyed
+      # children with disjoint keys): inserts overwrite old nodes in place,
+      # then the descending removes drop the just-inserted new nodes and
+      # the DOM ends up empty.
+      #
+      # The new shape is `[[:keyed_children, ops, removes]]`, applied as
+      # three phases by the patcher:
+      #   1. removes (descending old_index, against the original DOM snapshot)
+      #   2. content updates for kept children (against the snapshot, no move)
+      #   3. inserts in ascending new_index using insertBefore on the live DOM
       def self.diff_children_with_keys(old_children, new_children)
-        patches = [] #: Array[patch_t]
-
         # 1. Build key map from old children
         old_key_map = {} #: Hash[untyped, [Integer, child_t]]
         old_children.each_with_index do |child, index|
@@ -101,63 +114,60 @@ module Funicular
           end
         end
 
-        # 2. Track matched old indices
         matched_old_indices = {} #: Hash[Integer, bool]
+        ops = [] #: Array[Array[untyped]]
+        has_change = false
 
-        # 3. Process new children
+        # 2. Process new children, recording one op per new position
         new_children.each_with_index do |new_child, new_index|
           if new_child.is_a?(VNode) && new_child.respond_to?(:key) && new_child.key
             key = new_child.key
-
             if old_key_map[key]
               old_index, old_child = old_key_map[key]
               matched_old_indices[old_index] = true
-
-              # Diff existing element
               child_patches = diff(old_child, new_child)
-              unless child_patches.empty?
-                patches << [new_index, child_patches]
-              end
+              ops << [:keep, old_index, new_index, child_patches]
+              has_change = true unless child_patches.empty?
             else
-              # Insert new element
-              patches << [new_index, [[:replace, new_child, nil]]] # old_node is nil for insertion
+              ops << [:insert, new_index, new_child]
+              has_change = true
             end
           else
-            # Fallback to index-based for elements without keys
-            # Even if old_child.nil?, diff will handle it (insertion)
+            # Unkeyed new child: positional fallback. Match it with the
+            # old child at the same index only when that old child is
+            # itself unkeyed (otherwise the keyed old child is matched
+            # separately via its key, and the unkeyed new is a fresh insert).
             old_child = old_children[new_index]
-            child_patches = diff(old_child, new_child)
-            unless child_patches.empty?
-              patches << [new_index, child_patches]
+            old_is_keyed = old_child.is_a?(VNode) && old_child.respond_to?(:key) && old_child.key
+            if old_child.nil? || old_is_keyed
+              ops << [:insert, new_index, new_child]
+              has_change = true
+            else
+              matched_old_indices[new_index] = true
+              child_patches = diff(old_child, new_child)
+              ops << [:keep, new_index, new_index, child_patches]
+              has_change = true unless child_patches.empty?
             end
           end
         end
 
-        # 4. Remove unmatched old elements
+        # 3. Collect every unmatched old child to remove, keyed or not. An old
+        #    child that no new child matched (by key, or positionally for
+        #    unkeyed ones) is gone from the new render and must be removed.
+        #    Skipping unkeyed olds here left stale nodes in the DOM, e.g. a
+        #    "Loading..." placeholder that never disappeared once the keyed
+        #    list it was replaced by arrived.
+        removes = [] #: Array[[Integer, child_t]]
         old_children.each_with_index do |old_child, old_index|
           next unless old_child.is_a?(VNode)
           next if matched_old_indices[old_index]
-
-          if old_child.respond_to?(:key) && old_child.key # Only remove keyed children
-            patches << [old_index, [[:remove, old_child]]]
-          end
+          removes << [old_index, old_child]
+          has_change = true
         end
 
-        # Sort patches: updates first, removes last (descending index)
-        patches.sort { |a, b|
-          a_is_remove = a[1].length == 1 && a[1][0][0] == :remove
-          b_is_remove = b[1].length == 1 && b[1][0][0] == :remove
-
-          if a_is_remove && b_is_remove
-            b[0] <=> a[0] # Sort remove patches by descending index
-          elsif a_is_remove
-            1 # Remove patches come after non-remove patches
-          elsif b_is_remove
-            -1 # Non-remove patches come before remove patches
-          else
-            a[0] <=> b[0] # Sort non-remove patches by ascending index
-          end
-        }
+        return [] unless has_change
+
+        [[:keyed_children, ops, removes]]
       end
 
       def self.diff_children_by_index(old_children, new_children)

data/mrblib/file_upload.rb

@@ -1,4 +1,11 @@
-require 'rng'
+# 'rng' is a PicoRuby gem available only in the wasm build. When the runtime
+# is loaded under CRuby for SSR it is absent; FileUpload is client-only and
+# its methods are never called on the server (see Funicular.server?).
+begin
+  require 'rng'
+rescue LoadError
+  # not available outside wasm environment
+end
 
 module Funicular
   module FileUpload
@@ -31,6 +38,7 @@ module Funicular
     JAVASCRIPT
 
     def self.mount
+      return if Funicular.server?
       script = JS.document.createElement("script")
       script[:textContent] = JS_HELPER_CODE
       JS.document.body.appendChild(script)

data/mrblib/form_builder.rb

@@ -6,8 +6,15 @@ module Funicular
       @component = component
       @model_key = model_key
       @options = options
-      @error_class = options[:error_class] || "text-red-600 text-sm mt-1"
-      @field_error_class = options[:field_error_class] || "border-red-500"
+      # Per-form options win, then the global Funicular.configure_forms config,
+      # then the built-in defaults. The defaults are semantic class names whose
+      # CSS the gem ships and injects via picoruby_include_tag, so error styling
+      # works without depending on the host app's CSS pipeline (e.g. Tailwind,
+      # which never scans the gem and so would not generate utility classes
+      # emitted from here).
+      config = Funicular.form_builder_config || {}
+      @error_class = options[:error_class] || config[:error_class] || "funicular-error"
+      @field_error_class = options[:field_error_class] || config[:field_error_class] || "funicular-field-error"
     end
 
     # Generic field builder for input elements
@@ -26,7 +33,10 @@ module Funicular
 
       # Check for errors
       error_message = @component.state.errors ? @component.state.errors[field_key.to_sym] : nil
-      has_error = !error_message.nil?
+      # errors may be a single message (legacy) or an array of messages
+      # (Funicular::Model::Errors#messages). Show the first.
+      error_message = error_message.first if error_message.is_a?(Array)
+      has_error = !(error_message.nil? || error_message == "")
 
       # Merge CSS classes (add error class if error exists)
       css_class = field_options[:class]
@@ -89,7 +99,10 @@ module Funicular
       end
 
       error_message = @component.state.errors ? @component.state.errors[field_key.to_sym] : nil
-      has_error = !error_message.nil?
+      # errors may be a single message (legacy) or an array of messages
+      # (Funicular::Model::Errors#messages). Show the first.
+      error_message = error_message.first if error_message.is_a?(Array)
+      has_error = !(error_message.nil? || error_message == "")
 
       css_class = options[:class]
       css_class = css_class.to_s if css_class
@@ -149,7 +162,10 @@ module Funicular
       end
 
       error_message = @component.state.errors ? @component.state.errors[field_key.to_sym] : nil
-      has_error = !error_message.nil?
+      # errors may be a single message (legacy) or an array of messages
+      # (Funicular::Model::Errors#messages). Show the first.
+      error_message = error_message.first if error_message.is_a?(Array)
+      has_error = !(error_message.nil? || error_message == "")
 
       css_class = options[:class]
       css_class = css_class.to_s if css_class

data/mrblib/funicular.rb

@@ -15,12 +15,28 @@ rescue LoadError
 end
 
 module Funicular
-  VERSION = '0.1.0'
+  # Guard against redefinition: when the mrblib runtime is loaded into a
+  # CRuby/Rails process for SSR, lib/funicular/version.rb has already defined
+  # VERSION for the CRuby gem. In the wasm build VERSION is undefined here.
+  VERSION = '0.1.0' unless Funicular.const_defined?(:VERSION)
 
   def self.version
     VERSION
   end
 
+  # True when the runtime is loaded under CRuby on the server (SSR) rather
+  # than running as PicoRuby.wasm in the browser. JS-dependent entry points
+  # become no-ops in this mode. Defaults to false (browser).
+  @server = false
+
+  def self.server?
+    @server
+  end
+
+  def self.server=(value)
+    @server = value ? true : false
+  end
+
   def self.env
     @env ||= EnvironmentInquirer.new(ENV['FUNICULAR_ENV'] || ENV['RAILS_ENV'] || 'development')
   end
@@ -44,12 +60,57 @@ module Funicular
     @router
   end
 
+  # Read the SSR state embedded by the server (funicular_state_tag) as a
+  # Ruby Hash with string keys. Returns {} when absent or on the server.
+  # Goes through JSON.stringify/parse for a reliable JS->Ruby conversion.
+  def self.window_state
+    return {} if server?
+    win = JS.global[:window]
+    # @type var win: JS::Object?
+    return {} unless win
+    raw = win[:__FUNICULAR_STATE__]
+    return {} if raw.nil?
+    json = JS.global[:JSON]
+    # @type var json: untyped
+    json_str = json.stringify(raw)
+    JSON.parse(json_str.to_s)
+  rescue => e
+    puts "[Funicular] Failed to read window state: #{e.message}"
+    {}
+  end
+
+  # True when the server embedded hydration state on the page.
+  def self.has_ssr_state?
+    return false if server?
+    win = JS.global[:window]
+    # @type var win: JS::Object?
+    return false unless win
+    !win[:__FUNICULAR_STATE__].nil?
+  rescue
+    false
+  end
+
+  # The first element child of a container, or nil. Used to find the
+  # server-rendered root for hydration.
+  def self.first_element_child(container_element)
+    child = container_element[:firstElementChild]
+    child.is_a?(JS::Element) ? child : nil
+  end
+
   # Load schemas for models
   # Usage:
   #   Funicular.load_schemas({ User => "user", Session => "session" }) do
   #     Funicular.start(container: 'app') { |router| ... }
   #   end
   def self.load_schemas(models, &block)
+    # On the server there is no fetch and no need for client-side schemas:
+    # SSR injects plain data into component state directly. Just run the
+    # block so route registration (Funicular.start) still happens.
+    if server?
+      block.call if block
+      return
+    end
+
     schemas_loaded = 0
     total_schemas = models.size
 
@@ -78,7 +139,20 @@ module Funicular
   # Usage:
   #   Funicular.start(MyComponent, container: 'app')
   #   Funicular.start(MyComponent, container: 'app', props: { name: 'John' })
-  def self.start(component_class = nil, container: 'app', props: {}, &block)
+  def self.start(component_class = nil, container: 'app', props: {}, hydrate: false, &block)
+    # On the server we only need route registration so SSR can resolve a
+    # path to a component. Skip all DOM/JS work (container lookup, popstate
+    # listener, debug export).
+    if server?
+      if block
+        router = Router.new(nil)
+        @router = router
+        block.call(router)
+        return router
+      end
+      return nil
+    end
+
     # Export debug configuration to JavaScript
     export_debug_config
 
@@ -91,23 +165,33 @@ module Funicular
       container
     end
 
-    unless container_element
+    unless container_element.is_a?(JS::Element)
       raise "Container element not found: #{container}"
     end
 
+    # Hydrate automatically when the server embedded state, unless the caller
+    # explicitly opted out.
+    hydrate = true if hydrate == false && has_ssr_state?
+
     # If block is given, use router mode
     if block
       router = Router.new(container_element)
       @router = router
       block.call(router)
-      router.start
+      router.start(hydrate: hydrate)
       return router
     end
 
     # Otherwise, mount single component (backward compatible)
     if component_class
       instance = component_class.new(props)
-      instance.mount(container_element)
+      server_root = hydrate ? first_element_child(container_element) : nil
+      if server_root
+        instance.seed_state(window_state)
+        instance.hydrate(server_root)
+      else
+        instance.mount(container_element)
+      end
       return instance
     end
 
@@ -123,11 +207,15 @@ module Funicular
     attr_accessor :form_builder_config
 
     def configure_forms
+      # Defaults are semantic class names whose CSS the gem ships and injects
+      # via picoruby_include_tag (see assets/funicular.css).
       @form_builder_config ||= {
-        error_class: "text-red-600 text-sm mt-1",
-        field_error_class: "border-red-500"
+        error_class: "funicular-error",
+        field_error_class: "funicular-field-error"
       }
-      yield @form_builder_config if block_given?
+      config = @form_builder_config
+      # @type var config: Hash[Symbol, String]
+      yield config if block_given?
     end
   end
 
@@ -149,6 +237,7 @@ module Funicular
 
   # Export debug_color to JavaScript global variable
   def self.export_debug_config
+    return if server?
     if JS.global[:window]
       JS.global[:window][:FUNICULAR_DEBUG_COLOR] = @debug_color # steep:ignore
     end