funicular 0.5.0 → 0.5.2

data/lib/funicular/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
-module Funicular
-  VERSION = "0.5.0"
-end
+# The version is defined once in mrblib/version.rb so that the same value
+# is compiled into PicoRuby.wasm. This file only exists to keep the
+# conventional `require "funicular/version"` entry point working.
+require_relative "../../mrblib/version"

data/lib/tasks/funicular.rake

@@ -54,8 +54,8 @@ namespace :funicular do
     end
   end
 
-  desc "Install Funicular debug assets, PicoRuby.wasm artifacts, and test support into a Rails app"
-  task install: ["install:debug_assets", "install:wasm", "install:test"] do
+  desc "Install Funicular debug assets, the gem initializer, PicoRuby.wasm artifacts, and test support into a Rails app"
+  task install: ["install:debug_assets", "install:initializer", "install:wasm", "install:test"] do
     puts ""
     puts "All Funicular assets installed."
     puts ""
@@ -79,32 +79,39 @@ namespace :funicular do
   end
 
   namespace :install do
-    desc "Install Funicular debug JS/CSS assets and the gem initializer"
+    desc "Install Funicular debug JS/CSS assets"
     task :debug_assets do
       require "fileutils"
 
-      javascripts_dir  = Rails.root.join("app", "assets", "javascripts")
-      stylesheets_dir  = Rails.root.join("app", "assets", "stylesheets")
-      initializers_dir = Rails.root.join("config", "initializers")
+      javascripts_dir = Rails.root.join("app", "assets", "javascripts")
+      stylesheets_dir = Rails.root.join("app", "assets", "stylesheets")
 
       FileUtils.mkdir_p(javascripts_dir)
       FileUtils.mkdir_p(stylesheets_dir)
-      FileUtils.mkdir_p(initializers_dir)
 
-      source_js          = File.expand_path("../funicular/assets/funicular_debug.js", __dir__)
-      source_css         = File.expand_path("../funicular/assets/funicular_debug.css", __dir__)
-      source_initializer = File.expand_path("../funicular/assets/funicular.rb", __dir__)
+      source_js  = File.expand_path("../funicular/assets/funicular_debug.js", __dir__)
+      source_css = File.expand_path("../funicular/assets/funicular_debug.css", __dir__)
 
-      dest_js          = javascripts_dir.join("funicular_debug.js")
-      dest_css         = stylesheets_dir.join("funicular_debug.css")
-      dest_initializer = initializers_dir.join("funicular.rb")
+      dest_js  = javascripts_dir.join("funicular_debug.js")
+      dest_css = stylesheets_dir.join("funicular_debug.css")
 
-      FileUtils.cp(source_js,          dest_js)
-      FileUtils.cp(source_css,         dest_css)
+      FileUtils.cp(source_js,  dest_js)
+      FileUtils.cp(source_css, dest_css)
 
       puts "Installed Funicular debug assets:"
       puts "  - #{dest_js}"
       puts "  - #{dest_css}"
+    end
+
+    desc "Install the gem initializer (config/initializers/funicular.rb)"
+    task :initializer do
+      require "fileutils"
+
+      initializers_dir = Rails.root.join("config", "initializers")
+      FileUtils.mkdir_p(initializers_dir)
+
+      source_initializer = File.expand_path("../funicular/assets/funicular.rb", __dir__)
+      dest_initializer   = initializers_dir.join("funicular.rb")
 
       # The initializer belongs to the application once it exists:
       # re-running the installer must never clobber its configuration
@@ -113,6 +120,7 @@ namespace :funicular do
         puts "Skipped #{dest_initializer} (exists; delete it first to reinstall the template)"
       else
         FileUtils.cp(source_initializer, dest_initializer)
+        puts "Installed Funicular initializer:"
         puts "  - #{dest_initializer}"
       end
     end

data/minitest/ssr_test.rb

@@ -32,6 +32,22 @@ class SSRTest < Minitest::Test
                  serialize(el("p", {}, ["a & b <c>"]))
   end
 
