funicular 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c20fca7e6590276dff1b8d10dcec31cc33a7c89070f2d515b28a39123358a7bb
-  data.tar.gz: f96247a21b413702c3e999a0588b4366e7cb356535eca53d472ca36abd331c62
+  metadata.gz: 42012485f28870d0316fa30ba1fbebd4699c07cb8e61e5d201874d2eafd50d04
+  data.tar.gz: ab7f7e473a32d0a00b8bca5b0c67fc7e7b91a9a7860724e53631ea7d08dbcc41
 SHA512:
-  metadata.gz: f592cbc26f7266a421846e0cb7f9445dcbc34458025d33d3da0ba140a5c3a3b5ee1c7b646ae56d7d5097162ed587ec92bcb402cc5da113d905deaae8bdb18a6c
-  data.tar.gz: 9967e115be234ee8c29e3a605192a398cef6f6de7413d833beaf08b23829752f049e9ced1590761a8b7b1f1cbaccc515efdc9ec5ff0fa431879c83e06c37c88f
+  metadata.gz: 5488c967e48dd01768dc05acba5a350e07fb2fb5fc9ede01f5e06dd1274c1c4ee1fd7f0f4e76a2c616b74b8eff10260f5a14108d83798a34e25c3f785c4be7c7
+  data.tar.gz: 653010659b471071850c77dd459ff17984b906485cfcc9b396c3ecf1558686c353ca2ec65cc3940dad4497c79318515b833ff4219f7f9e301e93a041abbfbb30

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [Unreleased]
+
+### 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
+  class-level DSL (`database`, `scope`, `limit`, `key`, `expires_in`,
+  `cleared_on`, `subscribes_to`) to wire up persistence, TTL, event-based
+  clearing, and ActionCable integration.
+- `Funicular::Store.dispatch(:event)` for coordinated store clearing
+  (e.g., logout wipes all stores registered with `cleared_on :logout`)
+- `subscribes_to` DSL for embedding Cable message handling directly in
+  store classes; scopes gain `subscribe!` / `unsubscribe!` / `subscribed?`
+- Lazy KVS initialization: stores open IndexedDB on first access, removing
+  the need for explicit `init!` calls in application initializers
+- `Funicular::Store::Scope#on_change` / `off_change` for reactive UI
+  updates when store data changes
+
+### Changed
+
+- `Funicular::Cable::Consumer` now automatically resubscribes all active
+  subscriptions after WebSocket reconnect (`resubscribe_all`)
+
 ## [0.1.0] - 2026-04-20
 
 ### Added

data/README.md

@@ -55,9 +55,12 @@ The others are common resources.
 
 ## Documentation
 
