If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/stimulusreflex/stimulus_reflex shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4w ago
• 15 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live stimulusreflex/stimulus_reflex repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stimulusreflex/stimulus_reflex.

What it runs against: a local clone of stimulusreflex/stimulus_reflex — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in stimulusreflex/stimulus_reflex | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 59 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stimulusreflex/stimulus_reflex. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stimulusreflex/stimulus_reflex.git
#   cd stimulus_reflex
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of stimulusreflex/stimulus_reflex and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "stimulusreflex/stimulus_reflex(\\.git)?\\b" \\
  && ok "origin remote is stimulusreflex/stimulus_reflex" \\
  || miss "origin remote is not stimulusreflex/stimulus_reflex (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "javascript/stimulus_reflex.js" \\
  && ok "javascript/stimulus_reflex.js" \\
  || miss "missing critical file: javascript/stimulus_reflex.js"
test -f "app/channels/stimulus_reflex/channel.rb" \\
  && ok "app/channels/stimulus_reflex/channel.rb" \\
  || miss "missing critical file: app/channels/stimulus_reflex/channel.rb"
test -f "javascript/reflex.js" \\
  && ok "javascript/reflex.js" \\
  || miss "missing critical file: javascript/reflex.js"
test -f "javascript/process.js" \\
  && ok "javascript/process.js" \\
  || miss "missing critical file: javascript/process.js"
test -f "javascript/lifecycle.js" \\
  && ok "javascript/lifecycle.js" \\
  || miss "missing critical file: javascript/lifecycle.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 59 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~29d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/stimulusreflex/stimulus_reflex"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

StimulusReflex is a Rails library that adds real-time, reactive server-rendered views over WebSockets without requiring a separate JavaScript framework. It combines Stimulus controllers with ActionCable to enable two-way binding between frontend interactions and server-side Ruby logic, delivering morphed HTML diffs back to the browser for DOM updates—eliminating the complexity of building SPAs while keeping the Rails request/response model intact. Hybrid monorepo: app/channels/stimulus_reflex/channel.rb contains the ActionCable integration point, the javascript/ directory holds the client-side Stimulus controller glue (compiled via rollup to dist/stimulus_reflex.js), and docs/ is a VitePress site. The gem is published to RubyGems and npm is published as stimulus_reflex, making it dual-consumable.

Rails developers who want to build modern, reactive applications without learning React/Vue/Angular, specifically those who prefer server-side rendering and want to leverage their existing Rails expertise with ViewComponents, ERB templates, and ActiveJob.

Production-ready and actively maintained. The project uses semantic-release for version management (currently v3.5.5), has comprehensive CI/CD with StandardRB + Prettier-Standard linting and automated tests via GitHub Actions, and shows consistent contributions across Ruby and JavaScript. The monorepo structure with both a gem (224KB Ruby) and npm package (151KB JavaScript) indicates stable, dual-platform distribution.

Low to moderate risk: relies on ActionCable stability and maintains compatibility across Rails 6/7/8 (specified in package.json), has strong code style enforcement reducing maintenance debt, and lists only critical dependencies (Stimulus >=3.0, ActionCable, cable_ready). Main risk is community size compared to React/Vue ecosystems, though the project's 4-contributor team and active CI suggest sufficient stewardship for a focused solution.

Active maintenance with CI/CD pipelines for linting (StandardRB for Ruby, Prettier-Standard for JS), testing via web-test-runner, and documentation generation via VitePress. The presence of .github/workflows/dev-build.yml, tests.yml, prettier-standard.yml, and standardrb.yml shows continuous quality enforcement. No specific PR/milestone data visible, but the codebase structure indicates ongoing feature parity between gem and npm versions.

git clone https://github.com/stimulusreflex/stimulus_reflex.git
cd stimulus_reflex
bundle install
yarn install
bundle exec rake
yarn test

Daily commands: Tests: yarn test (web-test-runner) and bundle exec rake (Rails). Development watch: yarn build:watch for JS compilation, bundle exec rake for Rails. Docs preview: yarn docs:dev (VitePress on localhost:5173). Linting: yarn format (Prettier-Standard) and bundle exec standardrb (StandardRB).

• javascript/stimulus_reflex.js — Main entry point for the StimulusReflex client library—initializes reflexes, sets up event handlers, and orchestrates the core reflex lifecycle
• app/channels/stimulus_reflex/channel.rb — Server-side ActionCable channel handling all reflex requests, state management, and DOM morphing directives
• javascript/reflex.js — Core Reflex class that encapsulates request lifecycle, callbacks, and communication with the server channel
• javascript/process.js — Request processing pipeline that queues, deduplicates, and serializes reflex invocations for network transmission
• javascript/lifecycle.js — Implements the reflex callback hooks (before/after/success/error/finally) that orchestrate client-side side effects
• lib/stimulus_reflex/reflex.rb — Server-side base Reflex class that applications inherit from—contains action routing, permission checks, and morph helpers
• package.json — NPM package definition and version source-of-truth for the client library distribution

