funicular 0.2.0 → 0.3.0

data/demo/tic-tac-toe.html

@@ -38,8 +38,8 @@
         on_click.call if on_click
       end
 
-      def render
-        button(class: 'square', onclick: :handle_click) do
+      def render(h)
+        h.button(class: 'square', onclick: :handle_click) do
           props[:value] || ''
         end
       end
@@ -55,7 +55,7 @@
         }
       end
 
-      def render
+      def render(h)
         squares = props[:squares]
         x_is_next = props[:x_is_next]
 
@@ -66,22 +66,22 @@
           "Next player: #{x_is_next ? 'X' : 'O'}"
         end
 
-        div do
-          div(class: 'status') { status }
-          div(class: 'board-row') do
-            component(Square, value: squares[0], on_click: handle_click(0))
-            component(Square, value: squares[1], on_click: handle_click(1))
-            component(Square, value: squares[2], on_click: handle_click(2))
+        h.div do |hh|
+          hh.div(class: 'status') { status }
+          hh.div(class: 'board-row') do |hhh|
+            hhh.component(Square, value: squares[0], on_click: handle_click(0))
+            hhh.component(Square, value: squares[1], on_click: handle_click(1))
+            hhh.component(Square, value: squares[2], on_click: handle_click(2))
           end
-          div(class: 'board-row') do
-            component(Square, value: squares[3], on_click: handle_click(3))
-            component(Square, value: squares[4], on_click: handle_click(4))
-            component(Square, value: squares[5], on_click: handle_click(5))
+          hh.div(class: 'board-row') do |hhh|
+            hhh.component(Square, value: squares[3], on_click: handle_click(3))
+            hhh.component(Square, value: squares[4], on_click: handle_click(4))
+            hhh.component(Square, value: squares[5], on_click: handle_click(5))
           end
-          div(class: 'board-row') do
-            component(Square, value: squares[6], on_click: handle_click(6))
-            component(Square, value: squares[7], on_click: handle_click(7))
-            component(Square, value: squares[8], on_click: handle_click(8))
+          hh.div(class: 'board-row') do |hhh|
+            hhh.component(Square, value: squares[6], on_click: handle_click(6))
+            hhh.component(Square, value: squares[7], on_click: handle_click(7))
+            hhh.component(Square, value: squares[8], on_click: handle_click(8))
           end
         end
       end
@@ -96,8 +96,8 @@
       end
 
       def handle_play(i)
-        history = state.history
-        current_move = state.current_move
+        history = state[:history]
+        current_move = state[:current_move]
         current_squares = history[current_move].dup
 
         current_squares[i] = (current_move % 2 == 0) ? 'X' : 'O'
@@ -115,30 +115,30 @@
         }
       end
 
-      def render
-        history = state.history
-        current_move = state.current_move
+      def render(h)
+        history = state[:history]
+        current_move = state[:current_move]
         x_is_next = (current_move % 2 == 0)
         current_squares = history[current_move]
 
