hibiki_rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45614c5c98f4439de6f22da45a49d163ab7a06eccf53ed36108ee04d6b5c7f78
-  data.tar.gz: c1dd28764cc7462dbb7ceaa5d0b76e1a0371bd8cc5523fe54545533d7b759c36
+  metadata.gz: 3b21e4afc4b4e74e30f3c32286a1a75b30052e55145d25210bb3cecfbb3bc24c
+  data.tar.gz: 5c26612918d2b81c3a6a6a134710331ba656b25e9441856627ddf6b3ee093e71
 SHA512:
-  metadata.gz: 4908f9d337c86d575287ff2d21d3d74cd112334e893e8b042cb07e7e8a1de141ddd892b17b4b86d90ac2008ce8c7d9f4390fd1ebdd1cc1cafe88e75c6530c360
-  data.tar.gz: 392976be271a02c7b5e354ec0d3e46117e1a8772cb0a68b99d4570f1f95309bc7abac3e0cd3ca38961eaea5eb849d4e4343effa55911629d367555949ac93408
+  metadata.gz: acf106a0cda97184c5bd9a988bab71efb8be65c76e1f5b08785f96795d7a9dc21f67a5511a9a10ffa7b5fee49d498891ce7516b926eec1868d76820fd7c42c48
+  data.tar.gz: 5e8d7b8aba5eaf643e5c6f82dcde5c824bd8f9eb1594163dd872bc0a304a6b37a796069385ec8fdc78e8bfe48dd7d9345d4f60a20b77fe3f72760d02e9b0157e

data/CHANGELOG.md