+  def test_marks_empty_slots_and_seams_between_texts
+    assert_equal "<div><!----><b></b>a<!---->b<i></i>c</div>",
+                 serialize(el("div", {}, [nil, el("b"), "a", "b", el("i"), "c"]))
+  end
+
+  def test_raw_text_elements_are_not_marked
+    assert_equal "<textarea>ab</textarea>", serialize(el("textarea", {}, [nil, "a", "b"]))
+  end
+
+  def test_doubles_the_leading_newline_the_parser_strips
+    assert_equal "<pre>\n\nfoo</pre>", serialize(el("pre", {}, ["\nfoo"]))
+    assert_equal "<textarea>\n\nfoo</textarea>", serialize(el("textarea", {}, ["\nfoo"]))
+    assert_equal "<pre>foo\n</pre>", serialize(el("pre", {}, ["foo\n"]))
+    assert_equal "<div>\nfoo</div>", serialize(el("div", {}, ["\nfoo"]))
+  end
+
   def test_escapes_attribute_values
     assert_equal '<div title="&quot;hi&quot;"></div>',
                  serialize(el("div", { title: '"hi"' }))

data/mrblib/component.rb

@@ -418,6 +418,14 @@ module Funicular
       @suspense_definitions ||= {}
     end
 
+    # True while patch is re-rendering this component. Callers that would
+    # re-enter patch from inside that render (for example a child page that
+    # navigates in component_mounted) must take another path, because patch
+    # ignores nested calls.
+    def updating?
+      @updating
+    end
+
     # Update state and trigger re-render
     def patch(new_state)
       return unless @mounted
@@ -709,8 +717,8 @@ module Funicular
       end
 
       # Recursively bind events for children
-      if vnode.children && dom_element.children
-        children = dom_element.children.to_a
+      if vnode.children
+        children = VDOM.child_nodes(dom_element)
         vnode.children.each_with_index do |child_vnode, index|
           if child_vnode.is_a?(VDOM::Element)
             child_element = children[index]
@@ -748,8 +756,8 @@ module Funicular
         refs_map[ref_name] = dom_element
       end
 
-      if vnode.children && dom_element.children
-        children = dom_element.children.to_a
+      if vnode.children
+        children = VDOM.child_nodes(dom_element)
         vnode.children.each_with_index do |child_vnode, index|
           if child_vnode.is_a?(VDOM::Element)
             child_element = children[index]
@@ -810,6 +818,20 @@ module Funicular
       __view__.component(component_class, props, &block)
     end
 
+    def outlet
+      router = @runtime&.router
+      depth = router&.current_layouts&.index(self.class)
+      return unless router && depth
+
+      nested = router.current_layouts[depth + 1]
+      return component(nested, preserve: true, __route__: router.current_path) if nested
+
+      route = router.current_route
+      return unless route
+
+      component(route[0], route[1])
+    end
+
     def form_for(model_key, options = {}, &block)
       build_form_for(__view__, model_key, options, &block)
     end
@@ -1024,9 +1046,22 @@ module Funicular
       return unless vnode.is_a?(VDOM::Element)
       return unless dom_element
 
-      dom_children = dom_element.children.to_a
+      dom_children = VDOM.child_nodes(dom_element)
+      skipped = 0
+      previous_text = false
       vnode.children.each_with_index do |child, index|
-        child_dom = dom_children[index]
+        text = VDOM.text(child)
+        child_dom = dom_children[index + skipped]
+        if text && child_dom && child_dom[:nodeType] == 8
+          if text.empty?
+            dom_element.replaceChild(dom_element[:ownerDocument].createTextNode(''), child_dom)
+          elsif previous_text
+            dom_element.removeChild(child_dom)
+            skipped += 1
+            child_dom = dom_children[index + skipped]
+          end
+        end
+        previous_text = !text.to_s.empty?
         next unless child_dom
 
         if child.is_a?(VDOM::Component)

data/mrblib/debug.rb

@@ -136,11 +136,7 @@ module Funicular
         state = component.instance_variable_get(:@state) || {}
         result = {} #: Hash[String, String]
         state.each do |key, value|
-          begin
-            result[key.to_s] = value.inspect
-          rescue
-            result[key.to_s] = "<error inspecting value>"
-          end
+          result[key.to_s] = safe_inspect(value)
         end
         JSON.generate(result)
       end
@@ -159,11 +155,7 @@ module Funicular
             result[name] = "<omitted>"
             next
           end
-          begin
-            result[name] = component.instance_variable_get(var).inspect
-          rescue
-            result[name] = "<error inspecting value>"
-          end
+          result[name] = safe_inspect(component.instance_variable_get(var))
         end
         JSON.generate(result)
       end
