hibiki_rails 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc32112018a236bbd193028d2fe6a0c0650afd04cf8e6de5f26d84bed7de97a
-  data.tar.gz: 15fcf11847178df9f355279f7666b064a557ee5ebd0647f24373aeb638fb0131
+  metadata.gz: 514349fcd04fc813cc4833144b4355c56958e9055dda33aefbdc547517d73bfd
+  data.tar.gz: 1a9729ad926d72f9bdfb1b4411544893f59c3ebb40d2dd552165bed1299218e5
 SHA512:
-  metadata.gz: cf0c15e56804599427b2c9ee2e323118ed2dc6decb1862c1765544535313cf49587997375370cfa335db4b2a32cfb8b33dae6f81ffa8870cf73c99af418cc098
-  data.tar.gz: 7dd41bb7197cc96a93a9b878ab41ee02b33a18830ecdb8f8926193529cc2c890ca6336eaca1c9eb71f0963262251d07be77895dda03cfd954ae4483a7968fdf6
+  metadata.gz: eb8e0207e6b1281f7085e7258a9ed189f836b0427ea3172acf3711b118f80f1a0a8fa97474d5f4ff4deaf69ef0bec8d6083f3b09a3ee1178cb836335453f3d76
+  data.tar.gz: 1f4c370144b71c7baea0b3960d69d761b562f6590f281b079f1bf9a26173e7d83c415e262924030e02e4d5bd62876eab7b62c2a12b8a145298ea1d60ff2a5480

data/CHANGELOG.md

@@ -4,6 +4,61 @@ The gem and the npm package are released in lockstep and share these version
 numbers — `app/assets/javascripts/hibiki.js` is a single copy served both ways,
 so importmap and bundler apps always resolve identical client code.
 