Add a new server-side Reflex action

1. Create a new Reflex class inheriting from StimulusReflex::Reflex in app/reflexes/ (lib/stimulus_reflex/reflex.rb)
2. Define a public method for your action (e.g., def increment) (app/reflexes/example_reflex.rb)
3. Use morph or update helpers to specify DOM changes; optionally call render with partial/locals (lib/stimulus_reflex/reflex.rb)
4. In your view, add data-reflex='ClassName#method' to an element (link, form input, etc.) (app/views/example.html.erb)
5. Test with StimulusReflex::Testing helpers in spec/reflexes/ (docs/appendices/testing.md)

Add a client-side callback to the reflex lifecycle

1. Import reflexes or use Stimulus controller injection to access reflex instance (javascript/stimulus_reflex.js)
2. Call reflex.on('lifecycle:hook', callback) where hook is before, after, success, error, or finally (javascript/lifecycle.js)
3. Callback receives the Reflex instance and can inspect reflex.state, reflex.payload, or perform side effects (javascript/reflex.js)
4. Alternatively, register a global callback with StimulusReflex.on('reflex:success', handler) (javascript/callbacks.js)

Enable and customize DOM morphing behavior

1. Add data-reflex-morph='selector' to specify which DOM subtree to diff/update (default: document.body) (javascript/attributes.js)
2. Add data-reflex-root-path='selector' to scope morph to a specific container element (javascript/attributes.js)
3. In your Reflex action, the ActionCable channel automatically broadcasts CableReady commands to morph via morphdom (app/channels/stimulus_reflex/channel.rb)
4. To disable morphing, use morph :nothing in the reflex; to enable permanent DOM updates use morph :page (lib/stimulus_reflex/reflex.rb)

Add request-level logging and debugging

1. Set StimulusReflex.debug = true in your JavaScript initialization or app.js (javascript/debug.js)
2. Inspect reflex lifecycle with callbacks or use browser DevTools to monitor WebSocket messages (javascript/lifecycle.js)
3. On the server, add logging in your Reflex class methods; StimulusReflex provides access to session and cookies (lib/stimulus_reflex/reflex.rb)
4. Check docs/appendices/troubleshooting.md for common issues and detailed trace instructions (docs/appendices/troubleshooting.md)

• ActionCable (WebSocket) — Provides bidirectional, persistent connection for real-time reflex invocations and DOM broadcasts without polling; native to Rails
• Stimulus (JavaScript framework) — Lightweight, minimal framework for attaching behavior to HTML; enables declarative reflex triggers via data attributes without SPA overhead
• CableReady — Companion library that serializes server-side DOM operations into efficient CableReady commands, sent over ActionCable to morph the client DOM
• morphdom — Efficient JavaScript virtual-DOM diffing library that minimizes DOM mutations and preserves form state/focus during updates
• Redis (optional) — Used for ActionCable message queue persistence and multi-process server coordination; removable via no-redis mode for simplicity

• Server-driven rendering + morphdom over client-side SPA framework

  • Why: Leverage Rails' existing view layer and gem ecosystem; lower JavaScript complexity; faster initial page load
  • Consequence: Each reflex requires server round-trip; cannot work fully offline; higher server CPU for frequent reflexes vs. pure client-side state

• Request morphing via CableReady broadcasts vs. explicit JSON API responses

  • Why: Eliminates need for separate API serialization; server returns HTML that is automatically diffed and patched
  • Consequence: Tight coupling between server view markup and client expectations; harder to iterate on markup without breaking reflexes

• Declarative data attributes (data-reflex) over Stimulus Value Objects

  • Why: Lower friction for non-developers; simpler to add reflex behavior to existing ERB templates
  • Consequence: Less type-safety; attribute parsing complexity; harder to refactor without comprehensive find-and-replace

• Single ActionCable channel per application vs. multiple domain-specific channels

  • Why: Simplicity and default-friendly; one connection handles all reflexes
  • Consequence: All reflex traffic shares one queue; potential bottleneck if one Reflex class has high load; less isolation for multi-tenant apps

