hibiki_rails 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8ac38db2808ab9f20f6fccf7cf50c202454fc222cba122f6466e25cf5fe2eb3
-  data.tar.gz: 89b5a3ab98b4bf10ba10466de9f352d9e9e3c3a814abb35175df798aa4fafc89
+  metadata.gz: e95a440701dfeb3c02a3f6535b59cc18e51d66569dd76f9d793153f671120edc
+  data.tar.gz: 14869e53518e44f14089c7a1be15c166a51e9f61ff87867cd9fcbb848b20a3dc
 SHA512:
-  metadata.gz: 1d970c278b67be036e36a4703e3a38f6581b27bb890a4a7b599000755085a74f311646ae1519752e6457633590326bb9e6ca0fcf1b7fb1925e784d5f3a2c70b3
-  data.tar.gz: 468b0706478f48ee97019baf35b4da08912647b7a649575b8f970d05a21186cb85cf9c6c5dc89d9d0e6c75c6b0ad5c936c0b5cb6d8b223b5924edbb094ea2304
+  metadata.gz: 3937c28fbcd8ec47e540a2837b6c48d34b4152553037491a576a67b22679d58578c09c4b63ea316390a1a5d5d49e9c37b29fe277dd8150484a881899ee8f1b00
+  data.tar.gz: 88ca77fa4732bf3d08f7b207c57ec457bc601afa7111dda3d4660b51d62a1b305b88c9a98b1801cfdc5a29f2723f8d29f5b617b545cd3c9c952e1b3c9aef8329

data/CHANGELOG.md

@@ -4,6 +4,86 @@ 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.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
+
+**`hibiki:rails:upload_field` — a `has_one_attached` upload on both edit
+surfaces.** `bin/rails g hibiki:rails:upload_field Album cover` extends a
+hibiki:rails scaffold: the classic form gains a direct-upload file field plus
+a remove checkbox (a virtual `remove_cover` attribute whose purge yields to a
+same-submit upload), and the inline channel form gains a nameless file input
+that direct-uploads on change and hands only the signed blob id to the graph.
+The pending state lives in the channel (a generated concern under
+`app/channels/concerns`, one `include` in the channel), keyed by the form's
+dom, so it survives repaints and the edit row and inline create form stay
+independent; attach/purge happens after a successful commit. Both channel
+queries are preloaded with `with_attached_cover`, `:cover`/`:remove_cover`
+join the permitted params, and one shared
+`app/javascript/controllers/upload_field_controller.js` is emitted per app —
+parameterized by Stimulus values, so a second attachment reuses it. One
+attachment per run; `has_one_attached` only.
+
+**`--accept` — non-image formats.** `--accept=pdf,doc` narrows both file
+inputs (image by default; tokens `image`, `audio`, `video`, `pdf`, `csv`,
+`text`, `doc`, `xls`, `ppt`, plus any raw `type/subtype` or `.ext` passed
+through; an unknown token refuses before anything is written). Every display
+site — the inline form, the classic form, and the row on the index and show
+page — branches per blob at render time on `variable?`: an image gets its
+variant thumbnail, anything else its filename and size, with a
+`rails_blob_path` link on the row. That is one template for every accept
+list, so mixed lists work and a wrong-typed file past the advisory `accept`
+no longer breaks the index at `variant`. The image_processing notice fires
+only when an image type is accepted. The accept list stays advisory — the
+app owns any server-side content-type validation.
+
+**`--many` — `has_many_attached` galleries.** `bin/rails g
+hibiki:rails:upload_field Album photos --many` (implied when the model
+already declares `has_many_attached :photos`; `--many` against an existing
+`has_one_attached` refuses) generates the gallery shape on both surfaces.
+The inline form's input takes several files — the shared
+`upload_field_controller.js` now uploads one file after another, so a
+gallery's pending list keeps the pick order; a single-file input behaves
+as before, and a many-mode run refreshes a copy from before the loop. Each
+attached file carries a graph-owned ✕ (toggle: ✕ marks, Undo unmarks) and
+each pending file its own badge with a ✕ to drop it; the pending state per
+form dom is `{ adds:, removes: }`, applied after a successful commit by
+APPENDING through `attach` and purging the marked ids — the collection is
+never assigned, which since Rails 7.1 replaces it. The classic form gets
+the same append/remove split as two virtual model attributes,
+`add_photos` (a `multiple` direct-upload field, attached in `before_save`)
+and `remove_photo_ids` (a checkbox per attached file, purged in
+`after_save`), riding `params.expect` as a braced group. The row and show
+page render the gallery with the same per-blob thumbnail-or-filename
+branch, so `--many --accept=pdf` is a document list. Two css tokens
+(`gallery_item`, `upload_status_list`).
+
+The packaged client did not change — the emitted Stimulus controller imports
+`@rails/activestorage` from the app's own dependencies.
+
 ## 0.9.1 — 2026-08-18
 
 ### 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/css_variant.rb

