funicular 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa8a7ba40464c4e28ecc1b784612a9a62a8a88af985efd2508f142e03443fe9a
-  data.tar.gz: a81683de0aa13f2d91f21ccbddf6b8ed802f673567591adee4b12de6d0453d91
+  metadata.gz: 5816e8e43d54e6bec4b6bb8a06da6165ab138e549cdbad649d2acba002a5fec4
+  data.tar.gz: 51ed5ca984f12669bfd1587bf384ea685c54e2d03dff9552d3cc49485d29081f
 SHA512:
-  metadata.gz: b2809132d4fc00812c2443c2fb42e6744bbb25449beee2cb03c2b6cd2302792da21ba7d6a98ac462f7bcdc10b17af87988fa8fb38e635fa747d3bbba1e346c60
-  data.tar.gz: df0f03841a9f97ab6269f088be4b16a488430419cf7b5d196615488d098d149c6241bc08f495b477f3f539a72df13725412be09768fb90c3d96560677c9e2390
+  metadata.gz: 360c39bdc7375ae5967c37f0b24437fa6d254f8814520ae984cc455195ac957b1279988a430f752e731eb40eab62cbeba178bc1ad08dc8836c7ce64c0d0810d5
+  data.tar.gz: 31bb97a1b6fbedbf3d1b1539c3e8ea5a8169c91095733c09d38f465c463a56071ecb766524945e307b66998708e09fff0ce0f6388e009f54b9d9945169922259

data/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 ### Added
 