@@ -0,0 +1,234 @@
+# Changelog
+
+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.4.0 — 2026-08-03
+
+### Added
+
+**Loading and connection state, stamped by the client.** The first growth of the
+`data-hibiki-*` protocol since 0.3.0, and the first attributes in it that no Ruby
+helper emits — the client writes them at runtime and app CSS reads them:
+
+```
+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 an 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. The
+Ruby surface is unchanged: no new option on `on`, `hibiki_island` or `reactive`.
+
+**Actions are acknowledged once their batch has run**, and the ack is what clears
+the indicator. It cannot be "clear on the next render": the core's equality gate
+(hibiki 0.2.0) lets an ordinary action produce zero bytes — paging to the page
+you are already on, a search that does not change the query, a destroy of a row
+another tab already deleted — so a render-based rule hangs forever on gestures
+users make all the time. The ack sits in an `ensure`, so a raising action stops
+the spinner too, and a subscription that has gone away acks `dropped: true` from
+the cable thread instead, which is what lets the client tell "late" from "never".
+
+A page running the 0.3.0 client sends no sequence number and gets no ack, so
+nothing about this reaches an app that has not upgraded both halves.
+
+**Actions performed before the subscription confirms are queued, not dropped.**
+ActionCable's `Subscription#perform` silently returns false on a socket that is
+not open yet, and on the Turbo-broadcast path that window is about three
+serialised round trips — a click in it used to vanish. The queue covers the first
+connect window only: after a reconnect the server rebuilds the graph with default
+state, so replaying intent formed against the old one is worse than dropping it,
+and the island reads `offline` for the whole gap instead.
+
+Three class properties on `ChannelController` are the entire tuning surface —
+`busyDelay` (150 ms before a trip is worth mentioning), `busyGrace` (60 ms for a
+broadcast still in flight after its ack), `busyCeiling` (10 s before a trip is
+declared stalled rather than cleared silently). Deliberately not Stimulus values
+and not helper options; an app that wants different numbers subclasses and
+re-registers.
+
+The scaffold generators wire five sites to all of this — the counts line, the
+pagination bar, the infinite-scroll sentinel, the destroy button and the
+inline-edit Save — through a generated `_busy.html.erb` the app owns.
+
+**`hibiki:rails:scaffold` and `hibiki:rails:scaffold_controller`** — a reactive
+CRUD resource generated the way `rails g scaffold` generates a plain one.
+
+```sh
+bin/rails g hibiki:rails:scaffold Book title:string author:references
+bin/rails g hibiki:rails:scaffold_controller Book   # an existing model
+```
+
+The generated index is live: search, filter, sort and pagination are signal
+state rather than page loads, rows edit in place, and a write from anywhere —
+another tab, another user, the plain controller, a console — repaints every open
+list. Everything is derived from the model's schema (columns, types, `belongs_to`
+reflections, validators) or from the same `NAME field:type` argument list Rails'
+own scaffold takes.
+
+Stock `rails g scaffold` is untouched; these live under their own namespace.
+
+Live per-field validation is derived only from rules the form can actually
+evaluate before a round trip: presence, length, and numericality bounds that
+carry no `allow_nil:`/`allow_blank:` exemption for the value in hand. A
+validator gated on `if:`, `unless:` or `on:` depends on the record rather than
+the field, so it contributes nothing live — it still runs at commit and still
+lands in `#errors`, which the same per-field slots mirror. The clauses are
+generated once; add validators and re-run `scaffold_controller` to pick them up.
+
+**Field order is yours, and choosing it costs nothing.** With no field list the
+columns follow the schema, which for an app built from `schema.rb` means
+alphabetical. Passing them explicitly picks the order — and against a model that
+already exists the generator still reads that model for everything else, so the
+live clauses, a number field's `min:`/`max:` and a `belongs_to`'s display label
+all survive the choice:
+
+```sh
+bin/rails g hibiki:rails:scaffold_controller Author name:string bio:text age:integer
+```
+
+A field the model has no column for is still generated, from the argument list
+alone, and named in the post-install output — it may be a column whose migration
+is still to come, and a silently missing field is the worse failure.
+
+**A unique index with no uniqueness validator is called out.** A database
+constraint is not a validator, and the generated form can only mirror what the
+model checks — so without one, a duplicate raises `ActiveRecord::RecordNotUnique`
+on the graph thread instead of showing a field error, and the round trip
+completes having saved nothing. The generator names the column and the exact
+`validates` line, for single and composite indexes alike.
+
+Options: `--css=daisyui|tailwind|none` (detected when absent),
+`--infinite-scroll`, `--skip-pagination`, `--skip-search`, `--page-size=N`,
+`--skip-routes`.
+
+Three notes on what it does to an app you already have.
+
+**The model is modified** — one `delegate` per `belongs_to`, plus the
+`after_commit` broadcast the whole thing hangs off.
+
+**So is each model a `belongs_to` points at.** It gains the `has_many` half
+Rails' own scaffold never writes (without it the generated destroy button raises
+`InvalidForeignKey`) and a ping of its own, because a row prints the parent's
+label rather than its id — rename an author and every open books index would
+otherwise keep the old name. `dependent:` follows the association: `:destroy`
+when it is required, `:nullify` when it is `optional: true`. That ping is
+collection-grained, so an open *show* page keeps the old label until reload.
+
+Both injections are idempotent and announced, and anything you already declared
+is left alone — including a `dependent:` you chose yourself.
+
+And **restart the server afterwards**: `app/forms/` is likely new, and Rails
+computes autoload paths from the `app/*` glob at boot.
+
+### Fixed
+
+**The model injection missed every namespaced model.** Thor anchors
+`inject_into_class` on the class name as the file spells it, and the generator
+passed the demodulized one — so `app/models/admin/book.rb`, which Rails writes as
+`class Admin::Book < ApplicationRecord`, never matched. Silently: Thor rewrote
+the file byte-identical and the generator reported a modification. The delegate
+never landed, so the show page raised on arrival.
+
+## 0.3.0 — 2026-07-28
+
+### Security
+
+**Channel lifecycle methods were client-invocable on Rails 7.1 and 7.2.**
+Upgrade if you run hibiki_rails on either. Rails 8.x apps were never affected.
+
+ActionCable builds a channel's client-invocable actions from the public methods
+the class adds. The gem subtracted its lifecycle hooks through ActionCable's
+`internal_methods` hook — but **that hook only exists on Rails 8.x**; on 7.1 and
+7.2 `action_methods` never consults it, so the override was silently inert and
+the hooks stayed exposed.
+
+Reachable by any client that can open a subscription, against its own
+connection's graph. There is no cross-connection or cross-user data exposure;
+the impact is resource exhaustion:
+
+- `perform("build_graph")` — exposed on **every** affected app, since
+  `#build_graph` is always public. It re-runs the graph build outside
+  `Hibiki.root`, so the effects it creates are unowned and the dispose on
+  unsubscribe never reaches them, while the previous root is still held. Each
+  call leaks; repeated calls grow memory without bound.
+- `perform("subscribed")` — exposed only where an app defined `#subscribed`
+  public, which the ActiveRecord guide's own `after_commit` example did until
+  this release. It allocates a second `GraphActor` — a new **thread** — and
+  overwrites the reference to the first, so the original is never stopped.
+  Repeated calls exhaust the process's threads.
+
+Fixed by subtracting in `action_methods` itself, which works on every supported
+version:
+
+```ruby
+HIDDEN_ACTIONS = %w[build_graph subscribed unsubscribed].freeze
+def action_methods = super - HIDDEN_ACTIONS
+```
+
+No application change is required. Writing `#subscribed` and `#unsubscribed`
+private is still the better habit, because it also protects the methods this
+list does not know about — the guides now show them that way.
+
+### Added
+
+- `on(action, event:)` takes an **event list**, so one element can answer
+  several events: `on(:load_more, event: %i[click visible])`.
+- **`input`** joins the delegated events, with a per-control **`debounce:`**.
+  `:input` carries 250 ms unless told otherwise (`debounce: 0` opts out); the
+  value is stamped into the markup rather than being an invisible client
+  default.
+- **`visible`**, a pseudo-event backed by an `IntersectionObserver`, so a
+  load-more control can double as an infinite-scroll sentinel. It fires once
+  per observation and re-attaches to the replacement element after each
+  fragment swap.
+- **`confirm:`** on `on(...)` — a `window.confirm` gate. `data-turbo-confirm`
+  does nothing on a hibiki control, since it is not a Turbo-driven form.
+- **`reset: false`** on a submit, to keep a form's inputs. The default resets
+  them synchronously, before the server has replied, which is right for an
+  "add" form and destroys an edit form's contents on a failed commit.
+- **Subscribe params**: `hibiki_island(channel, cid:, params: { record_id: })`
+  reach the channel as `params[:key]`, which is how a channel learns which
+  record its page is about. They are client-supplied and untrusted — use one
+  only to look up a record inside a scope the channel chooses, and never
+  interpolate one into a streamable name. They cannot override `channel` or
+  `cid`.
+- The client has its own test suite (`spec/js`, vitest + happy-dom) and a CI
+  job, plus a pinned Rails 8.1 matrix leg.
+
+### Changed
+
+- **A changed checkbox now sends its checked state as a boolean**, and a
+  multi-select sends an array of its selected values. Previously both sent
+  `control.value` — the value *attribute* — so checking and unchecking a
+  checkbox produced byte-identical payloads. **This is a payload shape
+  change**: an action reading a `change` payload for a checkbox now receives
+  `true`/`false` rather than `"1"`. The form-submit path is unaffected.
+- `transmit_value` is **equality-gated**: an effect re-runs whenever any signal
+  it read changed, so a bumped version token used to re-send every reactive
+  value's text even when byte-identical. The block still runs unconditionally,
+  so dependency collection is unchanged — only the transmit is skipped. If you
+  render a reactive placeholder *inside* a broadcast-replaced fragment, render
+  it with its current value: the swap resets the DOM text and the gate now
+  suppresses the re-send that used to heal it.
+- Each graph job runs inside `Rails.application.executor`, so
+  `CurrentAttributes` are reset between jobs, autoloads are safe off the main
+  thread, and each job gets its own query cache.
+- Graph-thread errors are **logged** in development and test.
+  `ActiveSupport::ErrorReporter` has no subscribers by default, so in a stock
+  app these previously vanished entirely — no line, no stack, just a fragment
+  that stopped updating. Production behaviour is unchanged.
+
+## 0.2.0 — 2026-07-21
+
+- Reactive values: `reactive` / `reactive_attrs` / `transmit_value`, matched
+  document-wide so a value can render outside the island that computes it.
+- `Components::` namespacing for the Phlex generator.
+
+## 0.1.0 — 2026-07-18
+
+Initial release.