-        div(class: 'game') do
-          div(class: 'game-board') do
-            component(Board,
+        h.div(class: 'game') do |hh|
+          hh.div(class: 'game-board') do |hhh|
+            hhh.component(Board,
               x_is_next: x_is_next,
               squares: current_squares,
               on_play: ->(i) { handle_play(i) }
             )
           end
-          div(class: 'game-info') do
-            ol do
+          hh.div(class: 'game-info') do |hhh|
+            hhh.ol do |hhhh|
               history.each_with_index do |_squares, move|
                 description = if move > 0
                   "Go to move ##{move}"
                 else
                   'Go to game start'
                 end
-                li(key: move) do
-                  button(onclick: jump_to(move)) { description }
+                hhhh.li(key: move) do |item|
+                  item.button(onclick: jump_to(move)) { description }
                 end
               end
             end

data/docs/architecture.md

@@ -26,34 +26,47 @@ stay free of browser-only calls on any server code path
 
 ## `mrblib/` runtime: responsibilities
 
-| File(s)                                          | Responsibility                                                            |
-|--------------------------------------------------|---------------------------------------------------------------------------|
-| `funicular.rb`                                   | Top-level module: `start`, `router`, `server?`, `debug_color` export      |
-| `component.rb`                                   | `Funicular::Component` base: state, props, lifecycle, suspense, refs, styles |
-| `vdom.rb`                                         | Virtual DOM nodes and the element-factory DSL (`div`, `button`, ...)      |
-| `differ.rb`                                       | `Differ.diff(old, new)` -- minimal patch set, key-based list reconciliation |
-| `patcher.rb`                                      | `Patcher.apply(dom, patches)` -- apply patches to the real DOM            |
-| `html_serializer.rb`                             | `VDOM::HTMLSerializer` -- VDOM to HTML string (used by SSR)               |
-| `router.rb`                                       | Client-side router, route DSL, `RouteHelpers` generation, History API     |
-| `model.rb`                                        | Object-REST Mapper (`all`/`find`/`create`/`update`/`destroy`)            |
-| `http.rb`                                         | Low-level fetch wrapper, CSRF, IndexedDB response cache                    |
-| `cable.rb`                                        | ActionCable-compatible consumer/subscription client                       |
-| `store.rb`, `store_singleton.rb`, `store_collection.rb` | IndexedDB-backed stores, scope API, `subscribes_to`, event dispatch |
-| `form_builder.rb`                                | `form_for` and field helpers with inline error rendering                  |
-| `0_validations.rb`, `1_validators.rb`            | ActiveModel-style validators and `errors`                                 |
-| `styles.rb`                                       | CSS-in-Ruby `styles` DSL and the `s` helper                              |
-| `error_boundary.rb`                              | `ErrorBoundary` component                                                 |
-| `file_upload.rb`                                 | File / FormData upload helper                                              |
-| `debug.rb`                                        | Development-only component/error registry for the DevTools extension      |
-| `environment_inquirer.rb`                        | Environment detection (`server?`, `development?`)                         |
+| File(s)                                                 | Responsibility                                                                                  |
+|---------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| `funicular.rb`                                          | Top-level module: `start`, `router`, `server?`, `debug_color` export                            |
+| `runtime.rb`                                            | Per-app runtime context propagated through render/SSR/hydration                                 |
+| `view_context.rb`                                       | Thin render facade passed as `render(h)`: elements, components, forms, routes, styles, suspense |
+| `component.rb`                                          | `Funicular::Component` base: state, props, lifecycle, suspense loading, refs                    |
+| `vdom.rb`                                               | Virtual DOM nodes, including component vnodes with ordinary `children`                          |
+| `differ.rb`                                             | `Differ.diff(old, new)` -- minimal patch set, key-based list reconciliation                     |
+| `patcher.rb`                                            | `Patcher.apply(dom, patches)` -- apply patches to the real DOM                                  |
+| `html_serializer.rb`                                    | `VDOM::HTMLSerializer` -- VDOM to HTML string (used by SSR)                                     |
+| `router.rb`                                             | Client-side router, route DSL, per-runtime route helper object, History API                     |
+| `model.rb`                                              | Object-REST Mapper (`all`/`find`/`create`/`update`/`destroy`)                                   |
+| `http.rb`                                               | Low-level fetch wrapper, CSRF, IndexedDB response cache                                         |
+| `cable.rb`                                              | ActionCable-compatible consumer/subscription client                                             |
+| `store.rb`, `store_singleton.rb`, `store_collection.rb` | IndexedDB-backed stores, scope API, `subscribes_to`, event dispatch                             |
+| `form_builder.rb`                                       | `h.form_for` field helpers with inline error rendering                                          |
+| `0_validations.rb`, `1_validators.rb`                   | ActiveModel-style validators and `errors`                                                       |
+| `styles.rb`                                             | CSS-in-Ruby `styles { |css| css.define ... }` and `h.styles[...]` access                        |
+| `error_boundary.rb`                                     | `ErrorBoundary` component                                                                       |
+| `file_upload.rb`                                        | File / FormData upload helper                                                                   |
+| `debug.rb`                                              | Development-only component/error registry for the DevTools extension                            |
+| `environment_inquirer.rb`                               | Environment detection (`server?`, `development?`)                                               |
 
 The render cycle: a state change calls `patch()`, which rebuilds the component's
-VDOM, diffs it against the previous VDOM with `Differ`, and applies the result
-with `Patcher`. Event handlers are native DOM listeners, re-bound on each render.
+VDOM by calling `render(h)`, diffs it against the previous VDOM with `Differ`,
+and applies the result with `Patcher`. Event handlers are native DOM listeners,
+re-bound on each render.
+
+Application code receives all render helpers through `h`. HTML is authored as
+`h.div`, custom elements as `h.tag(:custom_element)`, child components as
+`h.component`, forms as `h.form_for`, styles as `h.styles[:name]`, resources as
+`h.resources[:name]`, and routes as `h.routes.user_path(id)`. Component state is
+explicitly read with `state[:name]` or `state.fetch(:name)`.
+
+Component children are ordinary VDOM children stored on
+`VDOM::Component#children`; there is no delayed `children_block` prop. This keeps
+SSR, diffing, ErrorBoundary rendering, and hydration on the same data model.
 
 ## `lib/` Rails integration
 
-- `compiler.rb` -- runs the vendored `picorbc` (WebAssembly, via Node.js) to
+- `compiler.rb` -- runs the vendored `mrbc` (WebAssembly, via Node.js) to
   compile `app/funicular/**/*.rb` (models, then stores, then components, then
   initializers) into a single `app/assets/builds/app.mrb`. `-g` is added in
   development for debug symbols.
@@ -73,12 +86,12 @@ with `Patcher`. Event handlers are native DOM listeners, re-bound on each render
 ## Vendored artifacts
 
 `rake copy_wasm` (run by `rake build`) copies the PicoRuby.wasm runtime and the
-`picorbc` compiler from the sibling `mrbgems/picoruby-wasm/npm/` directory into
+`mrbc` compiler from the sibling `mrbgems/picoruby-wasm/npm/` directory into
 `lib/funicular/vendor/`:
 
 - `vendor/picoruby/dist/` -- production runtime build
 - `vendor/picoruby/debug/` -- development runtime build (debug symbols)
-- `vendor/picorbc/` -- the mruby compiler (run through Node.js)
+- `vendor/mrbc/` -- the mruby compiler (run through Node.js)
 
 Because `copy_wasm` reads sibling directories inside the picoruby repository, it
 only works from within that checkout -- see Development below.
@@ -87,11 +100,11 @@ only works from within that checkout -- see Development below.
 
 For SSR the `mrblib/` framework is loaded into the Rails process under CRuby.
 `Funicular::SSR.render(path:, state:)` resolves the path against the routes in
-`app/funicular/initializer.rb`, builds the component's VDOM, and serializes it
-with `HTMLSerializer`. The state is also embedded as `window.__FUNICULAR_STATE__`
-so the browser can hydrate the markup rather than rebuild it. Keep `render`
-deterministic and free of browser-only calls so the same code is safe on both
-sides.
+`app/funicular/initializer.rb`, builds a `Runtime` around that router, builds the
+component's VDOM, and serializes it with `HTMLSerializer`. The state is also
+embedded as `window.__FUNICULAR_STATE__` so the browser can hydrate the markup
+rather than rebuild it. Keep `render(h)` deterministic and free of browser-only
+calls so the same code is safe on both sides.
 
 ## Development
 

data/lib/funicular/compiler.rb

@@ -5,11 +5,11 @@ require "shellwords"
 module Funicular
   class Compiler
     class NodeNotFoundError < StandardError; end
-    class PicorbcMissingError < StandardError; end
+    class MrbcMissingError < StandardError; end
 
-    # picorbc.js + picorbc.wasm bundled into the gem at build time by `rake copy_wasm`.
-    PICORBC_DIR = File.expand_path("vendor/picorbc", __dir__)
-    PICORBC_JS  = File.join(PICORBC_DIR, "picorbc.js")
+    # mrbc.js + mrbc.wasm bundled into the gem at build time by `rake copy_wasm`.
+    MRBC_DIR = File.expand_path("vendor/mrbc", __dir__)
+    MRBC_JS  = File.join(MRBC_DIR, "mrbc.js")
 
     # Ordered list of application source files under app/funicular/.
     # Order matters: models -> stores -> components -> initializer, so that
@@ -36,19 +36,19 @@ module Funicular
     end
 
     def compile
-      check_picorbc_availability!
+      check_mrbc_availability!
       gather_source_files
       compile_to_mrb
     end
 
     private
 
-    def check_picorbc_availability!
-      unless File.exist?(PICORBC_JS)
-        raise PicorbcMissingError, <<~ERROR
-          Vendored picorbc not found at #{PICORBC_JS}.
+    def check_mrbc_availability!
+      unless File.exist?(MRBC_JS)
+        raise MrbcMissingError, <<~ERROR
+          Vendored mrbc not found at #{MRBC_JS}.
 
-          The funicular gem ships picorbc.js + picorbc.wasm inside the gem
+          The funicular gem ships mrbc.js + mrbc.wasm inside the gem
           package. This file is missing, which likely means the gem was not
           installed correctly. Try reinstalling:
 
@@ -61,7 +61,7 @@ module Funicular
         raise NodeNotFoundError, <<~ERROR
           Node.js executable not found.
 
-          Funicular compiles Ruby to .mrb using a WebAssembly build of picorbc
+          Funicular compiles Ruby to .mrb using a WebAssembly build of mrbc
           which is run via Node.js. Please install Node.js and ensure `node`
           is on your PATH (or set the NODE environment variable).
         ERROR
@@ -88,6 +88,8 @@ module Funicular
       end
 
       # Create a small temp file for ENV setting
+      output_dir = File.dirname(output_file)
+      FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
       env_file = "#{output_file}.env.rb"
       File.open(env_file, "w") do |f|
         f.puts "ENV['FUNICULAR_ENV'] = '#{Rails.env}'"
@@ -106,12 +108,9 @@ module Funicular
     end
 
     def compile_to_mrb
-      output_dir = File.dirname(output_file)
-      FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
-
       all_files = @source_files.dup
       all_files << @env_file if @env_file
-      argv = [node_command, PICORBC_JS]
+      argv = [node_command, MRBC_JS]
       argv << "-g" if debug_mode
       argv += ["-o", output_file.to_s]
       argv += all_files.map(&:to_s)
@@ -129,7 +128,7 @@ module Funicular
       result = system(*argv)
 
       unless result
-        raise "Failed to compile with picorbc. Command: #{Shellwords.join(argv)}"
+        raise "Failed to compile with mrbc. Command: #{Shellwords.join(argv)}"
       end
 
       log "Successfully compiled to #{output_file}"

data/lib/funicular/helpers/picoruby_helper.rb

@@ -11,6 +11,11 @@ module Funicular
         local_dist:  "/picoruby/dist/init.iife.js"
       }.freeze
 
