hibiki_rails 0.17.2 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83e9656d09f3910405a4db7167b526c173158eb1035d5cb5129e4f916c88c278
-  data.tar.gz: e22b25605c6522e98cfdc86dcd685e62b3c60ed31ca865eb2daa53f74aaaf946
+  metadata.gz: 0ab077d178d71a16ddf8d0f5706179f7fbac93c4d851aae6e3ccda4ef0e4b674
+  data.tar.gz: 409e833560a3393d2ca3c0121c2e958f3d8bb986a0b62aaaed653fe0c0f06af3
 SHA512:
-  metadata.gz: 8c459eb9453de6af88c6e7859849a41dcbf7c0daa5d2e79da12e5ac8f729f4b85093e9d10c176d97cb8cd5141ef47ffeb0bcb2482aa03b223e42b2af4b13d9a6
-  data.tar.gz: 7ccd090ef5fdd72735d7bb45d356a1f7085fb6c323d42692c91b7226a5fd6ac058f0ea477efaa6d7693dfbfe66254d85c358e8ea5ca7d3fcd49f6fde56366040
+  metadata.gz: 552f5913948b16d8ed030b1eb12c35f7f28f0f109f31807dbbaf86f9b2320c3929c959c2872800785b635b9c05229df0ebe5c218e4429b490442ee2cb81ba133
+  data.tar.gz: 0ff3466d160bd5074a8d02530c87222fd8dcc5aeed43b033fb8ff3549decd55423286e1757511d352f39a5df47a4d60198dd0efb9fa254479febf43f1ea7d8c6

data/CHANGELOG.md

@@ -4,6 +4,89 @@ 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.19.0 — 2026-10-12
+
+### Added
+
+**History entries.** `transmit_url` takes `history: :push`, and each move of
+the URL becomes an entry in the browser's history. Use it for state that
+reads as a place, such as a wizard's step. The default, `history: :replace`,
+is unchanged.
+
+```ruby
+transmit_url(history: :push) { wizard_path(step: @step.value) }
+```
+
+**The `popstate` event.** `on(:visit, event: :popstate)` on the island root
+answers Back and Forward over those entries. The client performs the action
+with the query of the address the browser moved to.
+
+```erb
+<%= island WizardChannel, **on(:visit, event: :popstate) do |cid| %>
+```
+
+```ruby
+def visit(data) = turn_to(data["step"])
+```
+
+- The params come from the address bar. Check them as you would a subscribe
+  param.
+- A pushed URL becomes an entry only when it answers an action of this tab.
+  The first URL a channel sends, and one that follows another session's
+  write, replace as before.
+- If the action refuses the address, or changes nothing, the bar is put back
+  to the URL the channel last sent. No entry is added.
+- The payload is the flat query. A key ending in `[]` arrives as an array.
+- `popstate` takes no `debounce:` or `fallback:`.
+- Without a `popstate` action, Back over a pushed entry reloads the page at
+  that address. The page shows the right state if it reads the same params
+  on its first render, as a mirrored URL already requires.
+- Coming back to a pushed entry from another page also reloads it.
+- A page that has pushed an entry is left out of Turbo's snapshot cache.
+
+## 0.18.0 — 2026-10-11
+
+### Added
+
+**Instrumentation events.** A channel now publishes
+`ActiveSupport::Notifications` events, so an app can time what a graph does.
+Action Cable's own `perform_action.action_cable` covers only the hand-off to
+the graph's thread; the action, its effects and its renders run after it.
+
+| Event | Duration covers | Payload |
+|---|---|---|
+| `subscribe.hibiki_rails` | building the graph and its first renders | `channel` |
+| `unsubscribe.hibiki_rails` | disposing the graph | `channel` |
+| `action.hibiki_rails` | the action and every effect it flushed | `channel`, `action`, `wait`, `renders` |
+| `render.hibiki_rails` | one `broadcast_replace`, `broadcast_morph` or `broadcast_refresh` | `channel`, `target`, `method` |
+
+- The events are always on and need no configuration. The gem subscribes to
+  none of them. With no subscriber an action costs one to two microseconds
+  more than in 0.17.2.
+- A subscriber runs on the graph's thread, so keep it to cheap work in
+  memory.
+- An action the channel does not have publishes nothing. A raising action
+  publishes, with the exception in the payload.
+- `transmit_value` and `transmit_url` have no event of their own; Action
+  Cable's `transmit.action_cable` covers them.
+
+**`Hibiki::Rails.registry.tally`** returns the live subscriptions by channel
+class name.
+
+**Trips: how long a visitor waited.** With `HibikiController.reportTrips =
+true`, each island times its round trips and sends them with its next action.
+The channel publishes one `trip.hibiki_rails` event for each, with `channel`,
+`action`, `ack` (milliseconds until the server answered) and `paint`
+(milliseconds until the first render arrived, or `nil`).
+
+- Off by default. Set it once, on the class, for every island.
+- A dropped or stalled trip is not reported, and neither is the last trip on
+  a page, since no action follows it.
+- The figures come from the browser. The channel takes at most five per
+  action, only for its own actions, and clamps each to 0 to 60 000 ms.
+- `hbt` joins `hbk` as a reserved payload key. The channel removes it before
+  the action method sees its data.
+
 ## 0.17.2 — 2026-10-11
 
 ### Fixed