+## 0.12.0 — 2026-09-06
+
+### Added
+
+**`island` — the ERB block helper for the island root.** One call
+generates the cid, stamps the root with `hibiki_island`, and derives the
+channel's `turbo_stream_from` inside it:
+
+```erb
+<%= island CounterChannel do |cid| %>
+  ...
+<% end %>
+```
+
+- `cid:` defaults to a fresh UUID; the block receives it either way.
+- The stream source is derived from the channel class
+  (`turbo_stream_from channel.channel_name, cid`), so renaming the channel
+  cannot leave a hand-typed streamable behind. `transport: :transmit`
+  leaves it out: for a channel that transmits, or one that overrides
+  `stream_name` and writes its own line in the block. (`:broadcast` is the
+  default; the option is a named value rather than a boolean so it cannot
+  be mistaken for Turbo's own `data-turbo="false"`.)
+- `params:` passes through; `tag_name:` picks the root element; any other
+  keyword lands on it, with a `data:` hash merged beneath the island's own
+  keys.
+- Class-only (`constantize` a dynamic name at the call site) and ERB-only
+  (it needs ActionView's `capture`). Phlex components keep
+  `div(**hibiki_island(...))`, which remains the primitive.
+
+Generators are unchanged: their output keeps the explicit three-line form.
+No client change; the npm release is the lockstep bump.
+
+## 0.11.0 — 2026-09-05
+
+### Changed
+
+**The client rides turbo-rails' Action Cable consumer.** `hibiki.js` now
+takes its consumer from `cable.getConsumer()` (exported by
+`@hotwired/turbo-rails`) instead of importing `@rails/actioncable` itself.
+Islands and `turbo_stream_from` share ONE websocket where each page used to
+open two, an app's `cable.setConsumer(...)` applies to islands too, and the
+library stops reaching the page twice: bundler apps shed the second copy
+(~14.6 KB; turbo-rails imports `@rails/actioncable/src`, the client imported
+the package root, and a bundler cannot dedupe two specifiers), importmap apps
+stop fetching `actioncable.esm.js` next to the copy `turbo.min.js` already
+carries (~14.8 KB, one request).
+
+- npm: the `@rails/actioncable` peer dependency is gone; `@hotwired/turbo-rails
+  >= 8.0` is the peer instead (every Rails 8 app has it).
+- `hibiki:rails:install` no longer pins `@rails/actioncable`. An existing pin
+  is harmless — nothing imports it — and may be deleted.
+- Subscribing now awaits the consumer once (a microtask after the first
+  island); nothing observable changes, actions are still queued until the
+  subscription confirms.
+
 ## 0.10.0 — 2026-08-22
 
 ### Added

data/README.md

@@ -157,7 +157,7 @@ A few things that make a change easier to accept:
 
 The gem side needs nothing special: point an app's Gemfile at your clone with `gem "hibiki_rails", path: "../hibiki-rails"`.
 
-The npm side has one trap. `bun link` from an app resolves the linked package's own imports from the **symlink's realpath**, not from the app — so `hibiki.js` looks for `@rails/actioncable` inside your checkout rather than inside the app that linked it, and if the checkout has no `node_modules` the import fails at build time with nothing pointing at the cause.
+The npm side has one trap. `bun link` from an app resolves the linked package's own imports from the **symlink's realpath**, not from the app — so `hibiki.js` looks for `@hotwired/turbo-rails` and `@hotwired/stimulus` inside your checkout rather than inside the app that linked it, and if the checkout has no `node_modules` the import fails at build time with nothing pointing at the cause.
 
 ```sh
 cd hibiki-rails && bun install   # before linking, not after

data/app/assets/javascripts/hibiki.js

@@ -1,17 +1,16 @@
 // The packaged client for hibiki_rails. Two shapes, one plumbing:
 //
-// 1. The generic controller (HibikiController, register as "hibiki"):
+// 1. The generic controller (HibikiController, registered as "hibiki"):
 //    drives any island stamped by the Hibiki::Rails::Helpers Ruby
-//    helpers. Stimulus is the lifecycle host only (connect/disconnect
+//    helpers. Stimulus is only the lifecycle host (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
+//    never write Stimulus vocabulary.
+// 2. The subclassable base (ChannelController): for apps that prefer
 //    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
+//    subscription lifecycle, and transport handling. Plain actions are
+//    auto-forwarded to the channel; a subclass declares a method only
 //    when it needs something custom:
 //
 //      import { ChannelController } from "hibiki-rails"
@@ -27,18 +26,17 @@
 // Both shapes speak both transports. Transmit: the server's render
 // effects `transmit({ html: })` fragments that are swapped in by their
 // root DOM id, and `transmit_value` messages that update every
-// data-hibiki-value placeholder; `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.
+// data-hibiki-value placeholder. `received` is registered at subscribe
+// time, before the server runs build_graph, so the effects' first
+// transmits always land; the server-rendered HTML fills the space only
+// until they do. 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 —
+// The generic controller's attribute contract (private to this gem —
 // emitted by the Ruby helpers, interpreted here, versioned together):
 //
 //   island root   data-controller="hibiki"
@@ -60,25 +58,24 @@
 //   value sites   data-hibiki-value="<name>"           reactive-value placeholder;
 //                 the server's transmit_value message updates every match
 //
-// The protocol also has a client-written half — the first attributes in it
-// that no Ruby helper emits. These are stamped here at runtime and are
-// read-only to app code; app CSS is their whole audience:
+// The client writes the protocol's other half at runtime — read-only to
+// app code, addressed to app CSS:
 //
 //   island root   data-hibiki-busy       present while an action is in flight
 //                 aria-busy="true"       the same fact, for assistive tech
 //                 data-hibiki-state      connecting | ready | offline | stalled
 //   firing control data-hibiki-busy      on the control that started it
 //
-// Everything the app wants out of that is a descendant selector —
-// `[data-hibiki-busy] .spinner { display: inline-block }` — so per-row and
-// per-button feedback needs no server state and no `{#if loading}` branch.
-// Content is stale during a round trip, never absent.
+// App CSS reaches all of it with descendant selectors —
+// `[data-hibiki-busy] .spinner { display: inline-block }` — so per-row
+// and per-button feedback needs no server state. Content is stale during
+// a round trip, never absent.
 //
-// The left side of `->` is a hibiki event name, of which DOM events are a
-// subset: click, change, input, submit are delegated listeners, and
-// `visible` is a pseudo-event backed by an IntersectionObserver (the
-// element entering the viewport). Everything that is not "which event"
-// is a sibling attribute, so the token grammar never has to grow.
+// The left side of `->` is a hibiki event name: click, change, input,
+// and submit are delegated DOM listeners; `visible` is a pseudo-event
+// backed by an IntersectionObserver (the element entering the viewport).
+// Everything that is not "which event" is a sibling attribute, so the
+// token grammar never has to grow.
 //
 // App JS reaching the graph — the ONE public seam. A gesture that needs
 // script (drag-and-drop, a third-party widget) fires its action through
@@ -96,19 +93,18 @@
 //   import { performOn } from "hibiki-rails"
 //   performOn(element, "nested_move", { path, to })
 //
-// The return value is the whole contract: truthy (the trip's seq) means
-// the action was ACCEPTED — sent live, or queued during the initial
-// connect window — so a repaint is coming and the caller should leave the
-// DOM as the user arranged it (the morph lands as a visual no-op). Falsy
-// (undefined) means it was DROPPED — the island is offline, or the socket
-// turned out to be dead at send — and the caller owns recovery: revert
-// the gesture, or stand back and let the next repaint self-heal. Nothing
-// queues across an offline gap on purpose (a reconnect builds a fresh
-// server-side graph, so replayed intent would land on state it was not
-// formed against). Everything else is NOT a seam: the data-hibiki-*
-// attributes are private, and subclassing ChannelController to reach an
-// existing island opens a SECOND subscription — a second server-side
-// graph nobody paints from.
+// The return value is the whole contract. Truthy (the trip's seq): the
+// action was ACCEPTED — sent live, or queued during the initial connect
+// window — a repaint is coming, so leave the DOM as the user arranged it
+// and let the morph land as a visual no-op. Falsy (undefined): it was
+// DROPPED — the island is offline, or the socket was dead at send — and
+// the caller owns recovery: revert the gesture, or let the next repaint
+// self-heal. Nothing queues across an offline gap, on purpose: a
+// reconnect builds a fresh server-side graph, so replayed intent would
+// land on state it was not formed against. Everything else is NOT a
+// seam: the data-hibiki-* attributes are private, and subclassing
+// ChannelController to reach an existing island opens a SECOND
+// subscription — a second server-side graph nobody paints from.
 //
 // Register the generic controller under the identifier "hibiki" (the
 // helpers hardcode it):
@@ -116,11 +112,16 @@
 //   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.
+import { cable } from "@hotwired/turbo-rails"
+
+// One consumer shared by every controller — and with Turbo Streams: it is
+// turbo-rails' own (`cable.getConsumer()`), so islands and
+// `turbo_stream_from` multiplex over ONE websocket, and an app's
+// `cable.setConsumer(...)` applies to both. Never disconnected: islands
+// come and go with the DOM, the socket stays. Importing turbo-rails'
+// consumer rather than @rails/actioncable also keeps the library out of
+// the page twice (turbo-rails bundles it by a subpath specifier that no
+// importmap can serve).
 let consumer
 
 // Live islands by root element, for performOn's ancestor walk — membership
@@ -165,12 +166,12 @@ const formPayload = (form) => {
 }
 
 // Before a fallback form goes native, re-stamp its CSRF token from the
-// page's csrf-token meta — which is first-paint fresh and session-valid.
-// Server-side repaints render without a session (ApplicationController
-// .render has none), so a repainted form embeds a stale token or none at
-// all; and this only ever runs with scripts alive, which is exactly when
-// the DOM may have been repainted. A truly script-free page still holds
-// its first-paint token and never needed the help.
+// page's csrf-token meta tag, which is first-paint fresh and
+// session-valid. Server-side repaints render without a session
+// (ApplicationController.render has none), so a repainted form embeds a
+// stale token or none at all. This only runs with scripts alive —
+// exactly when the DOM may have been repainted; a script-free page
+// still holds its first-paint token.
 const freshenToken = (control) => {
   if (!(control instanceof HTMLFormElement)) return
   const meta = document.querySelector('meta[name="csrf-token"]')
@@ -191,21 +192,17 @@ export class ChannelController extends Controller {
   static values = { cid: String }
 
   // Transport-state timings. Class properties on purpose: not Stimulus
-  // values and not helper options, so the Ruby surface stays unchanged and
-  // an island stamps nothing about them. An app that wants different
+  // values and not helper options, so the Ruby surface stays unchanged
+  // and an island stamps nothing about them. An app that wants different
   // numbers subclasses and re-registers.
   //
-  // busyDelay   ms before a round trip is worth mentioning. A localhost
-  //             trip measures 18–25 ms, so 150 suppresses that flicker
-  //             outright while a 150 ms-RTT link crosses it about exactly.
-  //             Borrowed from Turbo's progress bar, which waits ~500 ms.
+  // busyDelay   ms before a round trip is worth mentioning — long enough
+  //             to swallow a localhost trip (18–25 ms) without flicker.
   // busyGrace   ms to wait after an ack for a Turbo render still in
-  //             flight. The ack travels the island's own socket; a
-  //             broadcast takes a pubsub hop, and measured against
-  //             generated output the direct frame beats the paint by
-  //             3.3–3.6 ms. That gap belongs to the server and its
-  //             backend, so it does not shrink on a fast link — and Redis
-  //             widens it. Hence a bound in tens of ms, not single digits.
+  //             flight. The ack rides the island's own socket while the
+  //             broadcast takes a pubsub hop, so the ack routinely wins
+  //             by a few ms — a gap owned by the server's backend, which
+  //             no fast link shrinks. Hence tens of ms, not single digits.
   // busyCeiling ms before a trip is declared stalled rather than silently
   //             cleared. On a bad link "we lost it" beats "nothing
   //             happened".
@@ -220,11 +217,10 @@ export class ChannelController extends Controller {
 
   // The synchronous half of connect: everything a listener firing in the
   // next millisecond depends on. HibikiController attaches its delegated
-  // listeners before openSubscription is even called, and the window
-  // before the subscription confirms is ~3 serialised round trips on the
-  // Turbo-broadcast path (Turbo's own subscribe, a SECOND websocket
-  // handshake, then ours) — tens of ms on localhost, about a second on a
-  // real remote link. Clicks in it used to vanish without a trace.
+  // listeners before openSubscription is even called, and on the
+  // Turbo-broadcast path the subscription takes ~3 serialised round
+  // trips to confirm — up to a second on a real link. Clicks in that
+  // window used to vanish without a trace.
   prepareTransport() {
     this.aborted = false
     this.subscribed = false
@@ -237,15 +233,16 @@ export class ChannelController extends Controller {
   }
 
   async openSubscription() {
-    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.
+    // transport) → only the consumer await below, a microtask once it
+    // exists (turbo-rails memoizes it).
     const source = this.streamSource()
     if (source) await streamConnected(source)
-    if (this.aborted) return // disconnected during the await
+    consumer ??= await cable.getConsumer()
+    if (this.aborted) return // disconnected during the awaits
     this.subscription = consumer.subscriptions.create(this.subscribeParams(), {
       received: (data) => this.handleMessage(data),
       connected: () => this.linkOpened(),
@@ -274,24 +271,23 @@ export class ChannelController extends Controller {
   // can never overwrite it. (`hbk` is the second reserved payload key —
   // ActionCable's own Subscription#perform already writes `action`.)
   //
-  // Returns the seq so a caller that knows which control fired can attach
-  // it; nobody has to. Returns undefined instead when the payload went
-  // nowhere: the socket turned out to be closed under a subscription still
-  // believed live, or the island was already offline. Public API on the
-  // island controller (the header's "App JS reaching the graph") — truthy
-  // = accepted, falsy = dropped and the caller owns recovery.
+  // Public API on the island controller (the header's "App JS reaching
+  // the graph"). Returns the seq when the action was accepted, so a
+  // caller that knows which control fired can attach it; returns
+  // undefined when the payload went nowhere — the socket turned out to
+  // be closed, or the island was already offline — and the caller owns
+  // recovery.
   perform(action, payload = {}) {
     const seq = ++this.seq
     payload.hbk = seq
     if (this.subscribed) {
       this.beginBusy(seq)
-      // Action Cable's Subscription#perform returns false when the socket
-      // is not open — the gap between the socket dying and the connection
-      // monitor noticing, during which `subscribed` still says live. The
-      // frame went nowhere: settle rather than letting the trip stall out
-      // at the ceiling, and stamp `offline` now instead of when the
-      // monitor catches up. The monitor still owns reconnecting; its
-      // `connected` callback restores `ready` exactly as after a real gap.
+      // Subscription#perform returns false when the socket is not open —
+      // the gap between the socket dying and the connection monitor
+      // noticing, during which `subscribed` still says live. The frame
+      // went nowhere: settle the trip rather than let it stall out at
+      // the ceiling, and stamp `offline` now instead of when the monitor
+      // catches up. The monitor still owns reconnecting.
       if (this.subscription.perform(action, payload) === false) {
         this.settle(seq)
         this.linkClosed()
@@ -299,19 +295,17 @@ export class ChannelController extends Controller {
       }
       return seq
     }
-    // Queue rather than drop while the subscription is still coming up.
-    // ActionCable's Subscription#perform silently returns false on a socket
-    // that is not open yet, so this was a silent no-op for the whole
-    // connect window — and the trigger has to be the `connected` callback,
-    // not "the subscription object exists", because the second websocket's
-    // handshake sits between the two.
+    // Queue rather than drop while the subscription is still coming up:
+    // Subscription#perform silently returns false on a socket not open
+    // yet, so the whole connect window used to be a silent no-op. The
+    // gate must be the `connected` callback, not "the subscription
+    // object exists" — the second websocket's handshake sits between
+    // the two.
     //
-    // Only that first window. Once the link has been up, a gap means the
-    // socket dropped, and reconnecting builds a FRESH graph server-side
-    // with default state — so replaying intent formed against the old one
-    // is worse than dropping it. The island is stamped `offline` for the
-    // whole gap, which is the signal the connect window cannot give: there
-    // the page is painted and looks live.
+    // Only that first window. Once the link has been up, a gap means
+    // the socket dropped, and the island is stamped `offline` for the
+    // whole gap — the signal the connect window cannot give, where the
+    // page is painted and looks live.
     if (!this.connectedOnce) {
       this.beginBusy(seq)
       this.queued.push([action, payload])
@@ -336,10 +330,10 @@ export class ChannelController extends Controller {
   linkClosed() {
     this.subscribed = false
     this.setState("offline")
-    // Deliberately NOT queued across the gap. A reconnect builds a fresh
-    // graph server-side with default state, so replaying intent formed
-    // against the old one is worse than dropping it. Outstanding records
-    // settle for the same reason: their acks are never coming.
+    // Deliberately NOT queued across the gap: a reconnect builds a fresh
+    // graph server-side, so replayed intent would land on state it was
+    // not formed against. Outstanding records settle for the same
+    // reason — their acks are never coming.
     this.queued = []
     this.settleAll()
   }
@@ -505,10 +499,10 @@ export class ChannelController extends Controller {
   // 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).
+  // forwards need zero code. Declared methods always win. Forwarders are
+  // defined at connect, so an action NAME first appearing in
+  // later-inserted markup isn't discovered; a name already seen keeps
+  // working anywhere, because 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+/)) {
@@ -563,9 +557,9 @@ export default class HibikiController extends ChannelController {
     islands.set(this.element, this)
     // Before the listeners, not after: a click delegated in the next
     // millisecond reaches perform(), which needs the busy map and the
-    // queue to exist. This is also what stamps data-hibiki-state
-    // ="connecting" synchronously, so the island can be dimmed for the
-    // whole window rather than from the middle of it.
+    // queue to exist. This also stamps data-hibiki-state="connecting"
+    // synchronously, so the island can be dimmed for the whole window
+    // rather than from the middle of it.
     this.prepareTransport()
 
     // Root-scoped delegation (bound to the island, not document): controls
@@ -674,13 +668,12 @@ export default class HibikiController extends ChannelController {
     // A fallback control's native behavior IS the degraded path: unless
     // the island is `ready`, stand aside — no perform, no queueing — and
     // the browser follows the href or submits the form to its own
-    // action=. Deliberately not the connect-window queue: a queued gesture
-    // renders nothing until the link comes up, while the control's
-    // destination answers immediately. Two touches before stepping back:
-    // a confirm: still gates the native behavior (scripts are running, so
-    // a destructive submit must not slip past the dialog), and a form's
-    // authenticity_token is freshened — server-rendered repaints carry no
-    // session, so their forms embed a stale token or none at all.
+    // action=. Deliberately not the connect-window queue: a queued
+    // gesture renders nothing until the link comes up, while the
+    // control's destination answers immediately. Two touches before
+    // stepping back: a confirm: still gates the native behavior
+    // (scripts are running, so a destructive submit must not slip past
+    // the dialog), and the form's CSRF token is freshened.
     const fallback = "hibikiFallback" in control.dataset
     if (fallback && this.state !== "ready") {
       const message = control.dataset.hibikiConfirm

data/config/importmap.rb

@@ -2,6 +2,7 @@
 
 # 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.
+# The app supplies the "@hotwired/stimulus" and "@hotwired/turbo-rails" pins
+# — both are part of the Rails 8 default stack. The client takes Action
+# Cable from turbo-rails' consumer, so no "@rails/actioncable" pin is needed.
 pin "hibiki-rails", to: "hibiki.js"

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

@@ -18,7 +18,7 @@ module Hibiki
 
         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."
+             "and creates the ApplicationCable boilerplate."
 
         # Exactly the lines `stimulus:manifest:update` emits for the shim,
         # so a later manifest run converges instead of duplicating.
@@ -38,14 +38,6 @@ module Hibiki
           "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.
@@ -81,11 +73,9 @@ module Hibiki
           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
+        # Bundler apps get the client from npm, not from the engine's asset.
+        def note_npm_package
+          bundler_note unless importmap?
         end
 
         private

data/lib/hibiki/rails/helpers.rb

@@ -2,6 +2,7 @@
 
 require "cgi/escape"
 require "json"
+require "securerandom"
 
 module Hibiki
   module Rails
@@ -24,7 +25,8 @@ module Hibiki
     # Both helpers return a `{ data: { ... } }` hash: splat it into Phlex
     # element methods or Rails tag helpers (`tag.div(**hibiki_island(...))`).
     # When the element needs other attributes on the same `data:` key, merge
-    # the hashes yourself (Phlex's `mix` does this).
+    # the hashes yourself (Phlex's `mix` does this). In ERB, #island wraps
+    # the root, the cid, and the Turbo stream source into one block helper.
     #
     # The emitted attribute names are a private contract between these
     # helpers and the gem's JS — they version together; don't hand-write
@@ -53,7 +55,12 @@ module Hibiki
       # the emitted markup instead of being an invisible default.
       DEFAULT_INPUT_DEBOUNCE = 250
 
-      private_constant :VALUE_NAME, :VALUE_TAG, :EVENT_NAME
+      # How an island's channel sends HTML back: Turbo broadcasts to a named
+      # stream (the root needs a stream source inside), or transmit down the
+      # subscription itself (it does not).
+      TRANSPORTS = %i[broadcast transmit].freeze
+
+      private_constant :VALUE_NAME, :VALUE_TAG, :EVENT_NAME, :TRANSPORTS
 
       # The shared name validator for both halves of a reactive value (the
       # view-side data-hibiki-value placeholder and the channel's
@@ -67,6 +74,23 @@ module Hibiki
         name
       end
 
+      # A tag name lands in raw markup, so it is allowlisted wherever a
+      # helper takes one.
+      def self.tag_name(name, of)
+        name = name.to_s
+        raise ArgumentError, "#{of} tag #{name.inspect} must match #{VALUE_TAG.inspect}" unless VALUE_TAG.match?(name)
+
+        name
+      end
+
+      # #island's transport option, allowlisted so a typo names itself.
+      def self.transport(value)
+        return value if TRANSPORTS.include?(value)
+
+        raise ArgumentError,
+              "island transport #{value.inspect} must be one of #{TRANSPORTS.map(&:inspect).join(', ')}"
+      end
+
       # The shared validator for both halves of an `event->action` token.
       def self.event_name(name)
         name = name.to_s
@@ -105,6 +129,33 @@ module Hibiki
         { data: }
       end
 
+      # The ERB spelling of the island root: a fresh cid, the #hibiki_island
+      # root, and the channel's own `turbo_stream_from channel_name, cid`
+      # inside it, in one block. The block receives the cid.
+      #
+      #   <%= island CounterChannel do |cid| %>
+      #     ...
+      #   <% end %>
+      #
+      # `transport: :transmit` leaves the stream source out — for a channel
+      # that transmits, or one that overrides #stream_name and writes its own
+      # turbo_stream_from inside the block. Other keywords land on the root
+      # element; a `data:` hash is merged beneath the island's own keys.
+      # Class-only: a dynamic name is `"#{kind.camelize}Channel".constantize`
+      # at the call site, never taken from a request param. Phlex components
+      # keep `div(**hibiki_island(...))`.
+      def island(channel, cid: nil, params: nil, transport: :broadcast, tag_name: :div, **attributes,
+                 &block)
+        island_guards!(channel, block)
+        tag_name = Helpers.tag_name(tag_name, "island")
+        transport = Helpers.transport(transport)
+        cid ||= SecureRandom.uuid
+        attributes[:data] = attributes[:data].to_h.merge(hibiki_island(channel, cid:, params:)[:data])
+        content = capture(cid, &block)
+        content = island_stream(channel, cid, content) if transport == :broadcast
+        tag.public_send(tag_name, content, **attributes)
+      end
+
       # Forward an event on this element as a channel action.
       #
       # `event:` names the event, or a list of them — the left side of the
@@ -169,11 +220,7 @@ module Hibiki
       # channels. Only the placeholder text is server-rendered: each site
       # keeps its own tag, classes, and attributes across updates.
       def reactive(name, placeholder = "", tag_name: :span)
-        tag_name = tag_name.to_s
-        unless VALUE_TAG.match?(tag_name)
-          raise ArgumentError,
-                "reactive value tag #{tag_name.inspect} must match #{VALUE_TAG.inspect}"
-        end
+        tag_name = Helpers.tag_name(tag_name, "reactive value")
         html = %(<#{tag_name} data-hibiki-value="#{Helpers.value_name(name)}">) +
                %(#{CGI.escapeHTML(placeholder.to_s)}</#{tag_name}>)
         html.respond_to?(:html_safe) ? html.html_safe : html
@@ -185,6 +232,25 @@ module Hibiki
 
       private
 
+      # #island's preconditions: a block, an ActionView receiver, a channel
+      # class.
+      def island_guards!(channel, block)
+        raise ArgumentError, "island needs a block" unless block
+        unless respond_to?(:output_buffer) && respond_to?(:tag)
+          raise ArgumentError, "island is ERB-only; use div(**hibiki_island(...)) in a Phlex component"
+        end
+        return if channel.is_a?(Class) && channel.respond_to?(:channel_name)
+
+        raise ArgumentError,
+              "island takes a channel class, got #{channel.inspect}; " \
+              "constantize a dynamic name at the call site"
+      end
+
+      # The broadcast transport's stream source, ahead of the block's content.
+      def island_stream(channel, cid, content)
+        safe_join([turbo_stream_from(channel.channel_name, cid), content])
+      end
+
       # #on's per-control modifiers, kept out of the token grammar. Each is
       # omitted when it matches the client's own default, so the common call
       # still stamps exactly one attribute.

data/lib/hibiki/rails/reactive_form.rb

@@ -257,7 +257,7 @@ module Hibiki
       # #errors when validation fails (the Rails #save convention). On
       # success the form re-hydrates: callbacks and database defaults may
       # have moved values, and #persisted? flips after an INSERT.
-      # rubocop:disable Naming/PredicateMethod -- boolean without a ?, exactly like AR's #save
+      # rubocop:disable-next Naming/PredicateMethod -- boolean without a ?, exactly like AR's #save
       def commit
         record = __hibiki_record!
         if record.update(**to_h)
@@ -276,7 +276,6 @@ module Hibiki
           false
         end
       end
-      # rubocop:enable Naming/PredicateMethod
 
       # The raising half. Re-assigns and raises ActiveRecord::RecordInvalid
       # (no rescue, and no AR constant named here); the nested associations

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.10.0"
+    VERSION = "0.12.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - planetaska