+      LOCAL_VARIANTS = {
+        local_debug: "debug",
+        local_dist:  "dist"
+      }.freeze
+
       # Minimal CSS the gem ships for class names it emits itself (e.g.
       # FormBuilder error states). Read once; see assets/funicular.css.
       BASE_CSS_PATH = File.expand_path("../assets/funicular.css", __dir__)
@@ -101,12 +106,30 @@ module Funicular
           end
           format(CDN_URL_TEMPLATE, version: version)
         elsif (path = LOCAL_PATHS[source])
-          path
+          local_picoruby_src(path, source)
         else
           raise ArgumentError,
                 "Unknown picoruby source: #{source.inspect}. Expected one of #{Funicular::Configuration::SOURCES.inspect}"
         end
       end
+
+      def local_picoruby_src(path, source)
+        cache_key = local_picoruby_cache_key(source)
+        return path if cache_key.nil?
+
+        "#{path}?v=#{cache_key}"
+      end
+
+      def local_picoruby_cache_key(source)
+        variant = LOCAL_VARIANTS.fetch(source)
+        version = Funicular.vendored_wasm_version
+        wasm = File.join(Funicular::VENDOR_PICORUBY_DIR, variant, "picoruby.wasm")
+        mtime = File.mtime(wasm).to_i
+
+        [version || Funicular::VERSION, mtime].join("-")
+      rescue Errno::ENOENT
+        Funicular.vendored_wasm_version || Funicular::VERSION
+      end
     end
   end
 end