+- 0.4.0 bareword component DSL: `render` (zero-arity) runs with `self` as
+  the component, so HTML tags, `component`, `form_for`, `link_to`,
+  `button_to`, `suspense`, `state`, `props`, `styles`, `resources`, and
+  `routes` are all called bareword, without the 0.3.0 `h.` receiver.
+- DSL collision detection: tag and helper names are reserved inside
+  component classes. Defining one raises `Funicular::DSLCollisionError` at
+  class-definition time (`method_added`) or at first mount
+  (`validate_dsl_conflicts!`, covering `attr_*` on mruby and included
+  modules). `allow_dsl_override :name` opts out per class; the shadowed
+  element stays reachable via `tag(:name, ...)`.
+- Bareword style definitions: the class-level `styles do ... end` block
+  runs on a `BasicObject` cleanroom builder, so any name (including
+  `display`, `hash`, ...) defines a style identically on mruby and CRuby.
+  The explicit `styles { |css| css.define(...) }` form remains for
+  computed values.
+- Generated style accessors: each declared style name becomes a real
+  method on a per-component accessor, e.g. `styles.button(:disabled)`;
+  the `styles[:name, variant]` form is kept.
+
+### Breaking Changes
+
+- **0.4.0 is a breaking DSL change against 0.3.0. Components written for
+  0.3.0 migrate mechanically: delete the `render(h)` parameter, drop the
+  `h.` receivers, convert `css.define :name, "..."` to bareword
+  `name "..."`, and `h.styles[:name, variant]` to
+  `styles.name(variant)`.**
+- `p` inside a component builds a `<p>` element. Debug with
+  `puts x.inspect`; a non-Hash argument to any tag raises `ArgumentError`
+  with a hint.
+- A local variable named after a tag shadows the zero-paren call form
+  (plain Ruby scoping); write `option()` or rename the local.
+- Tag and helper names (RESERVED_DSL) can no longer be defined as
+  component methods without `allow_dsl_override`.
+- Style lookups of unknown names raise (`NoMethodError` for
+  `styles.typo`, `ArgumentError` for `styles[:typo]`) instead of
+  silently returning an empty class string. Style definition values are
+  validated (String / Hash / keyword options; unknown option keys raise).
+- Tag helpers called while the component is not rendering raise
+  `Funicular::RenderContextError` instead of being silently dropped.
+- `ErrorBoundary` `fallback:`/`error:` procs keep an explicit view
+  context (`->(h, error) { h.div { ... } }`): they are created in the
+  parent's scope but run during the boundary's render, so barewords
+  cannot work there by design.
+- `Component#render_suspense` no longer takes a view context; suspense
+  `fallback:`/`error:`/content procs run bareword in their own component
+  (`fallback: -> { div { "Loading" } }`).
+
+### Changed
+
+- Requires picoruby-wasm with `JS::Object < BasicObject` (picoruby
+  9e69333f): Kernel names (`hash`, `send`, `open`, ...) no longer shadow
+  JS property access, and unknown `?`/`!` methods on JS values raise.
+
+## [0.3.0] - 2026-07-13
+
+### Added
+
+- 0.3.0 rendering architecture: `render(h)` now receives a `ViewContext`
+  facade for elements, components, forms, styles, resources, and routes.
+- Per-app `Runtime` context for route helpers and renderer/serializer
+  propagation, enabling isolated route helper sets across multiple apps.
+
+### Breaking Changes
+
+- **0.3.0 is a deliberate breaking DSL redesign. Existing Funicular
+  components written for 0.2.x require source changes.**
+- Component render methods must now accept a view context:
+  `def render(h)`. The former implicit component-level DSL methods for HTML
+  tags, `component`, `form_for`, `link_to`, `button_to`, `suspense`, styles,
+  resources, and route helpers have been removed.
+- HTML and framework helpers are now called through `h`, for example
+  `h.div`, `h.component(...)`, `h.form_for(...)`, `h.link_to(...)`,
+  `h.suspense(...)`, `h.styles[...]`, `h.resources[...]`, and `h.routes`.
+- Component state reads are explicit: use `state[:key]`, `state.fetch(:key)`,
+  or `h.state[:key]`. The old `state.key_name` method-style access has been
+  removed.
+- Style definitions are explicit: use `styles { |css| css.define(...) }`.
+  The old dynamic style definition DSL has been removed.
+- Component children are stored as `VDOM::Component#children`. The old
+  `children_block` prop path has been removed and no compatibility shim is
+  provided.
+- Route helpers are scoped by `Funicular::Runtime`; global
+  `Funicular::RouteHelpers` injection has been removed. Code that depends on
+  route helpers should use `h.routes`.
+- `FormBuilder`, `ErrorBoundary`, SSR, hydration, renderer, patcher, and HTML
+  serialization now operate through the same `ViewContext` / `Runtime`
+  architecture.
+
+### Changed
+
+- Since mruby-compiler-prism, which used to be mruby-compiler2 producing
+  picorbc, has become the default compiler for mruby, we changed the name
+  from picorbc to mrbc.
+
+### Fixed
+
+- Harden VDOM rendering against HTML and script injection in both SSR and
+  browser rendering: validate tag and attribute names, reject `script`
+  elements, and consistently block case-obfuscated event handlers, `srcdoc`,
+  and unsafe URL schemes including control-character variants.
+
+## [0.2.1] - 2026-06-15
+
+### Added
+
+- **Funicular::Component**: Add `name` field to form to find state changed.
+
+## [0.2.0] - 2026-06-11
+
+### Added
+
 - **Funicular::Store DSL**: Declarative client-side stores backed by
   IndexedDB. Subclass `Funicular::Store::Singleton` (one value per scope)
   or `Funicular::Store::Collection` (ordered list per scope) and use

data/README.md