@@ -176,6 +168,58 @@ module Funicular
 
       private
 
+      # Bounded inspect for the DevTools inspector. A plain Object#inspect
+      # walks the whole object graph: a component's @runtime reaches the
+      # router, the mounted component and its entire VDOM tree, and that
+      # recursion overflows the wasm C stack in a -O0 build. Without a
+      # guard page the overflow silently overwrites the heap below the
+      # stack, which surfaces later as garbage registers and GC crashes.
+      # Only leaves are inspected in full; containers and objects are
+      # summarized past INSPECT_MAX_DEPTH.
+      INSPECT_MAX_DEPTH = 3
+      INSPECT_MAX_ITEMS = 25
+
+      def safe_inspect(value, depth = 0)
+        case value
+        when nil, true, false, Integer, Float, Symbol, String
+          value.inspect
+        when Array
+          return "[...#{value.size} items]" if depth >= INSPECT_MAX_DEPTH
+          items = value.first(INSPECT_MAX_ITEMS).map { |v| safe_inspect(v, depth + 1) }
+          items << "...#{value.size - INSPECT_MAX_ITEMS} more" if value.size > INSPECT_MAX_ITEMS
+          "[#{items.join(', ')}]"
+        when Hash
+          return "{...#{value.size} pairs}" if depth >= INSPECT_MAX_DEPTH
+          pairs = [] #: Array[String]
+          value.each do |k, v|
+            break if pairs.size >= INSPECT_MAX_ITEMS
+            pairs << "#{safe_inspect(k, depth + 1)} => #{safe_inspect(v, depth + 1)}"
+          end
+          pairs << "...#{value.size - INSPECT_MAX_ITEMS} more" if value.size > INSPECT_MAX_ITEMS
+          "{#{pairs.join(', ')}}"
+        else
+          safe_inspect_object(value, depth)
+        end
+      rescue => e
+        "<#{e.class}: #{e.message}>"
+      end
+
+      def safe_inspect_object(value, depth)
+        # JS::Object#inspect is a shallow C implementation; other BasicObject
+        # proxies (style accessors) raise from method_missing on any name.
+        return value.inspect if defined?(::JS::Object) && ::JS::Object === value
+        return "#<BasicObject>" unless ::Object === value
+        klass = value.class.to_s
+        return "#<#{klass}>" if depth >= INSPECT_MAX_DEPTH
+        ivars = value.instance_variables
+        return value.inspect if ivars.empty?
+        parts = ivars.first(INSPECT_MAX_ITEMS).map do |iv|
+          "#{iv}=#{safe_inspect(value.instance_variable_get(iv), depth + 1)}"
+        end
+        parts << "...#{ivars.size - INSPECT_MAX_ITEMS} more" if ivars.size > INSPECT_MAX_ITEMS
+        "#<#{klass} #{parts.join(', ')}>"
+      end
+
       def get_state_keys(component)
         state = component.instance_variable_get(:@state)
         return [] unless state.is_a?(Hash)

data/mrblib/differ.rb

@@ -29,6 +29,8 @@ module Funicular
         else
           if old_node == new_node
             []
+          elsif old_node.is_a?(String) && new_node.is_a?(String)
+            [[:text, new_node]]
           else
             [[:replace, new_node, old_node]]
           end
@@ -38,11 +40,7 @@ module Funicular
       private
 
       def self.diff_text(old_node, new_node)
-        if old_node.content != new_node.content
-          [[:replace, new_node, old_node]]
-        else
-          []
-        end
+        old_node.content == new_node.content ? [] : [[:text, new_node.content]]
       end
 
       def self.diff_element(old_node, new_node)
@@ -103,8 +101,8 @@ module Funicular
       # 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
+      #   2. content updates for kept children (against the snapshot)
+      #   3. kept-node moves and inserts in new-index order on the live DOM
       def self.diff_children_with_keys(old_children, new_children)
         # 1. Build key map from old children
         old_key_map = {} #: Hash[untyped, [Integer, child_t]]
@@ -127,7 +125,7 @@ module Funicular
               matched_old_indices[old_index] = true
               child_patches = diff(old_child, new_child)
               ops << [:keep, old_index, new_index, child_patches]
-              has_change = true unless child_patches.empty?
+              has_change = true if old_index != new_index || !child_patches.empty?
             else
               ops << [:insert, new_index, new_child]
               has_change = true