data/lib/funicular/ssr/runtime.rb

@@ -27,6 +27,8 @@ module Funicular
         differ
         patcher
         styles
+        runtime
+        view_context
         debug
         component
         error_boundary

data/lib/funicular/ssr.rb

@@ -30,8 +30,9 @@ module Funicular
       return { html: "", state: {}, component: nil } unless component_class
 
       instance = component_class.new(symbolize_keys(params).merge(props))
+      instance.runtime = Funicular::Runtime.new(router)
       instance.seed_state(state)
-      html = Funicular::VDOM::HTMLSerializer.serialize(instance.build_vdom)
+      html = Funicular::VDOM::HTMLSerializer.serialize(instance.build_vdom, instance.runtime)
 
       { html: html, state: state, component: component_class }
     end

data/lib/funicular/testing/node_runner.rb

@@ -117,9 +117,9 @@ module Funicular
 
       def default_runtime_dir
         ENV["FUNICULAR_TEST_PICORUBY_DIR"] ||
-          existing_path(File.join(gem_root, "lib", "funicular", "vendor", "picoruby-test-node")) ||
           existing_path(File.expand_path("../picoruby/build/picoruby-wasm-test/bin", gem_root)) ||
           existing_path(File.expand_path("../../build/picoruby-wasm-test/bin", gem_root)) ||