data/README.md

@@ -125,6 +125,52 @@ The generated components are just Rails partials (or Phlex components, if you us
 
 Congratulations! Now you have your first reactive component!
 
+## Instrumentation
+
+A channel publishes `ActiveSupport::Notifications` events. They are always
+on, and the gem subscribes to none of them.
+
+| Event | Duration covers | Payload |
+|---|---|---|
+| `subscribe.hibiki_rails` | building the graph and its first renders | `channel` |
+| `unsubscribe.hibiki_rails` | disposing the graph | `channel` |
+| `action.hibiki_rails` | the action and every effect it flushed | `channel`, `action`, `wait`, `renders` |
+| `render.hibiki_rails` | rendering and handing the stream to Action Cable | `channel`, `target`, `method` |
+| `trip.hibiki_rails` | nothing | `channel`, `action`, `ack`, `paint` |
+
+```ruby
+ActiveSupport::Notifications.subscribe("action.hibiki_rails") do |event|
+  Rails.logger.info "#{event.payload[:channel]}##{event.payload[:action]} #{event.duration.round(1)}ms"
+end
+```
+
+- `channel` is the class name. `wait` is the milliseconds the action queued
+  for the graph's thread. `renders` is how many renders it caused.
+- `method` is `:replace`, `:morph` or `:refresh`. A refresh has no `target`.
+- An action the channel does not have publishes nothing. A raising action
+  publishes, with the exception in the payload.
+- Action Cable's `broadcast.action_cable` fires inside the render event, on
+  the same thread, and carries the message if you want its size.
+- `Hibiki::Rails.registry.tally` returns the live subscriptions by channel
+  class, and `registry.size` the total.
+
+**A subscriber runs on the graph's thread.** Keep it to cheap work in
+memory; anything slow holds up that visitor's actions.
+
+A `trip` is the browser's own timing of one action: `ack` is the
+milliseconds until the server answered and `paint` the milliseconds until
+its first render arrived, or `nil` when nothing rendered. Reporting is off
+until the app turns it on:
+
+```js
+import HibikiController from "hibiki-rails"
+HibikiController.reportTrips = true
+```
+
+Each island then sends its last trips with its next action. The figures come
+from visitors' browsers, so treat them as reported: the gem bounds them (five
+per action, known action names, 0 to 60 000 ms) and cannot verify them.
+
 ## Documentation
 
 Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>

data/app/assets/javascripts/hibiki.js

@@ -93,7 +93,9 @@
 //
 // 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).
+// backed by an IntersectionObserver (the element entering the viewport);
+// `popstate` is the window's, heard for the history entries a pushed
+// `{ url }` frame made.
 // Everything that is not "which event" is a sibling attribute, so the
 // token grammar never has to grow.
 //
@@ -185,6 +187,27 @@ let consumer
 // island pins nothing even if disconnect never ran.
 const islands = new WeakMap()
 
