hibiki_rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62779990991fb78726bc665b7ad93a93dabee5b49892fa99f6486ad42dc41679
-  data.tar.gz: 9cac4fa0143ab6b5f031d9ea0d9d213a1505108e1aa06894773d59f8594b6023
+  metadata.gz: 45614c5c98f4439de6f22da45a49d163ab7a06eccf53ed36108ee04d6b5c7f78
+  data.tar.gz: c1dd28764cc7462dbb7ceaa5d0b76e1a0371bd8cc5523fe54545533d7b759c36
 SHA512:
-  metadata.gz: bf6340bdef27fd3c320fff3a8d7fb90967d883783a965e61a90ccbae5d536b7bdcdfcba536d827089d3b389af1c07439ff7031ee11792c95a579752c8b235706
-  data.tar.gz: a9337451b21ecd955590683648f8a6d824bafa703ce096937387cff0fafaedf5ee5a959089558f7bf02037b00d39e40fd9fcab1bf3176cd976dcd1b957ab6443
+  metadata.gz: 4908f9d337c86d575287ff2d21d3d74cd112334e893e8b042cb07e7e8a1de141ddd892b17b4b86d90ac2008ce8c7d9f4390fd1ebdd1cc1cafe88e75c6530c360
+  data.tar.gz: 392976be271a02c7b5e354ec0d3e46117e1a8772cb0a68b99d4570f1f95309bc7abac3e0cd3ca38961eaea5eb849d4e4343effa55911629d367555949ac93408

data/README.md

@@ -76,8 +76,11 @@ Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>
 ## Development
 
 ```
-bundle exec rake   # specs + rubocop (same as CI)
+bundle exec rake   # Ruby specs + rubocop
+bun install && bun run test   # the client's own specs
 ```
 
