phlex-reactive 0.15.3 → 0.15.4

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

@@ -37,6 +37,7 @@ import * as hintsFeature from "phlex/reactive/features/hints"
 import * as deferFeature from "phlex/reactive/features/defer"
 import * as sortableFeature from "phlex/reactive/features/sortable"
 import * as presenceFeature from "phlex/reactive/features/presence"
+import * as countdownFeature from "phlex/reactive/features/countdown"
 
 // phlex/reactive/runtime — the reactive controller WITHOUT its feature
 // modules (issue #275): the code both client entries share. It is not an
@@ -436,6 +437,26 @@ const IMAGE_STATE = "data-reactive-image-state"
 const IMAGE_HIDDEN = "data-reactive-image-hidden"
 let imageFallbackListeners = null
 
+// --- A wrapper an op hides (issues #391, #392) -------------------------------
+// preview_file's wrap: and reactive_image_fallback's wrap: hide the box around
+// an img. The mark says the runtime set that `hidden`, so a show removes only
+// a hide of its own, never one the author wrote. On the element, for the
+// IMAGE_HIDDEN reason. Visibility only: a wrapper usually holds the img, so
+// nothing here writes its text.
+const WRAP_HIDDEN = "data-reactive-wrap-hidden"
+
+function hideWrap(el) {
+  if (el.hasAttribute("hidden")) return
+  el.setAttribute("hidden", "")
+  el.setAttribute(WRAP_HIDDEN, "")
+}
+
+function showWrap(el) {
+  if (!el.hasAttribute(WRAP_HIDDEN)) return
+  el.removeAttribute("hidden")
+  el.removeAttribute(WRAP_HIDDEN)
+}
+
 function imageFallback(img) {
   if (img?.localName !== "img") return null
   const raw = img.getAttribute(IMAGE_FALLBACK)
@@ -451,23 +472,33 @@ const hasImageSrc = (img) => img.getAttribute("src") || img.getAttribute("srcset
 
 // The node that shows the alt text: a selector resolved inside the img's own
 // root only (a document listener has no op scope).
-function imageAltNode(img, wire) {
-  if (typeof wire.alt !== "string" || !wire.alt) return null
+function imageRootNode(img, selector) {
+  if (typeof selector !== "string" || !selector) return null
   try {
-    const node = img.closest('[data-controller~="reactive"]')?.querySelector(wire.alt)
-    // Never a node that holds the img: its textContent would wipe the img.
-    return node && !node.contains(img) ? node : null
+    return img.closest('[data-controller~="reactive"]')?.querySelector(selector) ?? null
   } catch {
     return null
   }
 }
 
+function imageAltNode(img, wire) {
+  const node = imageRootNode(img, wire.alt)
+  // Never a node that holds the img: its textContent would wipe the img.
+  return node && !node.contains(img) ? node : null
+}
+
 function setImageState(img, wire, value) {
   if (value === "error") {
     if (wire.hide && !img.hasAttribute("hidden")) {
       img.setAttribute("hidden", "")
       img.setAttribute(IMAGE_HIDDEN, "")
     }
+    // wrap: (issue #392) may hold the img: only its visibility changes.
+    if (wire.wrap) {
+      const wrap = imageRootNode(img, wire.wrap)
+      if (wrap) hideWrap(wrap)
+      else console.warn(`[phlex-reactive] reactive_image_fallback wrap: ${JSON.stringify(wire.wrap)} is not in the root — skipped`)
+    }
     const node = imageAltNode(img, wire)
     if (node) {
       node.textContent = img.getAttribute("alt") ?? ""
@@ -483,6 +514,8 @@ function resetImage(img, wire = imageFallback(img)) {
   if (!wire || img.getAttribute(IMAGE_STATE) == null) return
   if (img.getAttribute(IMAGE_STATE) === "error") {
     if (img.hasAttribute(IMAGE_HIDDEN)) img.removeAttribute("hidden")
+    const wrap = imageRootNode(img, wire.wrap)
+    if (wrap) showWrap(wrap)
     const node = imageAltNode(img, wire)
     if (node) node.hidden = true
   }
@@ -1247,6 +1280,13 @@ const CLIENT_OPS = Object.freeze({
   // its first focusable descendant (opened-menu → first menuitem).
   focus: (el) => el.focus?.(),
   focus_first: (el) => firstFocusable(el)?.focus?.(),
+  // Issue #399: blur the focused element when it is the target or inside it
+  // (Escape ends a menu's :focus-within); focus elsewhere is left alone.
+  // ACTOR-ONLY like focus (BROADCAST_REFUSED_OPS server-side).
+  blur: (el) => {
+    const active = el.ownerDocument?.activeElement ?? globalThis.document?.activeElement
+    if (active && (active === el || el.contains?.(active))) active.blur?.()
+  },
 
   // Modal dialog ops (issue #365): HTMLDialogElement#showModal / #close.
   // ACTOR-ONLY like focus (BROADCAST_REFUSED_OPS server-side).
@@ -1429,8 +1469,18 @@ function previewFile(input, args, resolveTargets) {
   // valid: true (issue #382): an input the app marked invalid (setCustomValidity,
   // required) previews as empty. validity.valid, not checkValidity(): no
   // `invalid` event fired into the app's own listeners.
-  const files = args.valid === true && input.validity?.valid === false ? [] : (input.files ?? [])
-  const file = [...files].find((f) => typeof f?.type === "string" && f.type.startsWith("image/"))
+  const files = [...(args.valid === true && input.validity?.valid === false ? [] : (input.files ?? []))]
+  const accepts = previewAccepts(input, args.accept)
+  const listed = files.filter((f) => typeof f?.type === "string" && accepts(f))
+  // Only an image is painted: a listed PDF clears the preview, unrefused.
+  let file = listed.find((f) => f.type.startsWith("image/"))
+  // A refused file (issue #391) clears like an empty pick and says why. The
+  // input keeps its files and its validity: the page owns the reset. Size is
+  // read BEFORE an object URL exists, so an over-size file never gets one.
+  let reason = files.length > 0 && listed.length === 0 ? "type" : null
+  if (file && Number.isInteger(args.max_bytes) && file.size > args.max_bytes) reason = "size"
+  const refused = reason === "size" ? file : files[0]
+  if (reason) file = null
   forgetPreview(img)
   if (file) {
     const url = URL.createObjectURL(file)
@@ -1439,8 +1489,40 @@ function previewFile(input, args, resolveTargets) {
     watchPreviews()
   } else img.removeAttribute("src")
   resetImage(img)
-  if (args.name == null) return
-  for (const node of resolveTargets({ ...args, to: args.name })) node.textContent = file ? file.name : ""
+  if (args.wrap != null) {
+    const wraps = resolveTargets({ ...args, to: args.wrap })
+    if (wraps.length === 0) warnPreview(`wrap: ${JSON.stringify(args.wrap)} is not on the page`)
+    for (const wrap of wraps) file ? showWrap(wrap) : hideWrap(wrap)
+  }
+  if (args.name != null) {
+    for (const node of resolveTargets({ ...args, to: args.name })) node.textContent = file ? file.name : ""
+  }
+  if (reason) {
+    input.dispatchEvent(new CustomEvent("reactive:file-rejected", { bubbles: true, detail: { reason, file: refused } }))
+  }
+}
+
+// Which files the page takes: an image by default. accept: true reads the
+// input's own accept attribute; a string is that list for this op. A token is
+// an extension (".png"), a MIME type or a type/* wildcard, the browser's own
+// accept grammar. An absent or empty list keeps the image rule.
+function previewAccepts(input, accept) {
+  const tokens = String((accept === true ? input.getAttribute("accept") : typeof accept === "string" && accept) || "")
+    .toLowerCase()
+    .split(",")
+    .map((token) => token.trim())
+    .filter(Boolean)
+  if (tokens.length === 0) return (f) => f.type.startsWith("image/")
+  return (f) => {
+    const type = f.type.toLowerCase()
+    return tokens.some((token) =>
+      token[0] === "."
+        ? String(f.name).toLowerCase().endsWith(token)
+        : token.endsWith("/*")
+          ? type.startsWith(token.slice(0, -1))
+          : type === token,
+    )
+  }
 }
 
 function warnPreview(why) {
@@ -1988,6 +2070,11 @@ function presenceNeeded(root) {
   return root.getAttribute?.("data-reactive-presence") != null
 }
 
+// Countdowns (issue #400): the root is, or holds, a reactive_countdown.
+function countdownNeeded(root) {
+  return Boolean(root.matches?.("[data-reactive-countdown]") || root.querySelector?.("[data-reactive-countdown]"))
+}
+
 const PRODUCTION_FEATURES = [
   // (Its `waiting` hook is the opt-in entry's: core.js.) The draft restore
   // writes what a request reads, so it gates.
@@ -2003,6 +2090,8 @@ const PRODUCTION_FEATURES = [
   // Its announce is a request of its own; nothing it does at connect is read
   // by another request: it never gates.
   ["presence", [presenceNeeded, null]],
+  // A countdown writes only its own text and visibility: it never gates.
+  ["countdown", [countdownNeeded, null]],
   [
     // Stream effects and dismissing flashes are document-level: the module
     // has no connect. A root that DECLARES an effect only gets it fetched
@@ -2166,7 +2255,7 @@ function featureTimeoutMs() {
 export function reactiveFeatureNames() {
   return __SPLIT__
     ? [...FEATURES.keys()]
-    : ["persist", "defer", "form", "bindings", "compute", "sortable", "presence", "effects", "hints", "devtools"]
+    : ["persist", "defer", "form", "bindings", "compute", "sortable", "presence", "countdown", "effects", "hints", "devtools"]
 }
 
 export function __setReactiveFeatureForTest(name, needs, load, waiting, gates) {
@@ -2190,6 +2279,7 @@ export function __loadReactiveFeatureForTest(name) {
     compute: computeFeature,
     sortable: sortableFeature,
     presence: presenceFeature,
+    countdown: countdownFeature,
     effects: effectsFeature,
     hints: hintsFeature,
     devtools: devtoolsFeature,
@@ -2244,6 +2334,7 @@ const BINDINGS = 8
 const COMPUTE = 16
 const SORTABLE = 32
 const PRESENCE = 64
+const COUNTDOWN = 128
 
 // The default entry's features are part of this file: install them now, as
 // the opt-in entry does when one arrives.
@@ -2269,6 +2360,10 @@ const WINDOW_EARLY_TTL_MS = 1500
 // which a replay built from its trigger element's document carries).
 const isWindow = (target) => target != null && (target === globalThis.window || target.window === target)
 
+// Issue #393: the key on()'s dispatch debounce uses in #debounceTimers. An
+// on_client record keys on its JSON, which starts with "{", so never this.
+const DISPATCH_WAIT_KEY = "dispatch"
+
 function earlyState() {
   globalThis[EARLY_KEY] ??= { queue: [], connected: new WeakSet() }
   return globalThis[EARLY_KEY]
@@ -2425,8 +2520,8 @@ export default class extends Controller {
   }
 
   #tokenCache // freshest token, threaded synchronously across queued requests
-  #debounceTimers = new Map() // trigger element -> { timer, flush } pending dispatch
-  #throttleTimers = new Map() // trigger element -> Map(action -> suppression timer)
+  #debounceTimers = new Map() // trigger element -> Map(key -> { timer, flush }) pending run
+  #throttleTimers = new Map() // trigger element -> Map(action or record key -> suppression timer)
   #actionPathCache // page-stable action path, resolved once per controller
   #timeoutMsCache // page-stable request timeout (ms), resolved once per controller (issue #101)
   #tokenRegexCache // { id, token, self } — #extractToken's two per-id RegExps, rebuilt on id change (issue #118)
@@ -2465,7 +2560,7 @@ export default class extends Controller {
   #featureTurns = new Map() // name -> settles once that feature has had its turn to connect
   #featureEpoch = 0
   #featureHandle // the `core` handle features receive, built on first use
-  // The default entry (issue #305): one bit per feature, PERSIST … PRESENCE —
+  // The default entry (issue #305): one bit per feature, PERSIST … COUNTDOWN —
   // asked for (its marker read true) and connected on this connection.
   #featuresAsked = 0
   #featuresOn = 0
@@ -2568,6 +2663,7 @@ export default class extends Controller {
       this.#connectFeatureNow(COMPUTE, "compute", computeNeeded, (core) => computeFeature.connect(this, core, morphed))
       this.#connectFeatureNow(SORTABLE, "sortable", sortableNeeded, (core) => sortableFeature.connect(this, core))
       this.#connectFeatureNow(PRESENCE, "presence", presenceNeeded, (core) => presenceFeature.connect(this, core))
+      this.#connectFeatureNow(COUNTDOWN, "countdown", countdownNeeded, (core) => countdownFeature.connect(this, core))
     }
   }
 
@@ -2606,6 +2702,7 @@ export default class extends Controller {
       if (on & COMPUTE) this.#disconnectFeatureNow("compute", () => computeFeature.disconnect(this, core))
       if (on & SORTABLE) this.#disconnectFeatureNow("sortable", () => sortableFeature.disconnect(this, core))
       if (on & PRESENCE) this.#disconnectFeatureNow("presence", () => presenceFeature.disconnect(this, core))
+      if (on & COUNTDOWN) this.#disconnectFeatureNow("countdown", () => countdownFeature.disconnect(this, core))
     }
   }
 
@@ -2801,6 +2898,8 @@ export default class extends Controller {
       served: serverText,
       // Copy one <img> onto another (issue #373): the reactive_media binding.
       copyMedia,
+      // set_value's write (issue #374): reactive_show clear: (issue #394).
+      setValue: setFieldValue,
       // The confirm gate, as dispatch() runs it: the resolver inside the chain
       // (a synchronous throw is a cancel), never a rejection out.
       confirm: (message, context) =>
@@ -3233,13 +3332,21 @@ export default class extends Controller {
       if (record.shortcut != null && !shortcutApplies(record.shortcut, event, this.application?.schema?.keyMappings))
         continue
       if (onceBindingSpent(this, event, record)) continue
-      this.#runBinding(record.legacy ? { ...params, ops: record.ops } : record, event, trigger)
+      // A legacy attr reads its flags element-wide — but never a mix-ed on()'s
+      // debounce/throttle params (issue #393): those belong to the dispatch.
+      this.#runBinding(
+        record.legacy ? { ...params, ops: record.ops, debounce: undefined, throttle: undefined } : record,
+        event,
+        trigger,
+        records.indexOf(record),
+      )
     }
   }
 
   // One on_client binding (issue #95): its outside guard, preventDefault rule,
   // confirm gate, then its ops — every flag read from the binding itself.
-  #runBinding({ ops, confirm, confirmWhen, outside, window: windowBound, shortcut }, event, trigger) {
+  #runBinding(record, event, trigger, ordinal) {
+    const { ops, confirm, confirmWhen, outside, window: windowBound, shortcut } = record
     // Outside guard FIRST — identical semantics to dispatch() (issue #80): an
     // outside: trigger is a COMPLETE no-op for events inside this root, before
     // preventDefault and before any op runs.
@@ -3262,7 +3369,7 @@ export default class extends Controller {
     // which must NEVER prompt. The same confirmResolver gate on(:action,
     // confirm:) uses (issues #52/#55/#178), so a themed dialog covers both.
     const message = this.#effectiveConfirmMessage(confirm, confirmWhen)
-    const apply = () => this.#applyOps(this.#parseOps(ops))
+    const apply = this.#waitedOps(record, ordinal, trigger, () => this.#applyOps(this.#parseOps(ops)))
     if (!message) return apply()
     if (message instanceof Promise) {
       return message.then((resolved) => (resolved ? this.#confirmThen(resolved, trigger, apply) : apply()))
@@ -3270,6 +3377,20 @@ export default class extends Controller {
     this.#confirmThen(message, trigger, apply)
   }
 
+  // Issue #393: an on_client record's debounce:/throttle: — on()'s timers
+  // (#debounce trailing, #throttle leading), keyed on the trigger + the
+  // record's ordinal + JSON (two identical mix-ed records keep their own
+  // timers), so disconnect clears them with the dispatch ones. The wait sits
+  // after the outside guard, preventDefault and confirm, as on()'s does.
+  #waitedOps(record, ordinal, trigger, run) {
+    const debounce = Number(record.debounce) || 0
+    const throttle = Number(record.throttle) || 0
+    if (debounce <= 0 && throttle <= 0) return run
+    const key = JSON.stringify([ordinal, record])
+    if (debounce > 0) return () => this.#debounce(trigger, key, debounce, run)
+    return () => this.#throttle(trigger, key, throttle, run)
+  }
+
   // Client-side compute (issue #104) is the compute feature's (issue #275,
   // features/compute.js). This is the method its descriptor names
   // (input->reactive#recompute), so it stays. While the module is on its way
@@ -3554,30 +3675,45 @@ export default class extends Controller {
   // 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, busy) {
-    this.#clearDebounce(target)
+    this.#debounce(target, DISPATCH_WAIT_KEY, ms, () => this.#enqueue(action, params, optimistic, target, busy))
+  }
+
+  // The one trailing-edge timer on() and on_client (issue #393) share. Timers
+  // are keyed on target + key: on()'s dispatch uses DISPATCH_WAIT_KEY, an
+  // on_client record its ordinal + JSON (it starts with "["), so an on() debounce and an
+  // on_client debounce on one input never cancel each other. A window-bound
+  // trigger gets no blur flush: a window blur is a tab switch, not an edit.
+  #debounce(target, key, ms, run) {
+    this.#clearDebounce(target, key)
 
     const flush = () => {
-      this.#clearDebounce(target)
-      this.#enqueue(action, params, optimistic, target, busy)
+      this.#clearDebounce(target, key)
+      run()
     }
     const timer = setTimeout(flush, ms)
-    target?.addEventListener?.("blur", flush, { once: true })
-    this.#debounceTimers.set(target, { timer, flush })
+    if (!isWindow(target)) target?.addEventListener?.("blur", flush, { once: true })
+    let pending = this.#debounceTimers.get(target)
+    if (!pending) this.#debounceTimers.set(target, (pending = new Map()))
+    pending.set(key, { timer, flush })
   }
 
-  #clearDebounce(target) {
-    const pending = this.#debounceTimers.get(target)
+  #clearDebounce(target, key) {
+    const byKey = this.#debounceTimers.get(target)
+    const pending = byKey?.get(key)
     if (!pending) return
     clearTimeout(pending.timer)
     target?.removeEventListener?.("blur", pending.flush)
-    this.#debounceTimers.delete(target)
+    byKey.delete(key)
+    if (byKey.size === 0) this.#debounceTimers.delete(target)
   }
 
   // Clear every pending debounce timer (used on disconnect). Reuses
   // #clearDebounce so all timer/listener teardown stays in one place. Snapshot
-  // the keys first — #clearDebounce mutates the map as it goes.
+  // the entries first — #clearDebounce mutates the maps as it goes.
   #clearAllDebounces() {
-    for (const target of [...this.#debounceTimers.keys()]) this.#clearDebounce(target)
+    for (const [target, byKey] of [...this.#debounceTimers]) {
+      for (const key of [...byKey.keys()]) this.#clearDebounce(target, key)
+    }
   }
 
   // Leading-edge throttle (issue #80), mirroring #debounceDispatch: the FIRST
@@ -3587,16 +3723,22 @@ export default class extends Controller {
   // 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, busy) {
+    return this.#throttle(target, action, ms, () => this.#enqueue(action, params, optimistic, target, busy))
+  }
+
+  // The leading-edge window on() and on_client (issue #393) share; an
+  // on_client record keys on its ordinal + JSON, which no action name can equal.
+  #throttle(target, key, ms, run) {
     const timers = this.#throttleTimers.get(target) ?? new Map()
-    if (timers.has(action)) return // inside the window — suppress
+    if (timers.has(key)) return // inside the window — suppress
 
     const timer = setTimeout(() => {
-      timers.delete(action)
+      timers.delete(key)
       if (timers.size === 0) this.#throttleTimers.delete(target)
     }, ms)
-    timers.set(action, timer)
+    timers.set(key, timer)
     this.#throttleTimers.set(target, timers)
-    return this.#enqueue(action, params, optimistic, target, busy) // leading edge: fire NOW
+    return run() // leading edge: fire NOW
   }
 
   // Clear every throttle suppression timer (used on disconnect, alongside

data/lib/phlex/reactive/component/countdown_binding.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phlex
+  module Reactive
+    module Component
+      # A server deadline counted down on the client (issue #400).
+      #
+      #   span(**reactive_countdown(until: deadline.iso8601, waiting: "#wait", done: "#done")) { "2:00" }
+      #   div(id: "wait") { "Waiting" }
+      #   div(id: "done", hidden: true) { "Finished" }
+      #
+      # The client paints the time left from until: and Date.now at connect and
+      # once a second ("1:30": unpadded minutes, a colon, padded seconds — the
+      # only format, :ms), as textContent only. A tab that wakes late jumps to
+      # the real time left. At zero, or with until: already past on connect, the
+      # text is "0:00", data-reactive-countdown-state is "done", waiting: hides,
+      # done: shows (CSS selectors inside the root) and the element dispatches
+      # reactive:countdown-done once; the timer stops. A morph that keeps until:
+      # does not dispatch again; one that changes it counts down again. No
+      # request and no frame reload: the event is the hook.
+      #
+      # The countdown's content is its text, so waiting: and done: name nodes
+      # beside it, never inside it: a reactive root that is itself the
+      # countdown has nowhere to put them.
+      #
+      # The server renders the initial text and visibility, so the page reads
+      # with JavaScript off. until: is an ISO8601 date-time WITH a zone (Z or an
+      # offset), or a Time, which is written as one: a zoneless string would
+      # read as the browser's local time.
+      module CountdownBinding
+        ISO8601_WITH_ZONE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+
+        # `until` is a keyword: the value is read off the binding.
+        def reactive_countdown(until:, format: :ms, waiting: nil, done: nil, **attrs)
+          wire = { "until" => countdown_until!(binding.local_variable_get(:until)), "format" => countdown_format!(format) }
+          wire["waiting"] = countdown_selector!(:waiting, waiting) unless waiting.nil?
+          wire["done"] = countdown_selector!(:done, done) unless done.nil?
+          mix({ data: { reactive_countdown: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def countdown_until!(value)
+          value = value.utc.iso8601(value.subsec.zero? ? 0 : 3) if value.is_a?(Time) || value.respond_to?(:time_zone)
+          return value if countdown_iso8601?(value)
+
+          raise ArgumentError, "reactive_countdown until: must be an ISO8601 date-time with a zone " \
+                               "(e.g. \"2026-10-14T12:02:00Z\") or a Time, got #{value.inspect}"
+        end
+
+        # The shape (a zone is required), then a real date (no month 13).
+        def countdown_iso8601?(value)
+          value.is_a?(String) && value.match?(ISO8601_WITH_ZONE) && Time.iso8601(value) && true
+        rescue ::ArgumentError
+          false
+        end
+
+        def countdown_format!(format)
+          return "ms" if format == :ms
+
+          raise ArgumentError, "reactive_countdown format: must be :ms (the only format), got #{format.inspect}"
+        end
+
+        # A selector the client passes to querySelector inside the root.
+        def countdown_selector!(name, selector)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_countdown #{name}: #{selector} names the whole root — pass the selector of a node inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_countdown #{name}: must be a CSS selector (e.g. \"##{name}\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/component/field_references.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Render-time checks for a binding that names ANOTHER field: same:
+      # (issue #395), after: (#396) and clear: (#394). The binding's attrs are
+      # built before its section's children render, so the check waits for the
+      # end of the OUTERMOST Phlex render in progress and reads the fields that
+      # render produced — a field below the binding, or inside a nested
+      # component, counts. An unknown name (or a file input named in clear:)
+      # raises ArgumentError at render, never silently in the browser.
+      #
+      # Nothing is recorded when no binding names a field, and a helper called
+      # outside a render (no buffer to read) is not checked. A fragment render
+      # (only part of the template reaches the buffer) is not checked either,
+      # nor is a render that calls `flush`. The scan accepts any element with
+      # that name, including one inside a nested reactive root the client will
+      # not read (ownership is the client's rule), so it catches typos, not
+      # misplaced fields.
+      module FieldReferences
+        REFS_KEY = :__phlex_reactive_field_refs
+
+        # A start tag and its attributes (quoted values may hold ">").
+        TAG = %r{<[a-zA-Z][\w-]*((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>]+))?)*)\s*/?>}
+        # One attribute of that list, walked in order so a "name=" inside
+        # another attribute's quoted value is never read as the name.
+        ATTR = %r{\s+([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?}
+
+        private
+
+        def around_template(&)
+          # Thread#[] is fiber-local: a nested component, or a capture inside
+          # this render, shares the outermost render's list. `true` marks a
+          # render in progress with nothing recorded yet, so a render without
+          # such a binding allocates nothing here.
+          return super if Thread.current[REFS_KEY] || !defined?(@_state) || @_state.nil?
+
+          buffer = @_state.buffer
+          start = buffer.bytesize
+          Thread.current[REFS_KEY] = true
+          begin
+            super
+            refs = Thread.current[REFS_KEY]
+          ensure
+            Thread.current[REFS_KEY] = nil
+          end
+          check_field_references!(refs, buffer.byteslice(start..)) if refs.is_a?(Array) && !@_state.fragments
+        end
+
+        public
+
+        # A flush moves the buffer out mid-render, so the end-of-render scan
+        # would miss fields above it: record the references as unchecked.
+        def flush
+          Thread.current[REFS_KEY] = :flushed if Thread.current[REFS_KEY]
+          super
+        end
+
+        private
+
+        # Record a binding's field references for the end-of-render check.
+        # `names` are bare show names (scope-aware, like the client resolver);
+        # `no_file` refuses a file input under the name.
+        def reference_fields!(helper, key, names, no_file: false)
+          refs = Thread.current[REFS_KEY]
+          return unless refs
+
+          return if refs == :flushed
+
+          refs = Thread.current[REFS_KEY] = [] if refs == true
+          names.each { refs << [helper, key, it, field_wire_name(it), no_file] }
+        end
+
+        # Every same: name in a binding's compiled groups (issue #395).
+        def reference_same_fields!(helper, groups)
+          names = groups.flatten.filter_map { it["same"] }
+          reference_fields!(helper, :same, names.uniq) if names.any?
+        end
+
+        # The name the client's resolver queries: scope[name] under
+        # reactive_scope, a bracketed name (an author's raw wire name) verbatim.
+        def field_wire_name(name)
+          name.include?("[") ? name : scoped_field_name(name)
+        end
+
+        def check_field_references!(refs, html)
+          names, files = rendered_fields(html)
+          refs.each do |helper, key, name, wire, no_file|
+            unless names.include?(wire)
+              raise ArgumentError,
+                "#{helper} #{key}: #{name.to_sym.inspect} names no field this render produced " \
+                "(no element with name=\"#{wire}\")"
+            end
+            next unless no_file && files.include?(wire)
+
+            raise ArgumentError,
+              "#{helper} #{key}: #{name.to_sym.inspect} is a file input — a file field cannot be cleared"
+          end
+        end
+
+        # The name of every element the HTML renders, and those that are
+        # file inputs.
+        def rendered_fields(html)
+          names = Set.new
+          files = Set.new
+          html.scan(TAG) do
+            attrs = tag_attributes(Regexp.last_match(1).to_s)
+            next unless (name = attrs["name"])
+
+            names << name
+            files << name if attrs["type"]&.casecmp?("file")
+          end
+          [names, files]
+        end
+
+        # A tag's attributes by lowercased name (HTML attribute names are
+        # case-insensitive); the first occurrence wins, as in the browser.
+        def tag_attributes(text)
+          attrs = {}
+          text.scan(ATTR) do |key, double, single, bare|
+            value = double || single || bare
+            attrs[key.downcase] ||= value.nil? ? "" : CGI.unescapeHTML(value)
+          end
+          attrs
+        end
+      end
+    end
+  end
+end