@@ -72,13 +72,13 @@ git clone --recurse-submodules https://github.com/picoruby/picoruby.git
 cd picoruby/mrbgems/picoruby-funicular
 ```
 
-The CRubyGem side (`lib/`, `funicular.gemspec`, etc.) can be developed and tested independently inside that directory, but `rake copy_wasm` — which vendors the PicoRuby.wasm and picorbc wasm artifacts into the gem — relies on sibling directories within the picoruby repository (`mrbgems/picoruby-wasm/npm/`).
+The CRubyGem side (`lib/`, `funicular.gemspec`, etc.) can be developed and tested independently inside that directory, but `rake copy_wasm` — which vendors the PicoRuby.wasm and mrbc wasm artifacts into the gem — relies on sibling directories within the picoruby repository (`mrbgems/picoruby-wasm/npm/`).
 Running it from a standalone checkout will fail.
 
 ## Testing
 
 - CRubygem (Rails integration) test: `rake test` in this repository
-- PicoGem Funicular test: `rake test:gems:picoruby[picoruby-funicular]` in picoruby where mrbgems/picoruby-funicular exists as a submodule
+- PicoGem Funicular test: `rake test:gems:wasm[picoruby-funicular]` in picoruby where mrbgems/picoruby-funicular exists as a submodule
 
 ## Contributing
 

data/Rakefile

@@ -9,9 +9,17 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["minitest/**/*_test.rb"]
 end
 
+namespace :test do
+  desc "Run the test suite with SimpleCov coverage measurement (report in coverage/)"
+  task :coverage do
+    ENV["COVERAGE"] = "1"
+    Rake::Task["test"].invoke
+  end
+end
+
 task default: :test
 
-desc "Copy picoruby and picorbc wasm artifacts from picoruby-wasm into the gem"
+desc "Copy picoruby and mrbc wasm artifacts from picoruby-wasm into the gem"
 task :copy_wasm do
   require "fileutils"
   require "json"
@@ -59,25 +67,25 @@ task :copy_wasm do
   puts "  wrote picoruby/VERSION (#{picoruby_version})"
 
   # ------------------------------------------------------------------
-  # 2) picorbc compiler (node CLI, run by Funicular::Compiler)
+  # 2) mrbc compiler (node CLI, run by Funicular::Compiler)
   # ------------------------------------------------------------------
-  picorbc_src  = File.join(npm_root, "picorbc", "debug")
-  picorbc_dest = File.join(vendor_root, "picorbc")
-  abort "Missing #{picorbc_src}" unless Dir.exist?(picorbc_src)
+  mrbc_src  = File.join(npm_root, "mrbc", "debug")
+  mrbc_dest = File.join(vendor_root, "mrbc")
+  abort "Missing #{mrbc_src}" unless Dir.exist?(mrbc_src)
 
-  picorbc_version = JSON.parse(File.read(File.join(npm_root, "picorbc", "package.json"))).fetch("version")
-  picorbc_files = %w[picorbc.js picorbc.wasm]
+  mrbc_version = JSON.parse(File.read(File.join(npm_root, "mrbc", "package.json"))).fetch("version")
+  mrbc_files = %w[mrbc.js mrbc.wasm]
 
-  FileUtils.rm_rf(picorbc_dest)
-  FileUtils.mkdir_p(picorbc_dest)
-  picorbc_files.each do |fname|
-    src_file = File.join(picorbc_src, fname)
+  FileUtils.rm_rf(mrbc_dest)
+  FileUtils.mkdir_p(mrbc_dest)
+  mrbc_files.each do |fname|
+    src_file = File.join(mrbc_src, fname)
     abort "Missing file: #{src_file}" unless File.exist?(src_file)
-    FileUtils.copy_file(src_file, File.join(picorbc_dest, fname))
+    FileUtils.copy_file(src_file, File.join(mrbc_dest, fname))
   end
-  File.chmod(0755, File.join(picorbc_dest, "picorbc.js"))
-  File.write(File.join(picorbc_dest, "VERSION"), "#{picorbc_version}\n")
-  puts "  copied picorbc (#{picorbc_version})"
+  File.chmod(0755, File.join(mrbc_dest, "mrbc.js"))
+  File.write(File.join(mrbc_dest, "VERSION"), "#{mrbc_version}\n")
+  puts "  copied mrbc (#{mrbc_version})"
 
   # ------------------------------------------------------------------
   # 3) PicoRuby runtime for DOM-backed Node.js tests

data/demo/test_chartjs.html

@@ -44,7 +44,7 @@
           return
         end
 
-        current_data = state.data_sets[state.month_index]
+        current_data = state[:data_sets][state[:month_index]]
 
         config = {
           type: 'line',
@@ -69,7 +69,7 @@
       end
 
       def component_updated
-        puts "component_updated: Updating Chart.js with data index #{state.month_index}"
+        puts "component_updated: Updating Chart.js with data index #{state[:month_index]}"
         update_chart
       end
 
@@ -80,22 +80,22 @@
 
       def next_data_set(event)
         event.preventDefault if event
-        new_index = (state.month_index + 1) % state.data_sets.size
-        puts "next_data_set: Changing index from #{state.month_index} to #{new_index}"
+        new_index = (state[:month_index] + 1) % state[:data_sets].size
+        puts "next_data_set: Changing index from #{state[:month_index]} to #{new_index}"
         patch(month_index: new_index)
       end
 
       def prev_data_set(event)
         event.preventDefault if event
-        new_index = (state.month_index - 1) % state.data_sets.size
-        puts "prev_data_set: Changing index from #{state.month_index} to #{new_index}"
+        new_index = (state[:month_index] - 1) % state[:data_sets].size
+        puts "prev_data_set: Changing index from #{state[:month_index]} to #{new_index}"
         patch(month_index: new_index)
       end
 
       def update_chart
         return unless @chart
 
-        current_data = state.data_sets[state.month_index]
+        current_data = state[:data_sets][state[:month_index]]
         puts "update_chart: Setting data to #{current_data[:labels].join(', ')}"
 
         # Convert to JS objects
@@ -129,7 +129,7 @@
             button(id: "next-btn", onclick: :next_data_set) { "Next Quarter" }
           end
           div(id: "info") do
-            current = state.data_sets[state.month_index]
+            current = state[:data_sets][state[:month_index]]
             "Current data: #{current[:labels].join(', ')}"
           end
         end

data/demo/test_component.html

@@ -40,26 +40,26 @@
 
       def increment(event)
         event.preventDefault if event
-        patch(count: state.count + 1)
+        patch(count: state[:count] + 1)
       end
 
       def decrement(event)
         event.preventDefault if event
-        patch(count: state.count - 1)
+        patch(count: state[:count] - 1)
       end
 
       def render
         div(id: "counter-app") do
-          h2 { "Counter: #{state.count}" }
+          h2 { "Counter: #{state[:count]}" }
           div(id: "status") do
-            "Mounted: #{state.mounted}"
+            "Mounted: #{state[:mounted]}"
           end
           div do
             button(id: "increment-btn", onclick: :increment) { "+1" }
             button(id: "decrement-btn", onclick: :decrement) { "-1" }
           end
           div(ref: :display, id: "display") do
-            "Current value: #{state.count}"
+            "Current value: #{state[:count]}"
           end
         end
       end
@@ -89,7 +89,7 @@
       # Test 2: Initial state
       begin
         counter = TestCounter.new
-        initial_state = counter.state.count == 0
+        initial_state = counter.state[:count] == 0
         log_test("Initial state", initial_state)
       rescue => e
         log_test("Initial state", false)
@@ -139,13 +139,13 @@
         has_button = btn != nil
 
         # Test handler logic by calling it directly (standard testing approach)
-        initial_count = counter.state.count
+        initial_count = counter.state[:count]
         counter.increment(nil)
         sleep 0.05
 
         h2_element = JS.document.querySelector('#counter-app h2')
         text = h2_element.textContent.to_s
-        handler_works = counter.state.count == initial_count + 1 && text.include?("#{initial_count + 1}")
+        handler_works = counter.state[:count] == initial_count + 1 && text.include?("#{initial_count + 1}")
 
         log_test("Event handler (click)", has_button && handler_works)
       rescue => e

data/demo/test_error_boundary.html

@@ -125,11 +125,14 @@
           puts "  Component: #{info&.dig(:component_class)}"
         }
 
-        custom_fallback = ->(error) {
-          div(style: 'background: linear-gradient(135deg, #ff6b6b, #ee5a5a); color: white; padding: 20px; border-radius: 8px;') do
-            h3(style: 'margin-top: 0;') { "Custom Error Handler" }
-            p { "Caught: #{error.message}" }
-            p(style: 'font-size: 12px; opacity: 0.8;') { "This is a custom fallback provided via props." }
+        # NOTE: an ErrorBoundary fallback runs during the BOUNDARY's render,
+        # not this component's, so it cannot use bareword tags. It receives
+        # the boundary's view context and builds elements through it.
+        custom_fallback = ->(h, error) {
+          h.div(style: 'background: linear-gradient(135deg, #ff6b6b, #ee5a5a); color: white; padding: 20px; border-radius: 8px;') do
+            h.h3(style: 'margin-top: 0;') { "Custom Error Handler" }
+            h.p { "Caught: #{error.message}" }
+            h.p(style: 'font-size: 12px; opacity: 0.8;') { "This is a custom fallback provided via props." }
           end
         }
 

data/demo/test_router.html

@@ -71,7 +71,7 @@
             input(
               type: 'text',
               placeholder: 'Username',
-              value: state.username,
+              value: state[:username],
               oninput: :on_username_input
             )
           end
@@ -81,7 +81,7 @@
           end
 
           div(class: 'status') do
-            "Username: #{state.username}"
+            "Username: #{state[:username]}"
           end
         end
       end
@@ -94,7 +94,7 @@
 
       def increment(event)
         event.preventDefault
-        patch(count: state.count + 1)
+        patch(count: state[:count] + 1)
       end
 
       def go_to_settings(event)
@@ -107,7 +107,7 @@
           h2(class: 'page-title') { 'Home Page' }
 
           div do
-            "Counter: #{state.count}"
+            "Counter: #{state[:count]}"
           end
 
           div do
@@ -129,13 +129,13 @@
 
       def toggle_theme(event)
         event.preventDefault
-        new_theme = state.theme == 'light' ? 'dark' : 'light'
+        new_theme = state[:theme] == 'light' ? 'dark' : 'light'
         patch(theme: new_theme)
       end
 
       def toggle_notifications(event)
         event.preventDefault
-        patch(notifications: !state.notifications)
+        patch(notifications: !state[:notifications])
       end
 
       def go_to_home(event)
@@ -148,12 +148,12 @@
           h2(class: 'page-title') { 'Settings Page' }
 
           div do
-            span { "Theme: #{state.theme}" }
+            span { "Theme: #{state[:theme]}" }
             button(onclick: :toggle_theme) { 'Toggle Theme' }
           end
 
           div do
-            span { "Notifications: #{state.notifications ? 'ON' : 'OFF'}" }
+            span { "Notifications: #{state[:notifications] ? 'ON' : 'OFF'}" }
             button(onclick: :toggle_notifications) { 'Toggle Notifications' }
           end
 
@@ -190,7 +190,7 @@
           h2(class: 'page-title') { 'Users List' }
 
           ul do
-            state.users.each do |user|
+            state[:users].each do |user|
               li do
                 a(href: "/users/#{user[:id]}", onclick: go_to_user(user[:id])) do
                   user[:name]
@@ -221,7 +221,7 @@
           h2(class: 'page-title') { "User Detail" }
 
           div do
-            "Viewing user ID: #{state.user_id}"
+            "Viewing user ID: #{state[:user_id]}"
           end
 
           div do
@@ -229,7 +229,7 @@
           end
 
           div(class: 'status') do
-            "This page demonstrates dynamic routing with params[:id] = #{state.user_id}"
+            "This page demonstrates dynamic routing with params[:id] = #{state[:user_id]}"
           end
         end
       end

data/demo/tic-tac-toe.html

@@ -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'
@@ -116,8 +116,8 @@
       end
 
       def render
-        history = state.history
-        current_move = state.current_move
+        history = state[:history]
+        current_move = state[:current_move]
         x_is_next = (current_move % 2 == 0)
         current_squares = history[current_move]
 

data/docs/architecture.md

@@ -26,34 +26,67 @@ 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                                 |
+| `0_tags.rb`                                             | Bareword tag DSL mixed into `Component`; reserved-name list and collision errors                |
+| `view_context.rb`                                       | Internal element factory shared by the tag DSL, FormBuilder, and framework helpers              |
+| `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`                                       | `form_for` field helpers with inline error rendering                                            |
+| `0_validations.rb`, `1_validators.rb`                   | ActiveModel-style validators and `errors`                                                       |
+| `styles.rb`                                             | CSS-in-Ruby bareword `styles do ... end` builder and generated `styles.name` accessors          |
+| `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`, 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.
+
+Inside `render` (zero-arity as of 0.4.0), `self` is the component, so the
+DSL is bareword: HTML is authored as `div`, custom elements as
+`tag(:custom_element)`, child components as `component`, forms as `form_for`,
+styles as `styles.name(variant)` or `styles[:name]`, resources as
+`resources[:name]`, and routes as `routes.user_path(id)`. Component state is
+explicitly read with `state[:name]` or `state.fetch(:name)`.
+
+Tag and helper names (~46 words) are reserved inside component classes:
+defining one raises `DSLCollisionError` at class-definition time
+(`method_added`) or at first mount (`validate_dsl_conflicts!`, which also
+covers `attr_*` on mruby and included modules). `allow_dsl_override :name`
+opts out per class; the shadowed element stays reachable via `tag(:name)`.
+Two caveats are inherent to barewords: `p` builds a `<p>` element (use
+`puts x.inspect` for debugging; non-Hash arguments raise with a hint), and
+a local variable named after a tag shadows the zero-paren call form (write
+`option()` or rename the local). Procs handed to ANOTHER component --
+ErrorBoundary's `fallback:` -- run under that component's cursor and
+therefore receive an explicit view context instead of barewords.
+
+Style definitions are bareword too: the class-level `styles do ... end`
+block runs on a BasicObject cleanroom builder, so any name (including
+`display`, `hash`, ...) defines a style identically on mruby and CRuby.
+Computed values need the explicit form `styles { |css| css.define(...) }`.
+Unknown style lookups raise instead of returning an empty class string.
+
+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,25 +106,42 @@ 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.
 
+## JavaScript interop contract
+
+As of picoruby commit 9e69333f, `JS::Object` inherits `BasicObject` instead of
+`Object`. Consequences for framework code:
+
+- Dot access on JS values is reliable for names Kernel used to shadow
+  (`hash`, `send`, `open`, `class`, `method`, ...): they now reach the JS side
+  via `method_missing`.
+- The Ruby protocol predicates `nil?`, `is_a?`, `kind_of?`, `instance_of?`, and
+  `respond_to?` are defined in C on `JS::Object` (a `?` suffix is illegal in a
+  JS identifier, so they can never shadow a JS property). `respond_to?` does a
+  real method-table lookup only; it does not report JS properties.
+- Any other name ending in `?` or `!` raises `NoMethodError` instead of being
+  forwarded to JS, so typos fail loudly rather than silently returning nil.
+- `==`, `to_s`, `inspect`, `[]`, `[]=`, `to_a`, and `typeof` are defined
+  directly on `JS::Object` and behave as before.
+
 ## Server-side rendering, briefly
 
 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` deterministic and free of browser-only
+calls so the same code is safe on both sides.
 
 ## Development