phlex-reactive 0.12.4 → 0.12.6

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

@@ -103,10 +103,22 @@ export function registerReactiveJs() {
     const list = parseOps(this.getAttribute("data-reactive-ops"))
     if (!list.length) return
     const targetId = this.getAttribute("target")
+    // Issue #237: the server stamps the verbose gate on the stream element
+    // itself (verbose_errors), so document-scoped ops are diagnosable too.
+    const verbose = this.getAttribute("data-reactive-verbose") === "true"
     // With a target: scope to that element (missing → no-op). Without: document.
     const root = targetId ? document.getElementById(targetId) : null
-    if (targetId && !root) return
-    applyOps(list, (args) => streamOpTargets(args, root))
+    if (targetId && !root) {
+      if (verbose && !zeroTargetAlreadyWarned(`missing-root|#${targetId}`)) {
+        console.warn(`[phlex-reactive] reactive:js stream target root #${targetId} is not in the DOM — its ops were dropped`)
+      }
+      return
+    }
+    applyOps(
+      list,
+      (args) => streamOpTargets(args, root),
+      verbose ? (name, args) => diagnoseStreamZeroTargets(name, args, root) : undefined,
+    )
   }
 }
 
@@ -1043,6 +1055,215 @@ function runTransition(el, transition, flip) {
   setTimeout(cleanup, 350)
 }
 