-The spec suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`).
+Both are what CI runs. The Ruby suite boots a minimal inline Rails app (`spec/support/dummy_app.rb`); the JS suite (`spec/js/`) drives the real Stimulus controller in happy-dom against a stubbed Action Cable consumer.
+
+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/).
 

data/app/assets/javascripts/hibiki.js

@@ -44,11 +44,23 @@
 //   island root   data-controller="hibiki"
 //                 data-hibiki-channel-value="CounterChannel"
 //                 data-hibiki-cid-value="<per-page-load id>"
-//   controls      data-hibiki-on="<event>-><action>"   e.g. "click->increment"
+//                 data-hibiki-params-value='{"record_id":7}'  extra subscribe
+//                 params, merged UNDER channel/cid so they can't override them
+//   controls      data-hibiki-on="<event>-><action> ..."  whitespace-separated;
+//                 e.g. "click->load_more visible->load_more"
 //                 data-hibiki-with='{"index":3}'       optional JSON payload
+//                 data-hibiki-debounce="250"           ms to let the gesture settle
+//                 data-hibiki-confirm="Are you sure?"  window.confirm gate
+//                 data-hibiki-reset="false"            keep a submitted form's inputs
 //   value sites   data-hibiki-value="<name>"           reactive-value placeholder;
 //                 the server's transmit_value message updates every match
 //
+// 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.
+//
 // Register the generic controller under the identifier "hibiki" (the
 // helpers hardcode it):
 //
@@ -65,6 +77,19 @@ let consumer
 // camelCase Stimulus method name → snake_case Ruby channel action.
 const underscore = (name) => name.replace(/([A-Z])/g, "_$1").toLowerCase()
 
+// What a changed control contributes to its action's payload. A checkbox's
+// `value` is its value ATTRIBUTE, not its state, so reading `value` made
+// checking and unchecking send byte-identical payloads; a multi-select's
+// `value` is only its first selected option. A radio needs no special case:
+// `change` fires on the newly-checked input, so `value` is already right.
+const controlValue = (control) => {
+  if (control.type === "checkbox") return control.checked
+  if (control.multiple && control.selectedOptions) {
+    return [...control.selectedOptions].map((option) => option.value)
+  }
+  return control.value
+}
+
 // The subclassable base: one channel subscription per controller element,
 // identified by a per-page-load cid (data-<identifier>-cid-value).
 export class ChannelController extends Controller {
@@ -82,20 +107,28 @@ export class ChannelController extends Controller {
     if (source) await streamConnected(source)
     if (this.aborted) return // disconnected during the await
     this.subscription = consumer.subscriptions.create(
-      { channel: this.channelName(), cid: this.cidValue },
+      this.subscribeParams(),
       { received: (data) => this.received(data) }
     )
   }
 
+  // What identifies this subscription to the server. Override to add
+  // params; keep channel/cid, which the Ruby side requires.
+  subscribeParams() {
+    return { channel: this.channelName(), cid: this.cidValue }
+  }
+
   disconnect() {
     this.aborted = true
     this.subscription?.unsubscribe()
     this.subscription = undefined
   }
 
-  // DOM → server: what declared action methods call.
+  // 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.
   perform(action, payload = {}) {
-    this.subscription.perform(action, payload)
+    this.subscription?.perform(action, payload)
   }
 
   // Server → DOM (transmit transport). Two message shapes:
@@ -177,57 +210,174 @@ export class ChannelController extends Controller {
 // The generic controller: adds the data-hibiki-* wire protocol on top of
 // the base's plumbing.
 export default class HibikiController extends ChannelController {
-  static values = { channel: String } // cid inherited from the base
+  // cid inherited from the base. `params` defaults to {} when the island
+  // stamps no data-hibiki-params-value.
+  static values = { channel: String, params: Object }
 
   // The island stamps its channel; no inference.
   channelName() {
     return this.channelValue
   }
 
+  // Extra subscribe params go UNDER channel/cid: they are client-supplied,
+  // so a page must not be able to point its subscription at another channel
+  // or steal another tab's graph by naming its cid. The server-side rule
+  // that goes with this is in Helpers#hibiki_island.
+  subscribeParams() {
+    return { ...this.paramsValue, ...super.subscribeParams() }
+  }
+
   async connect() {
     // 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.
-    this.listeners = ["click", "change", "submit"].map((type) => {
+    this.listeners = ["click", "change", "input", "submit"].map((type) => {
       const handler = (event) => this.forward(event)
       this.element.addEventListener(type, handler)
       return [type, handler]
     })
+
+    // Debounce bookkeeping: a WeakMap keyed by control (so detached
+    // elements don't pin memory) plus a flat set of live timeouts, which is
+    // what disconnect can actually iterate.
+    this.timers = new WeakMap()
+    this.pending = new Set()
+
+    // `visible` is not a DOM event, so it needs its own observer beside the
+    // delegated listeners. Always on, never a pluggable module: an
+    // IntersectionObserver watching zero elements costs nothing at runtime,
+    // while an optional import brings back the failure mode where the
+    // attribute is present, the code isn't, and nothing errors.
+    this.observer = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue
+        // Fire once per observation. The re-scan after the next swap
+        // observes the REPLACEMENT element, and its fresh initial callback
+        // is what stops the classic "the new page didn't fill the viewport,
+        // so the loop stalls" trap.
+        this.observer.unobserve(entry.target)
+        this.dispatch(entry.target, { type: "visible", target: entry.target })
+      }
+    })
+
+    // Re-scan at the two 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.streamRender = (event) => {
+      const render = event.detail.render
+      event.detail.render = async (streamElement) => {
+        await render(streamElement)
+        this.scanSentinels()
+      }
+    }
+    document.addEventListener("turbo:before-stream-render", this.streamRender)
+
     await super.connect()
+    if (this.aborted) return
+    this.scanSentinels()
   }
 
   disconnect() {
     for (const [type, handler] of this.listeners) {
       this.element.removeEventListener(type, handler)
     }
+    document.removeEventListener("turbo:before-stream-render", this.streamRender)
+    for (const id of this.pending) clearTimeout(id)
+    this.pending.clear()
+    this.observer.disconnect()
     super.disconnect()
   }
 
-  // DOM → server: forward a control's event as a channel action. Nested
-  // islands: events bubble to every ancestor island's listener, so each
-  // controller only acts when the control belongs to ITS island.
+  // The other swap point: hibiki's own transmit transport.
+  received(data) {
+    super.received(data)
+    if (data.html) this.scanSentinels()
+  }
+
+  // Observe every `visible->` sentinel this island owns. observe() is a
+  // no-op for an element already being observed, so re-scanning is cheap
+  // and cannot double-fire a sentinel that merely stayed put.
+  scanSentinels() {
+    for (const control of this.element.querySelectorAll('[data-hibiki-on*="visible->"]')) {
+      if (control.closest('[data-controller~="hibiki"]') === this.element) {
+        this.observer.observe(control)
+      }
+    }
+  }
+
+  // DOM → server: forward a control's event as a channel action.
   forward(event) {
     const control = event.target.closest("[data-hibiki-on]")
-    if (!control) return
+    if (control) this.dispatch(control, event)
+  }
+
+  // The shared path for both sources of events — the delegated DOM
+  // listeners and the visibility observer.
+  dispatch(control, event) {
+    // Nested islands: events bubble to every ancestor island's listener, so
+    // each controller only acts when the control belongs to ITS island.
     if (control.closest('[data-controller~="hibiki"]') !== this.element) return
 
     const token = control.dataset.hibikiOn
       .split(/\s+/)
       .find((t) => t.startsWith(`${event.type}->`))
     if (!token) return
-
     const action = token.slice(event.type.length + 2)
+
+    // Before the confirm, not after: declining must not let the form
+    // navigate away.
+    if (event.type === "submit") event.preventDefault()
+
+    const message = control.dataset.hibikiConfirm
+    if (message && !window.confirm(message)) return
+
+    // The payload is built when the action actually fires, so a debounced
+    // input sends what the user finished typing rather than the first
+    // keystroke that started the timer.
+    const wait = Number(control.dataset.hibikiDebounce)
+    const fire = () => this.send(control, event, action)
+    if (wait > 0) this.debounce(control, action, wait, fire)
+    else fire()
+  }
+
+  send(control, event, action) {
     const payload = control.dataset.hibikiWith
       ? JSON.parse(control.dataset.hibikiWith)
       : {}
     if (event.type === "submit") {
-      event.preventDefault()
       Object.assign(payload, Object.fromEntries(new FormData(control)))
-    } else if (event.type === "change" && control.name) {
-      payload[control.name] = control.value
+    } else if (control.name && (event.type === "change" || event.type === "input")) {
+      payload[control.name] = controlValue(control)
     }
     this.perform(action, payload)
-    if (event.type === "submit") control.reset()
+    // 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.
+    if (event.type === "submit" && control.dataset.hibikiReset !== "false") {
+      control.reset()
+    }
+  }
+
+  // One timer per (control, action): two events on one element debounce
+  // independently, and a second control's typing never cancels the first's.
+  debounce(control, action, wait, fire) {
+    let byAction = this.timers.get(control)
+    if (!byAction) {
+      byAction = new Map()
+      this.timers.set(control, byAction)
+    }
+    const previous = byAction.get(action)
+    if (previous) {
+      clearTimeout(previous)
+      this.pending.delete(previous)
+    }
+    const id = setTimeout(() => {
+      byAction.delete(action)
+      this.pending.delete(id)
+      fire()
+    }, wait)
+    byAction.set(action, id)
+    this.pending.add(id)
   }
 }
 

data/lib/hibiki/rails/channel.rb

@@ -36,13 +36,23 @@ module Hibiki
       end
 
       module ClassMethods
-        private
+        # Lifecycle hooks, never client-invocable actions. Performing
+        # "build_graph" would rebuild the graph and leak the old root;
+        # "subscribed" would build a SECOND graph actor on the connection.
+        #
+        # These need subtracting because ActionCable computes action_methods
+        # as "public methods this class adds": #subscribed and #unsubscribed
+        # are private on its base class, so they are never subtracted for
+        # free, and a public app-side override — the shape the ActiveRecord
+        # guide's after_commit bridge invites — is added straight back by
+        # public_instance_methods(false).
+        HIDDEN_ACTIONS = %w[build_graph subscribed unsubscribed].freeze
 
-        # #build_graph is a lifecycle hook, not a client-invocable action:
-        # keep it out of action_methods even when an app defines it public
-        # (a client performing "build_graph" would rebuild the graph and
-        # leak the old root).
-        def internal_methods = super + [:build_graph]
+        # Subtracted here rather than through ActionCable's #internal_methods
+        # hook, which only exists on 8.x: on Rails 7.1 and 7.2 that hook is
+        # never consulted, so an override of it is silently dead code. This
+        # works on every supported version.
+        def action_methods = super - HIDDEN_ACTIONS
       end
 
       # ActionCable's single dispatch point for incoming actions. The whole
@@ -101,10 +111,27 @@ module Hibiki
       # derived, or an expression over several). Values are text, never
       # markup: the client assigns textContent, so nothing is interpreted as
       # HTML. Returns the effect, owned by the graph root like any other.
+      #
+      # Equality-gated: an effect re-runs whenever ANY signal it read
+      # changed, so a bumped db_version re-sent every value's text even when
+      # the text was byte-identical — once per reactive value, per ping.
+      # The block is still called unconditionally, so dependency collection
+      # is untouched; only the transmit is skipped.
+      #
+      # NOTE for placeholders rendered INSIDE a broadcast-replaced fragment:
+      # render them with their CURRENT value, not a static default. The swap
+      # resets the DOM text, and this gate now suppresses the re-send that
+      # used to heal it. Placeholders outside the replaced fragment (a nav
+      # badge, controls that are never re-rendered) are unaffected.
       def transmit_value(name, &compute)
         name = Helpers.value_name(name)
+        last = Object.new # never == a String, so the first run always sends
         Hibiki::Effect.new do
-          transmit({ value: { name:, text: compute.call.to_s } })
+          text = compute.call.to_s
+          unless text == last
+            last = text
+            transmit({ value: { name:, text: } })
+          end
         end
       end
 

data/lib/hibiki/rails/graph_actor.rb

@@ -46,9 +46,23 @@ module Hibiki
 
       # Per-job rescue keeps the worker alive: one bad action must not take
       # the whole graph down. StandardError only — an Interrupt should.
+      #
+      # Each job is one unit of work in the Rails sense, so it runs inside
+      # the executor: CurrentAttributes reset between jobs (state must not
+      # leak from one action to the next on a long-lived graph thread),
+      # Zeitwerk's permit_concurrent_loads around autoloads off the main
+      # thread, an AR query cache per job, and reloader participation.
+      #
+      # The rescue sits INSIDE the wrap deliberately. ExecutionWrapper.wrap
+      # reports anything that escapes it to Rails.error itself — handled:
+      # false, source "application.active_support" — and then re-raises, so
+      # rescuing outside would report every graph error twice, once as
+      # unhandled. Rescuing inside means @on_error stays the single sink for
+      # a StandardError; a non-StandardError still escapes the wrap and takes
+      # the worker down, exactly as before.
       def work
         while (job = @queue.pop)
-          begin
+          ::Rails.application.executor.wrap do
             job.call
           rescue StandardError => e
             @on_error.call(e)

data/lib/hibiki/rails/helpers.rb

@@ -15,7 +15,10 @@ module Hibiki
     #     button(**on(:increment)) { "+" }
     #     button(**on(:toggle, with: { index: 3 })) { "toggle" }
     #     input(name: "step", **on(:set_step, event: :change))
-    #     form(**on(:add, event: :submit)) { ... }
+    #     input(name: "q", **on(:search, event: :input))
+    #     button(**on(:destroy, confirm: "Are you sure?")) { "delete" }
+    #     button(**on(:load_more, event: %i[click visible])) { "more" }
+    #     form(**on(:save, event: :submit, reset: false)) { ... }
     #   end
     #
     # Both helpers return a `{ data: { ... } }` hash: splat it into Phlex
@@ -36,7 +39,21 @@ module Hibiki
       # lands in raw markup, so allowlist it too.
       VALUE_NAME = /\A[a-z][a-z0-9_-]*\z/i
       VALUE_TAG = /\A[a-z][a-z0-9-]*\z/i
-      private_constant :VALUE_NAME, :VALUE_TAG
+
+      # Event and action names share the hibiki_on attribute, which is a
+      # whitespace-separated token list — a name carrying a space or an
+      # arrow would silently change what the client dispatches. The dot is
+      # allowed so a future event qualifier (keydown.enter) needs no second
+      # grammar change.
+      EVENT_NAME = /\A[a-z][a-z0-9_.-]*\z/i
+
+      # Per-keystroke round trips are the failure mode #on exists to avoid,
+      # so :input carries a debounce unless the caller says otherwise. It is
+      # applied here rather than in the client, so the number is visible in
+      # the emitted markup instead of being an invisible default.
+      DEFAULT_INPUT_DEBOUNCE = 250
+
+      private_constant :VALUE_NAME, :VALUE_TAG, :EVENT_NAME
 
       # The shared name validator for both halves of a reactive value (the
       # view-side data-hibiki-value placeholder and the channel's
@@ -50,24 +67,80 @@ module Hibiki
         name
       end
 
+      # The shared validator for both halves of an `event->action` token.
+      def self.event_name(name)
+        name = name.to_s
+        unless EVENT_NAME.match?(name)
+          raise ArgumentError,
+                "event or action name #{name.inspect} must match #{EVENT_NAME.inspect}"
+        end
+        name
+      end
+
       # The island root: one channel subscription per island, identified by
       # a per-page-load cid (each tab is its own graph). `channel` is the
       # channel class or its name as a string.
-      def hibiki_island(channel, cid:)
+      #
+      # `params:` is a hash of extra subscribe params, reaching the channel
+      # as `params[:key]` beside `cid`. It is how a channel learns WHICH
+      # record its page is about (a show page's `record_id`), which is
+      # otherwise unexpressible — the subscription is the only server-side
+      # hook that runs before the graph is built.
+      #
+      # THE TRUST RULE. Subscribe params are client-supplied and untrusted,
+      # exactly like query params on a request: anyone can open a socket and
+      # send whatever they like. A channel may use one only to LOOK UP A
+      # RECORD INSIDE A SCOPE IT CHOOSES ITSELF —
+      # `current_user.books.find(params[:record_id])` — and must `reject`
+      # when the lookup fails. It must never interpolate a param into a
+      # streamable name, a class name, a column name, or a scope. The
+      # streamable a channel streams from is always derived server-side from
+      # the record it has already loaded and authorized. The client cannot
+      # override `channel` or `cid` through this hash.
+      def hibiki_island(channel, cid:, params: nil)
         channel_name = channel.is_a?(Class) ? channel.name : channel.to_s
-        { data: { controller: "hibiki", hibiki_channel_value: channel_name,
-                  hibiki_cid_value: cid } }
+        data = { controller: "hibiki", hibiki_channel_value: channel_name,
+                 hibiki_cid_value: cid }
+        data[:hibiki_params_value] = JSON.generate(params) unless params.nil?
+        { data: }
       end
 
-      # Forward a DOM event on this element as a channel action. `event:`
-      # picks the DOM event (:click, :change, :submit); `with:` is a hash
-      # sent as the action's payload. The client adds event-derived data on
-      # top: a changed control contributes `{ name => value }`, a submitted
-      # form contributes its FormData (and is reset after the perform).
-      def on(action, event: :click, with: nil)
-        data = { hibiki_on: "#{event}->#{action}" }
-        data[:hibiki_with] = JSON.generate(with) unless with.nil?
-        { data: }
+      # Forward an event on this element as a channel action.
+      #
+      # `event:` names the event, or a list of them — the left side of the
+      # `->` is a hibiki event name, of which DOM events are a subset:
+      # :click, :change, :input, :submit, plus the :visible pseudo-event
+      # (an IntersectionObserver sentinel — the element entering the
+      # viewport). A list makes one element answer several, which is how a
+      # load-more button doubles as an infinite-scroll sentinel:
+      #
+      #   on(:load_more, event: %i[click visible], with: { shown: rows.size })
+      #
+      # `with:` is a hash sent as the action's payload. The client adds
+      # event-derived data on top: a changed control contributes
+      # `{ name => value }` — a checkbox its checked state, a multi-select
+      # its selected values — and a submitted form contributes its FormData.
+      #
+      # Everything else is a per-control modifier, kept out of the token
+      # grammar so the `->` left side stays purely "which event":
+      #
+      #   debounce: ms  wait for the gesture to settle before performing.
+      #                 :input defaults to DEFAULT_INPUT_DEBOUNCE; pass 0 to
+      #                 send every keystroke.
+      #   confirm: msg  window.confirm before performing; declining performs
+      #                 nothing (and does not submit the form).
+      #   reset: false  keep a submitted form's inputs. The default resets
+      #                 them, which is right for an "add" form and wrong for
+      #                 an edit one — a failed commit would otherwise discard
+      #                 what the user typed, synchronously, before the server
+      #                 has even replied.
+      def on(action, event: :click, with: nil, debounce: nil, confirm: nil, reset: nil)
+        action = Helpers.event_name(action)
+        events = Array(event).map { Helpers.event_name(it) }
+        debounce = DEFAULT_INPUT_DEBOUNCE if debounce.nil? && events.include?("input")
+        tokens = events.map { "#{it}->#{action}" }.join(" ")
+        { data: { hibiki_on: tokens }
+            .merge(on_modifiers(with:, debounce:, confirm:, reset:)) }
       end
 
       # Placeholder for a single reactive value: `<%= reactive :doubled, 0 %>`
@@ -92,6 +165,21 @@ module Hibiki
       # The value's attributes, for stamping the placeholder yourself — the
       # Phlex form of #reactive: `span(**reactive_attrs(:doubled)) { "0" }`.
       def reactive_attrs(name) = { data: { hibiki_value: Helpers.value_name(name) } }
+
+      private
+
+      # #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:)
+        debounce = Integer(debounce) if debounce
+        {
+          hibiki_with: (JSON.generate(with) unless with.nil?),
+          hibiki_debounce: (debounce unless debounce.nil? || debounce.zero?),
+          hibiki_confirm: confirm&.to_s,
+          hibiki_reset: ("false" if reset == false)
+        }.compact
+      end
     end
   end
 end

data/lib/hibiki/rails/reactive_form.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Hibiki
+  module Rails
+    # A reactive form object over one ActiveRecord record: hydrate its
+    # attributes into signals at one edge, work reactively in the middle,
+    # commit back at the other. The record itself never enters the graph.
+    #
+    #   class TodoForm
+    #     include Hibiki::Rails::ReactiveForm
+    #
+    #     reactive_attributes Todo, :title, :done
+    #
+    #     derived(:title_error) { "can't be blank" if title.strip.empty? }
+    #     derived(:valid?)      { title_error.nil? }
+    #   end
+    #
+    #   form = TodoForm.from(Todo.find(id))   # or Todo.new — see below
+    #   form.title = "buy milk"               # a plain signal write
+    #   form.dirty?                           # => true
+    #   form.commit                           # => false if invalid
+    #   form.error_for(:title)                # => the model's own message
+    #
+    # One form class serves create AND update, the `form_with model:`
+    # convention: `from(Todo.new)` hydrates the column defaults and `commit`
+    # on an unpersisted record INSERTs, so create-vs-update is invisible to
+    # the caller. `dirty?` on a create form means "changed from the
+    # defaults" — exactly what enables a Create button.
+    #
+    # Two layers of validation, deliberately: hand-written deriveds give
+    # per-keystroke feedback (hand-picked, like client-side validation),
+    # while the model's own `validates` stay authoritative at commit and
+    # land in #errors. Nothing here names an ActiveRecord constant — the
+    # record is duck-typed (readers, #update, #save!, #errors,
+    # #persisted?) — but the casting below is AR's attribute API, which is
+    # why this lives in the Rails glue gem and not in the core.
+    module ReactiveForm
+      def self.included(base)
+        base.include(Hibiki::Reactive)
+        base.extend(ClassMethods)
+        # One derived over the whole attribute set rather than per-field
+        # change tracking: cheap, and enough for "enable the save button".
+        base.derived(:dirty?) { to_h != __hibiki_snapshot.value }
+      end
+
+      module ClassMethods
+        # Hydrate from a record — the only supported constructor. Extra
+        # arguments are forwarded to #initialize, so a form with its own
+        # constructor still works.
+        def from(record, ...) = new(...).hydrate(record)
+
+        # reactive_attributes Todo, :title, :done
+        #
+        # The model may be a Class or a String/Symbol; a name is resolved on
+        # every use, so a form class under app/ never pins a constant across
+        # a Zeitwerk reload.
+        def reactive_attributes(model, *names)
+          @hibiki_model = model
+          @hibiki_attributes = names.map(&:to_sym)
+          casts = __hibiki_casts
+          @hibiki_attributes.each do |name|
+            state name
+            casts.define_method(:"#{name}=") { |value| super(self.class.hibiki_type(name).cast(value)) }
+          end
+        end
+
+        def hibiki_attributes
+          @hibiki_attributes || __hibiki_inherited(:hibiki_attributes) || []
+        end
+
+        def hibiki_model
+          model = @hibiki_model || __hibiki_inherited(:hibiki_model)
+          raise "#{self} has no reactive_attributes declaration" if model.nil?
+
+          model.is_a?(Module) ? model : model.to_s.constantize
+        end
+
+        # Channel action params arrive as strings; casting through the
+        # model's own attribute type is the difference between
+        # `done = "false"` meaning false and meaning true.
+        def hibiki_type(name) = hibiki_model.type_for_attribute(name.to_s)
+
+        private
+
+        # Declarations live in class ivars, so subclasses have to walk up
+        # for them — the generated methods inherit on their own.
+        def __hibiki_inherited(reader)
+          superclass.public_send(reader) if superclass.respond_to?(reader)
+        end
+
+        # One module per class, prepended once: the casting writer wraps
+        # the writer `state` defined on the class itself (via super)
+        # instead of replacing it.
+        def __hibiki_casts = @__hibiki_casts ||= Module.new.tap { prepend(it) }
+      end
+
+      # The record, held in a plain ivar and NEVER in a signal: it is the
+      # boundary, touched only by #hydrate and #commit.
+      attr_reader :record
+
+      # Also the "reset from a reloaded record" path. One batch, so a
+      # re-hydrate is one effect run rather than one per attribute.
+      def hydrate(record)
+        @record = record
+        Hibiki.batch do
+          self.class.hibiki_attributes.each { |name| public_send(:"#{name}=", record.public_send(name)) }
+          __hibiki_snapshot.value = to_h
+          __hibiki_errors.value = {}
+        end
+        self
+      end
+
+      def persisted? = record&.persisted? || false
+
+      # Reads every attribute signal, so anything derived from it tracks
+      # them all.
+      def to_h = self.class.hibiki_attributes.to_h { |name| [name, public_send(name)] }
+
+      # Write the record. Returns false and mirrors the model's errors into
+      # #errors when validation fails (the Rails #save convention). On
+      # success the form re-hydrates: callbacks and database defaults may
+      # have moved values, and #persisted? flips after an INSERT.
+      # rubocop:disable Naming/PredicateMethod -- boolean without a ?, exactly like AR's #save
+      def commit
+        record = __hibiki_record!
+        if record.update(**to_h)
+          hydrate(record)
+          true
+        else
+          __hibiki_errors.value = record.errors.to_hash
+          false
+        end
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # The raising half. #commit has already assigned the attributes and
+      # mirrored the errors, so #save! re-validates the same record and
+      # raises ActiveRecord::RecordInvalid — no rescue, and no AR constant
+      # named here.
+      def commit! = commit || __hibiki_record!.save!
+
+      # { title: ["can't be blank"] } — mirrored at a failed commit,
+      # cleared at a successful one. Reactive like any other signal read:
+      # an effect over #error_for repaints when a commit fails.
+      def errors = __hibiki_errors.value
+
+      def error_for(name) = errors[name.to_sym]&.first
+
+      private
+
+      # Snapshot and errors are plain States rather than `state` macros on
+      # purpose: the macro would generate public writers and invite writes
+      # that bypass #hydrate and #commit.
+      def __hibiki_snapshot = @__hibiki_snapshot ||= Hibiki::State.new({})
+
+      def __hibiki_errors = @__hibiki_errors ||= Hibiki::State.new({})
+
+      def __hibiki_record!
+        record || raise("#{self.class} has no record — build it with .from(record)")
+      end
+    end
+  end
+end

data/lib/hibiki/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Hibiki
   module Rails
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/hibiki/rails.rb

@@ -12,8 +12,25 @@ module Hibiki
     # This is the outer layer of the funnel — a flush error first goes to
     # an app-set Hibiki.error_handler if there is one, and only re-raises
     # into the actor's per-job rescue when there isn't.
+    #
+    # It ALSO logs, in local environments only. ActiveSupport::ErrorReporter
+    # has no subscribers by default, so report alone means a graph-thread
+    # exception vanishes completely in a stock app: no log line, no stack,
+    # and the only symptom is a fragment that stops updating. That cost real
+    # debugging time while the CRUD reference app was built. `local?` is
+    # development + test, so production apps — which do have a subscriber —
+    # get no duplicate line. Swap the whole thing per graph via
+    # GraphActor.new(on_error:) if you want different behaviour.
     def self.default_error_reporter
-      ->(error) { ::Rails.error.report(error, handled: true, source: "hibiki_rails") }
+      lambda do |error|
+        if ::Rails.env.local? && ::Rails.logger
+          ::Rails.logger.error(
+            "[hibiki_rails] #{error.class}: #{error.message}\n" \
+            "#{Array(error.backtrace).first(20).join("\n")}"
+          )
+        end
+        ::Rails.error.report(error, handled: true, source: "hibiki_rails")
+      end
     end
   end
 end
@@ -25,4 +42,5 @@ require_relative "rails/debounce"
 require_relative "rails/broadcasts"
 require_relative "rails/channel"
 require_relative "rails/helpers"
+require_relative "rails/reactive_form"
 require_relative "rails/engine"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hibiki_rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - planetaska
@@ -102,6 +102,7 @@ files:
 - lib/hibiki/rails/engine.rb
 - lib/hibiki/rails/graph_actor.rb
 - lib/hibiki/rails/helpers.rb
+- lib/hibiki/rails/reactive_form.rb
 - lib/hibiki/rails/registry.rb
 - lib/hibiki/rails/version.rb
 - lib/hibiki_rails.rb