@@ -156,10 +154,12 @@ module Funicular
         #    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.
+        #    list it was replaced by arrived. Raw String children are text
+        #    nodes in the DOM (normalize_children keeps them as Strings), so
+        #    they must be collected here as well. normalize_children never
+        #    leaves nil in the list, so every entry is a real DOM node.
         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]
           removes << [old_index, old_child]
           has_change = true

data/mrblib/funicular.rb

@@ -15,11 +15,8 @@ rescue LoadError
 end
 
 module Funicular
-  # 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.5.0' unless Funicular.const_defined?(:VERSION)
-
+  # VERSION is defined in mrblib/version.rb, which is compiled into the wasm
+  # build alongside this file and loaded by lib/funicular/version.rb on CRuby.
   def self.version
     VERSION
   end

data/mrblib/html_serializer.rb

@@ -18,6 +18,13 @@ module Funicular
       # Props that must never be emitted as HTML attributes.
       SKIP_PROPS = %i[ref key]
 
+      RAW_TEXT_ELEMENTS = %w[textarea title style]
+
+      # The HTML parser drops one newline right after the start tag of these
+      # elements. Emit an extra newline so the text node the client VDOM
+      # expects survives parsing with its content intact.
+      NEWLINE_STRIPPING_ELEMENTS = %w[pre textarea listing]
+
       def self.serialize(vnode, runtime = nil)
         new(runtime).render(vnode)
       end
@@ -50,27 +57,33 @@ module Funicular
         tag = element.tag
         attrs = serialize_props(element.props)
 
-        if VOID_ELEMENTS.include?(tag.downcase)
+        lower = tag.downcase
+        if VOID_ELEMENTS.include?(lower)
           "<#{tag}#{attrs}>"
         else
-          "<#{tag}#{attrs}>#{render_children(element.children)}</#{tag}>"
+          inner = render_children(element.children, !RAW_TEXT_ELEMENTS.include?(lower))
+          inner = "\n#{inner}" if NEWLINE_STRIPPING_ELEMENTS.include?(lower) && inner.start_with?("\n")
+          "<#{tag}#{attrs}>#{inner}</#{tag}>"
         end
       end
 
-      def render_children(children)
-        parts = [] #: Array[String]
-        children.each do |child|
-          if child.is_a?(VNode)
-            parts << render(child)
-          elsif child.is_a?(String)
-            parts << escape_html(child)
-          elsif child.is_a?(Array)
-            parts << render_children(child)
-          elsif !child.nil?
-            parts << escape_html(child.to_s)
+      # Element#children is flattened by normalize_children, so nested arrays
+      # need no handling here.
+      def render_children(children, marks)
+        previous_text = false
+        children.map do |child|
+          text = VDOM.text(child)
+          html = if text
+            escape_html(text)
+          elsif child.is_a?(VNode)
+            render(child)
+          else
+            ''
           end
-        end
-        parts.join
+          html = "<!---->#{html}" if marks && text && (text.empty? || previous_text)
+          previous_text = !text.to_s.empty?
+          html
+        end.join
       end
 
       def render_text(text)

data/mrblib/patcher.rb

@@ -24,6 +24,8 @@ module Funicular
             # Props patches only make sense for Element nodes (text nodes have
             # no attributes); narrow before delegating.
             update_props(element, patch[1]) if element.is_a?(JS::Element)
+          when :text
+            element[:nodeValue] = patch[1].to_s
           when :update_and_rebind
             instance, internal_patches, new_vdom = patch[1], patch[2], patch[3]
             old_dom_element = instance.dom_element
@@ -31,9 +33,13 @@ module Funicular
             # Apply internal patches and get the potentially new root element
             new_dom_element = Patcher.new(@doc, instance.runtime).apply(old_dom_element, internal_patches)
 
-            # Update the instance's reference to its root DOM element if it changed
+            # Update the instance's reference to its root DOM element if it
+            # changed. The new root must also become this apply's return
+            # value; otherwise a caller that stores the result (for example
+            # the keyed_children snapshot) keeps pointing at a detached node.
             if new_dom_element != old_dom_element && new_dom_element.is_a?(JS::Element)
               instance.dom_element = new_dom_element
+              result = new_dom_element
             end
 
             # Update the instance's VDOM to the new one AFTER applying patches
