phlex-reactive 0.10.0 → 0.11.0

data/app/javascript/phlex/reactive/reactive_controller.js

@@ -13,6 +13,9 @@ import { confirmResolver } from "phlex/reactive/confirm"
 // Client-side computes (data bindings): the reducer registry behind
 // reactive_compute. Bare specifier for the same import-map reason as confirm.
 import { computeReducer } from "phlex/reactive/compute"
+// Conditional-confirm predicates (issue #179): the registry behind the
+// confirm: { predicate: "name" } escape hatch. Same bare-specifier reason.
+import { confirmPredicate } from "phlex/reactive/confirm_predicate"
 
 // The ONE generic controller behind every reactive Phlex component. It
 // replaces the per-feature Stimulus controllers you'd otherwise hand-write
@@ -1011,7 +1014,12 @@ export default class extends Controller {
   #busyPending = 0 // root aria-busy pending counter (remove only at zero)
   #busyActions = new Map() // action -> in-flight count (root's space-separated busy set + busy_on)
   #busyTokenCounts = new WeakMap() // element -> Map(action -> count): its data-reactive-busy token set
-  #loadingSnapshots = new Map() // trigger element -> { count, disabled, text } refcounted snapshot
+  #textDisableSnapshots = new Map() // trigger -> { count, disabled, html } refcounted text/disable snapshot (issue #181)
+  // Issue #183: the `input` events recompute dispatches for its OWN output writes,
+  // marked so a re-entrant recompute on THIS root skips re-running the reducer
+  // (single-pass write set). Per-instance, so another root's events are never
+  // swallowed. WeakSet: entries drop when the short-lived Event is GC'd.
+  #computeSelfDispatched = new WeakSet()
   // Dirty tracking (issue #103): the bound re-scan (turbo:morph-element) and the
   // navigate-away guard handlers, held so disconnect() can remove exactly them.
   #boundScanDirty
@@ -1186,10 +1194,17 @@ export default class extends Controller {
     // modifier params (issue #80). The client decides preventDefault behavior
     // from event.params — set by the Ruby on() — never by sniffing the
     // Stimulus descriptor.
-    const { action, params, debounce, throttle, confirm, outside, window: windowBound, optimistic, loading } =
+    const { action, params, debounce, throttle, confirm, confirmWhen, outside, window: windowBound, optimistic } =
       event.params
     if (!action) return
 
+    // The pending-state hint (issue #181): data-reactive-busy-param. During a
+    // deploy overlap a page rendered by the PREVIOUS gem still emits the old
+    // data-reactive-loading-param — read it as a fallback so an in-flight page
+    // keeps its pending affordance until the next full render. The old `class:`
+    // key is remapped to add_class: so it flows through the one hint applier.
+    const busy = event.params.busy ?? this.#legacyLoadingHint(event.params.loading)
+
     // Outside guard FIRST (issue #80): an outside: trigger only fires for
     // events whose target is OUTSIDE this component's ROOT (containment against
     // this.element — .contains includes the root itself). An event inside the
@@ -1230,8 +1245,14 @@ export default class extends Controller {
     // `change` isn't cancelable, so preventDefault was already a no-op there.
     if (!windowBound && !this.#keepsNativeToggle(optimistic, target)) event.preventDefault()
 
-    // No confirm message → proceed straight away (unchanged fast path).
-    if (!confirm) return this.#proceed(target, action, params, debounce, throttle, optimistic, loading)
+    // Resolve the EFFECTIVE confirm message (issue #179): a plain string confirm:
+    // is that string (static, #52); a Hash confirm: (confirmWhen) evaluates its
+    // condition/predicate over the collected fields and returns the message ONLY
+    // when it fires, else null → no dialog. No confirm at all → also null.
+    const message = this.#effectiveConfirmMessage(confirm, confirmWhen)
+
+    // No message → proceed straight away (unchanged fast path).
+    if (!message) return this.#proceed(target, action, params, debounce, throttle, optimistic, busy)
 
     // Confirmation gate (issue #52, made overridable + async in #55). A reactive
     // trigger can't use Hotwire's data-turbo-confirm — this controller preempts
@@ -1245,10 +1266,10 @@ export default class extends Controller {
     // genuine bug inside #proceed is NOT silently swallowed. Enqueue ONLY on a
     // truthy resolution — nothing is enqueued, no timer scheduled, otherwise.
     Promise.resolve()
-      .then(() => confirmResolver(confirm))
+      .then(() => confirmResolver(message))
       .catch(() => false)
       .then((ok) => {
-        if (ok) this.#proceed(target, action, params, debounce, throttle, optimistic, loading)
+        if (ok) this.#proceed(target, action, params, debounce, throttle, optimistic, busy)
       })
   }
 
@@ -1259,7 +1280,7 @@ export default class extends Controller {
   // the component resets whatever they toggled (by design — a signed action
   // owns state that must survive re-renders).
   runOps(event) {
-    const { ops, outside, window: windowBound } = event.params
+    const { ops, confirm, confirmWhen, outside, window: windowBound } = event.params
 
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
@@ -1269,10 +1290,33 @@ export default class extends Controller {
     // Element-bound triggers preventDefault (a bare button inside a <form>
     // must not submit it); window-bound triggers (window:/outside:) never do —
     // they hear every matching event on the page, and preventDefault-ing those
-    // would kill native clicks site-wide (issue #80 rationale).
+    // would kill native clicks site-wide (issue #80 rationale). Runs BEFORE the
+    // (possibly async) confirm gate below — a native default can't wait for a
+    // pending dialog (same ordering as dispatch()).
     if (!windowBound) event.preventDefault()
 
-    this.#applyOps(this.#parseOps(ops))
+    // Resolve the effective confirm message — static string, or the conditional
+    // Hash form (issue #179) evaluated over collected fields. Null → no dialog.
+    const message = this.#effectiveConfirmMessage(confirm, confirmWhen)
+
+    // No message → apply straight away (unchanged fast path, no prompt).
+    if (!message) return this.#applyOps(this.#parseOps(ops))
+
+    // Confirmation gate for client ops (issue #178) — the SAME confirmResolver
+    // gate on(:action, confirm:) uses (issues #52/#55), reused verbatim so a
+    // themed dialog set with setConfirmResolver covers BOTH paths. A destructive
+    // client op (clear a draft, reset a form) gets the one-line themed confirm
+    // without a round trip. Call the resolver INSIDE the chain (leading .then)
+    // so even a SYNCHRONOUS override throw rejects here instead of escaping
+    // runOps — a throwing dialog is a cancel, like dismissing it. The gate is
+    // here (the user gesture), NOT in #applyOps: that applier is shared with the
+    // server-pushed reactive:js stream action, which must NEVER prompt.
+    Promise.resolve()
+      .then(() => confirmResolver(message))
+      .catch(() => false)
+      .then((ok) => {
+        if (ok) this.#applyOps(this.#parseOps(ops))
+      })
   }
 
   // Dirty tracking (issue #103). Wired by reactive_field(dirty: true) /
@@ -1305,6 +1349,16 @@ export default class extends Controller {
   // changed = that output's name — the reducer must be convergent (see
   // compute.js) so the change guard settles the chain.
   recompute(event) {
+    // Issue #183 — single-pass write set: an `input` event this method dispatched
+    // for its OWN output writes is self-marked. Re-running the reducer on it would
+    // re-enter from a partially-written DOM (the old mid-loop-dispatch corruption
+    // class). Skip the reducer for our own event — but ONLY ours: the marker lives
+    // in a per-instance WeakSet, so a genuinely different root's compute event (or
+    // a real user edit) is never swallowed. The event still bubbled and fired every
+    // OTHER listener (dirty tracking, show bindings, sibling roots) before reaching
+    // here; we simply don't recompute a second time from our own write.
+    if (event && this.#computeSelfDispatched.has(event)) return
+
     // Inputs may be a JSON ARRAY of names (array form — every input coerced
     // through Number, the shipped behavior) or a JSON OBJECT of name→type (hash
     // form, issue #104 — :number coerced, :string read raw). #parseComputeInputs
@@ -1330,12 +1384,19 @@ export default class extends Controller {
     // The memo is per-CALL only: an output write dispatches `input` (issue #76),
     // re-entering recompute, which correctly rebuilds a fresh map (a morph may
     // have replaced the nodes) — it is NEVER stored on the instance.
+    // Scope (issue #183, mirroring #showFieldValue): a bare compute name `cash`
+    // under `data-reactive-scope="order"` resolves as `[name="order[cash]"]`. A
+    // name already carrying a bracket (a raw wire name the author passed) is used
+    // verbatim — so bracketed literals pass through unscoped.
+    const scope = this.element.getAttribute?.("data-reactive-scope") || null
+    const scoped = (name) => (scope && !name.includes("[") ? `${scope}[${name}]` : name)
+
     const owns = this.#ownershipFilter()
     const byName = new Map()
     const ownedField = (name) => {
       if (byName.has(name)) return byName.get(name)
       let found = null
-      for (const el of this.element.querySelectorAll(`[name="${name}"]`)) {
+      for (const el of this.element.querySelectorAll(`[name="${scoped(name)}"]`)) {
         if (owns(el)) {
           found = el // FIRST-WINS (radio groups, Rails hidden+checkbox name pairs)
           break
@@ -1381,36 +1442,61 @@ export default class extends Controller {
 
     // meta.changed stays on #changedComputeField (its own #ownsField check over
     // the raw event target) — NOT this resolver. The issue-#15 nested-rejection
-    // test depends on that path being unchanged.
-    const result = reduce(values, { changed: this.#changedComputeField(event, inputs) }) || {}
+    // test depends on that path being unchanged. ONE run, from the ONE pre-write
+    // snapshot above (issue #183): its result drives the whole single-pass write.
+    const result = reduce(values, { changed: this.#changedComputeField(event, inputs, scope) }) || {}
+
+    // Issue #183 — SINGLE-PASS WRITE SET. Three ordered phases, so declared output
+    // order stops being semantics and a wrong order can no longer corrupt values:
+    //
+    //   1. BATCH the field writes from the ONE result. Each output name in the
+    //      allowlist (outputs:) whose owned field's value actually changes is
+    //      written now (change-guarded) and remembered — but NO `input` event is
+    //      dispatched yet, so nothing re-enters mid-batch.
+    //   2. PAINT the sinks from the SETTLED values: any owned reactive_text node by
+    //      presence (issue #183 change #4 — a text node no longer needs its name in
+    //      outputs:), then the cross-root mirror: ids (issue #159).
+    //   3. DISPATCH a self-marked `input` on each changed field. The marker (a
+    //      per-instance WeakSet) makes recompute skip re-running the reducer for our
+    //      own write, while the event still fires every OTHER listener (chained
+    //      repaint, dirty tracking, show bindings, sibling roots).
+    const changedFields = []
     for (const name of outputs) {
       if (!(name in result)) continue
       const field = ownedField(name)
-      // Output resolution (issue #104): write to the owned named FIELD if one
-      // exists, ELSE mirror to every owned [data-reactive-text="<name>"] node.
-      if (field) {
-        // Real browsers do NOT fire `input` on a programmatic .value write (issue
-        // #76), so after writing we dispatch a bubbling `input` ourselves — that's
-        // what drives a chained repaint (a summary listener, a second compute),
-        // matching the server's set_value + dispatch("input") contract. The write
-        // is CHANGE-GUARDED: an unchanged value is skipped entirely (no write, no
-        // event). The guard is what lets a reducer with overlapping inputs/outputs
-        // (the shipped payment_split shape) settle — an unconditional dispatch
-        // would re-enter input->reactive#recompute forever.
-        if (String(result[name]) === field.value) continue
-        field.value = result[name]
-        field.dispatchEvent(new Event("input", { bubbles: true }))
-      } else {
-        // A text-node output: textContent, XSS-safe by construction. Change-
-        // guarded too (compare before writing), but NO input dispatch — a text
-        // node has no listener contract, so nothing chains off it.
-        this.#mirrorText(name, result[name])
-      }
+      if (!field) continue // a non-field output paints as a text sink in phase 2
+      if (String(result[name]) === field.value) continue // change-guard — unchanged, skip
+      field.value = result[name]
+      changedFields.push(field)
     }
 
-    // Cross-root text mirrors (issue #159) — AFTER the outputs are applied, so
-    // a mirror keyed on a just-written output paints the settled value.
+    // Phase 2 — text sinks declare themselves (issue #183 change #4): every result
+    // key paints into any owned [data-reactive-text="<name>"] node by PRESENCE,
+    // regardless of outputs: membership. Runs from settled field values. A null/
+    // undefined result value is SKIPPED (never stringified to "null"/"undefined") —
+    // the same "no value this pass, don't paint" filter #applyComputeMirrors uses.
+    for (const name of Object.keys(result)) {
+      const value = result[name]
+      if (value === undefined || value === null) continue
+      this.#mirrorText(name, value)
+    }
+
+    // Cross-root text mirrors (issue #159) — AFTER the batch + text sinks, so a
+    // mirror keyed on a just-written output paints the settled value.
     this.#applyComputeMirrors(result, ownedField)
+
+    // Phase 3 — dispatch the deferred `input` events (issue #183). Real browsers
+    // do NOT fire `input` on a programmatic .value write (issue #76), so we do it
+    // ourselves, matching the server's set_value + dispatch("input") contract.
+    // Each event is SELF-MARKED so our own re-entry skips the reducer (guard at the
+    // top of recompute) — but the event still bubbles and fires every other
+    // listener. Dispatched AFTER all writes + paints, so a chained listener reads
+    // SETTLED values, never a half-written DOM.
+    for (const field of changedFields) {
+      const inputEvent = new Event("input", { bubbles: true })
+      this.#computeSelfDispatched.add(inputEvent)
+      field.dispatchEvent(inputEvent)
+    }
   }
 
   // Client-side list navigation (combobox keyboard nav, issue #72). Wired by
@@ -1517,11 +1603,26 @@ export default class extends Controller {
   // named form control OWNED by this root (not a nested reactive root's, issue
   // #15) AND its name is among the declared compute inputs; anything else
   // (a direct call, an unowned/undeclared target) yields null.
-  #changedComputeField(event, inputs) {
+  //
+  // Scope-aware (issue #184): under data-reactive-scope, the edited field's DOM
+  // name is scoped (order[allowance]) while the declared inputs are BARE
+  // (allowance). Strip the scope prefix off the DOM name before comparing, and
+  // return the BARE name — so a reducer branching on `changed` sees the same
+  // names it declared, scoped or not.
+  #changedComputeField(event, inputs, scope) {
     const target = event?.target
     if (!target?.name || typeof target.closest !== "function") return null
-    if (!inputs.includes(target.name)) return null
-    return this.#ownsField(target) ? target.name : null
+    const bare = this.#unscopeName(target.name, scope)
+    if (!inputs.includes(bare)) return null
+    return this.#ownsField(target) ? bare : null
+  }
+
+  // Strip a leading `scope[…]` wrapper off a DOM field name, returning the bare
+  // inner name; a name that isn't wrapped in this scope passes through unchanged.
+  #unscopeName(name, scope) {
+    if (!scope) return name
+    const prefix = `${scope}[`
+    return name.startsWith(prefix) && name.endsWith("]") ? name.slice(prefix.length, -1) : name
   }
 
   // Write `value` into every owned [data-reactive-text="<name>"] node via
@@ -1590,7 +1691,7 @@ export default class extends Controller {
   // Split out of dispatch so both the no-confirm fast path and the post-confirm
   // microtask share one place (issue #55). `target` is captured up front because
   // this can run in a later microtask, after event.target has been reset.
-  #proceed(target, action, params, debounce, throttle, optimistic, loading) {
+  #proceed(target, action, params, debounce, throttle, optimistic, busy) {
     // Lifecycle veto point (issue #79): one cancelable reactive:before-dispatch
     // per user gesture — post-preventDefault, post-confirm, PRE-debounce (and
     // PRE-throttle, the same timing). event.preventDefault() skips the
@@ -1608,21 +1709,21 @@ export default class extends Controller {
     // Debounced trigger (e.g. on(:update, event: "input", debounce: 300)):
     // coalesce rapid events into ONE round trip after a quiet period, instead of
     // one POST per keystroke (issue #17). A blur flushes a pending dispatch.
-    // The optimistic hint (issue #98) and the loading state (issue #99) ride to
+    // The optimistic hint (issue #98) and the busy state (issue #181) ride to
     // the flush too, so they apply ONCE per enqueue — a debounced input must not
     // flap toggle_class per keystroke, and its element must NOT be disabled
     // during the quiet period (that would break typing). Both apply at ENQUEUE.
     const ms = Number(debounce) || 0
-    if (ms > 0) return this.#debounceDispatch(target, ms, action, params, optimistic, loading)
+    if (ms > 0) return this.#debounceDispatch(target, ms, action, params, optimistic, busy)
 
     // Throttled trigger (e.g. on(:track, event: "scroll", window: true,
     // throttle: 250), issue #80): LEADING-EDGE rate limit — fire the first
     // event immediately, drop the rest until the window elapses. debounce and
     // throttle are mutually exclusive (the Ruby on() raises on both).
     const throttleMs = Number(throttle) || 0
-    if (throttleMs > 0) return this.#throttleDispatch(target, throttleMs, action, params, optimistic, loading)
+    if (throttleMs > 0) return this.#throttleDispatch(target, throttleMs, action, params, optimistic, busy)
 
-    return this.#enqueue(action, params, optimistic, target, loading)
+    return this.#enqueue(action, params, optimistic, target, busy)
   }
 
   // Apply the optimistic hint ONCE (recording its inverse) and chain the round
@@ -1631,29 +1732,55 @@ export default class extends Controller {
   // #98). Applying here — the single flush/enqueue point every path funnels
   // through — is what makes a hint apply once per enqueue, not per raw dispatch.
   //
-  // The loading state (issue #99) applies here too, for the same reason: enqueue
+  // The busy state (issue #181) applies here too, for the same reason: enqueue
   // is the moment the request is committed to the queue, so the always-on busy
   // vocabulary (data-reactive-busy on the trigger + root, aria-busy via a pending
-  // counter, busy_on scoping) and the loading hint (disable + class + text swap)
+  // counter, busy_on scoping) and the busy hint (disable + class + text swap)
   // cover the WHOLE pending window — queue wait included — not just the fetch. It
   // returns a `settle` closure that #perform runs in its finally (success OR
   // failure), guarded so a morph-replaced trigger is never clobbered.
-  #enqueue(action, params, optimistic, target, loading) {
+  #enqueue(action, params, optimistic, target, busy) {
     const inverse = this.#applyOptimistic(optimistic, target)
-    const settle = this.#applyLoading(action, target, loading)
-    this.queue = (this.queue ?? Promise.resolve()).then(() => this.#perform(action, params, inverse, settle))
+    const settle = this.#applyBusy(action, target, busy)
+    // Debug-only teaching aid (issue #181): if optimistic: { hide: true } is used
+    // for instant-delete but the reply RE-RENDERS the element (bringing it back),
+    // that hint was pointless — the developer likely wanted reply.remove. Capture
+    // the hidden nodes now; the success path re-checks the OBSERVED DOM after the
+    // morph (never inferred from the verb) and warns if any came back visible.
+    const resurrect = this.#debugEnabled() ? this.#buildResurrectionCheck(optimistic, target) : null
+    this.queue = (this.queue ?? Promise.resolve())
+      .then(() => this.#perform(action, params, inverse, settle, resurrect))
     return this.queue
   }
 
+  // Snapshot the elements an optimistic hide: targeted (the trigger, or the `to:`
+  // selector) so the success path can detect a resurrection. Returns null unless
+  // a hide: hint is present — nothing else can be "resurrected".
+  #buildResurrectionCheck(optimistic, target) {
+    if (!optimistic?.hide) return null
+    const hidden = this.#hintTargets(optimistic, target)
+    if (!hidden.length) return null
+    return () => {
+      const back = hidden.filter((el) => el.isConnected && !el.hidden)
+      if (!back.length) return
+      console.warn(
+        "[phlex-reactive] optimistic: { hide: true } was undone by the reply's re-render — " +
+          "the element is visible again. For an instant delete, return reply.remove so the " +
+          "server removes it; otherwise the hide only flashes.",
+        back,
+      )
+    }
+  }
+
   // Reset a per-element timer; only enqueue the round trip after `ms` of quiet.
   // Also flush immediately on blur so leaving the field never drops the last
   // edit (a long debounce shouldn't swallow a value the user tabbed away from).
-  #debounceDispatch(target, ms, action, params, optimistic, loading) {
+  #debounceDispatch(target, ms, action, params, optimistic, busy) {
     this.#clearDebounce(target)
 
     const flush = () => {
       this.#clearDebounce(target)
-      this.#enqueue(action, params, optimistic, target, loading)
+      this.#enqueue(action, params, optimistic, target, busy)
     }
     const timer = setTimeout(flush, ms)
     target?.addEventListener?.("blur", flush, { once: true })
@@ -1681,7 +1808,7 @@ export default class extends Controller {
   // are keyed on action + target, NOT target alone: window-bound scroll/resize
   // events all share event.target === document, so two window-bound triggers
   // on one component would otherwise collide on one timer.
-  #throttleDispatch(target, ms, action, params, optimistic, loading) {
+  #throttleDispatch(target, ms, action, params, optimistic, busy) {
     const timers = this.#throttleTimers.get(target) ?? new Map()
     if (timers.has(action)) return // inside the window — suppress
 
@@ -1691,7 +1818,7 @@ export default class extends Controller {
     }, ms)
     timers.set(action, timer)
     this.#throttleTimers.set(target, timers)
-    return this.#enqueue(action, params, optimistic, target, loading) // leading edge: fire NOW
+    return this.#enqueue(action, params, optimistic, target, busy) // leading edge: fire NOW
   }
 
   // Clear every throttle suppression timer (used on disconnect, alongside
@@ -1852,7 +1979,7 @@ export default class extends Controller {
     /* eslint-enable no-console */
   }
 
-  async #perform(action, params, inverse, settle) {
+  async #perform(action, params, inverse, settle, resurrect) {
     // Auto-collect named field values inside this component so a button-
     // triggered action still receives sibling inputs (Livewire-style), plus any
     // chosen file inputs in the SAME walk. Explicit params
@@ -2046,6 +2173,10 @@ export default class extends Controller {
       // replace (Response.morph) or an update morphs in place, preserving the
       // focused input + caret on unchanged nodes — see issue #28.
       window.Turbo.renderStreamMessage(html)
+      // Debug-only (issue #181): the morph may apply a microtask later, so check
+      // the resurrected-hide case AFTER it lands. Off the debug path, resurrect is
+      // null — zero cost.
+      if (resurrect) queueMicrotask(resurrect)
       // A successful apply CLEARS any prior failure marker (issue #100), so
       // error-driven CSS on the root (a red border, a shake) resets on recovery.
       this.#clearError()
@@ -2192,6 +2323,54 @@ export default class extends Controller {
     return (el) => this.#ownsField(el)
   }
 
+  // Resolve the effective confirm message (issue #179). A plain string is the
+  // static #52 form (always shown). A confirmWhen JSON payload is the CONDITIONAL
+  // form — evaluated over the SAME collected fields reactive_compute reads — and
+  // returns the message ONLY when it fires, else null (proceed, no dialog):
+  //   { groups, message }    — the reactive_show conditions fold (anyOfAllsMatches)
+  //   { predicate, message } — a registered fn (setConfirmPredicate) over the fields
+  // A missing predicate warns and returns null (PROCEED without a dialog) — the
+  // compute unknown-reducer posture. This is soft-validation UX; the endpoint's
+  // authorize/default-deny is the real gate, so failing OPEN here never grants
+  // anything the server wouldn't already allow.
+  #effectiveConfirmMessage(confirm, confirmWhen) {
+    if (confirm) return confirm
+    if (!confirmWhen) return null
+
+    // Stimulus auto-parses a JSON-object -param value, so confirmWhen usually
+    // arrives ALREADY parsed. Accept an object as-is; parse a string defensively
+    // (a hand-built attr, or a non-Stimulus caller). A malformed string warns and
+    // proceeds without a dialog (default-deny UX — the server is the real gate).
+    let payload = confirmWhen
+    if (typeof confirmWhen === "string") {
+      try {
+        payload = JSON.parse(confirmWhen)
+      } catch {
+        console.warn(`[phlex-reactive] malformed conditional confirm payload ${JSON.stringify(confirmWhen)} — skipped`)
+        return null
+      }
+    }
+    if (!payload || typeof payload !== "object") return null
+
+    const { fields } = this.#collectFields()
+    const fieldValue = (name) => fields[name]
+
+    let fires
+    if (typeof payload.predicate === "string") {
+      const fn = confirmPredicate(payload.predicate)
+      if (!fn) {
+        console.warn(`[phlex-reactive] confirm predicate "${payload.predicate}" is not registered — proceeding without a dialog (register it with setConfirmPredicate)`)
+        return null
+      }
+      fires = !!fn(fields)
+    } else {
+      // Declarative: the DNF groups fold, identical to reactive_show — matches → fire.
+      fires = anyOfAllsMatches(payload.groups?.any, fieldValue) === true
+    }
+
+    return fires ? payload.message : null
+  }
+
   // One walk over THIS root's named controls (not a nested reactive root's),
   // returning both the scalar `fields` and any chosen `files`. The ownership
   // predicate is hoisted ONCE (issue #117) via #ownershipFilter — in the common
@@ -2723,79 +2902,30 @@ export default class extends Controller {
     return type === "checkbox" || type === "radio"
   }
 
-  // Apply the optimistic hint (issue #98) to its targets NOW and return the
-  // INVERSE — the exact ops to replay on failure. Cosmetic only: class ops and
-  // hidden, applied to the trigger by default or to a `to:` selector scoped to
-  // the root. `checked: :keep` records the trigger's post-flip state so a
-  // failure snaps the native control back; it applies no DOM change itself (the
-  // browser already flipped it). Returns null when there is nothing to do, so
-  // the success/failure paths can cheaply skip.
+  // Apply the OPTIMISTIC hint (issue #98) NOW and return its `undo` closure — the
+  // exact ops to replay on FAILURE (optimistic reverts only when the round trip
+  // fails; success leaves server truth or the deliberately-standing hint). It is
+  // the same op vocabulary busy: uses (issue #181) via the one #applyHint engine;
+  // the ONLY optimistic-specific op is checked: :keep (honorChecked = true).
   #applyOptimistic(optimistic, trigger) {
     if (!optimistic) return null
-
-    // Class + hidden ops share one target set (trigger, or the `to:` selector).
-    const targets = this.#optimisticTargets(optimistic, trigger)
-    const undo = []
-    for (const el of targets) {
-      if (optimistic.add_class) {
-        // Undo only the classes this op ACTUALLY added — a class already present
-        // was not our change, so reverting it would strip a class the element
-        // legitimately had (the add was a no-op). Capture the real delta now.
-        const added = optimistic.add_class.filter((c) => !el.classList.contains(c))
-        el.classList.add(...added)
-        if (added.length) undo.push(() => el.classList.remove(...added))
-      }
-      if (optimistic.remove_class) {
-        // Symmetric: undo only the classes actually removed — one already absent
-        // wasn't our change, so re-adding it would introduce a class that wasn't
-        // there before.
-        const removed = optimistic.remove_class.filter((c) => el.classList.contains(c))
-        el.classList.remove(...removed)
-        if (removed.length) undo.push(() => el.classList.add(...removed))
-      }
-      if (optimistic.toggle_class) {
-        // toggle_class is its own inverse regardless of prior state — toggling
-        // the same classes back exactly restores it, no delta tracking needed.
-        optimistic.toggle_class.forEach((c) => el.classList.toggle(c))
-        undo.push(() => optimistic.toggle_class.forEach((c) => el.classList.toggle(c)))
-      }
-      if (optimistic.hide) {
-        el.hidden = true
-        undo.push(() => (el.hidden = false))
-      }
-    }
-
-    // checked: :keep — the native flip already happened on the trigger; record
-    // the inverse (flip it back) so a failure reverts the control's state.
-    if (optimistic.checked === "keep" && trigger && "checked" in trigger) {
-      const flipped = trigger.checked
-      undo.push(() => (trigger.checked = !flipped))
-    }
-
+    const undo = this.#applyHint(optimistic, trigger, true)
     return undo.length ? undo : null
   }
 
-  // Replay the recorded inverse ops on failure (issue #98), guarded by
-  // isConnected: a plain (non-morph) replace can detach this subtree before the
-  // failure lands, and reverting a stale/detached node is pointless (it's gone)
-  // — so a disconnected root skips the revert entirely. On success NOTHING calls
-  // this: the server re-render overwrites the hint, or (reply.remove /
-  // streams-only) the hint is deliberately left standing.
+  // Replay the recorded undo ops on failure (issue #98), guarded by isConnected:
+  // a plain (non-morph) replace can detach this subtree before the failure lands,
+  // and reverting a stale/detached node is pointless (it's gone) — so a
+  // disconnected root skips the revert entirely. On success NOTHING calls this:
+  // the server re-render overwrites the hint, or (reply.remove / streams-only)
+  // the hint is deliberately left standing.
   #revertOptimistic(inverse) {
     if (!inverse) return
     if (!this.element.isConnected) return
     for (const undo of inverse) undo()
   }
 
-  // The elements an optimistic class/hidden hint applies to: the `to:` selector
-  // (resolved like an op target — "@root" is the root, a selector is scoped to
-  // this root's owned matches) or, with no `to:`, the trigger itself.
-  #optimisticTargets(optimistic, trigger) {
-    if (optimistic.to == null) return trigger ? [trigger] : []
-    return this.#opTargets({ to: optimistic.to })
-  }
-
-  // Apply the loading state for THIS enqueue (issue #99) and return a `settle`
+  // Apply the BUSY state for THIS enqueue (issue #181) and return a `settle`
   // closure that undoes exactly this enqueue's contribution when the round trip
   // finishes (success OR any failure). Everything is refcounted so overlapping
   // enqueues never clobber: A's settle can't clear busy while B is still pending.
@@ -2806,23 +2936,121 @@ export default class extends Controller {
   //      space-separated, per-action refcounted set), aria-busy on the root (a
   //      pending counter), and data-reactive-busy on any busy_on element scoped
   //      to this action. Apps style a spinner with pure CSS and zero Ruby.
-  //   2. The loading HINT (only when loading:/disable_with: was declared):
-  //      disable the trigger, add a loading class (to the trigger or a `to:`
-  //      target), swap its text. These apply at ENQUEUE — never during a debounce
-  //      quiet period — so a debounced input is not disabled mid-typing.
-  #applyLoading(action, trigger, loading) {
+  //   2. The busy HINT (only when busy: was declared): the SAME cosmetic op set
+  //      as optimistic: (class ops, hide/show, disable, text), applied through
+  //      the one #applyHint engine and reverted on SETTLE (not on failure). These
+  //      apply at ENQUEUE — never during a debounce quiet period — so a debounced
+  //      input is not disabled mid-typing. checked: is optimistic-only, so busy:
+  //      passes honorChecked = false (the Ruby on() already rejects it — this is
+  //      belt-and-braces).
+  #applyBusy(action, trigger, busy) {
     this.#markBusy(action, trigger)
-    const restoreHint = this.#applyLoadingHint(action, trigger, loading)
+    const undo = busy ? this.#applyHint(busy, trigger, false) : []
 
     let settled = false
     return () => {
       if (settled) return // one settle per enqueue, even if called twice
       settled = true
       this.#unmarkBusy(action, trigger)
-      restoreHint()
+      // Busy reverts on SETTLE regardless of outcome, guarded per element.
+      for (const op of undo) op()
     }
   }
 
+  // The ONE pending-state hint engine (issue #181), shared by optimistic: (revert
+  // on failure) and busy: (revert on settle) — they differ only in WHEN the
+  // returned undo ops run, never in the ops themselves. Applies the hint's
+  // cosmetic ops to their targets (the trigger by default, or a `to:` selector
+  // scoped to the root) and returns an array of undo closures. Class ops and
+  // hide/show use a DELTA inverse (undo only what THIS call changed, so it
+  // composes across overlapping enqueues); disable/text use a REFCOUNTED snapshot
+  // (the true pre-hint value survives an overlapping enqueue that would otherwise
+  // capture the already-swapped label as the "original"). `honorChecked` gates
+  // checked: :keep — an optimistic-only native-control revert.
+  #applyHint(hint, trigger, honorChecked) {
+    const undo = []
+    for (const el of this.#hintTargets(hint, trigger)) {
+      if (hint.add_class) {
+        // Undo only the classes this op ACTUALLY added — a class already present
+        // was not our change, so reverting it would strip a class the element
+        // legitimately had. Capture the real delta now.
+        const added = hint.add_class.filter((c) => !el.classList.contains(c))
+        el.classList.add(...added)
+        if (added.length) undo.push(() => el.classList.remove(...added))
+      }
+      if (hint.remove_class) {
+        // Symmetric: undo only the classes actually removed.
+        const removed = hint.remove_class.filter((c) => el.classList.contains(c))
+        el.classList.remove(...removed)
+        if (removed.length) undo.push(() => el.classList.add(...removed))
+      }
+      if (hint.toggle_class) {
+        // toggle_class is its own inverse regardless of prior state.
+        hint.toggle_class.forEach((c) => el.classList.toggle(c))
+        undo.push(() => hint.toggle_class.forEach((c) => el.classList.toggle(c)))
+      }
+      if (hint.hide) {
+        el.hidden = true
+        undo.push(() => (el.hidden = false))
+      }
+      if (hint.show) {
+        el.hidden = false
+        undo.push(() => (el.hidden = true))
+      }
+    }
+
+    // disable/text swap the TRIGGER (a `to:` retargets only the class/hide/show
+    // ops above — disable/text are inherently trigger affordances). Refcounted so
+    // overlapping enqueues restore correctly.
+    if (trigger && (hint.disable || hint.text != null)) {
+      undo.push(this.#applyTextDisable(hint, trigger))
+    }
+
+    // checked: :keep — the native flip already happened on the trigger; record
+    // the inverse (flip it back) so a revert restores the control's state.
+    if (honorChecked && hint.checked === "keep" && trigger && "checked" in trigger) {
+      const flipped = trigger.checked
+      undo.push(() => (trigger.checked = !flipped))
+    }
+
+    return undo
+  }
+
+  // The elements a hint's class/hide/show ops apply to: the `to:` selector
+  // (resolved like an op target — "@root" is the root, a selector is scoped to
+  // this root's owned matches) or, with no `to:`, the trigger itself.
+  #hintTargets(hint, trigger) {
+    if (hint.to == null) return trigger ? [trigger] : []
+    return this.#opTargets({ to: hint.to })
+  }
+
+  // Swap the trigger's disabled/innerHTML for a pending hint, snapshotting the
+  // ORIGINAL once per trigger (refcounted so an overlapping enqueue never
+  // snapshots the already-swapped "Saving…" as the original), and return the undo
+  // closure. text swaps innerHTML (issue #181), NOT textContent: a composite
+  // trigger like `<button><svg/> Save</button>` has child nodes, and
+  // textContent = "Saving…" would DESTROY the icon; innerHTML preserves the
+  // markup structure and restores it byte-for-byte.
+  #applyTextDisable(hint, trigger) {
+    const snap = this.#textDisableSnapshots.get(trigger)
+    if (snap) {
+      snap.count++
+    } else {
+      this.#textDisableSnapshots.set(trigger, {
+        count: 1,
+        disabled: trigger.disabled,
+        html: trigger.innerHTML,
+        hadText: hint.text != null,
+        swappedTo: hint.text,
+      })
+    }
+
+    if (hint.disable) trigger.disabled = true
+    if (hint.text != null) trigger.innerHTML = hint.text
+
+    return () => this.#restoreTextDisable(trigger, hint)
+  }
+
   // Layer 1 — the always-on busy markers. Trigger + root carry the action token;
   // the root's counter drives aria-busy; busy_on elements scoped to this action
   // light up. Refcounts (#busyActions, #busyPending) so overlapping requests
@@ -2886,72 +3114,35 @@ export default class extends Controller {
     )
   }
 
-  // Layer 2 — the loading HINT (disable + class + text). Snapshots the trigger's
-  // ORIGINAL disabled/text/classes on the FIRST enqueue for that trigger
-  // (refcounted so an overlapping enqueue never snapshots the already-swapped
-  // "Saving…" as the original), applies the swap, and returns a restore closure.
-  // With no hint, returns a no-op restore (the always-on busy markers still ran).
-  #applyLoadingHint(action, trigger, loading) {
-    if (!loading || !trigger) return () => {}
-
-    const classTargets = this.#loadingTargets(loading, trigger)
-    const classes = Array.isArray(loading.class) ? loading.class : []
-    const addedByTarget = []
-    for (const el of classTargets) {
-      const added = classes.filter((c) => !el.classList.contains(c))
-      el.classList.add(...added)
-      if (added.length) addedByTarget.push([el, added])
-    }
-
-    // Snapshot disabled/text ONCE per trigger (refcounted). A second overlapping
-    // enqueue increments the count but does NOT re-snapshot — so the recorded
-    // "original" is the true pre-loading state, never the swapped label.
-    const snap = this.#loadingSnapshots.get(trigger)
-    if (snap) {
-      snap.count++
-    } else if (loading.disable || loading.text != null) {
-      this.#loadingSnapshots.set(trigger, {
-        count: 1,
-        disabled: trigger.disabled,
-        text: trigger.textContent,
-        hadText: loading.text != null,
-      })
-    }
-
-    if (loading.disable) trigger.disabled = true
-    if (loading.text != null) trigger.textContent = loading.text
-
-    return () => {
-      for (const [el, added] of addedByTarget) if (el.isConnected) el.classList.remove(...added)
-      this.#restoreLoadingSnapshot(trigger, loading)
-    }
-  }
-
-  // Restore the trigger's disabled/text from its snapshot when the LAST enqueue
-  // for that trigger settles (refcount → 0). GUARDED: skip a disconnected
+  // Restore the trigger's disabled/innerHTML from its snapshot when the LAST
+  // enqueue for that trigger settles (refcount → 0). GUARDED: skip a disconnected
   // trigger (a plain replace detached it — the node is gone), and do NOT restore
-  // the text if it no longer equals what we swapped IN (a morph rendered a new
-  // server label — clobbering it with the old text would fight server truth).
-  #restoreLoadingSnapshot(trigger, loading) {
-    const snap = this.#loadingSnapshots.get(trigger)
+  // the label if it no longer equals what we swapped IN (a morph rendered a new
+  // server label — clobbering it with the old markup would fight server truth).
+  // The comparison + restore both use innerHTML so a composite trigger (icon +
+  // label) round-trips its full markup, not a flattened text run (issue #181).
+  #restoreTextDisable(trigger, hint) {
+    const snap = this.#textDisableSnapshots.get(trigger)
     if (!snap) return
     if (--snap.count > 0) return // another enqueue for this trigger is still pending
-    this.#loadingSnapshots.delete(trigger)
+    this.#textDisableSnapshots.delete(trigger)
 
     if (!trigger.isConnected) return // detached — nothing to restore
 
-    if (loading.disable) trigger.disabled = snap.disabled
-    // Only restore the label if the trigger still shows OUR swapped text; a
-    // changed textContent means the server morph relabeled it — leave it.
-    if (snap.hadText && trigger.textContent === loading.text) trigger.textContent = snap.text
+    if (hint.disable) trigger.disabled = snap.disabled
+    if (snap.hadText && trigger.innerHTML === snap.swappedTo) trigger.innerHTML = snap.html
   }
 
-  // The elements a loading class applies to: the `to:` selector (resolved like
-  // an op target — "@root" is the root, a selector is scoped to this root's
-  // owned matches) or, with no `to:`, the trigger itself.
-  #loadingTargets(loading, trigger) {
-    if (loading.to == null) return trigger ? [trigger] : []
-    return this.#opTargets({ to: loading.to })
+  // Deploy-overlap read shim (issue #181): a page still rendered by the PREVIOUS
+  // gem emits the old data-reactive-loading-param, whose `class:` key is the busy
+  // vocabulary's `add_class:`. Remap it so an in-flight legacy page keeps its
+  // pending affordance through the one #applyHint engine. Returns null for the
+  // common (no legacy param) case so the fast path is untouched. Drop this shim
+  // one minor after #181 ships (no page can still carry the old attr by then).
+  #legacyLoadingHint(loading) {
+    if (!loading || typeof loading !== "object") return null
+    const { class: cls, ...rest } = loading
+    return cls == null ? loading : { ...rest, add_class: cls }
   }
 
   // The action path comes from a <meta> tag that is fixed for the page's life,