data/README.md

@@ -59,6 +59,40 @@ bin/rails g hibiki:rails:stimulus counter static_pages
 
 This creates a minimal working reactive component in the given view path.
 
+### Generating a whole CRUD resource
+
+For a full reactive resource — a live index with search, filtering, sorting and
+pagination, plus edit-in-place — use the scaffold generators:
+
+```sh
+# Model, migration, route and the reactive resource, like rails g scaffold
+bin/rails g hibiki:rails:scaffold Book title:string author:references
+
+# Or, for a model you already have — the schema is read for you
+bin/rails g hibiki:rails:scaffold_controller Book
+
+# Same, but you pick the field order; everything else still comes from the model
+bin/rails g hibiki:rails:scaffold_controller Book title:string author:references
+```
+
+Your plain `rails g scaffold` is untouched. The generated markup is styled to
+match your app (DaisyUI, Tailwind, or unstyled — detected automatically, or
+forced with `--css=`). Run `bin/rails g hibiki:rails:scaffold --help` for the
+rest of the options.
+
+Listing the fields yourself only chooses their order and which ones appear — the
+model still answers everything else, so the live validation, a number field's
+`min:`/`max:` and a `belongs_to`'s display label all survive the choice.
+
+Your models are edited, not just read: the one being scaffolded gains the
+`after_commit` broadcast that makes writes from anywhere reach an open list, and
+each model a `belongs_to` points at gains the `has_many` half plus a ping of its
+own, so renaming a parent repaints the lists that print its name. Both are
+idempotent, announced, and leave anything you already declared alone.
+
+Restart the server afterwards: `app/forms/` is new, and Rails works out its
+autoload paths at boot.
+
 ### Render the reactive component
 
 The generated components are just Rails partials (or Phlex components, if you used the Phlex generator), so you can render one anywhere like any other partial:
@@ -73,6 +107,8 @@ Congratulations! Now you have your first reactive component!
 
 Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>
 
+Release notes and upgrade advice: [CHANGELOG.md](CHANGELOG.md). **If you run Rails 7.1 or 7.2, read the 0.3.0 entry** — it fixes channel lifecycle methods that were client-invocable on those versions.
+
 ## Development
 
 ```
@@ -84,3 +120,29 @@ Both are what CI runs. The Ruby suite boots a minimal inline Rails app (`spec/su
 
 The gem and the npm package are **released in lockstep**: `app/assets/javascripts/hibiki.js` is the single copy — the engine puts it on the asset path and `package.json` points `main`/`module`/`exports` at it — so importmap and bundler apps must never be able to resolve different client code. Bump `lib/hibiki/rails/version.rb` and `package.json` in the same commit, and publish both. The version table lives in [the JS client docs](https://planetaska.github.io/hibiki/the-js-client/).
 
+## Contributing
+
+Bug reports and pull requests are welcome at <https://github.com/planetaska/hibiki-rails>.
+
+A few things that make a change easier to accept:
+
+- **`bundle exec rake` and `bun run test` both green.** They are what CI runs, and the client half is easy to forget — most changes here touch one side, but the wire protocol is shared by both.
+- **A regression spec first** for anything that was a bug. `spec/js/` covers the client, `spec/generators/` the generated output.
+- **Generated code follows `rubocop-rails-omakase`**, which is what a stock Rails app lints with — not this gem's own style. The templates are written to satisfy the app's linter, not ours.
+- **The `data-hibiki-*` attributes are a private contract** between the Ruby helpers and the vendored JS, and the two halves ship in one version — so a change to either side belongs in one commit with the other. Two of them, `data-hibiki-busy` and `data-hibiki-state`, are written by the client rather than by a helper, and apps select on them from CSS; those need a CHANGELOG entry even when no Ruby changes.
+
+### Running against a checkout
+
+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.
+
+```sh
+cd hibiki-rails && bun install   # before linking, not after
+```
+
+This affects only development against a clone. Anyone installing the published package resolves normally and never sees it.
+
+## License
+
+[MIT](LICENSE.txt)

data/app/assets/javascripts/hibiki.js

@@ -55,6 +55,20 @@
 //   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:
+//
+//   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.
+//
 // 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
@@ -95,8 +109,53 @@ const controlValue = (control) => {
 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
+  // 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.
+  // 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.
+  // busyCeiling ms before a trip is declared stalled rather than silently
+  //             cleared. On a bad link "we lost it" beats "nothing
+  //             happened".
+  static busyDelay = 150
+  static busyGrace = 60
+  static busyCeiling = 10000
+
   async connect() {
+    this.prepareTransport()
+    await this.openSubscription()
+  }
+
+  // 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.
+  prepareTransport() {
     this.aborted = false
+    this.subscribed = false
+    this.connectedOnce = false
+    this.seq = 0
+    this.renders = 0
+    this.busy = new Map()
+    this.queued = []
+    this.setState("connecting")
+  }
+
+  async openSubscription() {
     consumer ??= createConsumer()
     this.defineForwarders()
     // Turbo-broadcast transport: wait for the element's own stream source
@@ -106,10 +165,11 @@ export class ChannelController extends Controller {
     const source = this.streamSource()
     if (source) await streamConnected(source)
     if (this.aborted) return // disconnected during the await
-    this.subscription = consumer.subscriptions.create(
-      this.subscribeParams(),
-      { received: (data) => this.received(data) }
-    )
+    this.subscription = consumer.subscriptions.create(this.subscribeParams(), {
+      received: (data) => this.handleMessage(data),
+      connected: () => this.linkOpened(),
+      disconnected: () => this.linkClosed()
+    })
   }
 
   // What identifies this subscription to the server. Override to add
@@ -120,15 +180,174 @@ export class ChannelController extends Controller {
 
   disconnect() {
     this.aborted = true
+    this.settleAll()
     this.subscription?.unsubscribe()
     this.subscription = undefined
+    this.subscribed = false
+    this.queued = []
   }
 
-  // DOM → server: what declared action methods call. Optional chaining
-  // because a debounced action can fire after disconnect, and a sentinel
-  // can fire while connect is still awaiting its stream source.
+  // DOM → server: what declared action methods call. Every perform carries
+  // a sequence number under the reserved `hbk` key and opens a busy record
+  // that the matching ack closes; the seq is stamped LAST so a form field
+  // 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.
   perform(action, payload = {}) {
-    this.subscription?.perform(action, payload)
+    const seq = ++this.seq
+    payload.hbk = seq
+    if (this.subscribed) {
+      this.beginBusy(seq)
+      this.subscription.perform(action, payload)
+      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.
+    //
+    // 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.
+    if (!this.connectedOnce) {
+      this.beginBusy(seq)
+      this.queued.push([action, payload])
+    }
+    return seq
+  }
+
+  // ActionCable's `connected`, i.e. the server confirmed the subscription.
+  // Fires again after every reconnect.
+  linkOpened() {
+    this.subscribed = true
+    this.connectedOnce = true
+    this.setState("ready")
+    const queued = this.queued
+    this.queued = []
+    for (const [action, payload] of queued) this.subscription.perform(action, payload)
+  }
+
+  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.
+    this.queued = []
+    this.settleAll()
+  }
+
+  setState(state) {
+    this.state = state
+    this.element.setAttribute("data-hibiki-state", state)
+  }
+
+  // ── The busy machine ──────────────────────────────────────────────────
+  //
+  // A depth counter, not a boolean: typing while a page loads is one island
+  // with two actions outstanding. No requestAnimationFrame anywhere — it
+  // never fires in a background tab, which is exactly when a stuck
+  // indicator goes unnoticed.
+
+  beginBusy(seq) {
+    const record = {
+      control: null,
+      // Which render the island was on when this started, so the ack can
+      // ask "has anything painted since?" without consulting a clock.
+      renders: this.renders,
+      ceiling: setTimeout(() => this.stall(seq), this.constructor.busyCeiling)
+    }
+    this.busy.set(seq, record)
+    // Start the show-delay on 0→1 only: a second overlapping action must
+    // not restart it, because the user has been waiting since the first.
+    if (this.busy.size === 1) {
+      this.showTimer = setTimeout(() => this.showBusy(), this.constructor.busyDelay)
+    }
+    return record
+  }
+
+  // Attach the control that started a trip, so it can carry its own flag.
+  // Controls inside a server-replaced fragment are cleared by the swap
+  // itself (an idiomorph repaint syncs attributes, and the incoming HTML
+  // has none); controls outside it — the search field — need the removal
+  // in settle().
+  trackControl(seq, control) {
+    const record = this.busy.get(seq)
+    if (!record) return
+    record.control = control
+    if (this.busyShown) control.setAttribute("data-hibiki-busy", "")
+  }
+
+  showBusy() {
+    this.showTimer = undefined
+    this.busyShown = true
+    this.element.setAttribute("data-hibiki-busy", "")
+    this.element.setAttribute("aria-busy", "true")
+    for (const record of this.busy.values()) {
+      record.control?.setAttribute("data-hibiki-busy", "")
+    }
+  }
+
+  // The clear rule, and the whole design: a `dropped` ack settles at once
+  // because nothing is coming; a normal ack settles at once if a render has
+  // already landed, and otherwise waits out the grace window for one still
+  // in flight, then settles regardless — an action that legitimately
+  // rendered nothing is the ordinary case the ack exists for.
+  acknowledge({ ack, dropped }) {
+    // Any ack proves the link is alive again.
+    if (this.state === "stalled") this.setState("ready")
+    const record = this.busy.get(ack)
+    if (!record) return
+    if (dropped || this.renders > record.renders) return this.settle(ack)
+    record.grace = setTimeout(() => this.settle(ack), this.constructor.busyGrace)
+  }
+
+  settle(seq) {
+    const record = this.busy.get(seq)
+    if (!record) return
+    clearTimeout(record.ceiling)
+    clearTimeout(record.grace)
+    this.busy.delete(seq)
+    record.control?.removeAttribute("data-hibiki-busy")
+    if (this.busy.size === 0) this.hideBusy()
+  }
+
+  settleAll() {
+    for (const seq of [...this.busy.keys()]) this.settle(seq)
+    this.hideBusy() // an already-empty map still has a show timer to cancel
+  }
+
+  hideBusy() {
+    clearTimeout(this.showTimer)
+    this.showTimer = undefined
+    this.busyShown = false
+    this.element.removeAttribute("data-hibiki-busy")
+    this.element.removeAttribute("aria-busy")
+  }
+
+  // Say so rather than clearing silently: on a bad link the honest report
+  // is "we lost it", and a cleared indicator claims the opposite.
+  stall(seq) {
+    this.settle(seq)
+    this.setState("stalled")
+  }
+
+  // Every inbound frame lands here first. Acks are transport bookkeeping,
+  // handled by the base and deliberately NOT routed through received() — so
+  // a subclass that overrides received without calling super still clears
+  // its pending state.
+  handleMessage(data) {
+    if (data && "ack" in data) return this.acknowledge(data)
+    if (data && data.html) this.renders++
+    this.received(data)
   }
 
   // Server → DOM (transmit transport). Two message shapes:
@@ -228,6 +447,13 @@ export default class HibikiController extends ChannelController {
   }
 
   async connect() {
+    // 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.
+    this.prepareTransport()
+
     // 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.
@@ -267,12 +493,18 @@ export default class HibikiController extends ChannelController {
       const render = event.detail.render
       event.detail.render = async (streamElement) => {
         await render(streamElement)
+        // The Turbo transport's paint. Counting it here is what lets an ack
+        // settle immediately instead of waiting out its grace window. The
+        // listener is on the document, so an unrelated broadcast counts too
+        // — which at worst settles an already-acked trip a few ms early,
+        // never one that has not been acked at all.
+        this.renders++
         this.scanSentinels()
       }
     }
     document.addEventListener("turbo:before-stream-render", this.streamRender)
 
-    await super.connect()
+    await this.openSubscription()
     if (this.aborted) return
     this.scanSentinels()
   }
@@ -349,7 +581,9 @@ export default class HibikiController extends ChannelController {
     } else if (control.name && (event.type === "change" || event.type === "input")) {
       payload[control.name] = controlValue(control)
     }
-    this.perform(action, payload)
+    // perform stamps `hbk` after this merge, so a field literally named hbk
+    // loses to the seq rather than corrupting it.
+    this.trackControl(this.perform(action, payload), control)
     // Resetting is right for an "add" form and wrong for an edit one: it
     // runs synchronously, before the server has replied, so a failed commit
     // would discard what the user typed.