hibiki_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73beec766683bf4a92c8bebcb19b62e58686f50f68e3b16f0a958c2d0d155de1
+  data.tar.gz: 8ce7469020b298e4e94b7fa7daef8bafb5443a891fc90163339750f400aa9228
+SHA512:
+  metadata.gz: 3f5fc7f1fe7a4f72047d86e054612e9144e5815cc1a96d2fa87737573f9701ce2b2c6d713992822ee6cd90cae7b6cae5b4647bb6001b3f863dee2f38354ec131
+  data.tar.gz: 67f0275c2e22bd291fc8940f84a99775c9e1acac5e3542ffc68edd9c896e26f9e786270904bfa75029e78c872984560fdeca6499532f4128c4f65a1c420ab7b2

data/README.md

@@ -0,0 +1,252 @@
+# hibiki_rails
+
+Rails glue for [hibiki](https://github.com/planetaska/hibiki):
+connection-scoped signal graphs over ActionCable, pushing re-rendered HTML
+to the page — either through Turbo Streams, or over the channel's own
+subscription to the gem's packaged client (see "The packaged client").
+
+```
+cable action arrives → mutate signals → effects render partials →
+Turbo Streams broadcast → Turbo morphs the DOM
+```
+
+A graph lives per cable connection (in practice: per browser tab), built
+when the channel subscribes and disposed when it unsubscribes. Effects
+subscribe to whatever signals they read; when an action writes a signal,
+exactly the affected effects re-render and broadcast.
+
+Incubating inside the hibiki repo while the core gem is pre-release; will
+be extracted to its own repository once hibiki 0.1.0 ships and this API
+stabilizes. Rails >= 8.0 (what's tested), Ruby >= 3.4.
+
+## Usage
+
+```ruby
+class CounterChannel < ApplicationCable::Channel
+  include Hibiki::Rails::Channel
+
+  # Runs once on the graph's own thread, inside Hibiki.root.
+  def build_graph
+    @count = Hibiki::State.new(0)
+    @step  = Hibiki::State.new(1)
+    doubled = Hibiki::Derived.new { @count.value * 2 }
+
+    Hibiki::Effect.new do
+      broadcast_replace target: "count", partial: "counter/count",
+                        locals: { count: @count.value, doubled: doubled.value }
+    end
+    Hibiki::Effect.new do
+      broadcast_replace target: "step", partial: "counter/step",
+                        locals: { step: @step.value }
+    end
+  end
+
+  # Actions are plain methods that touch signals directly: each one runs
+  # on the graph thread inside one Hibiki.batch, so N writes still mean
+  # one re-run per affected effect.
+  def increment = @count.value += @step.value
+  def burst     = 10.times { @count.value += 1 }
+end
+```
+
+The page supplies a per-page-load graph id (`cid`) and listens on the
+matching stream:
+
+```erb
+<div data-controller="counter" data-counter-cid-value="<%= @cid %>">
+  <%= turbo_stream_from "counter", @cid %>
+  <%= render "count", count: 0, doubled: 0 %>  <%# placeholder, see below %>
+  ...
+</div>
+```
+
+with `@cid = SecureRandom.uuid` in the controller action. The channel
+broadcasts to `[channel_name, cid]` — override `stream_name` (and/or
+`cid`) to derive identity differently.
+
+## What the concern does
+
+- `subscribed` — rejects without a `cid` param, then runs `build_graph`
+  inside `Hibiki.root` on a dedicated worker thread (a `GraphActor`).
+  ActionCable dispatches on a thread pool with no per-channel ordering;
+  hibiki's threading model is confinement — so cable threads only enqueue,
+  and the graph lives on exactly one thread.
+- every action — the whole body is posted to that thread wrapped in one
+  `Hibiki.batch`. `rescue_from` still applies (it runs on the graph
+  thread); what it doesn't handle goes to `Rails.error` (source
+  `"hibiki_rails"`).
+- `unsubscribed` — disposes the root (running `on_cleanup` hooks) and
+  stops the worker, draining what was already queued.
+- dev reloading — an Engine hook disposes every live graph before code
+  reloads (stale effects would run old class versions forever); cable
+  clients auto-reconnect and rebuild. Graph state resets on reload, like
+  any remount.
+
+## Broadcast helpers
+
+Available inside effects (all bound to `stream_name`):
+
+- `broadcast_replace(target:, **rendering)` — `partial:`/`locals:`,
+  `html:`, or anything Turbo's renderer accepts.
+- `broadcast_morph(target:, **rendering)` — replace via Turbo 8 morphing
+  (keeps focus/scroll).
+- `broadcast_refresh` — tell the page to refresh itself.
+- `broadcast_refresh_effect(wait: 0.25) { ...read signals... }` — the
+  morph-everything style: tracks whatever the block reads and answers
+  changes with a debounced refresh, one per burst of actions rather than
+  one per action.
+
+## The packaged client
+
+The gem vendors its own JavaScript, turbo-rails-style: the engine puts
+`hibiki.js` on the app's asset path and merges the `"hibiki-rails"` pin into the
+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 create the one-line shim yourself:
+
+```js
+// 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.)
+
+The client is one generic Stimulus controller that drives any *island*: a
+DOM subtree bound to one channel subscription. Islands are stamped with
+the opt-in `Hibiki::Rails::Helpers` — include it where you want the bare
+names (`ApplicationHelper` for ERB, individual Phlex components); the gem
+never includes it for you:
+
+```erb
+<%= tag.div(**hibiki_island(TodosChannel, cid: @cid)) do %>
+  <%= render TodoList.new %>  <%# placeholder; replaced by DOM id %>
+  <%= tag.form(**on(:add, event: :submit)) do %>
+    <input type="text" name="title">
+    <button>add</button>
+  <% end %>
+<% end %>
+```
+
+- `hibiki_island(channel, cid:)` — the island root: one subscription,
+  identified by the page's `cid`.
+- `on(action, event:, with:)` — forward a DOM event (`:click` default,
+  `:change`, `:submit`) as a channel action, with `with:` as its payload.
+  A changed control also sends `{ name => value }`; a submitted form sends
+  its FormData and is reset after performing.
+
+Transport is the channel's own subscription in both directions: render
+effects call `transmit({ html: })` and the client swaps each fragment in
+by its root DOM id (`Hibiki::Phlex.render_effect` pairs naturally):
+
+```ruby
+def build_graph
+  @list = TodoList.new
+  Hibiki::Phlex.render_effect(@list) { |html| transmit({ html: }) }
+end
+```
+
+Because the client registers its `received` callback at subscribe time —
+before the server ever runs `build_graph` — the effects' first transmits
+always land: no Turbo stream, no connected-wait, and the server-rendered
+initial HTML is only a paint-avoidance placeholder. One rule carries over
+from any replace-fragment design: never transmit a fragment containing
+the input the user is currently typing in.
+
+The `data-hibiki-*` attributes the helpers emit are a private contract
+with the vendored JS — they version together; don't hand-write them in
+app code. The protocol itself is Stimulus-free (Stimulus only hosts the
+controller lifecycle), so a hand-rolled client can drive the same
+attributes: `toy-phlex/` in the parent repo does it in ~40 lines. The
+helper interface's shape is inspired by
+[phlex-reactive](https://phlex-reactive.zoolutions.llc)'s `on(...)`
+actions.
+
+## Generators
+
+Each supported shape has a generator that scaffolds it as a *working*
+mini-example — one state, one derived, one action, one effect; run it,
+render the output from any page, click `+1`, watch it live-update — meant
+to be reshaped in place, not filled in from scratch:
+
+```sh
+bin/rails g hibiki:rails:install                  # one-time wiring: register line,
+                                                  # Helpers include, ApplicationCable
+                                                  # boilerplate + actioncable pin
+                                                  # (idempotent)
+bin/rails g hibiki:rails:stimulus NAME [VIEW_PATH]  # channel + ChannelController
+                                                    # subclass + view partial
+bin/rails g hibiki:rails:island NAME [VIEW_PATH]    # channel + helpers-stamped view
+                                                    # partial, no per-component JS
+bin/rails g hibiki:rails:phlex NAME                 # channel + Phlex component +
+                                                    # island wrapper (needs hibiki_phlex)
+```
+
+`VIEW_PATH` is the views directory under `app/views` (defaults to `NAME`);
+the emitted partial is self-contained (`cid` defaults to a per-render
+uuid), so `<%= render "counter/counter" %>` — or `<%= render
+CounterIsland.new %>` for the Phlex shape — is the only line a page needs.
+The `stimulus` shape works with zero wiring; `island` and `phlex` need the
+one-time `hibiki:rails:install` (they print a hint when it's missing).
+Namespaced names work (`admin/counter` pins `static channel` where the
+Stimulus identifier can't infer it). In apps without an importmap
+(jsbundling/vite), where `controllers/index.js` has no eager loader, the
+`stimulus` generator also appends the controller's import/register pair
+to it — the same lines `stimulus:manifest:update` would emit.
+
+## The initial-state pattern (Turbo transport)
+
+Islands on the Turbo-broadcast transport instead (the "Usage" example
+above) have an ordering problem the transmit transport doesn't: the
+graph's effects do their first run inside `subscribed` — usually before
+the page's `turbo_stream_from` subscription has confirmed — so the first
+broadcast would be lost. Fix the ordering on the client with the packaged
+`streamConnected` helper: wait for Turbo to stamp the `connected`
+attribute on the stream source, then subscribe the graph channel.
+
+```js
+// in the Stimulus controller driving the channel
+import { streamConnected } from "hibiki-rails"
+
+async connect() {
+  this.consumer = createConsumer()
+  await streamConnected(this.element.querySelector("turbo-cable-stream-source"))
+  this.subscription = this.consumer.subscriptions.create(
+    { channel: "CounterChannel", cid: this.cidValue }, {}
+  )
+}
+```
+
+With that in place the server-rendered initial HTML is only a
+paint-avoidance placeholder — the first broadcast always lands and
+replaces it, so it doesn't have to match the graph's initial state.
+
+## Error handling layers
+
+1. `rescue_from` on the channel — handles action errors, on the graph
+   thread.
+2. `Hibiki.error_handler = ->(error, effect) { ... }` — app-level routing
+   for effect errors raised during a flush (the gem does not set this).
+3. The graph worker's per-job rescue — everything unhandled lands in
+   `Rails.error.report(..., source: "hibiki_rails")`. Override per channel
+   via `build_graph_actor` and `GraphActor.new(on_error:)`.
+
+## Development
+
+```
+bundle exec rake   # specs + rubocop (same as CI)
+```
+
+The spec suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`);
+the live end-to-end proof app is `spike/` in the parent repo.