• Does not handle server-side persistent storage or database transactions—relies on Rails ORM (ActiveRecord) for that
• Does not provide client-side state management like Redux—state lives on server and is re-rendered per reflex
• Does not support offline-first or local-first architecture—all reflexes require WebSocket connectivity
• Does not enforce authentication or authorization—delegates to Rails' existing Devise/Pundit/CanCan integrations
• Does not generate or enforce TypeScript types

ActionCable requirement: This is not a drop-in library; it requires ActionCable infrastructure (Redis by default for multi-process, or memory adapter for dev). Stimulus peer dependency: Strict requirement for Stimulus >=3.0; older projects on Stimulus 2.x will not work. No offline mode: All reflexes require live WebSocket; there is no fallback for disconnected states (see docs/appendices/troubleshooting.md). ViewComponent version compatibility: While supported, ViewComponent version mismatches with Rails can cause rendering issues. .node-version and .ruby-version pinning: These are strict; development requires Node 18+ and Ruby 3.0+; check these before yarn install / bundle install.

• ActionCable / WebSocket channels — StimulusReflex's entire transport layer depends on ActionCable's persistent WebSocket connection; understanding how Rails channels multiplex messages is essential to debugging reflex failures
• DOM morphing / virtual diffing — The server sends back complete HTML; morphdom diffs and applies only the changes, avoiding full-page rerenders while preserving component state—core to performance
• Server-Sent Events / Streaming updates — While StimulusReflex uses ActionCable's bidirectional channels, understanding SSE patterns helps when building real-time notification systems that complement reflexes
• Rails fragment caching / Russian doll caching — StimulusReflex encourages cache-friendly server rendering; partial re-renders leverage Rails' caching hierarchy to avoid redundant database queries on every reflex
• Stimulus lifecycle hooks (initialize, connect, disconnect) — StimulusReflex integrates reflexes into Stimulus' lifecycle; knowing when controllers connect/disconnect helps manage WebSocket subscriptions and event listeners
• Two-way data binding — StimulusReflex establishes implicit two-way binding: form inputs trigger reflexes that update the DOM, but without explicit Vue/React reactivity—understanding this pattern prevents over-engineering
• Broadcast / multicast message delivery — ActionCable's broadcast API allows one reflex to update multiple connected clients; critical for collaborative or real-time shared-state features

• hotwired/stimulus — Required peer dependency (>=3.0); StimulusReflex wraps Stimulus controllers to handle server communication
• rails/actioncable — Core transport layer; StimulusReflex sends reflexes and receives updates over ActionCable WebSockets
• cable-ready/cable_ready — Direct dependency for DOM morphing and mutation updates; handles the server-to-client HTML patching
• ViewComponent/view_component — First-class integration partner; StimulusReflex apps commonly render ViewComponents instead of ERB partials
• hotwired/turbo-rails — Complementary Hotwired library for page navigation; often used alongside StimulusReflex for full-stack reactive UX

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for javascript/test directory with coverage for core reflex lifecycle

The repo has a test infrastructure (web-test-runner, @open-wc/testing) and a test script, but the javascript/test/**/*.test.js pattern suggests tests may be sparse or missing. Given that StimulusReflex is a complex library managing websocket communication, DOM morphing, and stimulus integration, comprehensive unit tests for the core reflex lifecycle (initialization, request/response handling, error states) would significantly improve code reliability and make future contributions safer.

• [ ] Examine javascript/test directory structure and identify missing test files
• [ ] Create unit tests for app/channels/stimulus_reflex/channel.rb integration with JavaScript reflex handling
• [ ] Add tests for websocket lifecycle events (connect, disconnect, error handling)
• [ ] Add tests for DOM morphing edge cases and morph mode variations (reference to docs/guide/morph-modes.md)
• [ ] Ensure test:watch script works properly and update package.json test documentation

Add GitHub Actions workflow for JavaScript bundle size monitoring and regression detection

The repo has multiple CI workflows (.github/workflows/tests.yml, dev-build.yml, etc.) but no automated bundle size tracking. Given that stimulus_reflex publishes both ESM (dist/stimulus_reflex.js) and UMD (dist/stimulus_reflex.umd.js) builds, and has explicit main/module/browser entry points in package.json, a workflow using tools like bundlewatch or size-limit would prevent accidental performance regressions and help maintain the library's lean footprint.

• [ ] Add size-limit or bundlewatch configuration to package.json with thresholds for both dist/stimulus_reflex.js and dist/stimulus_reflex.umd.js
• [ ] Create .github/workflows/bundle-size.yml that runs on PR and reports size deltas
• [ ] Document expected bundle sizes in README.md or docs/appendices/deployment.md
• [ ] Integrate with existing build process (rollup.config.mjs) to ensure accurate measurements

Add integration test examples in docs/appendices/testing.md for real-world reflex testing patterns

