hibiki_rails: install registers the client via a file-backed shim

stimulus:manifest:update rewrites controllers/index.js wholesale from
the *_controller.js files, so the unmanaged import/register lines the
install generator appended were dropped on every manifest run. Install
now creates app/javascript/controllers/hibiki_controller.js re-exporting
the packaged controller: the manifest re-derives the exact "hibiki"
registration from the filename, importmap apps eager-load it (index.js
untouched), and jsbundling apps get the manifest-format pair appended.
A hint flags pre-shim direct registrations that would now double up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: planetaska

hibiki_rails/README.md

@@ -104,20 +104,24 @@ import map, so importmap-rails apps have no install step beyond
 registering the controller — `bin/rails g hibiki:rails:install` does it
 (plus the `Helpers` include below, the `ApplicationCable` boilerplate,
 and the `@rails/actioncable` pin — a stock app has neither until its
-first `rails g channel`), or add the line yourself:
+first `rails g channel`), or create the one-line shim yourself:
 
 ```js
-// app/javascript/controllers/index.js
-import HibikiController from "hibiki-rails"
-application.register("hibiki", HibikiController) // identifier must be "hibiki"
+// app/javascript/controllers/hibiki_controller.js
+export { default } from "hibiki-rails" // registers as "hibiki" — the helpers hardcode that identifier
 ```
 