+// History entries a pushed `{ url }` frame made, by the key in their state,
+// and the one window listener that answers Back and Forward over them.
+//
+// Turbo hears popstate first, whatever the listener's phase: the browser
+// runs a window's listeners in the order they were added. It answers an
+// entry carrying its own state with a restore visit, and an entry without
+// it by adopting it in place. So these entries carry only the key. The
+// island that made one answers it (pop). An entry whose island has left
+// the page, or declares no `popstate`, is loaded afresh: Turbo has by then
+// filed a snapshot of the page on show under the entry's address, and a
+// new document is the one thing that leaves none of that behind.
+//
+// Always listening, not from the first push: after a reload the browser
+// still counts the entries the old document pushed as this document's, and
+// answers Back over them with a popstate no island here made.
+const pushers = new Map()
+window.addEventListener("popstate", (event) => {
+  const key = event.state?.hibiki
+  if (key && !pushers.get(key)?.pop?.(event)) window.location.reload()
+})
+
 // The generic island CONTAINING element, or undefined. The walk performOn
 // uses, exported for the motion module's `own` policy — which reads the
 // island's trip records, so a ChannelController subclass (not in the map)
@@ -284,6 +307,10 @@ export class ChannelController extends Controller {
   static busyCeiling = 10000
   static focusGrace = 500
 
+  // Whether to tell the server how long each trip took (see "Trips"
+  // below). Off unless an app sets it, once, for every island.
+  static reportTrips = false
+
   async connect() {
     this.prepareTransport()
     await this.openSubscription()
@@ -302,9 +329,13 @@ export class ChannelController extends Controller {
     this.seq = 0
     this.renders = 0
     this.busy = new Map()
+    this.trips = []
     this.settledAt = -Infinity
     this.lastControl = null
     this.queued = []
+    // Marks the history entries this island made; see replaceUrl().
+    this.historyKey = `${Date.now()}-${Math.random()}`
+    this.popping = undefined
     this.setState("connecting")
   }
 
@@ -334,6 +365,8 @@ export class ChannelController extends Controller {
 
   disconnect() {
     this.aborted = true
+    pushers.delete(this.historyKey)
+    this.popping = undefined // the bar is the next page's now
     this.settleAll()
     this.subscription?.unsubscribe()
     this.subscription = undefined
@@ -345,7 +378,8 @@ export class ChannelController extends Controller {
   // 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`.)
+  // ActionCable's own Subscription#perform already writes `action`. `hbt`
+  // is the third: the trips timed since the last perform.)
   //
   // Public API on the island controller (the header's "App JS reaching
   // the graph"). Returns the seq when the action was accepted, so a
@@ -356,8 +390,10 @@ export class ChannelController extends Controller {
   perform(action, payload = {}) {
     const seq = ++this.seq
     payload.hbk = seq
+    delete payload.hbt
     if (this.subscribed) {
-      this.beginBusy(seq)
+      this.sendTrips(payload)
+      this.beginBusy(seq, action)
       // 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
@@ -383,7 +419,8 @@ export class ChannelController extends Controller {
     // whole gap — the signal the connect window cannot give, where the
     // page is painted and looks live.
     if (!this.connectedOnce) {
-      this.beginBusy(seq)
+      this.sendTrips(payload)
+      this.beginBusy(seq, action)
       this.queued.push([action, payload])
       return seq
     }
@@ -430,9 +467,11 @@ export class ChannelController extends Controller {
   // means the server has not answered, and a hold is motion after the
   // answer.
 
-  beginBusy(seq) {
+  beginBusy(seq, action) {
     const record = {
       control: null,
+      action,
+      at: performance.now(),
       // 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,
@@ -486,11 +525,13 @@ export class ChannelController extends Controller {
     if (this.state === "stalled") this.setState("ready")
     const record = this.busy.get(ack)
     if (!record) return
+    if (!dropped) record.ack = Math.round(performance.now() - record.at)
     if (dropped || this.renders > record.renders) return this.settle(ack)
     record.grace = setTimeout(() => this.settle(ack), this.constructor.busyGrace)
   }
 
   settle(seq) {
+    if (this.popping === seq) this.popped()
     const record = this.busy.get(seq)
     if (!record) return
     clearTimeout(record.ceiling)
@@ -499,6 +540,7 @@ export class ChannelController extends Controller {
     this.settledAt = performance.now()
     record.control?.removeAttribute("data-hibiki-busy")
     if (this.busy.size === 0) this.hideBusy()
+    if (record.ack !== undefined && this.constructor.reportTrips) this.keepTrip(record)
   }
 
   settleAll() {
@@ -528,13 +570,49 @@ export class ChannelController extends Controller {
     this.setState("stalled")
   }
 
+  // ── Trips ─────────────────────────────────────────────────────────────
+  //
+  // Only the browser sees both halves of a trip land: the ack on the
+  // island's socket and the render after its pubsub hop. With reportTrips
+  // on, each acked trip is kept as its action, the ms to the ack and the ms
+  // to the first render of its own (null when nothing rendered), and the
+  // next perform carries the last five under `hbt`. A dropped or stalled
+  // trip is not reported, and the last trip on a page never is.
+
+  keepTrip({ action, at, ack, paint }) {
+    this.trips.push({ action, at, ack, paint, settled: this.settledAt })
+    if (this.trips.length > 5) this.trips.shift()
+  }
+
+  sendTrips(payload) {
+    if (!this.trips.length) return
+    payload.hbt = this.trips.map(({ action, ack, paint }) => [action, ack, paint ?? null])
+    this.trips = []
+  }
+
+  // A render of this island's own has arrived. Timed now, not when it is
+  // applied: the order and motion holds come after the answer. A trip that
+  // settled a moment ago still takes it, by the rule own() uses.
+  arrived() {
+    const now = performance.now()
+    for (const record of this.busy.values()) record.paint ??= Math.round(now - record.at)
+    for (const trip of this.trips) {
+      if (trip.paint === undefined && now - trip.settled <= this.constructor.focusGrace) {
+        trip.paint = Math.round(now - trip.at)
+      }
+    }
+  }
+
   // 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++
+    if (data && data.html) {
+      this.renders++
+      this.arrived()
+    }
     this.received(data)
   }
 
@@ -546,7 +624,8 @@ export class ChannelController extends Controller {
   // textContent assignment keeps values text-only and preserves each
   // site's own tag/classes, so per-placeholder styling survives updates.
   //
-  // { url } — mirror graph state into the address bar (transmit_url).
+  // { url } — mirror graph state into the address bar (transmit_url);
+  // with `push`, as a history entry.
   //
   // { html } — a fragment: swap it in by its root id. The swap is holdable
   // the way Turbo's is: `hibiki:before-render` bubbles from the island
@@ -558,7 +637,7 @@ export class ChannelController extends Controller {
   //
   // Anything else is not ours to interpret. Subclasses may override, but
   // should call super (or handle `value`) to keep reactive values live.
-  received({ html, value, url }) {
+  received({ html, value, url, push }) {
     if (value) {
       const selector = `[data-hibiki-value="${CSS.escape(value.name)}"]`
       for (const site of document.querySelectorAll(selector)) {
@@ -566,7 +645,7 @@ export class ChannelController extends Controller {
       }
       return
     }
-    if (url !== undefined) return this.replaceUrl(url)
+    if (url !== undefined) return this.replaceUrl(url, push)
     if (!html) return
     const template = document.createElement("template")
     template.innerHTML = html
@@ -584,15 +663,48 @@ export class ChannelController extends Controller {
     return event.detail.render()
   }
 
-  // replaceState, never pushState: the URL is a mirror of graph state, not
-  // a history entry — Back needs no popstate handling and leaves the page
-  // normally. Same-origin only, so a channel can move the bar solely
-  // within its own app (replaceState would throw on a cross-origin URL;
-  // refusing keeps it silent and intentional).
-  replaceUrl(url) {
+  // replaceState unless the channel asked for entries: the URL is a mirror
+  // of graph state, and Back leaves the page normally. Same-origin only, so
+  // a channel can move the bar solely within its own app (replaceState
+  // would throw on a cross-origin URL; refusing keeps it silent and
+  // intentional).
+  //
+  // A pushed URL becomes an entry only when it answers this tab's own
+  // action, so neither the first frame nor another session's write adds
+  // one, and never while a Back is being answered: an action that refuses
+  // the popped URL corrects the bar in place. The entry it leaves and the
+  // one it makes carry this island's key in place of Turbo's state; see
+  // `pushers`. The page is also kept out of Turbo's snapshot cache from
+  // then on, since Turbo no longer knows which address a snapshot is of.
+  replaceUrl(url, push = false) {
     const resolved = new URL(url, window.location.href)
     if (resolved.origin !== window.location.origin) return
-    history.replaceState(history.state, "", resolved)
+    this.url = resolved.href
+    if (!push || this.popping !== undefined || !this.own()) {
+      return history.replaceState(history.state, "", resolved)
+    }
+    if (resolved.href === window.location.href) return
+    pushers.set(this.historyKey, this)
+    window.Turbo?.cache?.exemptPageFromCache?.()
+    history.replaceState(this.entry(), "")
+    history.pushState(this.entry(), "", resolved)
+  }
+
+  // The state of an entry this island answers for: what is there now,
+  // less Turbo's part.
+  entry() {
+    const { turbo, ...rest } = history.state ?? {}
+    return { ...rest, hibiki: this.historyKey }
+  }
+
+  // The Back being answered is over. An action that changed nothing sent no
+  // URL, so the bar still shows the popped one: put back the last the
+  // channel gave, which is the state the page is in.
+  popped() {
+    this.popping = undefined
+    if (this.url && this.url !== window.location.href) {
+      history.replaceState(history.state, "", this.url)
+    }
   }
 
   // `static channel = "..."` wins; otherwise infer Rails-style from the
@@ -684,6 +796,7 @@ const KEYS = {
 }
 const KEYED = '[data-hibiki-on*="keydown."]'
 const HOTKEYED = '[data-hibiki-on*="@window"]'
+const POPPED = '[data-hibiki-on*="popstate->"]'
 const ISLAND = '[data-controller~="hibiki"]'
 
 // A key press that is a gesture: not part of an IME composition (Safari
@@ -855,6 +968,9 @@ export default class HibikiController extends ChannelController {
     this.streamRender = (event) => {
       const render = event.detail.render
       const stream = event.detail.newStream
+      if (stream?.getAttribute?.("data-hibiki-from") === `${this.channelValue}/${this.cidValue}`) {
+        this.arrived()
+      }
       // Taken now, not when the render's turn comes: see arrival().
       const arrival = this.arrival()
       event.detail.render = (streamElement) =>
@@ -1166,6 +1282,31 @@ export default class HibikiController extends ChannelController {
     }
   }
 
+  // Back or Forward landed on an entry this island made, or the one it
+  // first pushed from: the control declaring `popstate`, the root as a
+  // rule, performs its action with the entry's query. Turbo has adopted the
+  // entry by now and written its own state there, which would make the
+  // next visit to it a restore; the entry's own state goes back. False
+  // when nothing here answers, and the page is loaded afresh instead.
+  pop(event) {
+    const control = [this.element, ...this.element.querySelectorAll(POPPED)].find(
+      (element) => element.closest(ISLAND) === this.element && element.matches(POPPED)
+    )
+    const token = control?.dataset.hibikiOn.split(/\s+/).find((t) => t.startsWith("popstate->"))
+    if (!token) return false
+    history.replaceState(event.state, "")
+    const payload = control.dataset.hibikiWith ? JSON.parse(control.dataset.hibikiWith) : {}
+    const query = new URLSearchParams(window.location.search)
+    for (const key of new Set(query.keys())) {
+      const all = query.getAll(key)
+      payload[payloadKey(key)] = key.endsWith("[]") ? all : all.at(-1)
+    }
+    this.flush()
+    this.popping = this.perform(token.slice(10), payload)
+    if (this.popping === undefined) this.popped() // offline: nothing will answer
+    return true
+  }
+
   // A matched key is the control's gesture, so its default goes. A fallback
   // control on an island that is not ready stands aside: a key has no
   // native destination, but its default may be the form's own submit.

data/lib/hibiki/rails/broadcasts.rb

@@ -13,14 +13,19 @@ module Hibiki
     # All private — a public helper would become a client-invocable action
     # (see the NOTE on Hibiki::Rails::Channel).
     module Broadcasts
+      include Instrumentation
+
       private
 
       # Replace the element with DOM id `target` (accepts partial:/locals:,
       # html:, or anything Turbo's renderer takes).
       def broadcast_replace(target:, attributes: {}, **rendering)
-        Turbo::StreamsChannel.broadcast_replace_to(
-          *stream_name, target:, attributes: attributes.merge(render_stamp), **rendering
-        )
+        method = attributes[:method].to_s == "morph" ? :morph : :replace
+        instrument_render(target:, method:) do
+          Turbo::StreamsChannel.broadcast_replace_to(
+            *stream_name, target:, attributes: attributes.merge(render_stamp), **rendering
+          )
+        end
       end
 
       # Replace via Turbo 8 morphing (<turbo-stream action="replace"
@@ -32,7 +37,7 @@ module Hibiki
       # Tell the page to refresh itself (Turbo 8 morph-everything style).
       # Pair with Debounce when many writes should mean one refresh.
       def broadcast_refresh
-        Turbo::StreamsChannel.broadcast_refresh_to(*stream_name)
+        instrument_render(method: :refresh) { Turbo::StreamsChannel.broadcast_refresh_to(*stream_name) }
       end
 
       # The Morph-everything style as one call: an effect that tracks

data/lib/hibiki/rails/channel.rb

@@ -30,11 +30,23 @@ module Hibiki
     # other public method would be picked up by Channel#action_methods and
     # become client-invocable.
     module Channel
+      # #transmit_url's history option, allowlisted so a typo names itself.
+      HISTORIES = %i[replace push].freeze
+      private_constant :HISTORIES
+
       def self.included(base)
         base.extend(ClassMethods)
         base.include(Broadcasts)
       end
 
+      # What a history mode adds to the `{ url: }` frame.
+      def self.url_frame(history)
+        return history == :push ? { push: true } : {} if HISTORIES.include?(history)
+
+        raise ArgumentError,
+              "transmit_url history #{history.inspect} must be one of #{HISTORIES.map(&:inspect).join(', ')}"
+      end
+
       module ClassMethods
         # Lifecycle hooks, never client-invocable actions. Performing
         # "build_graph" would rebuild the graph and leak the old root;
@@ -77,13 +89,20 @@ module Hibiki
       # produces zero bytes, and "clear on the next render" would hang
       # forever. `delete`, not `[]`: the key must not reach the action
       # method's data. No `hbk`, no ack, so a 0.3.0 page keeps working.
+      #
+      # `hbt` is the third reserved key: the trips the browser timed since
+      # its last action (see Instrumentation#trips_from). Deleted whether or
+      # not anyone listens, for the same reason as `hbk`.
       def perform_action(data)
         seq = data.delete("hbk")
+        trips = trips_from(data.delete("hbt"))
+        asked = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         # A nil actor means the subscription was rejected or already torn
         # down; drop the action rather than blow up the cable thread.
         posted = @__hibiki_actor&.post do
-          Hibiki.batch { super(data) }
+          trips.each { instrument("trip", it) }
+          instrument_action(data, asked) { Hibiki.batch { super(data) } }
         ensure
           # Hibiki.batch flushes in its own ensure, so effects queued
           # before a raise have run by the time this does — the ack is
@@ -111,7 +130,9 @@ module Hibiki
         # The block runs owned + untracked (Hibiki.root); the effects it
         # creates do their dependency-collecting first run right here, on
         # the graph thread.
-        @__hibiki_actor.post { @__hibiki_root = Hibiki.root { build_graph } }
+        @__hibiki_actor.post do
+          instrument("subscribe") { @__hibiki_root = Hibiki.root { build_graph } }
+        end
         Hibiki::Rails.registry.register(self)
       end
 
@@ -123,7 +144,7 @@ module Hibiki
         return unless @__hibiki_actor
 
         Hibiki::Rails.registry.unregister(self)
-        @__hibiki_actor.post { @__hibiki_root.dispose }
+        @__hibiki_actor.post { instrument("unsubscribe") { @__hibiki_root.dispose } }
         @__hibiki_actor.stop
       end
 
@@ -168,24 +189,30 @@ module Hibiki
       end
 
       # Mirror graph state into the page's address bar: wraps the block in
-      # an effect that transmits `{ url: }`; the packaged client
-      # history.replaceState's the bar to it. replaceState, never pushState —
-      # the URL is a MIRROR of state, not a history entry, so Back needs no
-      # popstate choreography and leaves the page normally. Compute a
-      # same-origin path ("/songs?page=2" — the client refuses anything
-      # else), and omit params that hold their defaults, or the bar grows
-      # noise on the first transmit. Pair it with first-paint code that READS
-      # those params (controller + subscribe-params seeding), so the mirrored
-      # URL reloads to the state it names. Equality-gated like
-      # #transmit_value: re-runs track every signal read, re-sends only when
-      # the URL actually moved.
-      def transmit_url(&compute)
+      # an effect that transmits `{ url: }`, and the packaged client moves
+      # the bar to it. Compute a same-origin path ("/songs?page=2" — the
+      # client refuses anything else), and omit params that hold their
+      # defaults, or the bar grows noise on the first transmit. Pair it with
+      # first-paint code that READS those params (controller +
+      # subscribe-params seeding), so the mirrored URL reloads to the state
+      # it names. Equality-gated like #transmit_value: re-runs track every
+      # signal read, re-sends only when the URL actually moved.
+      #
+      # history: :replace (the default) is replaceState: the URL is a MIRROR
+      # of state, not a history entry, so Back leaves the page normally.
+      # history: :push makes each move an entry, for state that reads as a
+      # place (a wizard's step). Back then needs an answer: put
+      # `on(:visit, event: :popstate)` on the island root, and the client
+      # performs that action with the popped URL's query params. They come
+      # from the address bar, so treat them like a subscribe param.
+      def transmit_url(history: :replace, &compute)
+        frame = Channel.url_frame(history)
         last = Object.new
         Hibiki::Effect.new do
           url = compute.call.to_s
           unless url == last
             last = url
-            transmit({ url: })
+            transmit({ url: }.merge(frame))
           end
         end
       end

data/lib/hibiki/rails/helpers.rb

@@ -6,6 +6,7 @@ require "securerandom"
 
 require_relative "dom_props"
 require_relative "keys"
+require_relative "modifiers"
 
 module Hibiki
   module Rails
@@ -187,6 +188,10 @@ module Hibiki
       # `{ name => value }` — a checkbox its checked state, a multi-select
       # its selected values — and a submitted form contributes its FormData.
       #
+      # `event: :popstate` goes on the island root and answers Back and
+      # Forward over the entries `transmit_url(history: :push)` made; the
+      # payload is the popped URL's query.
+      #
       # Everything else is a per-control modifier, kept out of the token
       # grammar so the `->` left side stays purely "which event":
       #
@@ -221,9 +226,10 @@ module Hibiki
         action = Helpers.event_name(action)
         events = Array(event).map { Helpers.event(it) }
         debounce = DEFAULT_INPUT_DEBOUNCE if debounce.nil? && events.include?("input")
+        Modifiers.popstate!(debounce:, fallback:) if events.include?("popstate")
         tokens = events.map { "#{it}->#{action}" }.join(" ")
         { data: { hibiki_on: tokens }
-            .merge(on_modifiers(with:, debounce:, confirm:, reset:, fallback:)) }
+            .merge(Modifiers.attributes(with:, debounce:, confirm:, reset:, fallback:)) }
       end
 
       # Placeholder for a single reactive value: `<%= reactive :doubled, 0 %>`
@@ -305,20 +311,6 @@ module Hibiki
       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.
-      def on_modifiers(with:, debounce:, confirm:, reset:, fallback:)
-        {
-          hibiki_with: (JSON.generate(with) unless with.nil?),
-          # nonzero? returns the integer itself, so 0 compacts away.
-          hibiki_debounce: (Integer(debounce).nonzero? if debounce),
-          hibiki_confirm: confirm&.to_s,
-          hibiki_reset: ("false" if reset == false),
-          hibiki_fallback: ("true" if fallback)
-        }.compact
-      end
     end
   end
 end

data/lib/hibiki/rails/instrumentation.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # The channel's ActiveSupport::Notifications events (`*.hibiki_rails`).
+    # Always on: with no subscriber `instrument` only yields. The gem
+    # subscribes to none of them. A subscriber runs on the graph thread, so
+    # it holds up that graph for as long as it takes.
+    #
+    # All private — a public helper would become a client-invocable action
+    # (see the NOTE on Hibiki::Rails::Channel).
+    module Instrumentation
+      # The most trips one action may report, and the longest time one may
+      # claim, in ms. The figures come from a browser, so they are bounded
+      # rather than believed.
+      TRIP_LIMIT = 5
+      TRIP_RANGE = (0..60_000)
+
+      EVENTS = %w[subscribe unsubscribe action render trip].to_h { [it, "#{it}.hibiki_rails"] }.freeze
+
+      private
+
+      # With nobody listening this is one lookup and a yield; no payload is
+      # built.
+      def instrument(event, payload = nil, &)
+        return (yield({}) if block_given?) unless listening?(event)
+
+        ActiveSupport::Notifications.instrument(EVENTS.fetch(event), { channel: self.class.name, **payload }, &)
+      end
+
+      # `asked` is the clock as the cable thread posted the action; `wait` is
+      # how long the graph thread took to reach it, in ms. An action the
+      # channel does not have gets no event: the name is the client's, and a
+      # subscriber that stores it must not be handed arbitrary strings.
+      def instrument_action(data, asked)
+        action = data["action"].to_s
+        return yield unless listening?("action") && self.class.action_methods.include?(action)
+
+        before = @__hibiki_render_count.to_i
+        instrument("action", { action:, wait: ms_since(asked) }) do |payload|
+          yield
+        ensure
+          payload[:renders] = @__hibiki_render_count.to_i - before
+        end
+      end
+
+      def listening?(event) = ActiveSupport::Notifications.notifier.listening?(EVENTS.fetch(event))
+
+      def ms_since(clock) = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - clock) * 1000
+
+      def instrument_render(method:, target: nil, &)
+        @__hibiki_render_count = @__hibiki_render_count.to_i + 1
+        instrument("render", { target:, method: }.compact, &)
+      end
+
+      # The trips a browser reported under `hbt`, as event payloads. Each is
+      # `[action, ack, paint]`: ms to the ack, and ms to the first render, or
+      # nil when nothing rendered.
+      def trips_from(reported)
+        reported.is_a?(Array) ? reported.first(TRIP_LIMIT).filter_map { trip(*it) } : []
+      end
+
+      def trip(action = nil, ack = nil, paint = nil, *)
+        return unless action.is_a?(String) && self.class.action_methods.include?(action)
+        return unless ack.is_a?(Numeric) && (paint.nil? || paint.is_a?(Numeric))
+
+        { action:, ack: ack.clamp(TRIP_RANGE), paint: paint&.clamp(TRIP_RANGE) }
+      end
+    end
+  end
+end

data/lib/hibiki/rails/modifiers.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hibiki
+  module Rails
+    # Helpers#on's per-control modifiers, kept out of the token grammar.
+    module Modifiers
+      # The attributes beside hibiki_on. Each is omitted when it matches the
+      # client's own default, so the common call still stamps exactly one.
+      def self.attributes(with:, debounce:, confirm:, reset:, fallback:)
+        {
+          hibiki_with: (JSON.generate(with) unless with.nil?),
+          # nonzero? returns the integer itself, so 0 compacts away.
+          hibiki_debounce: (Integer(debounce).nonzero? if debounce),
+          hibiki_confirm: confirm&.to_s,
+          hibiki_reset: ("false" if reset == false),
+          hibiki_fallback: ("true" if fallback)
+        }.compact
+      end
+
+      # Back is not a gesture on a control: it has nothing to wait for and
+      # no native destination to fall back to.
+      def self.popstate!(**modifiers)
+        given = modifiers.compact.keys
+        raise ArgumentError, "a popstate event takes no #{given.join(' or ')}" if given.any?
+      end
+    end
+  end
+end

data/lib/hibiki/rails/registry.rb

@@ -28,6 +28,13 @@ module Hibiki
         @lock.synchronize { @channels.size }
       end
 
+      # The live subscriptions by channel class name. Count from this rather
+      # than from subscribe and unsubscribe events: a development reload
+      # drops sockets without running `unsubscribed`.
+      def tally
+        @lock.synchronize { @channels.map { it.class.name }.tally }
+      end
+
       # Close each distinct cable connection, which routes every one of
       # its channels through the normal unsubscribed path — dispose root,
       # stop actor, unregister — so teardown has exactly ONE code path and

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.17.2"
+    VERSION = "0.19.0"
   end
 end

data/lib/hibiki/rails.rb

@@ -68,6 +68,7 @@ require_relative "rails/version"
 require_relative "rails/registry"
 require_relative "rails/graph_actor"
 require_relative "rails/debounce"
+require_relative "rails/instrumentation"
 require_relative "rails/broadcasts"
 require_relative "rails/channel"
 require_relative "rails/nested_actions"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.17.2
+  version: 0.19.0
 platform: ruby
 authors:
 - planetaska
@@ -187,7 +187,9 @@ files:
 - lib/hibiki/rails/engine.rb
 - lib/hibiki/rails/graph_actor.rb
 - lib/hibiki/rails/helpers.rb
+- lib/hibiki/rails/instrumentation.rb
 - lib/hibiki/rails/keys.rb
+- lib/hibiki/rails/modifiers.rb
 - lib/hibiki/rails/nested_actions.rb
 - lib/hibiki/rails/reactive_form.rb
 - lib/hibiki/rails/registry.rb