@@ -121,7 +121,25 @@ module Hibiki
           fieldset_legend: "fieldset-legend px-2",
           nested_row: "border border-base-300 rounded-box p-3 mb-2 space-y-2",
           btn_ghost_sm: "btn btn-sm btn-ghost",
-          btn_outline_sm: "btn btn-sm btn-outline"
+          btn_outline_sm: "btn btn-sm btn-outline",
+
+          # The upload field (hibiki:rails:upload_field): the attachment row
+          # in both forms, its thumbnail, the non-image filename link on the
+          # row, and the pending badge on its own full-width line under the
+          # controls (the row wraps, so a long filename never pushes Remove
+          # off-screen). upload_row, upload_status and thumb are plain
+          # utilities, so the tailwind variant inherits them.
+          upload_row: "flex flex-wrap items-center gap-3",
+          upload_status: "w-full",
+          # --many: one chip per attached file (thumb + ✕) and the pending
+          # list, which wraps like the row.
+          gallery_item: "inline-flex items-center gap-1",
+          upload_status_list: "w-full flex flex-wrap gap-2",
+          thumb: "rounded",
+          file_link: "link link-hover",
+          file_input: "file-input w-full",
+          file_input_sm: "file-input file-input-sm",
+          badge_info: "badge badge-info"
         }.freeze
 
         # DaisyUI is a plugin over Tailwind, and the merge says so literally:
@@ -179,7 +197,16 @@ module Hibiki
           fieldset_legend: "px-2 text-sm font-medium text-gray-700",
           nested_row: "rounded-md border border-gray-200 p-3 mb-2 space-y-2",
           btn_ghost_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1"),
-          btn_outline_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1")
+          btn_outline_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1"),
+          file_link: "text-indigo-600 hover:underline",
+          file_input: "block w-full text-sm text-gray-700 file:mr-3 file:rounded-md " \
+                      "file:border-0 file:bg-gray-100 file:px-3 file:py-2 file:text-sm " \
+                      "file:font-medium file:text-gray-700 hover:file:bg-gray-200",
+          file_input_sm: "block text-xs text-gray-700 file:mr-2 file:rounded-md " \
+                         "file:border-0 file:bg-gray-100 file:px-2 file:py-1 file:text-xs " \
+                         "file:font-medium file:text-gray-700 hover:file:bg-gray-200",
+          badge_info: "inline-flex items-center rounded-full bg-sky-100 px-2 py-1 " \
+                      "text-xs font-medium text-sky-800"
         ).freeze
 
         # Every lookup misses, so every class argument is omitted entirely.

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    module Generators
+      # Threading the extras: hash through a pre-0.7.0 scaffold's partial
+      # chain. Scaffolds since 0.7.0 emit it themselves (list -> row ->
+      # row_form, untouched), so on those this is a no-op probe; older
+      # output gets the header/keyword plus the two render calls retrofitted,
+      # anchored on text every scaffold emitted verbatim.
+      #
+      # Shared by every add-on generator that rides extras:
+      # (hibiki:rails:multiselect, hibiki:rails:upload_field). Depends on the
+      # generator for view_path/row_partial/row_form_partial/phlex?.
+      module ExtrasThreading
+        private
+
+        def thread_extras_through_partials
+          return if wired?(extras_probe_path, "extras")
+
+          say_status :compat, "pre-0.7 scaffold — threading extras: through the partials", :yellow
+          phlex? ? thread_extras_phlex : thread_extras_erb
+          return if wired?(extras_probe_path, "extras")
+
+          say_status :warn, "could not thread extras: automatically. Pass an extras: {} local " \
+                            "from the list partial down to #{row_form_partial} yourself.", :yellow
+        end
+
+        def extras_probe_path = phlex? ? view_path("row_form.rb") : view_path("_#{row_form_partial}.html.erb")
+
+        def thread_extras_erb
+          [view_path("_list.html.erb"), view_path("_#{row_partial}.html.erb"),
+           view_path("_#{row_form_partial}.html.erb")].each do |path|
+            # /m: the row form's locals header wraps onto a second line.
+            gsub_file path, /^(<%# locals: \(.*?)\) -%>/m, '\1, extras: {}) -%>', verbose: false
+          end
+          # `form: form` appears exactly once per file, inside the one render
+          # call that must pass extras on.
+          gsub_file view_path("_list.html.erb"), "form: form", "form: form, extras: extras"
+          gsub_file view_path("_#{row_partial}.html.erb"), "form: form", "form: form, extras: extras"
+        end
+
+        def thread_extras_phlex
+          %w[list.rb row.rb row_form.rb].each do |basename|
+            path = view_path(basename)
+            gsub_file path, /(def initialize\([^)]*)\)/, '\1, extras: {})', verbose: false
+            gsub_file path, /^(\s*)@form = form$/, "\\1@form = form\n\\1@extras = extras", verbose: false
+          end
+          gsub_file view_path("list.rb"), "form: @form", "form: @form, extras: @extras"
+          gsub_file view_path("row.rb"), "form: @form", "form: @form, extras: @extras"
+        end
+      end
+    end
+  end
+end

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