hibiki_rails 0.17.0 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbcb87c658d3e83cc6c10f216a69e78266878aa8396ed9662e3f06d8c6213027
-  data.tar.gz: d6a66d149293d26e43edf4cd31ec20eb5886cc0d3db2b935b5b0c3c333965292
+  metadata.gz: 4919aaf1d8c96e1436138dfc5c0050602e0590447ccf9daebb5598072bf01e2d
+  data.tar.gz: 214048d87eec87fa482744750f736eb3d3004381864e69c12b1664a10ffaf9a5
 SHA512:
-  metadata.gz: 0e027bd60c62abdf4d269b94cd38f0e008889b42d205b9f2d98d737f1455acd60f467cf9951a5a35f77bbc3ee02120b8e5f6397fc43dc9b7dc7842d91c73372e
-  data.tar.gz: 28a6058a2a235ef23e02d52b5dbdf7177f97b6ba96971d9c72ea0d0302d6eaf380854b2e283069177b2038a06a2d45af540bf3b929a62f53baa7144589c33bc3
+  metadata.gz: f1da64047eb007f11f45f55007519808ad717f9b53968273455586c3977486f1e03e2478f9041c05a7f9d889191d6591a7e116e21d918dfb7719b337e0eeed3b
+  data.tar.gz: 1ed922620989a1997ef4231a7c2e737cbca070ff3c3917966c74b1ed48c28e087e08fd7763152eeb96b713e8675b5126d831b07e5e4dc10e22c31d20cb908fdb

data/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.17.1 — 2026-10-09
+
+### Fixed
+
+**Renders sent over the broadcast transport could reach the page out of
+order.** Action Cable hands each broadcast to a pool of threads, so two
+renders a channel sent a millisecond apart could be delivered in either
+order. When both drew the same target, the page ended on the older one and
+stayed wrong until something rendered that target again: a Save button left
+enabled, a note that contradicted the server's state. It was always
+possible; since 0.17.0 sends a debounced field's text just ahead of a click
+or a submit, any form with one did it routinely.
+
+- `broadcast_replace` and `broadcast_morph` now number their renders, and
+  the client applies them in the order the channel sent them. Nothing changes
+  in the channel or the view.
+- A render that arrives ahead of an earlier one waits for it, for at most
+  100 ms. One that arrives later than that is still drawn, unless a newer
+  render has drawn the same target since.
+- `broadcast_refresh`, the transmit transport, and streams an app sends with
+  `Turbo::StreamsChannel` itself are not affected and not changed.
+- Both halves are needed, so update the gem and the npm package together. A
+  page on one side only behaves as 0.17.0 did.
+- `broadcast_replace` and `broadcast_morph` also accept `attributes:`, which
+  are kept on the stream beside the gem's own.
+
 ## 0.17.0 — 2026-10-08
 
 ### Added

data/app/assets/javascripts/hibiki.js

@@ -66,6 +66,9 @@
 //                 beside them existing to change the text
 //   focus sites   data-hibiki-focus="true|select"      takes focus, and has its
 //                 text selected, when a render this tab caused inserts it
+//   turbo streams data-hibiki-seq="3"                  the render's number, and
+//                 data-hibiki-from="CounterChannel/<cid>" the island it is for;
+//                 see "Render order" below
 //
 // The client writes the protocol's other half at runtime — read-only to
 // app code, addressed to app CSS:
@@ -118,6 +121,16 @@
 // nearest id-bearing ancestor. Only controls: when none of these is there,
 // focus is left where the browser put it. Any render, whoever caused it.
 //
+// Render order. Action Cable hands each broadcast to a worker pool, so two
+// renders the channel sent a millisecond apart can arrive in either order,
+// and the page would end on the older one. The channel numbers its Turbo
+// streams and the island applies them in that order: one that arrives ahead
+// of its turn is held until the missing ones come, or until `orderGrace`
+// runs out on one that never will. A render that turns up after it was
+// given up on is still drawn, unless a later one has drawn the same target
+// since. A stream with no number, or another island's, is left alone. The
+// transmit transport needs none of this: it writes to the socket in order.
+//
 // 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
 // the island's OWN subscription: `perform(action, payload)` on the island