@@ -65,18 +71,23 @@ module Funicular
             #   1. snapshot DOM children, then remove unmatched keyed old
             #      children (descending old_index so the snapshot indices
             #      remain valid as removes happen).
-            #   2. apply content updates to kept children in place. The
+            #   2. apply content updates to kept children. The
             #      lookup is by snapshot[old_index], so updates are stable
-            #      regardless of subsequent insertions.
-            #   3. insert new children at their new_index using
-            #      insertBefore on the live DOM. Processed in ascending
-            #      new_index order so each insertion fixes its own
-            #      position before later inserts run.
+            #      regardless of removals.
+            #   3. place kept and new children at their new_index using
+            #      insertBefore on the live DOM. Ops are already in ascending
+            #      new_index order, so each placement fixes the next position.
+            #
+            # Phase 3 tracks the live child order in a Ruby array instead of
+            # re-reading childNodes per op. Every childNodes.to_a allocates a
+            # fresh JS::Object wrapper per node, so wrappers of the same DOM
+            # node never compare equal and the read itself is O(n) across the
+            # wasm boundary. Identity is therefore decided with equal? on the
+            # snapshot objects, which is both exact and free.
             ops = patch[1]
             removes = patch[2]
 
-            child_nodes = element[:childNodes]
-            snapshot = child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[untyped]
+            snapshot = VDOM.child_nodes(element)
 
             # Phase 1: removes (descending old_index)
             sorted_removes = removes.sort { |a, b| b[0] <=> a[0] }
@@ -88,9 +99,10 @@ module Funicular
               unmount_component(old_vnode)
               parent_el = target.parentElement
               parent_el.removeChild(target) if parent_el
+              snapshot[old_index] = nil
             end
 
-            # Phase 2: updates against the snapshot (no movement)
+            # Phase 2: updates against the snapshot
             ops.each do |op|
               next unless op[0] == :keep
               old_index = op[1]
@@ -98,31 +110,45 @@ module Funicular
               next if child_patches.empty?
               target = snapshot[old_index]
               next if target.nil?
-              apply(target, child_patches)
+              snapshot[old_index] = apply(target, child_patches)
             end
 
-            # Phase 3: inserts in ascending new_index order
+            # Phase 3: moves and inserts in ascending new_index order.
+            # `live` mirrors the DOM child order after phases 1 and 2 and is
+            # updated alongside every DOM mutation, so a node already sitting
+            # at new_index is left untouched (no detach/re-attach).
+            live = snapshot.compact #: Array[untyped]
             ops.each do |op|
-              next unless op[0] == :insert
-              new_index = op[1]
-              new_vnode = op[2]
-              new_node = create_element(new_vnode)
+              case op[0]
+              when :keep
+                new_node = snapshot[op[1]]
+                new_index = op[2]
+              when :insert
+                new_index = op[1]
+                new_node = create_element(op[2])
+              else
+                next
+              end
               next if new_node.nil?
-              live_nodes = element[:childNodes]
-              live_arr = live_nodes.is_a?(JS::Object) ? live_nodes.to_a : [] #: Array[untyped]
-              ref = live_arr[new_index]
-              if ref.nil?
-                element.appendChild(new_node) if element.is_a?(JS::Element)
+              current = live[new_index]
+              next if current.equal?(new_node)
+              live.delete_if { |n| n.equal?(new_node) }
+              if new_index < live.length
+                live.insert(new_index, new_node)
+              else
+                live << new_node
+              end
+              next unless element.is_a?(JS::Element)
+              if current.nil?
+                element.appendChild(new_node)
               else
-                element.insertBefore(new_node, ref) if element.is_a?(JS::Element)
+                element.insertBefore(new_node, current)
               end
             end
           when Integer
             child_index = patch[0]
             child_patches = patch[1]
-            # Use childNodes instead of children to include text nodes
-            child_nodes = element[:childNodes]
-            children = child_nodes.is_a?(JS::Object) ? child_nodes.to_a : [] #: Array[JS::Object]
+            children = VDOM.child_nodes(element)
             child_element = children[child_index]
             if child_element.nil?
               # No existing child at this index - we need to create new elements
@@ -140,7 +166,7 @@ module Funicular
               end
             elsif child_element.is_a?(JS::Object)
               # Recurse into the child node. apply handles both Element and
-              # text Node cases (the latter only meaningfully via :replace).
+              # text Node cases (the latter via :text or :replace).
               apply(child_element, child_patches)
             end
           end