data/app/assets/javascripts/hibiki.js

@@ -0,0 +1,231 @@
+// The packaged client for hibiki_rails. Two shapes, one plumbing:
+//
+// 1. The generic controller (HibikiController, register as "hibiki"):
+//    drives any island stamped by the Hibiki::Rails::Helpers Ruby
+//    helpers. Stimulus is the lifecycle host only (connect/disconnect
+//    across Turbo navigation, morphs, and dynamic insertion); the wire
+//    protocol is hibiki-owned data attributes, so server-side components
+//    never write Stimulus vocabulary and a non-Stimulus client can speak
+//    the same attributes (toy-phlex's vanilla driver is the proof).
+// 2. The subclassable base (ChannelController): for apps that prefer the
+//    familiar Stimulus structure (data-controller="counter",
+//    data-action="counter#increment"). The base owns the consumer, the
+//    subscription lifecycle, and transport handling; plain actions are
+//    auto-forwarded to the channel, so a subclass only declares a method
+//    when it needs something custom:
+//
+//      import { ChannelController } from "hibiki-rails"
+//
+//      // identifier "counter" infers CounterChannel (override with
+//      // `static channel = "..."` when the names don't line up)
+//      export default class extends ChannelController {
+//        setStep(event) {
+//          this.perform("set_step", { step: event.target.value })
+//        }
+//      }
+//
+// Both shapes speak both transports. Transmit: the server's render
+// effects `transmit({ html: })` fragments that are swapped in by their
+// root DOM id; `received` is registered at subscribe time — before the
+// server runs build_graph — so the effects' first transmits always land
+// (the server-rendered initial HTML is only a paint-avoidance
+// placeholder). Turbo broadcasts: when the controller's element contains
+// its own <turbo-cable-stream-source> (turbo_stream_from), the graph's
+// first broadcast is lost unless that stream has already confirmed ITS
+// subscription — so connect awaits it (streamConnected) before
+// subscribing, and rendering flows back over the Turbo stream while
+// `received` stays idle.
+//
+// The attribute contract of the generic controller (private to this gem —
+// emitted by the Ruby helpers, interpreted here, versioned together):
+//
+//   island root   data-controller="hibiki"
+//                 data-hibiki-channel-value="CounterChannel"
+//                 data-hibiki-cid-value="<per-page-load id>"
+//   controls      data-hibiki-on="<event>-><action>"   e.g. "click->increment"
+//                 data-hibiki-with='{"index":3}'       optional JSON payload
+//
+// Register the generic controller under the identifier "hibiki" (the
+// helpers hardcode it):
+//
+//   import HibikiController from "hibiki-rails"
+//   application.register("hibiki", HibikiController)
+import { Controller } from "@hotwired/stimulus"
+import { createConsumer } from "@rails/actioncable"
+
+// One consumer shared by every controller — ActionCable multiplexes
+// subscriptions over a single websocket. Never disconnected: islands come
+// and go with the DOM, the socket stays.
+let consumer
+
+// camelCase Stimulus method name → snake_case Ruby channel action.
+const underscore = (name) => name.replace(/([A-Z])/g, "_$1").toLowerCase()
+
+// The subclassable base: one channel subscription per controller element,
+// identified by a per-page-load cid (data-<identifier>-cid-value).
+export class ChannelController extends Controller {
+  static values = { cid: String }
+
+  async connect() {
+    this.aborted = false
+    consumer ??= createConsumer()
+    this.defineForwarders()
+    // Turbo-broadcast transport: wait for the element's own stream source
+    // to confirm before subscribing, so the graph's dependency-collecting
+    // first run broadcasts into a live stream. No source (transmit
+    // transport) → this path is fully synchronous, exactly as before.
+    const source = this.streamSource()
+    if (source) await streamConnected(source)
+    if (this.aborted) return // disconnected during the await
+    this.subscription = consumer.subscriptions.create(
+      { channel: this.channelName(), cid: this.cidValue },
+      { received: (data) => this.received(data) }
+    )
+  }
+
+  disconnect() {
+    this.aborted = true
+    this.subscription?.unsubscribe()
+    this.subscription = undefined
+  }
+
+  // DOM → server: what declared action methods call.
+  perform(action, payload = {}) {
+    this.subscription.perform(action, payload)
+  }
+
+  // Server → DOM (transmit transport): swap each transmitted fragment in
+  // by its root id. Broadcast-transport channels never transmit, and a
+  // non-html transmit is not ours to interpret. Subclasses may override.
+  received({ html }) {
+    if (!html) return
+    const template = document.createElement("template")
+    template.innerHTML = html
+    for (const fragment of [...template.content.children]) {
+      document.getElementById(fragment.id)?.replaceWith(fragment)
+    }
+  }
+
+  // `static channel = "..."` wins; otherwise infer Rails-style from the
+  // identifier: "counter" → CounterChannel, "my-thing" → MyThingChannel.
+  channelName() {
+    if (this.constructor.channel) return this.constructor.channel
+    const pascal = this.identifier
+      .split(/[-_]/)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join("")
+    return `${pascal}Channel`
+  }
+
+  // Auto-forwarding: every data-action token addressed to this identifier
+  // whose method the subclass did NOT declare gets a generated forwarder
+  // that performs the underscored action with no payload — so plain
+  // forwards need zero code. Declared methods always win. Methods are
+  // defined at connect: action NAMES first appearing in later-inserted
+  // markup aren't discovered (names already seen keep working anywhere,
+  // Stimulus binds the elements itself).
+  defineForwarders() {
+    for (const control of this.element.querySelectorAll("[data-action]")) {
+      for (const token of control.dataset.action.trim().split(/\s+/)) {
+        const method = this.forwardableMethod(token)
+        if (method && typeof this[method] !== "function") {
+          this[method] = () => this.perform(underscore(method))
+        }
+      }
+    }
+  }
+
+  // Token forms: "identifier#method", "event->identifier#method", plus
+  // trailing :options — returns the method name, or null when the token
+  // addresses another controller.
+  forwardableMethod(token) {
+    const descriptor = token.includes("->") ? token.split("->")[1] : token
+    const [identifier, method] = descriptor.split("#")
+    if (identifier !== this.identifier || !method) return null
+    return method.split(":")[0]
+  }
+
+  // The element's own <turbo-cable-stream-source>, if any. Scoped like
+  // forward() below: a nested controller's source belongs to IT.
+  streamSource() {
+    return [...this.element.querySelectorAll("turbo-cable-stream-source")].find(
+      (s) => s.closest(`[data-controller~="${this.identifier}"]`) === this.element
+    )
+  }
+}
+
+// The generic controller: adds the data-hibiki-* wire protocol on top of
+// the base's plumbing.
+export default class HibikiController extends ChannelController {
+  static values = { channel: String } // cid inherited from the base
+
+  // The island stamps its channel; no inference.
+  channelName() {
+    return this.channelValue
+  }
+
+  async connect() {
+    // Root-scoped delegation (bound to the island, not document): controls
+    // inside server-replaced fragments keep working with no rebinding.
+    // Set up synchronously so disconnect can always tear them down.
+    this.listeners = ["click", "change", "submit"].map((type) => {
+      const handler = (event) => this.forward(event)
+      this.element.addEventListener(type, handler)
+      return [type, handler]
+    })
+    await super.connect()
+  }
+
+  disconnect() {
+    for (const [type, handler] of this.listeners) {
+      this.element.removeEventListener(type, handler)
+    }
+    super.disconnect()
+  }
+
+  // DOM → server: forward a control's event as a channel action. Nested
+  // islands: events bubble to every ancestor island's listener, so each
+  // controller only acts when the control belongs to ITS island.
+  forward(event) {
+    const control = event.target.closest("[data-hibiki-on]")
+    if (!control) return
+    if (control.closest('[data-controller~="hibiki"]') !== this.element) return
+
+    const token = control.dataset.hibikiOn
+      .split(/\s+/)
+      .find((t) => t.startsWith(`${event.type}->`))
+    if (!token) return
+
+    const action = token.slice(event.type.length + 2)
+    const payload = control.dataset.hibikiWith
+      ? JSON.parse(control.dataset.hibikiWith)
+      : {}
+    if (event.type === "submit") {
+      event.preventDefault()
+      Object.assign(payload, Object.fromEntries(new FormData(control)))
+    } else if (event.type === "change" && control.name) {
+      payload[control.name] = control.value
+    }
+    this.perform(action, payload)
+    if (event.type === "submit") control.reset()
+  }
+}
+
+export { HibikiController }
+
+// The Turbo-broadcast race helper the base uses internally, still
+// exported for custom (non-Stimulus) clients: resolves once Turbo stamps
+// the `connected` attribute on the given <turbo-cable-stream-source>.
+export function streamConnected(element) {
+  if (element.hasAttribute("connected")) return Promise.resolve()
+
+  return new Promise((resolve) => {
+    const observer = new MutationObserver(() => {
+      if (element.hasAttribute("connected")) {
+        observer.disconnect()
+        resolve()
+      }
+    })
+    observer.observe(element, { attributeFilter: ["connected"] })
+  })
+}