While docs/appendices/testing.md exists, the repo lacks concrete, runnable examples of how to test reflexes in a Rails application. This is particularly important given the complexity of testing websocket-based reactive features. Adding example test cases (RSpec, Minitest) for common patterns like form submissions, async operations, and error handling would significantly improve contributor onboarding and reduce support burden.

• [ ] Review docs/appendices/testing.md for gaps in reflex testing guidance
• [ ] Add RSpec examples for testing reflex actions with various response types
• [ ] Add examples for testing reflex classes that use persistence and authentication (reference to docs/guide/persistence.md and docs/guide/authentication.md)
• [ ] Include examples for stubbing ActionCable connections in tests
• [ ] Add troubleshooting section linking to docs/appendices/troubleshooting.md for common test failures

• The docs/appendices/ directory is sparse (deployment, events, glossary, no-redis, release-history, team, testing, troubleshooting exist but are linked in structure only). A new contributor could expand the docs/appendices/testing.md with concrete examples of testing reflexes using the test helpers, cross-referencing app/channels/stimulus_reflex/channel.rb.
• The javascript/test/ directory lacks visible test files in the file list. A contributor could write test specs for the client-side controller lifecycle (before_reflex, after_reflex hooks) using the existing @open-wc/testing devDependency, mirroring Rails test patterns.
• Add a TypeScript definitions file (stimulus_reflex.d.ts) to the npm package distribution (currently absent from files list in package.json). This would unlock IDE autocomplete for TypeScript users importing the library and requires adding typescript as a devDependency.

StimulusReflex is a well-structured Rails reactive framework with generally good security practices due to Rails' built-in protections. However, several medium-severity concerns exist around XSS prevention in DOM morphing operations and potential issues with incomplete dependency auditing. The codebase appears to follow Rails conventions for authentication and CSRF protection, but WebSocket-specific security considerations (rate limiting, error handling, CSRF in WebSocket upgrades) need explicit documentation and verification. No hardcoded secrets or critical infrastructure issues were identified in the visible files. Overall security posture is good but would benefit from comprehensive documentation of security best practices for StimulusReflex users.

• Medium · Potential XSS Risk in DOM Morphing Operations — javascript/app.js, javascript/callbacks.js, app/channels/stimulus_reflex/channel.rb. The codebase includes morphdom-based DOM manipulation (referenced in keywords and likely in javascript/app.js). Without proper sanitization of incoming data from WebSocket messages, there is a risk of XSS attacks when updating the DOM with user-controlled or untrusted data. Fix: Ensure all data received via ActionCable WebSocket is properly sanitized before DOM insertion. Use CableReady's built-in sanitization and implement Content Security Policy (CSP) headers. Validate and escape data on both server and client sides.
• Medium · Incomplete Dependency Information — package.json. The package.json file is truncated in the provided content, making it impossible to fully audit all dev dependencies. The @rollup/plugin-* dependencies and others are incomplete, which could mask security issues in build-time dependencies. Fix: Perform a complete audit with 'npm audit' or 'yarn audit' on the full package.json file. Regularly update dependencies and use tools like Dependabot to track security updates.
• Medium · No Visible CSRF Protection Configuration — app/channels/stimulus_reflex/channel.rb, javascript/app.js. While the codebase integrates with Rails (which has built-in CSRF protection), there is no explicit documentation or configuration visible for CSRF token handling in WebSocket communications via ActionCable/CableReady. Fix: Ensure CSRF tokens are properly included in WebSocket upgrade requests. Verify that ActionCable is configured with proper CSRF verification. Document CSRF handling for reflex calls.
• Low · Missing Security Headers Documentation — Configuration files not visible in provided structure. No visible configuration for security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the codebase. While this may be configured at the Rails application level, it should be documented. Fix: Document recommended security headers for applications using StimulusReflex. Include CSP configuration examples that allow WebSocket connections and Stimulus Reflex operations.
• Low · Potential Information Disclosure in Error Messages — app/channels/stimulus_reflex/channel.rb. WebSocket-based reflexes may expose detailed error messages or stack traces to clients if not properly handled, especially in development environments. Fix: Implement proper error handling to avoid exposing sensitive information. Return generic error messages to clients in production and log detailed errors server-side only.
• Low · No Visible Rate Limiting Implementation — app/channels/stimulus_reflex/channel.rb. The codebase does not show evidence of rate limiting on reflex operations, which could allow abuse of server resources through repeated WebSocket calls. Fix: Implement rate limiting on reflex operations, either at the channel level or using middleware. Consider using gems like rack-attack or similar solutions for ActionCable.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.