@@ -753,6 +766,11 @@ export default class HibikiController extends ChannelController {
   // stamps no data-hibiki-params-value.
   static values = { channel: String, params: Object }
 
+  // ms a Turbo render that arrived ahead of its turn waits for the ones
+  // before it (see inOrder). Only a lost broadcast waits it out; a late one
+  // is a pool hop behind, a millisecond or two.
+  static orderGrace = 100
+
   // The island stamps its channel; no inference.
   channelName() {
     return this.channelValue
@@ -833,19 +851,23 @@ export default class HibikiController extends ChannelController {
     // Re-scan at the points a fragment can be swapped under us, rather
     // than blanket-observing the document: a MutationObserver over the page
     // is a real per-mutation cost paid by every app on it.
+    this.resetOrder()
     this.streamRender = (event) => {
       const render = event.detail.render
+      const stream = event.detail.newStream
+      // Taken now, not when the render's turn comes: see arrival().
       const arrival = this.arrival()
-      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.scan(arrival)
-      }
+      event.detail.render = (streamElement) =>
+        this.inOrder(stream, async () => {
+          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.scan(arrival)
+        })
     }
     document.addEventListener("turbo:before-stream-render", this.streamRender)
     // A refresh stream morphs the page after its own render has returned,
@@ -882,9 +904,99 @@ export default class HibikiController extends ChannelController {
     this.unsent.clear()
     this.marks.clear()
     this.observer.disconnect()
+    this.resetOrder()
     super.disconnect()
   }
 
+  // A reconnect builds a fresh graph, which numbers its renders from 1.
+  linkClosed() {
+    this.resetOrder()
+    super.linkClosed()
+  }
+
+  // ── Render order ──────────────────────────────────────────────────────
+  //
+  // `due` is the number of the next render to apply and `held` the renders
+  // waiting on it, by number. `missed` and `drawn` exist only after a gap
+  // was given up on: the numbers skipped, and the last number drawn into
+  // each target since, which is what tells a late render it is stale.
+
+  // Run `job` (the render and what follows it) when the stream's turn
+  // comes, or never when it is stale. Jobs are CALLED in order and not
+  // awaited: a call reaches the swap, or the motion module's queue, before
+  // it returns, and that queue keeps the order from there.
+  inOrder(stream, job) {
+    const seq = Number(stream?.getAttribute?.("data-hibiki-seq"))
+    if (!seq || stream.getAttribute("data-hibiki-from") !== `${this.channelValue}/${this.cidValue}`) {
+      return job()
+    }
+    const target = stream.getAttribute("target")
+    const run = () => {
+      this.drew(target, seq)
+      return job()
+    }
+    if (seq < this.due) {
+      // Late. A number never given up on is a repeat, or older than
+      // anything remembered.
+      const stale = !this.missed.delete(seq) || this.drawn.get(target) > seq
+      return stale ? Promise.resolve() : run()
+    }
+    if (seq > this.due) {
+      return new Promise((resolve) => {
+        this.held.set(seq, () => resolve(run()))
+        this.orderTimer ??= setTimeout(() => this.giveUp(), this.constructor.orderGrace)
+      })
+    }
+    const done = run()
+    this.due++
+    this.release()
+    return done
+  }
+
+  // Apply the held renders that now follow on. Any still held wait on a
+  // new gap, with a new grace.
+  release() {
+    for (let run; (run = this.held.get(this.due)); this.due++) {
+      this.held.delete(this.due)
+      run()
+    }
+    clearTimeout(this.orderTimer)
+    this.orderTimer = this.held.size
+      ? setTimeout(() => this.giveUp(), this.constructor.orderGrace)
+      : undefined
+  }
+
+  // The grace ran out: move past the missing numbers to the first held.
+  giveUp() {
+    const first = Math.min(...this.held.keys())
+    for (let seq = this.due; seq < first; seq++) this.missed.add(seq)
+    this.missedAt = performance.now()
+    this.due = first
+    this.release()
+  }
+
+  // Remember what was drawn while a missed render may still turn up, and
+  // no longer: one later than the ceiling is lost by the same measure a
+  // trip is.
+  drew(target, seq) {
+    if (performance.now() - this.missedAt > this.constructor.busyCeiling) this.missed.clear()
+    if (!this.missed.size) return this.drawn.clear()
+    if (!(this.drawn.get(target) > seq)) this.drawn.set(target, seq)
+  }
+
+  // Start counting again from 1. Renders still held are the old graph's
+  // last word, so they are applied first, in order.
+  resetOrder() {
+    clearTimeout(this.orderTimer)
+    this.orderTimer = undefined
+    const held = [...(this.held ?? [])].sort(([a], [b]) => a - b)
+    this.due = 1
+    this.held = new Map()
+    this.missed = new Set()
+    this.drawn = new Map()
+    for (const [, run] of held) run()
+  }
+
   // The other swap point: hibiki's own transmit transport. A held swap
   // hands back a promise; the replacement sentinel exists only after it.
   received(data) {

data/lib/hibiki/rails/broadcasts.rb

@@ -17,16 +17,16 @@ module Hibiki
 
       # Replace the element with DOM id `target` (accepts partial:/locals:,
       # html:, or anything Turbo's renderer takes).
-      def broadcast_replace(target:, **rendering)
-        Turbo::StreamsChannel.broadcast_replace_to(*stream_name, target:, **rendering)
+      def broadcast_replace(target:, attributes: {}, **rendering)
+        Turbo::StreamsChannel.broadcast_replace_to(
+          *stream_name, target:, attributes: attributes.merge(render_stamp), **rendering
+        )
       end
 
       # Replace via Turbo 8 morphing (<turbo-stream action="replace"
       # method="morph">): keeps focus/scroll where a plain replace resets.
-      def broadcast_morph(target:, **rendering)
-        Turbo::StreamsChannel.broadcast_replace_to(
-          *stream_name, target:, attributes: { method: :morph }, **rendering
-        )
+      def broadcast_morph(target:, attributes: {}, **rendering)
+        broadcast_replace(target:, attributes: { method: :morph }.merge(attributes), **rendering)
       end
 
       # Tell the page to refresh itself (Turbo 8 morph-everything style).
@@ -47,6 +47,17 @@ module Hibiki
           broadcast_refresh
         end
       end
+
+      # The number each render carries, and the island it is for. Action
+      # Cable hands every broadcast to a worker pool, so two sent a
+      # millisecond apart can reach the page in either order; the client
+      # applies them by number. Counted per subscription from 1, on the
+      # graph thread alone. A refresh carries none: it fetches the page, so
+      # its order does not matter. Part of the private data-hibiki contract.
+      def render_stamp
+        @__hibiki_renders = @__hibiki_renders.to_i + 1
+        { "data-hibiki-seq": @__hibiki_renders, "data-hibiki-from": "#{self.class.name}/#{params[:cid]}" }
+      end
     end
   end
 end

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.17.0"
+    VERSION = "0.17.1"
   end
 end

metadata

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