+The registration is a file-backed shim on purpose: importmap apps
+eager-load it from the controllers directory, jsbundling apps get the
+matching import/register pair in `controllers/index.js` (the install
+generator appends it), and because it is derived from a real controller
+file, `bin/rails stimulus:manifest:update` regenerates it instead of
+dropping it.
+
 (jsbundling/vite apps: `npm install hibiki-rails` — the [npm
 package](https://www.npmjs.com/package/hibiki-rails) is the same module the
 engine vendors, and pulls in `@rails/actioncable`; release in lockstep with
-the gem. One caveat: `bin/rails stimulus:manifest:update` regenerates
-`controllers/index.js` from the controller files and drops the register
-line above — re-run `hibiki:rails:install` afterwards, it's idempotent.)
+the gem.)
 
 The client is one generic Stimulus controller that drives any *island*: a
 DOM subtree bound to one channel subscription. Islands are stamped with

hibiki_rails/lib/generators/hibiki/rails/generator_helpers.rb

@@ -11,6 +11,7 @@ module Generators
       # destination_root, so the install generator uses them too.
       module GeneratorHelpers
         INDEX_JS = "app/javascript/controllers/index.js"
+        SHIM = "app/javascript/controllers/hibiki_controller.js"
         APPLICATION_HELPER = "app/helpers/application_helper.rb"
         REGISTER_FRAGMENT = 'application.register("hibiki"'
         IMPORTMAP = "config/importmap.rb"
@@ -34,7 +35,9 @@ def nested? = !regular_class_path.empty?
 
         def name_parts = regular_class_path + [file_name]
 
-        def hibiki_registered? = wired?(INDEX_JS, REGISTER_FRAGMENT)
+        # The install generator's file-backed shim is the wiring artifact;
+        # the index.js fragment covers hand-wired (or pre-shim) apps.
+        def hibiki_registered? = exists?(SHIM) || wired?(INDEX_JS, REGISTER_FRAGMENT)
 
         def helpers_included? = wired?(APPLICATION_HELPER, "Hibiki::Rails::Helpers")
 

hibiki_rails/lib/generators/hibiki/rails/install/install_generator.rb

@@ -8,8 +8,9 @@ module Rails
     module Generators
       # Wiring only — the client itself stays vendored in the engine (the
       # data-hibiki-* attribute names are a private Ruby↔JS contract that
-      # versions inside this gem, so nothing is ever copied into the app).
-      # Every action is idempotent by content check, so rerunning is safe.
+      # versions inside this gem, so the client is never copied into the
+      # app; the shim it creates only re-exports it). Every action is
+      # idempotent by content check, so rerunning is safe.
       class InstallGenerator < ::Rails::Generators::Base
         include GeneratorHelpers
 
@@ -19,12 +20,11 @@ class InstallGenerator < ::Rails::Generators::Base
              "controller, includes Hibiki::Rails::Helpers in ApplicationHelper, " \
              "creates the ApplicationCable boilerplate, and pins @rails/actioncable."
 
+        # Exactly the lines `stimulus:manifest:update` emits for the shim,
+        # so a later manifest run converges instead of duplicating.
         REGISTER = <<~JS
 
-          // The packaged hibiki client (the "hibiki-rails" module: the engine's
-          // importmap pin, or the npm package in bundler apps). The identifier
-          // must be "hibiki" — the Ruby helpers hardcode it in data-controller.
-          import HibikiController from "hibiki-rails"
+          import HibikiController from "./hibiki_controller"
           application.register("hibiki", HibikiController)
         JS
 
@@ -46,8 +46,18 @@ class InstallGenerator < ::Rails::Generators::Base
           pin "@rails/actioncable", to: "actioncable.esm.js"
         RUBY
 
+        # The registration lives in a file-backed shim so that
+        # `stimulus:manifest:update` (which rewrites index.js wholesale from
+        # the *_controller.js files) re-derives it instead of dropping it.
+        def create_shim_controller
+          template "hibiki_controller.js.tt", SHIM
+        end
+
+        # Importmap apps eager-load the shim from the controllers directory;
+        # a manifest-style index.js (jsbundling) must name it explicitly.
         def register_controller
-          return say_status :identical, INDEX_JS, :blue if hibiki_registered?
+          return legacy_registration_hint if importmap?
+          return say_status :identical, INDEX_JS, :blue if wired?(INDEX_JS, REGISTER_FRAGMENT)
           return manual_wiring(INDEX_JS, REGISTER) unless exists?(INDEX_JS)
 
           append_to_file INDEX_JS, REGISTER
@@ -80,6 +90,17 @@ def pin_actioncable
 
         private
 
+        # Installs that predate the shim registered straight in index.js;
+        # left in place next to the eager-loaded shim that would register
+        # "hibiki" twice.
+        def legacy_registration_hint
+          return unless wired?(INDEX_JS, REGISTER_FRAGMENT)
+
+          say_status :hint, "#{INDEX_JS} still registers \"hibiki\" directly — " \
+                            "remove those lines; the eager-loaded " \
+                            "hibiki_controller.js shim replaces them", :yellow
+        end
+
         def bundler_note
           say_status :skip, "#{IMPORTMAP} not found — with a JS bundler, " \
                             "npm/yarn add hibiki-rails instead (it pulls in " \

hibiki_rails/lib/generators/hibiki/rails/install/templates/hibiki_controller.js.tt

@@ -0,0 +1,7 @@
+// Registers the packaged hibiki client (the "hibiki-rails" module: the
+// engine's importmap pin, or the npm package in bundler apps) as the
+// "hibiki" Stimulus controller — the Ruby helpers hardcode that
+// identifier in data-controller. File-backed on purpose: `bin/rails
+// stimulus:manifest:update` re-derives this exact registration from the
+// filename, so it survives manifest rewrites.
+export { default } from "hibiki-rails"

hibiki_rails/spec/generators/install_generator_spec.rb

@@ -14,6 +14,7 @@
   end
 
   let(:index_js) { File.join(@destination, "app/javascript/controllers/index.js") }
+  let(:shim) { File.join(@destination, "app/javascript/controllers/hibiki_controller.js") }
   let(:application_helper) { File.join(@destination, "app/helpers/application_helper.rb") }
   let(:importmap) { File.join(@destination, "config/importmap.rb") }
   let(:cable_channel) { File.join(@destination, "app/channels/application_cable/channel.rb") }
@@ -38,16 +39,47 @@ def seed_stock_app
     RUBY
   end
 
-  it "registers the packaged controller and includes the helpers" do
+  it "creates the file-backed shim and includes the helpers" do
     seed_stock_app
+    original_index = File.read(index_js)
     run_generator(described_class, destination: @destination)
 
-    expect(File.read(index_js)).to include('import HibikiController from "hibiki-rails"')
-      .and include('application.register("hibiki", HibikiController)')
+    expect(File.read(shim)).to include('export { default } from "hibiki-rails"')
+    # Importmap apps eager-load the shim — index.js stays untouched, so
+    # stimulus:manifest:update has nothing of ours to drop.
+    expect(File.read(index_js)).to eq(original_index)
     expect(File.read(application_helper))
       .to include("module ApplicationHelper\n  include Hibiki::Rails::Helpers\nend")
   end
 
+  it "registers the shim in a manifest-style index.js (jsbundling apps)" do
+    seed_stock_app
+    File.delete(importmap)
+    File.write(index_js, %(import { application } from "./application"\n))
+    run_generator(described_class, destination: @destination)
+
+    # Exactly the lines stimulus:manifest:update emits for the shim file,
+    # so later manifest runs converge instead of dropping the registration.
+    expect(File.read(index_js)).to include('import HibikiController from "./hibiki_controller"')
+      .and include('application.register("hibiki", HibikiController)')
+    expect(File.read(shim)).to include('export { default } from "hibiki-rails"')
+  end
+
+  it "hints when a pre-shim registration is still in an importmap index.js" do
+    seed_stock_app
+    File.write(index_js, <<~JS)
+      import { application } from "controllers/application"
+      import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+      eagerLoadControllersFrom("controllers", application)
+      import HibikiController from "hibiki-rails"
+      application.register("hibiki", HibikiController)
+    JS
+    output = run_generator(described_class, destination: @destination)
+
+    expect(output).to include("remove those lines")
+    expect(File.exist?(shim)).to be(true)
+  end
+
   it "creates the ApplicationCable boilerplate and pins @rails/actioncable" do
     seed_stock_app
     run_generator(described_class, destination: @destination)
@@ -64,11 +96,20 @@ def seed_stock_app
     output = run_generator(described_class, destination: @destination)
 
     expect(output).to include("identical")
-    expect(File.read(index_js).scan('application.register("hibiki"').count).to eq(1)
     expect(File.read(application_helper).scan("Hibiki::Rails::Helpers").count).to eq(1)
     expect(File.read(importmap).scan("@rails/actioncable").count).to eq(1)
   end
 
+  it "is idempotent in jsbundling apps: the registration is appended once" do
+    seed_stock_app
+    File.delete(importmap)
+    File.write(index_js, %(import { application } from "./application"\n))
+    run_generator(described_class, destination: @destination)
+    run_generator(described_class, destination: @destination)
+
+    expect(File.read(index_js).scan('application.register("hibiki"').count).to eq(1)
+  end
+
   it "never touches an existing ApplicationCable" do
     seed_stock_app
     FileUtils.mkdir_p(File.dirname(cable_channel))
@@ -93,6 +134,7 @@ class Channel < ActionCable::Channel::Base
     expect(output).to include('application.register("hibiki", HibikiController)')
     expect(output).to include("include Hibiki::Rails::Helpers")
     expect(File.exist?(index_js)).to be(false)
+    expect(File.exist?(shim)).to be(true)
   end
 
   it "points bundler apps at the npm package instead of pinning" do