+          existing_path(File.join(gem_root, "lib", "funicular", "vendor", "picoruby-test-node")) ||
           File.join(gem_root, "lib", "funicular", "vendor", "picoruby-test-node")
       end
 

data/lib/funicular/vendor/mrbc/VERSION

@@ -0,0 +1 @@
+4.0.1

data/lib/funicular/vendor/{picorbc/picorbc.js → mrbc/mrbc.js}

@@ -619,7 +619,7 @@ function createExportWrapper(name, nargs) {
 var wasmBinaryFile;
 
 function findWasmBinary() {
-  return locateFile('picorbc.wasm');
+  return locateFile('mrbc.wasm');
 }
 
 function getBinarySync(file) {
@@ -5128,6 +5128,8 @@ var wasmImports = {
   /** @export */
   invoke_vi,
   /** @export */
+  invoke_vii,
+  /** @export */
   invoke_viii
 };
 
@@ -5164,6 +5166,17 @@ function invoke_viii(index,a1,a2,a3) {
   }
 }
 
+function invoke_vii(index,a1,a2) {
+  var sp = stackSave();
+  try {
+    getWasmTableEntry(index)(a1,a2);
+  } catch(e) {
+    stackRestore(sp);
+    if (e !== e+0) throw e;
+    _setThrew(1, 0);
+  }
+}
+
 function invoke_vi(index,a1) {
   var sp = stackSave();
   try {

data/lib/funicular/vendor/picoruby/VERSION

@@ -1 +1 @@
-4.0.0
+4.0.1

data/lib/funicular/vendor/picoruby/debug/init.iife.js

@@ -47,7 +47,15 @@
     Module.picorubyRun = function() {
       const MRB_TICK_UNIT = 4; // Must match the value in build_config/picoruby-wasm.rb
       const BATCH_DURATION = 16; // ~1 frame (16.67ms)
+      const IDLE_DELAY = 4;
       const MAX_CATCHUP_TICKS = 10; // Cap to avoid freeze when tab returns from background
+      const runStepStatus = Module._mrb_run_step_status || function() {
+        const result = Module._mrb_run_step();
+        return result < 0 ? -1 : 1;
+      };
+      const gcSchedulerPending = Module._mrb_gc_scheduler_pending_wasm || function() {
+        return 0;
+      };
       let lastTick = performance.now();
       function run() {
         const now = performance.now();
@@ -61,13 +69,20 @@
           lastTick = now;
         }
         const sliceStart = performance.now();
+        let progressed = false;
         while (performance.now() - sliceStart < BATCH_DURATION) {
-          const result = Module._mrb_run_step();
-          if (result < 0) {
-            console.error('mrb_run_step returned', result, '- scheduler continues');
+          const status = runStepStatus();
+          if (status < 0) {
+            console.error('mrb_run_step_status returned', status, '- scheduler continues');
+            break;
           }
+          if (status === 0) {
+            break;
+          }
+          progressed = true;
         }
-        setTimeout(run, 0);
+        const delay = progressed || gcSchedulerPending() === 1 ? 0 : IDLE_DELAY;
+        setTimeout(run, delay);
       }
       run();
     };