+// ---------------------------------------------------------------------------
+// Client-only drafts (issue #239) — reactive_persist. A root that declares
+// data-reactive-persist='{"key","ttl","debounce"[,"fields"][,"restore"]}'
+// keeps a localStorage draft of every persistable OWNED control (write on
+// input/change, restore on connect, clear on a successful submit / TTL / the
+// persist_clear op). The storage layer is MODULE-LEVEL and keyed on the root
+// element — the controller's connect/write path and the persist_state /
+// persist_clear client ops (which receive only the element) share it. Every
+// storage access is try/catch'd: a private window, a quota error or blocked
+// storage degrades to "no draft", never a thrown bootstrap. Nothing here
+// leaves the browser: no token, no POST, values are replayed via
+// .value/.checked only (never HTML).
+// ---------------------------------------------------------------------------
+const PERSIST_VERSION = 1
+const PERSIST_PREFIX = "phlex-reactive:persist:"
+// Never persisted regardless of author intent: no server default to restore
+// into (hidden, file), secrets (password), and non-value controls.
+const PERSIST_EXCLUDED_TYPES = new Set(["hidden", "file", "password", "submit", "button", "reset", "image"])
+const PERSIST_STATE_ATTR = "data-reactive-persist-state"
+// Once-per-root guards: a malformed payload warns once; the storage-failure
+// dev note (debug mode only) prints once.
+const persistPayloadWarned = new WeakSet()
+const persistFailureNoted = new WeakSet()
+
+// The root's parsed payload, or null (undeclared / malformed → warned once).
+// A control-level "off" (reactive_persist_skip) is never a root payload.
+function persistPayload(root) {
+  const raw = root?.getAttribute?.("data-reactive-persist")
+  if (!raw || raw === "off") return null
+  try {
+    const payload = JSON.parse(raw)
+    if (payload && typeof payload === "object" && typeof payload.key === "string" && payload.key !== "") return payload
+  } catch {
+    // fall through to the warn
+  }
+  if (!persistPayloadWarned.has(root)) {
+    persistPayloadWarned.add(root)
+    console.warn(`[phlex-reactive] malformed reactive_persist payload ${JSON.stringify(raw)} — persistence disabled`)
+  }
+  return null
+}
+
+function persistStorage() {
+  try {
+    return typeof localStorage === "undefined" ? null : localStorage
+  } catch {
+    return null // the accessor itself can throw (blocked site data)
+  }
+}
+
+// The dev lens for "why did nothing come back": ONLY under data-reactive-debug
+// (Phlex::Reactive.debug), once per root — production stays silent.
+function persistNoteFailure(root, error) {
+  if (root?.getAttribute?.("data-reactive-debug") !== "true" || persistFailureNoted.has(root)) return
+  persistFailureNoted.add(root)
+  console.info(`[phlex-reactive] reactive_persist: storage unavailable — draft skipped (${error?.name ?? error})`)
+}
+
+function persistKeyFor(payload) {
+  return PERSIST_PREFIX + payload.key
+}
+
+// Read + validate the draft: null when absent, unparsable, another schema
+// version, or expired (an expired draft is REMOVED on read). Returns
+// { fields, state } with state null when the draft carries none.
+function persistRead(root, payload) {
+  const store = persistStorage()
+  if (!store) return null
+  let raw
+  try {
+    raw = store.getItem(persistKeyFor(payload))
+  } catch (error) {
+    persistNoteFailure(root, error)
+    return null
+  }
+  if (!raw) return null
+  let draft
+  try {
+    draft = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (!draft || typeof draft !== "object" || draft.v !== PERSIST_VERSION) return null
+  const ttlMs = Number(payload.ttl) * 1000
+  if (!(Number(draft.savedAt) + ttlMs > Date.now())) {
+    persistRemove(root, payload)
+    return null
+  }
+  const fields = draft.fields && typeof draft.fields === "object" ? draft.fields : {}
+  const state = draft.state && typeof draft.state === "object" ? draft.state : null
+  return { fields, state }
+}
+
+function persistWrite(root, payload, { fields, state }) {
+  const store = persistStorage()
+  if (!store) return false
+  const draft = { v: PERSIST_VERSION, savedAt: Date.now(), fields }
+  if (state) draft.state = state
+  try {
+    store.setItem(persistKeyFor(payload), JSON.stringify(draft))
+    return true
+  } catch (error) {
+    persistNoteFailure(root, error)
+    return false
+  }
+}
+
+function persistRemove(root, payload) {
+  root?.removeAttribute?.(PERSIST_STATE_ATTR)
+  const store = persistStorage()
+  if (!store) return
+  try {
+    store.removeItem(persistKeyFor(payload))
+  } catch (error) {
+    persistNoteFailure(root, error)
+  }
+}
+
+// The persistable controls this root OWNS (#15: a nested reactive root's
+// controls are its own), minus the excluded types, the reactive_persist_skip
+// marker, and — when `fields` narrows the set — any undeclared name.
+function persistControls(root, payload) {
+  const allow = Array.isArray(payload.fields) ? new Set(payload.fields) : null
+  const out = []
+  for (const el of root.querySelectorAll("input[name], select[name], textarea[name]")) {
+    if (el.closest('[data-controller~="reactive"]') !== root) continue
+    if (PERSIST_EXCLUDED_TYPES.has(el.type)) continue
+    if (el.getAttribute("data-reactive-persist") === "off") continue
+    if (allow && !allow.has(el.name)) continue
+    out.push(el)
+  }
+  return out
+}
+
+function persistSelectMultiple(el) {
+  return el.tagName === "SELECT" && el.multiple
+}
+
+// Snapshot the owned controls: radio → the checked value (null when the group
+// has none, so a restore leaves it alone), checkbox → checked, multi-select →
+// the selected values, else .value. Mirrors #collectFields' reads.
+function persistSnapshot(root, payload) {
+  const fields = {}
+  for (const el of persistControls(root, payload)) {
+    const name = el.name
+    if (el.type === "radio") {
+      if (el.checked) fields[name] = el.value
+      else if (!Object.hasOwn(fields, name)) fields[name] = null
+    } else if (el.type === "checkbox") {
+      fields[name] = el.checked
+    } else if (persistSelectMultiple(el)) {
+      fields[name] = [...el.options].filter((o) => o.selected).map((o) => o.value)
+    } else {
+      fields[name] = el.value
+    }
+  }
+  return fields
+}
+
+// Replay the draft into the owned controls. Default (restore: blank): a
+// control the server rendered NON-BLANK keeps its value — a 422 re-render's
+// submitted values beat an older draft. restore: "always" lets the draft win.
+// Values land via .value/.checked/.selected only — never HTML.
+function persistApply(root, payload, fields) {
+  const always = payload.restore === "always"
+  const controls = persistControls(root, payload)
+  for (const el of controls) {
+    if (!Object.hasOwn(fields, el.name)) continue
+    const value = fields[el.name]
+    if (value === null || value === undefined) continue
+    if (el.type === "radio") {
+      if (!always && controls.some((c) => c.type === "radio" && c.name === el.name && c.checked)) continue
+      el.checked = el.value === String(value)
+    } else if (el.type === "checkbox") {
+      if (!always && el.checked) continue
+      el.checked = Boolean(value)
+    } else if (persistSelectMultiple(el)) {
+      if (!always && [...el.options].some((o) => o.selected)) continue
+      const wanted = new Set((Array.isArray(value) ? value : [value]).map(String))
+      for (const o of el.options) o.selected = wanted.has(o.value)
+    } else {
+      if (!always && el.value !== "") continue
+      el.value = String(value)
+    }
+  }
+}
+
+// The persist_state op body: merge a FLAT bag into the root's draft (re-
+// snapshotting the fields so the write is whole) and mirror it on the root.
+// A root without reactive_persist is a call-site bug — warn and skip.
+function persistWriteState(root, state) {
+  const payload = persistPayload(root)
+  if (!payload) {
+    console.warn("[phlex-reactive] persist_state on a root without reactive_persist — skipped")
+    return
+  }
+  if (!state || typeof state !== "object") return
+  const current = persistRead(root, payload)
+  const merged = { ...(current?.state ?? {}), ...state }
+  if (persistWrite(root, payload, { fields: persistSnapshot(root, payload), state: merged })) {
+    root.setAttribute?.(PERSIST_STATE_ATTR, JSON.stringify(merged))
+  }
+}
+
+function persistClearRoot(root) {
+  const payload = persistPayload(root)
+  if (payload) persistRemove(root, payload)
+}
+
 // The client-op whitelist behind on_client (issue #95, extended in #96). Mirrors
 // Phlex::Reactive::JS's vocabulary; an op name not in this map is
 // warn-and-skipped by #applyOps (client-side default-deny — a stale or newer
@@ -1119,6 +1340,13 @@ const CLIENT_OPS = Object.freeze({
   // an actor reply's stream from a broadcast's, and reply.js legitimately
   // carries this op.
   paste_into: (el) => pasteClipboardInto(el),
+
+  // Client-only drafts (issue #239): merge a flat state bag into the root's
+  // reactive_persist draft / forget the draft. ACTOR-ONLY like focus/submit
+  // (BROADCAST_REFUSED_OPS server-side) — rewriting or wiping every
+  // subscriber's draft from a broadcast would be hostile.
+  persist_state: (el, args) => persistWriteState(el, args.state),
+  persist_clear: (el) => persistClearRoot(el),
 })
 
 // The form a submit op commits (issue #226), in order: the target itself when
@@ -1491,7 +1719,7 @@ function computeOpsList(raw) {
 // chain still applies — client-side default-deny, one bad op never takes down
 // its siblings. Object.hasOwn (not a bare read) so inherited Object members
 // ("constructor") can't masquerade as ops.
-function applyOps(list, resolveTargets) {
+function applyOps(list, resolveTargets, onZeroTargets) {
   for (const entry of list) {
     if (!Array.isArray(entry)) continue
     const [name, args = {}] = entry
@@ -1499,10 +1727,70 @@ function applyOps(list, resolveTargets) {
       console.warn(`[phlex-reactive] unknown client op ${JSON.stringify(name)} — skipped`)
       continue
     }
-    for (const el of resolveTargets(args)) CLIENT_OPS[name](el, args)
+    const targets = resolveTargets(args)
+    if (targets.length === 0 && onZeroTargets) onZeroTargets(name, args)
+    for (const el of targets) CLIENT_OPS[name](el, args)
   }
 }
 
+// --- zero-target diagnostics (issue #237) -----------------------------------
+// An op resolving ZERO targets is indistinguishable from a working no-op, and
+// the documented scoping traps (nested-root ownership filter, root-self
+// selector, stream default scope) all present exactly that way. Under the
+// verbose gate (data-reactive-verbose, stamped when Phlex::Reactive
+// .verbose_errors is on — dev/test by default — or the debug attr) warn ONCE
+// per unique (label, selector, scope) with a targeted hint when the element
+// EXISTS but sits outside the op's scope. Everything below runs only after a
+// zero-match with the gate on; production (no attr) pays one boolean per empty
+// resolution and never probes the DOM.
+//
+// Dedupe is keyed per document (page lifetime): a WeakMap entry per document
+// means a fresh page — or a fresh unit-harness stub — starts clean, and the
+// per-keystroke reducer ($ops) path can never flood the console.
+const zeroTargetWarnSets = new WeakMap()
+
+function zeroTargetAlreadyWarned(key) {
+  const doc = globalThis.document
+  if (!doc) return true
+  let seen = zeroTargetWarnSets.get(doc)
+  if (!seen) {
+    seen = new Set()
+    zeroTargetWarnSets.set(doc, seen)
+  }
+  if (seen.has(key)) return true
+  seen.add(key)
+  return false
+}
+
+// Guarded probes: unit harnesses stub partial documents/roots, and an exotic
+// selector could throw — a diagnostic must never break the op pipeline.
+function countMatches(node, selector) {
+  try {
+    return node?.querySelectorAll?.(selector)?.length ?? 0
+  } catch {
+    return 0
+  }
+}
+
+function emitZeroTargetWarn(label, to, scope, hint) {
+  if (zeroTargetAlreadyWarned(`${label}|${to}|${scope}`)) return
+  console.warn(`[phlex-reactive] ${label} matched zero targets for selector "${to}" (${scope})${hint}`)
+}
+
+// The stream-path diagnoser (reactive:js). No ownership filter exists here, so
+// the only trap is the target-root scope: the selector matches document-wide
+// but the op was scoped to the stream's target root.
+function diagnoseStreamZeroTargets(name, args, root) {
+  const to = args.to
+  if (typeof to !== "string" || to === "" || to === "@root") return
+  let hint = ""
+  if (root && !args.global) {
+    const n = countMatches(globalThis.document, to)
+    if (n > 0) hint = ` — it matches ${n} element(s) outside the stream's target root; use global: true`
+  }
+  emitZeroTargetWarn(`client op "${name}"`, to, root ? `scoped to #${root.id || "?"}` : "document-scoped", hint)
+}
+
 // Resolve a reactive:js op's targets against its `target` root (issue #97).
 // "@root" is the root element itself; a selector resolves WITHIN it; a bare
 // selector with no root (no `target` attr on the stream) resolves document-wide
@@ -1603,6 +1891,17 @@ export default class extends Controller {
   // Clipboard-trigger availability gate (issue #228): the bound morph re-sync,
   // held for teardown.
   #boundSyncClipboard
+  // Client-only drafts (issue #239): the parsed root payload (null when
+  // undeclared), the restore-complete latch (no write may run before the
+  // connect restore — a connect must never overwrite a draft with server
+  // blanks), the ONE per-root trailing-edge write timer, and the bound
+  // input/change/turbo:submit-end handlers held for teardown.
+  #persistConfig = null
+  #persistRestored = false
+  #persistTimer = null
+  #boundPersistInput
+  #boundPersistChange
+  #boundPersistSubmitEnd
 
   // Mark that a reactive controller actually connected, so the registration
   // guard above knows the controller was registered (issue #26 part 2).
@@ -1644,6 +1943,18 @@ export default class extends Controller {
       this.element.addEventListener?.("turbo:morph-element", this.#boundProbeLazyDefer)
     }
 
+    // Client-only drafts (issue #239) — ONLY when the root declares
+    // data-reactive-persist (one attribute read otherwise). Runs FIRST among
+    // the feature blocks ON PURPOSE: the restore writes the draft into the
+    // owned controls, and every later connect seed (dirty baseline, show,
+    // on-complete's arm-without-fire, filter, tags, nested-json, the compute
+    // self-seed) then reads the restored DOM naturally — no synthetic
+    // input/change events (which would FIRE reactive_on_complete bindings and
+    // reducer $ops on page load). Restore is connect-only: a
+    // turbo:morph-element is server truth arriving, never re-restored.
+    this.#persistConfig = persistPayload(this.element)
+    if (this.#persistConfig) this.#connectPersist()
+
     // Dirty tracking (issue #103) — ONLY when this root opts in (track_dirty: or a
     // reactive_field(dirty:)), so a component that never uses it pays nothing (no
     // baseline scan, no morph listener on every broadcast). A plain (outerHTML)
@@ -1823,6 +2134,10 @@ export default class extends Controller {
   // leading-edge timer holds no pending POST, but leaving it running would leak
   // it past the element's life.
   disconnect() {
+    // Persist FIRST: flush a pending draft write while the fields are still
+    // readable (Turbo disconnects before leaving the page — a fast visit
+    // otherwise loses the last keystrokes).
+    this.#teardownPersist()
     this.#clearAllDebounces()
     this.#clearAllThrottles()
     this.#teardownDirtyTracking()
@@ -2204,7 +2519,11 @@ export default class extends Controller {
     const fire = signature !== null && signature !== this.#computeOpsSignature && eventDriven
     this.#computeOpsSignature = signature
     if (!fire) return
-    applyOps(list, (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args))
+    applyOps(
+      list,
+      (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args),
+      (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
+    )
   }
 
   // Client-side list navigation (combobox keyboard nav, issue #72). Wired by
@@ -3691,7 +4010,13 @@ export default class extends Controller {
       if (matches === null) return
       const fire = matches && !this.#onCompleteStates[i] && Boolean(event)
       this.#onCompleteStates[i] = matches
-      if (fire) applyOps(binding.ops, (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args))
+      if (fire) {
+        applyOps(
+          binding.ops,
+          (args) => this.#opTargets(args.to == null ? { ...args, to: "@root" } : args),
+          (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
+        )
+      }
     })
   }
 
@@ -3896,6 +4221,87 @@ export default class extends Controller {
 
   // Remove the show-sync listeners on disconnect, so a stray event after a
   // Turbo morph/navigation never re-evaluates against a detached root.
+  // Client-only drafts (issue #239): restore the draft into the owned
+  // controls, expose the state bag, announce, then arm the write listeners.
+  // The restore reads ONCE and never writes back — the restored latch stays
+  // false until it completes, so no listener can clobber the draft with the
+  // server's blanks. The submit-end listener is DOCUMENT-level (the event
+  // fires on the form, which is usually an ANCESTOR of this root) and gated
+  // on the form containing this root.
+  #connectPersist() {
+    const payload = this.#persistConfig
+    this.#persistRestored = false
+    const draft = persistRead(this.element, payload)
+    if (draft) {
+      persistApply(this.element, payload, draft.fields)
+      if (draft.state) this.element.setAttribute?.(PERSIST_STATE_ATTR, JSON.stringify(draft.state))
+      this.#emit("reactive:persist-restored", { key: payload.key, fields: draft.fields, state: draft.state ?? {} })
+    }
+    this.#persistRestored = true
+
+    this.#boundPersistInput = () => this.#schedulePersistWrite()
+    this.#boundPersistChange = () => this.#persistWriteNow()
+    this.#boundPersistSubmitEnd = (event) => this.#persistSubmitEnd(event)
+    this.element.addEventListener?.("input", this.#boundPersistInput)
+    this.element.addEventListener?.("change", this.#boundPersistChange)
+    document.addEventListener?.("turbo:submit-end", this.#boundPersistSubmitEnd)
+  }
+
+  // Trailing-edge debounce for keystrokes — ONE timer per root (a snapshot is
+  // a full pass, so per-field timers would only multiply writes).
+  #schedulePersistWrite() {
+    if (!this.#persistRestored) return
+    const ms = Number(this.#persistConfig?.debounce) || 0
+    if (ms <= 0) return this.#persistWriteNow()
+    if (this.#persistTimer !== null) clearTimeout(this.#persistTimer)
+    this.#persistTimer = setTimeout(() => {
+      this.#persistTimer = null
+      this.#persistWriteNow()
+    }, ms)
+  }
+
+  // Snapshot every persistable owned control and write. Re-reads the current
+  // draft first so a state bag written by persist_state survives the write
+  // (the bag lives in storage, not on the instance — the op has no instance).
+  #persistWriteNow() {
+    if (!this.#persistRestored || !this.#persistConfig) return
+    if (this.#persistTimer !== null) {
+      clearTimeout(this.#persistTimer)
+      this.#persistTimer = null
+    }
+    const payload = this.#persistConfig
+    const current = persistRead(this.element, payload)
+    persistWrite(this.element, payload, { fields: persistSnapshot(this.element, payload), state: current?.state ?? null })
+  }
+
+  // A SUCCESSFUL Turbo form submission of the form that owns this root
+  // forgets the draft. tagName (not instanceof) so a cross-realm form counts.
+  #persistSubmitEnd(event) {
+    if (!event?.detail?.success) return
+    const form = event.target
+    if (form?.tagName !== "FORM" || typeof form.contains !== "function") return
+    if (!form.contains(this.element)) return
+    // Drop a pending keystroke write too — the disconnect flush that follows
+    // Turbo's redirect visit would otherwise resurrect the just-cleared draft.
+    if (this.#persistTimer !== null) {
+      clearTimeout(this.#persistTimer)
+      this.#persistTimer = null
+    }
+    persistRemove(this.element, this.#persistConfig)
+  }
+
+  // Flush a pending write, then drop every listener (disconnect()).
+  #teardownPersist() {
+    if (!this.#persistConfig) return
+    if (this.#persistTimer !== null) this.#persistWriteNow()
+    this.element.removeEventListener?.("input", this.#boundPersistInput)
+    this.element.removeEventListener?.("change", this.#boundPersistChange)
+    document.removeEventListener?.("turbo:submit-end", this.#boundPersistSubmitEnd)
+    this.#boundPersistInput = this.#boundPersistChange = this.#boundPersistSubmitEnd = undefined
+    this.#persistConfig = null
+    this.#persistRestored = false
+  }
+
   #teardownShowSync() {
     if (!this.#boundSyncShow) return
     this.element.removeEventListener?.("input", this.#boundSyncShow)
@@ -4233,19 +4639,39 @@ export default class extends Controller {
     fd.append("token", token)
     fd.append("act", action)
     for (const [key, value] of Object.entries(params)) {
-      this.#appendField(fd, `params[${key}]`, value)
+      this.#appendField(fd, this.#wireKey(key), value)
     }
     const multiNames = this.#multiFileNames(files)
     for (const { name, file, multiple } of files) {
       // params[name][] when the input is `multiple` (array shape even for one
       // file) OR the name repeats across inputs; otherwise a lone scalar file.
       const asArray = multiple || multiNames.has(name)
-      const key = asArray ? `params[${name}][]` : `params[${name}]`
+      const key = asArray ? `${this.#wireKey(name)}[]` : this.#wireKey(name)
       fd.append(key, file, file.name)
     }
     return fd
   }
 
+  // The multipart wire key for a collected field/file name: params[...] with
+  // the name's OWN brackets expanded into nesting segments (issue #231). The
+  // old verbatim wrap of a Rails-bracketed name — params[blog_post[summary]] —
+  // is unparseable by Rack: a scalar arrived as {"blog_post[summary" => {"]" =>
+  // value}} (data corruption written through `update!` with a 200) and a file
+  // never reached its schema key (silent drop). Expanding blog_post[summary]
+  // into params[blog_post][summary] mirrors the server's bracket_path exactly —
+  // split at the first "[", then each non-empty bracket segment; an empty
+  // trailing segment (tags[]) drops, matching how the JSON path's
+  // expand_bracket_keys coerces the same name — so a multipart body and a JSON
+  // body coerce identically for the same fields (the documented contract).
+  // A flat name stays a single params[name] wrap, byte-identical to before.
+  #wireKey(name) {
+    const raw = String(name)
+    const head = raw.indexOf("[")
+    if (head === -1) return `params[${raw}]`
+    const segments = [raw.slice(0, head), ...(raw.slice(head).match(/[^\[\]]+/g) ?? [])]
+    return `params${segments.map((segment) => `[${segment}]`).join("")}`
+  }
+
   // Append a param leaf to FormData under its bracketed key. FormData carries
   // only strings, so a NON-scalar param (a nested object or an array) is
   // bracket-EXPANDED into params[key][sub] / params[key][index][...] fields —
@@ -4309,7 +4735,41 @@ export default class extends Controller {
   // logic lives in the shared applyOps so runOps and the reactive:js stream
   // action interpret the SAME vocabulary the SAME way (client-side default-deny).
   #applyOps(list) {
-    applyOps(list, (args) => this.#opTargets(args))
+    applyOps(
+      list,
+      (args) => this.#opTargets(args),
+      (name, args) => this.#diagnoseZeroTargets(`client op "${name}"`, args),
+    )
+  }
+
+  // Issue #237: the verbose gate for zero-target diagnostics — the
+  // verbose_errors stamp (ON by default in dev/test) or full debug mode (a
+  // debug user must never see less). Read live off the root like #debugEnabled.
+  #verboseEnabled() {
+    return this.element?.getAttribute?.("data-reactive-verbose") === "true" || this.#debugEnabled()
+  }
+
+  // Issue #237: called when a selector-form target resolved to ZERO elements on
+  // this root. Gated + deduped (module helpers); builds the trap-specific hint:
+  // the root-self selector (root-scoped resolution never includes the root),
+  // the nested-reactive-root ownership filter, or plain out-of-scope. All DOM
+  // probes run only here — after a zero-match with the gate on.
+  #diagnoseZeroTargets(label, args) {
+    if (!this.#verboseEnabled()) return
+    const to = args.to
+    if (typeof to !== "string" || to === "" || to === "@root") return
+    let hint = ""
+    if (!args.global) {
+      if (this.element?.matches?.(to)) {
+        hint = " — the selector matches this component's own root, which root-scoped resolution never includes; use to: :root"
+      } else if (countMatches(this.element, to) > 0) {
+        hint = " — it matches only inside a nested reactive root (excluded by ownership scoping); use global: true"
+      } else {
+        const n = countMatches(globalThis.document, to)
+        if (n > 0) hint = ` — it matches ${n} element(s) outside this scope; use global: true`
+      }
+    }
+    emitZeroTargetWarn(label, to, `scoped to #${this.element?.id || "?"}`, hint)
   }
 
   // Resolve an op's targets: "@root" is this element; a selector resolves
@@ -4462,7 +4922,10 @@ export default class extends Controller {
   // 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 })
+    const targets = this.#opTargets({ to: hint.to })
+    // Issue #237: a hint aimed at nothing is the same silent trap as an op.
+    if (targets.length === 0) this.#diagnoseZeroTargets("busy/optimistic hint", { to: hint.to })
+    return targets
   }
 
   // Swap the trigger's disabled/innerHTML for a pending hint, snapshotting the