-You may want to see Tic-Tac-Toe tutorial first: [https://picoruby.org/funicular](https://picoruby.org/funicular)
+User documentation is hosted on **picoruby.org**:
 
-Then, dig [docs/](docs/).
+- [Getting Started with Funicular](https://picoruby.org/funicular-getting-started) — a standalone, no-Rails tutorial
+- [Funicular on Rails](https://picoruby.org/funicular-on-rails) — installation, the asset pipeline, and a feature-by-feature tutorial plus reference (components, routing, forms, data fetching, stores, realtime, SSR, styling, debugging)
+
+For contributors working on the gem itself, see [docs/architecture.md](docs/architecture.md).
 
 ## Development
 
@@ -72,6 +75,11 @@ 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 vendorsthe PicoRuby.wasm and picorbc 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
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/picoruby/funicular.

data/Rakefile

@@ -78,6 +78,35 @@ task :copy_wasm do
   File.chmod(0755, File.join(picorbc_dest, "picorbc.js"))
   File.write(File.join(picorbc_dest, "VERSION"), "#{picorbc_version}\n")
   puts "  copied picorbc (#{picorbc_version})"
+
+  # ------------------------------------------------------------------
+  # 3) PicoRuby runtime for DOM-backed Node.js tests
+  # ------------------------------------------------------------------
+  test_runtime_src = ENV["PICORUBY_WASM_TEST_DIR"] ||
+                     File.expand_path("../../build/picoruby-wasm-test/bin", __dir__)
+  test_runtime_dest = File.join(vendor_root, "picoruby-test-node")
+  test_runtime_files = %w[picoruby.js picoruby.wasm]
+  optional_test_runtime_files = %w[picoruby.wasm.map]
+
+  unless Dir.exist?(test_runtime_src)
+    abort "PicoRuby WASM test runtime not found: #{test_runtime_src}\n" \
+          "Run `MRUBY_CONFIG=picoruby-wasm-test rake all` from the picoruby checkout, " \
+          "or set PICORUBY_WASM_TEST_DIR to the directory containing picoruby.js."
+  end
+
+  FileUtils.rm_rf(test_runtime_dest)
+  FileUtils.mkdir_p(test_runtime_dest)
+  test_runtime_files.each do |fname|
+    src_file = File.join(test_runtime_src, fname)
+    abort "Missing file: #{src_file}" unless File.exist?(src_file)
+    FileUtils.copy_file(src_file, File.join(test_runtime_dest, fname))
+  end
+  optional_test_runtime_files.each do |fname|
+    src_file = File.join(test_runtime_src, fname)
+    FileUtils.copy_file(src_file, File.join(test_runtime_dest, fname)) if File.exist?(src_file)
+  end
+  File.write(File.join(test_runtime_dest, "VERSION"), "#{picoruby_version}\n")
+  puts "  copied picoruby-test-node (#{picoruby_version})"
 end
 
 # Make sure the wasm artifacts are refreshed before the gem is packaged for release.

data/docs/architecture.md

@@ -1,409 +1,118 @@
-# Funicular Architecture
-
-This document provides a comprehensive analysis of Funicular's architectural design decisions and how they compare to other modern SPA frameworks.
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Architecture Design Decisions](#architecture-design-decisions)
-  - [1. Data Flow](#1-data-flow)
-  - [2. Rendering Strategy](#2-rendering-strategy)
-  - [3. Reactivity Model](#3-reactivity-model)
-  - [4. Component Model](#4-component-model)
-  - [5. State Management](#5-state-management)
-  - [6. Routing](#6-routing)
-  - [7. Rendering Mode](#7-rendering-mode)
-  - [8. Template System](#8-template-system)
-  - [9. Build Strategy](#9-build-strategy)
-  - [10. Concurrency](#10-concurrency)
-  - [11. Event System](#11-event-system)
-  - [12. Error Handling](#12-error-handling)
-  - [13. Data Fetching](#13-data-fetching)
-- [Comparison with Other Frameworks](#comparison-with-other-frameworks)
-- [Design Philosophy](#design-philosophy)
-- [Trade-offs](#trade-offs)
-- [Best Use Cases](#best-use-cases)
-
-## Overview
-
-Funicular is a **unidirectional, Virtual DOM-based SPA framework** for PicoRuby.wasm. It adopts design patterns similar to React while embracing Ruby's expressiveness and integrating seamlessly with Rails.
-
-**Core Principle**: Pure Ruby browser applications with explicit, predictable data flow.
-
-## Architecture Design Decisions
-
-### 1. Data Flow
-
-**Choice**: Unidirectional (One-way) Data Binding
-
-```ruby
-# State flows DOWN to UI
-state -> VDOM -> DOM rendering
-
-# Events flow UP to trigger state updates
-DOM events -> event handlers -> patch() -> state update -> re-render
-```
-
-**Evidence**:
-- State is immutable, updatable only via `patch()`
-- Direct state mutation is blocked by `StateAccessor`
-- Form inputs require explicit event handlers + `patch()` calls
-
-**Comparison**:
-
-| Framework | Binding Type | Update Mechanism |
-|-----------|--------------|------------------|
-| **Funicular** | Unidirectional | `patch()` + VDOM diffing |
-| React | Unidirectional | `setState()` + VDOM diffing |
-| Vue 2 | Bidirectional (v-model) | Reactivity proxy + VDOM |
-| Angular | Bidirectional | Two-way data binding |
-| Svelte | Unidirectional | Compile-time reactivity |
-
-### 2. Rendering Strategy
-
-**Choice**: Virtual DOM with Diffing Algorithm
-
-**Implementation**:
-- Custom VDOM implementation (`vdom.rb`)
-- `Differ.diff()` calculates minimal changes
-- `Patcher.apply()` applies patches to real DOM
-- **Key-based reconciliation** for efficient list updates
-
-**Code Reference**:
-```ruby
-# Component re-renders when state changes
-def re_render
-  new_vdom = build_vdom
-  patches = VDOM::Differ.diff(@vdom, new_vdom)
-  @dom_element = VDOM::Patcher.apply(@dom_element, patches)
-  @vdom = new_vdom
-end
-```
-
-**Benefits**:
-- Efficient DOM updates (minimal mutations)
-- Declarative UI (describe what, not how)
-- Cross-platform potential (VDOM is abstraction layer)
-
-### 3. Reactivity Model
-
-**Choice**: Explicit Updates (Manual Trigger)
-
-| Approach | Mechanism | Examples |
-|----------|-----------|----------|
-| **Explicit Updates** | Manual `setState()`/`patch()` | React, **Funicular** |
-| Auto-tracking | Proxy/Getter dependency tracking | Vue 3, Solid.js |
-| Compile-time | Compiler analyzes dependencies | Svelte |
-
-**Example**:
-```ruby
-def handle_input(event)
-  patch(username: event.target[:value])  # Explicit call
-end
-```
-
-**Benefits**:
-- Simple, predictable
-- Low runtime overhead
-- Easy to debug (explicit control flow)
-
-### 4. Component Model
-
-**Choice**: Class-based Components
-
-```ruby
-class ChatComponent < Funicular::Component
-  def initialize_state
-    { messages: [] }
-  end
-
-  def component_mounted
-    # Lifecycle hook
-  end
-
-  def render
-    div { "Chat UI" }
-  end
-end
-```
-
-**Features**:
-- Lifecycle hooks: `component_mounted`, `component_unmounted`
-- Instance variables for component-local data
-- Suspense support for async data loading
-- Similar to React Class Components
-
-### 5. State Management
-
-**Choice**: Local State + Props Drilling + Model Layer
-
-| Approach | Description | Example |
-|----------|-------------|---------|
-| **Local State** | Component-scoped `@state` | **Funicular** |
-| Global Store | Centralized state tree | Redux, Vuex |
-| Context/DI | Share state within tree | React Context |
-
-**Architecture**:
-- Components manage their own state (`@state`)
-- Parent-to-child communication via `props`
-- Server state managed by `Model` layer (ActiveRecord-style API)
-
-**No Global Store**: Funicular intentionally omits Redux-style global state to keep things simple. For shared state, use:
-- Props drilling
-- Model layer for server data
-- Component composition
-
-### 6. Routing
-
-**Choice**: Client-Side Routing (History API)
-
-```ruby
-Funicular.start(container: 'app') do |router|
-  router.get('/chat/:channel_id', to: ChatComponent, as: 'chat_channel')
-end
-```
-
-**Features**:
-- Rails-style DSL
-- URL parameter extraction (`/chat/:id` -> `{ id: "123" }`)
-- Auto-generated URL helpers: `chat_channel_path(id)`
-- History API for SPA navigation
-
-### 7. Rendering Mode
-
-**Choice**: Pure Client-Side Rendering (CSR)
-
-| Mode | Description | Funicular Support |
-|------|-------------|-------------------|
-| **CSR** | Render in browser | ✅ Yes |
-| SSR | Server-side rendering | ❌ No (for now...) |
-| SSG | Static site generation | ❌ No |
-| ISR | Incremental static regen | ❌ No |
-
-**Reason**: PicoRuby.wasm runs only in browsers. Rails serves JSON APIs + assets.
-
-### 8. Template System
-
-**Choice**: Ruby DSL (Not JSX or Template Strings)
-
-```ruby
-def render
-  div(class: 'container') do
-    h1 { 'Welcome' }
-    input(value: state.username, oninput: :handle_input)
-  end
-end
-```
-
-**Features**:
-- HTML tag names are Ruby methods
-- Blocks for child elements
-- Event handlers as symbols or Procs
-- Full Ruby expressiveness (loops, conditionals, etc.)
-
-**Comparison**:
-
-| Framework | Template Syntax |
-|-----------|-----------------|
-| React | JSX (XML-like) |
-| Vue | Template strings with directives |
-| Svelte | HTML-like template syntax |
-| **Funicular** | **Ruby DSL** |
-
-### 9. Build Strategy
-
-**Choice**: Runtime Execution (No Build Step)
-
-| Approach | Description | Examples |
-|----------|-------------|----------|
-| **Runtime** | Code runs directly in browser | Vue (CDN), **Funicular** |
-| Compile-time | Pre-build required | Svelte, Angular |
-| Hybrid | JSX compiled, runtime VDOM | React |
-
-**Funicular's Approach**:
-- `app/funicular/**/*.rb` files are compiled to mruby bytecode (`.mrb`) via `picorbc`
-- Compilation output: `app/assets/builds/app.mrb`
-- Rails autoloading is explicitly disabled for `app/funicular/` directory
-- Asset pipeline automatically handles compilation (hooks into `assets:precompile`)
-- Developers don't need to manually compile (transparent automation)
-
-**Build Process**:
-```bash
-# Automatic in production
-rake assets:precompile  # -> calls funicular:compile
-
-# Manual compilation (if needed)
-rake funicular:compile
-```
-
-**Benefits**:
-- Automated compilation via asset pipeline
-- Developers work with plain Ruby files
-- Production serves optimized bytecode
-- No separate build tool required (uses existing Rails toolchain)
-
-### 10. Concurrency
-
-**Choice**: Synchronous Rendering + Async Data Fetching
-
-- `patch()` triggers immediate `re_render()`
-- No batching or scheduling
-- Suspense feature for async data with loading states
-- `min_delay` option prevents spinner flickering
-
-```ruby
-use_suspense :user,
-  ->(resolve, reject) { User.find(id, &resolve) },
-  min_delay: 300  # Minimum loading spinner duration
-```
-
-### 11. Event System
-
-**Choice**: Native DOM Events (Not Synthetic Events)
-
-- Direct `addEventListener` usage
-- Event listeners re-bound on each re-render
-- `cleanup_events()` prevents memory leaks
-- No event pooling or synthetic event objects
-
-**Unified Callback Handling**:
-
-All event handlers accept `Symbol | Method | Proc`:
-
-```ruby
-# All valid:
-button(onclick: :handle_click)                    # Symbol (recommended)
-button(onclick: method(:handle_click))            # Method (explicit)
-button(onclick: -> { handle_click })              # Proc (inline)
-button(onclick: -> { patch(count: count + 1) })  # Proc (inline logic)
-```
-
-**Recommendation**:
-- Use `:symbol` for method references (concise)
-- Use `-> { }` for inline logic
-- Use `method(:name)` when passing callbacks to child components
-
-### 12. Error Handling
-
-**Choice**: Error Boundary Pattern (React-style)
-
-```ruby
-component(Funicular::ErrorBoundary,
-  fallback: ->(error) { div { "Error: #{error.message}" } }
-) do
-  component(RiskyComponent)
-end
-```
-
-- Catches errors from child components
-- Displays fallback UI
-- Prevents entire app crash
-- Stack-based boundary resolution
-
-### 13. Data Fetching
-
-**Choice**: Manual Fetch + Model Abstraction Layer
-
-**Low-level**: `HTTP.get`, `HTTP.post`
-**High-level**: `Model.all`, `Model.find`, `Model.create`
-
-```ruby
-# ActiveRecord-style API
-User.all do |users, error|
-  patch(users: users)
-end
-```
-
-**Features**:
-- Callback-based (not Promise-based)
-- Automatic CSRF token handling
-- Rails API integration
-- No built-in caching (like SWR/React Query)
-
-## Comparison with Other Frameworks
-
-### Funicular vs React
-
-| Aspect | Funicular | React |
-|--------|-----------|-------|
-| Language | Ruby | JavaScript/JSX |
-| Components | Class-based | Function (Hooks) or Class |
-| State Update | `patch()` | `setState()` / `useState()` |
-| VDOM | Custom implementation | Custom implementation |
-| Data Fetching | Model layer | Manual / libraries |
-| Routing | Built-in | Separate library |
-| Build Step | Asset Pipeline integration | Required (Babel/JSX) |
-
-### Funicular vs Vue
-
-| Aspect | Funicular | Vue |
-|--------|-----------|-----|
-| Data Binding | Unidirectional | Bidirectional (v-model) |
-| Reactivity | Explicit `patch()` | Auto-tracking (Proxy) |
-| Templates | Ruby DSL | HTML-like templates |
-| SSR | No | Yes |
-
-### Funicular vs Svelte
-
-| Aspect | Funicular | Svelte |
-|--------|-----------|--------|
-| VDOM | Yes | No (compiles to imperative code) |
-| Reactivity | Explicit | Compile-time analysis |
-| Build Step | Asset Pipeline integration | Required (compiler) |
-
-## Design Philosophy
-
-Funicular embodies **"PicoRuby.wasm-based React"** with these principles:
-
-1. **Ruby First**: Leverage Ruby's expressiveness for frontend development
-2. **Explicit Over Magic**: Predictable, explicit state updates
-3. **Rails Integration**: Seamless Rails API + ActionCable + Asset Pipeline integration
-4. **Simple by Default**: No global state, no complex build tools
-5. **Progressive Enhancement**: Start simple, add complexity when needed
-
-## Trade-offs
-
-### Strengths
-
-✅ **Ruby Expressiveness**: Full Ruby syntax in templates
-```ruby
-state.messages.map { |msg| div(key: msg.id) { msg.content } }
+# Architecture (contributor guide)
+
+This document is for people working **on** Funicular itself. User-facing
+documentation -- how to build apps with Funicular -- lives at
+[picoruby.org/wasm](https://picoruby.org/funicular-getting-started).
+
+Funicular is a unidirectional, Virtual DOM-based SPA framework for
+PicoRuby.wasm. State flows down to the DOM; events flow up through `patch()` to
+update state and trigger a re-render. There is no global store, no auto-tracking
+reactivity, and no separate build tool -- compilation rides on the Rails asset
+pipeline.
+
+## Two sides of one repository
+
+Funicular ships as two cooperating pieces (plus a Chrome extension):
+
+- **PicoGem `picoruby-funicular`** (`mrblib/`) -- the runtime that executes in
+  the browser under PicoRuby.wasm. This is the framework proper.
+- **CRubyGem `funicular`** (`lib/`) -- the Rails integration: the compiler
+  wrapper, middleware, railtie, view helpers, and the server-side rendering
+  runtime.
+
+The same `mrblib/` code also runs under CRuby during SSR (see below), so it must
+stay free of browser-only calls on any server code path
+(`Funicular.server?` is true there).
+
+## `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?`)                         |
+
+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.
+
+## `lib/` Rails integration
+
+- `compiler.rb` -- runs the vendored `picorbc` (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.
+- `middleware.rb` -- development only; watches `app/funicular/` and recompiles on
+  change, then invalidates the Propshaft asset cache.
+- `railtie.rb` -- inserts the middleware, exposes view helpers, loads the rake
+  tasks.
+- `helpers/picoruby_helper.rb` -- `picoruby_include_tag`,
+  `funicular_app_container`, `funicular_state_tag`.
+- `configuration.rb` -- per-environment runtime source selection
+  (`:local_debug` / `:local_dist` / `:cdn`).
+- `ssr.rb`, `ssr/runtime.rb` -- load the `mrblib/` runtime into the Rails process
+  and render a route's VDOM to HTML, injecting state for client hydration.
+- `schema.rb` -- introspect an ActiveRecord model's `validators_on` and emit
+  client-side validators inline with the schema.
+
+## 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
+`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)
+
+Because `copy_wasm` reads sibling directories inside the picoruby repository, it
+only works from within that checkout -- see Development below.
+
+## 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.
+
+## Development
+
+This repository is a submodule of
+[picoruby/picoruby](https://github.com/picoruby/picoruby). Do not check it out
+standalone; clone the parent and work from there:
+
+```console
+git clone --recurse-submodules https://github.com/picoruby/picoruby.git
+cd picoruby/mrbgems/picoruby-funicular
 ```
 
-✅ **No Build Step**: Instant development feedback
-
-✅ **Rails Integration**: CSRF tokens, ActiveRecord-style APIs
-
-✅ **Lightweight Dependencies**: Minimal gem dependencies
-
-### Limitations
-
-❌ **No SSR**: PicoRuby.wasm is browser-only (for now...)
-
-❌ **No npm Ecosystem**: Limited to Ruby gems
-
-❌ **State Management**: No global store (can be complex at scale)
-
-❌ **Performance Overhead**: WebAssembly Ruby execution slower than native JS
-
-## Best Use Cases
-
-### ✅ Well-Suited For:
-
-- **Rails SPA Features**: Adding interactive UI to Rails apps
-- **Small to Medium SPAs**: Dashboard, admin panels, chat apps
-- **Ruby Teams**: Frontend work by Ruby developers
-- **Rapid Prototyping**: Quick interactive UI development
-
-### ❌ Not Ideal For:
-
-- **SEO-Critical Apps**: Needs SSR (use Rails views or Next.js)
-- **Large-Scale SPAs**: Complex state management requirements
-- **Mobile Apps**: Use React Native or native solutions
-- **Performance-Critical**: Real-time games, high-frequency updates
+The CRubyGem side (`lib/`, `funicular.gemspec`) can be developed and tested
+independently inside that directory, but `rake copy_wasm` relies on sibling
+directories within the picoruby repository and fails from a standalone checkout.
 
-## Conclusion
+PicoGem dependencies are declared in `mrbgem.rake` (picoruby-wasm,
+picoruby-indexeddb, picoruby-json, and the mruby `*-ext` gems).
 
-Funicular adopts proven patterns from React (unidirectional flow, VDOM) while providing unique value through **Ruby ecosystem integration**. It's not trying to replace JavaScript frameworks for all use cases, but rather offers a compelling alternative for Ruby teams building interactive web applications.
+## Testing
 
-The architecture prioritizes **simplicity, predictability, and Rails integration** over features like maximum performance. This makes it an excellent choice for its target use cases: Ruby teams building SPAs as part of Rails applications.
+- CRubyGem (Rails integration): `rake test` in this repository.
+- PicoGem runtime: `rake test:gems:picoruby[picoruby-funicular]` in the parent
+  picoruby repository, where `mrbgems/picoruby-funicular` exists as a submodule.

data/lib/funicular/assets/funicular.css

@@ -0,0 +1,23 @@
+/* Funicular base styles.
+ *
+ * Injected into the page by picoruby_include_tag so that class names emitted
+ * from inside the gem (which the host app's CSS pipeline never sees -- e.g.
+ * Tailwind only scans the app's own sources) still render. Keep this minimal
+ * and namespaced under .funicular-* so it cannot clash with app styles.
+ *
+ * Apps that prefer their own utilities can override per form via
+ * form_for(..., field_error_class: "...", error_class: "..."). */
+
+.funicular-field-error {
+  border-color: #ef4444 !important; /* red-500, wins over a base border color */
+  background-color: #fef2f2;        /* red-50 */
+  box-shadow: 0 0 0 1px #ef4444;
+}
+
+.funicular-error {
+  margin-top: 0.25rem;
+  color: #dc2626;                   /* red-600 */
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+  font-weight: 500;
+}