data/config/importmap.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Merged into the host app's import map by the Engine's importmap
+# initializer (importmap-rails reads every path in config.importmap.paths).
+# The app supplies the "@hotwired/stimulus" and "@rails/actioncable" pins —
+# both are part of the Rails 8 default stack.
+pin "hibiki-rails", to: "hibiki.js"

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Hibiki
+  module Rails
+    module Generators
+      # Shared naming and wiring-detection helpers for the hibiki:rails:*
+      # generators. The naming helpers ride on NamedBase's name parts
+      # (regular_class_path / file_name); the wiring predicates only need
+      # 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"
+
+        private
+
+        # First streamable of the concern's [channel_name, cid] convention:
+        # ActionCable's channel_name for Admin::CounterChannel is
+        # "admin:counter".
+        def stream_name = name_parts.join(":")
+
+        # The Stimulus identifier Rails derives from
+        # app/javascript/controllers/<file_path>_controller.js.
+        def identifier = name_parts.join("--").tr("_", "-")
+
+        # Root id of the replaced fragment — namespaced with the component's
+        # own name so several generated islands can share a page.
+        def display_dom_id = "#{name_parts.join('_')}_display"
+
+        def nested? = !regular_class_path.empty?
+
+        def name_parts = regular_class_path + [file_name]
+
+        # 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")
+
+        # importmap-rails apps eager-load the controllers directory;
+        # jsbundling apps register each controller in index.js by hand.
+        def importmap? = exists?(IMPORTMAP)
+
+        def exists?(path) = File.exist?(File.join(destination_root, path))
+
+        def wired?(path, fragment)
+          full = File.join(destination_root, path)
+          File.exist?(full) && File.read(full).include?(fragment)
+        end
+
+        def manual_wiring(path, snippet)
+          say_status :skip, "#{path} not found — add this yourself:", :yellow
+          say snippet
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require_relative "../generator_helpers"
+
+module Hibiki
+  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 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
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Wires the packaged hibiki client: registers the \"hibiki\" Stimulus " \
+             "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
+
+          import HibikiController from "./hibiki_controller"
+          application.register("hibiki", HibikiController)
+        JS
+
+        INCLUDE_LINE = "  include Hibiki::Rails::Helpers\n"
+
+        # Stock Rails apps don't have these until the first `rails g
+        # channel` — the hibiki:rails:* generators write their channels
+        # directly, so install supplies the boilerplate they inherit.
+        APPLICATION_CABLE = {
+          "channel.rb.tt" => "app/channels/application_cable/channel.rb",
+          "connection.rb.tt" => "app/channels/application_cable/connection.rb"
+        }.freeze
+
+        # Same event: the stock importmap has no @rails/actioncable pin
+        # until the first `rails g channel` adds it. The packaged client
+        # imports it, so pin it here (the asset ships in actioncable).
+        PIN = <<~RUBY
+
+          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 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
+        end
+
+        def include_helpers
+          return say_status :identical, APPLICATION_HELPER, :blue if helpers_included?
+          return manual_wiring(APPLICATION_HELPER, INCLUDE_LINE) unless exists?(APPLICATION_HELPER)
+
+          inject_into_file APPLICATION_HELPER, INCLUDE_LINE,
+                           after: /module ApplicationHelper\s*\n/
+        end
+
+        # Presence is enough — an app's own ApplicationCable (customized
+        # or not) is never touched.
+        def create_application_cable
+          APPLICATION_CABLE.each do |source, destination|
+            next say_status :exist, destination, :blue if exists?(destination)
+
+            template source, destination
+          end
+        end
+
+        def pin_actioncable
+          return bundler_note unless importmap?
+          return say_status :identical, IMPORTMAP, :blue if wired?(IMPORTMAP, "@rails/actioncable")
+
+          append_to_file IMPORTMAP, PIN
+        end
+
+        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 " \
+                            "@rails/actioncable)", :yellow
+        end
+      end
+    end
+  end
+end

data/lib/generators/hibiki/rails/install/templates/channel.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Stock ActionCable boilerplate (`rails g channel` would create the same
+# file) — the hibiki:rails:* generators emit channels that inherit it.
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end