phlex-reactive 0.15.1 → 0.15.2

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

@@ -200,6 +200,7 @@ export function registerReactiveStreamRender() {
   if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
   streamRenderRegistered = true
   document.addEventListener("turbo:before-stream-render", (event) => {
+    streamOwnReply(event)
     streamIntoRoots(event)
     streamModals(event)
     // The opt-in entry sees every stream (it may hold one for a module the
@@ -356,6 +357,68 @@ export function __resetReactiveModalsForTest() {
   modalsRegistered = false
 }
 
+// --- keep: a morph re-applies what a kept client op did (issue #369) ---------
+// A morph rewrites `class`, `hidden` and every attribute from the server
+// render, so a selection made with on_client ops was lost to the next reply or
+// broadcast morph. An op with keep: records its RESULT on each target — each
+// class on or off, `hidden`, an attribute's value (null: absent) — and the one
+// document listener below puts that back after Turbo morphs the element in
+// place. The result, not the op: a toggle must not flip again on every morph.
+// The latest kept op on an element and a class or attribute wins, so "clear
+// all, then select one" leaves one. Classes and attributes no kept op touched
+// follow the render. Weak: an element a stream replaces is a new element.
+//
+// One Map per element: ".name" → whether that class is on; an attribute name →
+// its value, null when absent. show/hide/toggle keep the `hidden` attribute,
+// so the morph puts back the visibility without running a transition again.
+// (No attribute name starts with ".", so the two kinds of key never meet.)
+// An entry is re-inserted on every kept op, so the Map replays in op order:
+// a kept add_class after a kept set_attr("class", …) still wins.
+const kept = new WeakMap()
+
+function keepResult(el, name, args, resolveTargets) {
+  const state = kept.get(el) ?? new Map()
+  kept.set(el, state)
+  const put = (key, value) => {
+    state.delete(key)
+    state.set(key, value)
+  }
+  if (name.endsWith("_class")) for (const c of args.classes ?? []) put(`.${c}`, el.classList.contains(c))
+  else if (name.endsWith("_attr")) attrRefused(args.name) || put(args.name, el.getAttribute(args.name))
+  else if (name === "show" || name === "hide" || name === "toggle") {
+    put("hidden", el.getAttribute("hidden"))
+    // The expanded: trigger's aria-expanded is kept on the trigger: a document
+    // listener has no op scope to resolve it from later.
+    if (args.expanded != null) {
+      for (const trigger of resolveTargets({ ...args, to: args.expanded })) {
+        keepResult(trigger, "set_attr", { name: "aria-expanded" })
+      }
+    }
+  }
+}
+
+let keepRegistered = false
+
+export function registerReactiveKeep() {
+  if (keepRegistered) return
+  if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
+  keepRegistered = true
+  // turbo:morph-element fires for every element Idiomorph morphed in place,
+  // after its attributes were synced from the new render.
+  document.addEventListener("turbo:morph-element", (event) => {
+    const el = event.target
+    for (const [key, value] of kept.get(el) ?? []) {
+      if (key[0] === ".") el.classList.toggle(key.slice(1), value)
+      else if (value == null) el.removeAttribute(key)
+      else if (el.getAttribute(key) !== value) el.setAttribute(key, value)
+    }
+  })
+}
+
+export function __resetReactiveKeepForTest() {
+  keepRegistered = false
+}
+
 // For the opt-in entry: what to do with a stream before its render — hold it
 // for a module the incoming content needs. `handle(event, effects)` gets the
 // loaded effects module (or undefined) and wraps the stream with it itself.
@@ -470,18 +533,21 @@ export function registerReactiveMorphFocus() {
     const el = event.target
     const next = event.detail?.newElement // absent when Turbo asks before a removal
     if (!next || event.defaultPrevented) return
+    const holds = holdsTypedValue(el)
+    // Before the default below is overwritten (issue #370).
+    if (holds) noteHeld(el, next)
     if (el.hasAttribute?.("data-reactive-editable")) {
       serverTexts.set(el, editableValue(next))
-      if (!holdsTypedValue(el)) return
+      if (!holds) return
       for (const { name } of [...el.attributes]) {
-        if (!next.hasAttribute(name) && name !== "contenteditable") el.removeAttribute(name)
+        if (!next.hasAttribute(name) && name !== "contenteditable" && name !== HELD) el.removeAttribute(name)
       }
       for (const { name, value } of next.attributes) {
         if (name !== "contenteditable" && el.getAttribute(name) !== value) el.setAttribute(name, value)
       }
       return event.preventDefault()
     }
-    if (el.localName !== "input" || !holdsTypedValue(el)) return
+    if (el.localName !== "input" || !holds) return
     const value = next.getAttribute("value")
     if (value == null) el.removeAttribute("value")
     else if (el.getAttribute("value") !== value) el.setAttribute("value", value)
@@ -490,10 +556,110 @@ export function registerReactiveMorphFocus() {
   // text when first focused — before anything can be typed into it.
   document.addEventListener("focusin", (event) => seedServerText(event.target))
   document.addEventListener("turbo:before-morph-attribute", (event) => {
-    if (event.detail?.attributeName === "value" && holdsTypedValue(event.target)) event.preventDefault()
+    const name = event.detail?.attributeName
+    if ((name === "value" || name === HELD) && holdsTypedValue(event.target)) event.preventDefault()
+  })
+  // The user took theirs: the field reads its default again.
+  document.addEventListener("input", (event) => {
+    const el = event.target
+    if (el?.hasAttribute?.(HELD) && typedValue(el) === serverValue(el)) el.removeAttribute(HELD)
   })
 }
 
+// --- Knowing what was held (issue #370) ---
+// A morph that holds a focused field (above) over a render whose value differs
+// from the field's default — its last server value — means someone else changed
+// the field while the user typed. The field is marked data-reactive-held (kept
+// through later morphs while focused, like `value`), a bubbling reactive:held
+// { name, theirs } is dispatched, and the root's next action sends the names as
+// X-Reactive-Held. The root's own reply never marks (it answers exactly those
+// values), and once applied the root holds nothing. A morph of the field while
+// unfocused writes the server's value and drops the mark with it.
+const HELD = "data-reactive-held"
+const ROOT = '[data-controller~="reactive"]'
+let replyRoot = null
+const replying = new Map()
+
+function typedValue(el) {
+  return el.hasAttribute("data-reactive-editable") ? editableValue(el) : el.value
+}
+
+function serverValue(el) {
+  return el.hasAttribute("data-reactive-editable") ? serverText(el) : el.defaultValue
+}
+
+function renderedValue(next) {
+  if (next.hasAttribute("data-reactive-editable")) return editableValue(next)
+  return next.localName === "textarea" ? next.textContent : (next.getAttribute("value") ?? "")
+}
+
+function noteHeld(el, next) {
+  const name = el.getAttribute("name")
+  // A checkbox's or radio's value is the option, not what the user typed.
+  if (!name || /^(checkbox|radio)$/.test(el.type) || replying.has(el.closest(ROOT))) return
+  const theirs = renderedValue(next)
+  if (theirs === typedValue(el)) return el.removeAttribute(HELD)
+  if (theirs === serverValue(el)) return
+  el.setAttribute(HELD, "")
+  el.dispatchEvent(new CustomEvent("reactive:held", { bubbles: true, detail: { name, theirs } }))
+}
+
+// The names a root's next request reports: its own marked fields (not a nested
+// root's), still different from their default. As a header value: JSON with
+// every non-ASCII character escaped (fetch refuses a code point above 0xFF).
+function heldHeader(root) {
+  const names = []
+  for (const el of root.querySelectorAll(`[${HELD}]`)) {
+    if (el.closest(ROOT) !== root) continue
+    const name = el.getAttribute("name")
+    if (typedValue(el) === serverValue(el)) el.removeAttribute(HELD)
+    else if (name && !names.includes(name)) names.push(name)
+  }
+  if (names.length === 0) return null
+  return JSON.stringify(names).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`)
+}
+
+function releaseHeld(root) {
+  for (const el of root.querySelectorAll(`[${HELD}]`)) if (el.closest(ROOT) === root) el.removeAttribute(HELD)
+}
+
+// Hand a root's own reply to Turbo: while its streams render nothing in the
+// root is marked, and once they have the root holds nothing. Turbo announces
+// each stream synchronously inside renderStreamMessage (streamOwnReply wraps
+// its render, innermost); a reply none of whose streams rendered releases now.
+// An error reply (release false) never marks either, but releases nothing: the
+// server refused those values rather than answering them.
+function renderOwnReply(root, html, release = true) {
+  const own = { root, streams: 0, release }
+  const previous = replyRoot
+  replyRoot = own
+  try {
+    window.Turbo.renderStreamMessage(html)
+  } finally {
+    replyRoot = previous
+  }
+  if (release && own.streams === 0) releaseHeld(root)
+}
+
+function streamOwnReply(event) {
+  const own = replyRoot
+  const detail = event.detail
+  const render = detail?.render
+  if (!own || typeof render !== "function") return
+  own.streams++
+  detail.render = async (el) => {
+    replying.set(own.root, (replying.get(own.root) || 0) + 1)
+    try {
+      return await render(el)
+    } finally {
+      const left = replying.get(own.root) - 1
+      if (left) replying.set(own.root, left)
+      else replying.delete(own.root)
+      if (own.release) releaseHeld(own.root)
+    }
+  }
+}
+
 export function __resetReactiveMorphFocusForTest() {
   morphFocusRegistered = false
 }
@@ -693,6 +859,7 @@ export function registerReactiveActions() {
   registerReactiveStreamRender()
   registerReactiveMorphFocus()
   registerReactiveModals()
+  registerReactiveKeep()
   registerReactivePlaintext()
   registerReactiveOffline()
   registerReactiveDev()
@@ -767,7 +934,8 @@ if (typeof window !== "undefined" && typeof document !== "undefined") {
 // time; this guards a hand-built / forged ops attr from bypassing it. Refused:
 // event handlers (on*, XSS), URL-bearing names (a javascript: navigation
 // surface), and style (CSS injection). Case-insensitive, mirroring js.rb.
-const REFUSED_ATTR_URL = new Set(["href", "src", "srcdoc", "action", "formaction", "xlink:href", "style"])
+// srcset (issue #373) too: a URL list that picks what an <img> loads.
+const REFUSED_ATTR_URL = new Set(["href", "src", "srcset", "srcdoc", "action", "formaction", "xlink:href", "style"])
 function attrRefused(name) {
   const lower = String(name).toLowerCase()
   return lower.startsWith("on") || REFUSED_ATTR_URL.has(lower)
@@ -964,6 +1132,19 @@ const CLIENT_OPS = Object.freeze({
     if (el.textContent !== text) el.textContent = text
   },
 
+  // Copy a server-rendered image (issue #373): src, srcset and alt from the
+  // `from` <img>, resolved with the op's own scoping (the `submitter:`
+  // precedent). The URL is read off that element, never from an argument —
+  // the src refusal above stays. A selector that does not parse (a URL
+  // string) is a miss, like one that matches nothing.
+  copy_media: (el, args, resolveTargets) => {
+    let source = null
+    try {
+      source = resolveTargets({ ...args, to: args.from })[0] ?? null
+    } catch {}
+    copyMedia(el, source)
+  },
+
   // Tick or untick a whole checkbox group (issue #342) — "clear selection".
   // The bindings feature flips the root's OWNED boxes the way its select-all
   // header does (every box set, then input + change on each flipped one) and
@@ -1033,6 +1214,17 @@ const CLIENT_OPS = Object.freeze({
   // carries this op.
   paste_into: (el) => pasteClipboardInto(el),
 
+  // Preview a chosen file (issue #375): paint the input's first image file
+  // onto the `into` <img> through an object URL made HERE from the input's
+  // own File. The op carries no URL and `args.url` is never read, so the src
+  // refusal of set_attr (issue #96) stays whole. ACTOR-ONLY like paste_into
+  // (BROADCAST_REFUSED_OPS server-side).
+  preview_file: (el, args, resolveTargets) => previewFile(el, args, resolveTargets),
+
+  // A field's live value (issue #374): the paste_into write without the
+  // clipboard or the focus. ACTOR-ONLY (BROADCAST_REFUSED_OPS server-side).
+  set_value: (el, args) => setFieldValue(el, String(args.value ?? "")),
+
   // 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
@@ -1074,7 +1266,7 @@ function pasteClipboardInto(field) {
     .then((text) => {
       if (!text) return
       field.value = text
-      if (typeof field.dispatchEvent === "function") field.dispatchEvent(new Event("input", { bubbles: true }))
+      dispatchInput(field)
       field.focus?.()
     })
     .catch(() => {
@@ -1083,6 +1275,104 @@ function pasteClipboardInto(field) {
     })
 }
 
+// --- Preview a chosen file (issue #375) ---
+// img -> the object URL preview_file last made for it. The runtime owns it:
+// never an op argument, never an attribute a caller sets. An entry lives
+// while the img is on the page AND still shows that URL; a re-pick, a clear,
+// a non-image file, the img leaving the page or a morph that strips its src
+// in place revokes it. One MutationObserver notices the last two, and only
+// while some preview is live: it then wakes on every DOM mutation of the page
+// (a live feed, a drag), and each wake is a walk over the few live previews.
+const previews = new Map()
+let previewObserver = null
+
+function previewFile(input, args, resolveTargets) {
+  if (input?.tagName !== "INPUT" || input.type !== "file") {
+    return warnPreview(`reads an input[type=file], not <${input?.localName}>`)
+  }
+  const img = typeof resolveTargets === "function" ? resolveTargets({ ...args, to: args.into })[0] : null
+  // Duck-typed on tagName (the isDialog precedent): only an <img> ever gets a
+  // src here — never an iframe, a script, a frame or anything else.
+  if (img?.tagName !== "IMG") {
+    return warnPreview(`paints an <img>, and ${JSON.stringify(args.into)} is ${img ? `a <${img.localName}>` : "not on the page"}`)
+  }
+  const file = [...(input.files ?? [])].find((f) => typeof f?.type === "string" && f.type.startsWith("image/"))
+  forgetPreview(img)
+  if (file) {
+    const url = URL.createObjectURL(file)
+    previews.set(img, url)
+    img.setAttribute("src", url)
+    watchPreviews()
+  } else img.removeAttribute("src")
+  if (args.name == null) return
+  for (const node of resolveTargets({ ...args, to: args.name })) node.textContent = file ? file.name : ""
+}
+
+function warnPreview(why) {
+  console.warn(`[phlex-reactive] preview_file ${why} — skipped`)
+}
+
+// Revoke the URL preview_file made for `img`, if it made one.
+function forgetPreview(img) {
+  const url = previews.get(img)
+  if (url === undefined) return
+  previews.delete(img)
+  URL.revokeObjectURL(url)
+  if (previews.size === 0) {
+    previewObserver?.disconnect()
+    previewObserver = null
+  }
+}
+
+function watchPreviews() {
+  if (previewObserver || typeof MutationObserver !== "function" || !document?.documentElement) return
+  previewObserver = new MutationObserver(() => {
+    for (const [img, url] of previews) if (!img.isConnected || img.getAttribute("src") !== url) forgetPreview(img)
+  })
+  previewObserver.observe(document.documentElement, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["src"],
+  })
+}
+
+export function __resetReactivePreviewsForTest() {
+  previewObserver?.disconnect()
+  previewObserver = null
+  previews.clear()
+}
+
+// The set-value contract's dispatch (issue #183): a bubbling `input`, so
+// compute reducers, show bindings and on_complete run as if the user typed.
+function dispatchInput(field) {
+  if (typeof field.dispatchEvent === "function") field.dispatchEvent(new Event("input", { bubbles: true }))
+}
+
+// The body of the set_value op (issue #374). Writes the IDL .value — never the
+// attribute, never HTML — and dispatches `input` only when the field's value
+// actually moved (compared after the write: a textarea normalizes CRLF, a
+// select ends at "" for a value no option has). No `change`, no focus. Only an
+// input, textarea or select is a target, so a contenteditable (reactive_editable's
+// to write) warns and skips like any other node. A file input takes "" alone —
+// the browser throws on anything else.
+function setFieldValue(field, value) {
+  if (!/^(input|textarea|select)$/.test(field.localName) || (field.type === "file" && value !== "")) {
+    console.warn("[phlex-reactive] set_value skipped: not a field it can write", field)
+    return
+  }
+  const before = fieldState(field)
+  field.value = value
+  if (fieldState(field) !== before) dispatchInput(field)
+}
+
+// What set_value compares: .value, or for a <select multiple> its whole
+// selection — assigning .value deselects every other option, which .value
+// (the first selected) alone would not show.
+function fieldState(field) {
+  return field.type === "select-multiple" ? [...field.selectedOptions].map((o) => o.value).join("\n") : field.value
+}
+
 // Apply a hidden-flag change, optionally animated by a [during, from, to]
 // transition (issue #96). Split out so show/hide/toggle share it.
 function setHidden(el, hidden, args) {
@@ -1110,6 +1400,31 @@ function guardAttr(name) {
   return false
 }
 
+// Copy src, srcset and alt from one <img> onto another (issue #373) — the
+// copy_media op and the reactive_media binding (the bindings feature reaches it
+// through the core handle). Only an <img> target is written, so an iframe,
+// script, object, embed or frame never receives a src from here. A source that
+// is missing, not an <img> or has no src clears the target. Each attribute is
+// written only when it changes, so the same URL twice does not reload. Returns
+// the alt copied, false when it cleared, or null when the target was skipped.
+function copyMedia(target, source) {
+  if (target?.localName !== "img") {
+    console.warn(`[phlex-reactive] copy_media targets an <img>, not <${target?.localName}> — skipped`)
+    return null
+  }
+  const src = source?.localName === "img" ? source.getAttribute("src") : null
+  const pick = (name) => (src ? source.getAttribute(name) : null)
+  for (const name of ["srcset", "src"]) {
+    const value = pick(name)
+    if (value == null) {
+      if (target.hasAttribute(name)) target.removeAttribute(name)
+    } else if (target.getAttribute(name) !== value) target.setAttribute(name, value)
+  }
+  const alt = pick("alt") ?? ""
+  if (target.getAttribute("alt") !== alt) target.setAttribute("alt", alt)
+  return src ? alt : false
+}
+
 // The first focusable descendant of `el`, in document order — the natural
 // keyboard target inside an opened menu/dialog. Covers the standard focusable
 // set; :not([tabindex="-1"]) drops explicitly-removed nodes. Returns null when
@@ -1352,7 +1667,10 @@ function applyOps(list, resolveTargets, onZeroTargets) {
     }
     const targets = resolveTargets(args)
     if (targets.length === 0 && onZeroTargets) onZeroTargets(name, args)
-    for (const el of targets) CLIENT_OPS[name](el, args, resolveTargets)
+    for (const el of targets) {
+      CLIENT_OPS[name](el, args, resolveTargets)
+      if (args?.keep === true) keepResult(el, name, args, resolveTargets)
+    }
   }
 }
 
@@ -1497,8 +1815,8 @@ function formNeeded(root) {
 // Show bindings and cross-root show targets, completion bindings, option
 // filtering, the bulk-selection group bindings (enable, select-all, count —
 // issue #319) and their cross-root targets (#343), the tag-chip input, draft
-// nested rows and editable text's keys and paste (#351): a form's client-only
-// bindings. The root declares one, or
+// nested rows, editable text's keys and paste (#351) and media previews
+// (#373): a form's client-only bindings. The root declares one, or
 // owns an element that does. (The probes the connect-time gates ran before
 // the split, unchanged.)
 function bindingsNeeded(root) {
@@ -1508,7 +1826,7 @@ function bindingsNeeded(root) {
     ) ||
     (root.querySelectorAll?.("[data-reactive-show-field], [data-reactive-show]") ?? []).length > 0 ||
     root.querySelector?.(
-      "[data-reactive-nested-json], [data-reactive-nested-list], [data-reactive-confirm-when-param], [data-reactive-enable], [data-reactive-select-all], [data-reactive-count], [data-reactive-editable]",
+      "[data-reactive-nested-json], [data-reactive-nested-list], [data-reactive-confirm-when-param], [data-reactive-enable], [data-reactive-select-all], [data-reactive-count], [data-reactive-editable], [data-reactive-media]",
     ) != null
   )
 }
@@ -2342,6 +2660,8 @@ export default class extends Controller {
       plain: plaintextSupported,
       text: editableValue,
       served: serverText,
+      // Copy one <img> onto another (issue #373): the reactive_media binding.
+      copyMedia,
       // 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) =>
@@ -3340,6 +3660,9 @@ export default class extends Controller {
           presenceNeeded(this.element) &&
           document.getElementById(`reactive-presence-src-${this.element.id}`)?.getAttribute("connection-id")
         if (presence) headers["X-Reactive-Presence"] = presence
+        // The fields a morph held over a changed server value (issue #370).
+        const held = heldHeader(this.element)
+        if (held) headers["X-Reactive-Held"] = held
 
         // ONLY `fetch` itself is the network boundary — offline, DNS, a reset
         // connection. Everything below this inner try (reading the body,
@@ -3421,7 +3744,7 @@ export default class extends Controller {
             if (__SPLIT__) this.#devtools((devtools) => devtools.recordBody(debug, errorBody, fresh))
             else devtoolsFeature.recordBody(debug, errorBody, fresh)
           }
-          window.Turbo.renderStreamMessage(errorBody)
+          renderOwnReply(this.element, errorBody, false)
         }
         this.#markError("http")
         this.#emitError(action, params, allParams, { kind: "http", status: response.status, body: errorBody })
@@ -3452,8 +3775,9 @@ export default class extends Controller {
       // Turbo applies the <turbo-stream> ops by id. A plain replace is an
       // outerHTML swap (focus on the replaced subtree is lost); a method="morph"
       // replace (Response.morph) or an update morphs in place, preserving the
-      // focused input + caret on unchanged nodes — see issue #28.
-      window.Turbo.renderStreamMessage(html)
+      // focused input + caret on unchanged nodes — see issue #28. As the root's
+      // own reply, it clears what the root held (issue #370).
+      renderOwnReply(this.element, 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.

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

@@ -15,6 +15,7 @@ module Phlex
         include Selection
         include Sortable
         include Editable
+        include MediaBinding
 
         # The acting client's SSE connection id during the current action (nil
         # outside an action, or when the client isn't subscribed to a stream).
@@ -31,6 +32,20 @@ module Phlex
           Phlex::Reactive.current_connection_id
         end
 
+        # The names of this action's posted fields that a morph held over a
+        # changed server value (issue #370): someone else changed the field
+        # while this user typed, and this tab kept the user's text. [] when
+        # nothing was held, and outside an action. Filtered to the action's
+        # declared params; a hint about what the user saw, never authorization.
+        #
+        #   def save(title: nil)
+        #     return conflict!(title) if reactive_held_fields.include?("title") && title != @note.title
+        #     @note.update!(title:)
+        #   end
+        def reactive_held_fields
+          Phlex::Reactive::HeldFields.current
+        end
+
         # Manually satisfy the verify_authorized guard (issue #168) for a bespoke
         # authorization check the interceptor can't see — a hand-rolled policy, a
         # feature flag, an ownership comparison that doesn't go through one of

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # A preview image that follows a field (issue #373), with no URL in the
+      # page's ops or attributes: the server renders every candidate <img>
+      # (hidden), and the binding copies the one whose key matches.
+      #
+      #   input(name: "code")
+      #   img(id: "logo", alt: "", **reactive_media(
+      #     from: :code, take: 3,
+      #     pool: { "007" => "#logo-007", "011" => "#logo-011" },
+      #     label: "#caption", blank_label: "Unknown"
+      #   ))
+      #   img(id: "logo-007", src: "/logos/007.svg", alt: "North", hidden: true)
+      #
+      # The field is read the way reactive_show reads one (owned fields, a
+      # radio group's checked value, reactive_scope applied). `take:` keeps the
+      # first n characters as the key; omit it to use the whole value. A pool
+      # value is a CSS SELECTOR for an <img> inside the root, never a URL: the
+      # client copies that element's src, srcset and alt the way
+      # js.copy_media does. A key, selector or element that misses clears the
+      # preview. `label:` names a node whose textContent becomes the chosen
+      # image's alt (`blank_label`, or "", on a miss). Client-only: no token,
+      # no round trip.
+      #
+      # Named MediaBinding, not Media: this module sits in every reactive
+      # component's ancestry, and a bare `Media` would shadow a host app's kit
+      # component of that name (issue #233).
+      module MediaBinding
+        def reactive_media(from:, pool: nil, take: nil, label: nil, blank_label: nil, **attrs)
+          wire = { "field" => media_field!(from) }
+          wire["take"] = media_take!(take) unless take.nil?
+          wire["pool"] = media_pool!(pool)
+          wire["label"] = media_selector!(:label, label) unless label.nil?
+          wire["blank"] = blank_label.to_s unless blank_label.nil?
+          mix({ data: { reactive_media: wire.to_json } }, attrs)
+        end
+
+        private
+
+        def media_field!(from)
+          name = from.to_s if from.is_a?(Symbol) || from.is_a?(String)
+          return name unless name.nil? || name.strip.empty?
+
+          raise ArgumentError, "reactive_media from: needs the field name to watch (e.g. from: :code), got #{from.inspect}"
+        end
+
+        def media_take!(take)
+          return take if take.is_a?(Integer) && take.positive?
+
+          raise ArgumentError, "reactive_media take: must be a positive Integer (or omitted for the whole value), " \
+                               "got #{take.inspect}"
+        end
+
+        def media_pool!(pool)
+          if pool.nil?
+            raise ArgumentError, "reactive_media needs pool: — a Hash of key => selector of a server-rendered <img> " \
+                                 "(e.g. pool: { \"007\" => \"#logo-007\" })"
+          end
+          unless pool.is_a?(Hash) && !pool.empty?
+            raise ArgumentError,
+              "reactive_media pool: must be a non-empty Hash of key => <img> selector, got #{pool.inspect}"
+          end
+
+          pool.to_h { |key, selector| [key.to_s, media_selector!(:pool, selector)] }
+        end
+
+        # A pool value or label: is a selector, never a URL — the client only
+        # ever passes it to querySelector.
+        def media_selector!(kind, selector)
+          if selector == JS::ROOT_SENTINEL
+            raise ArgumentError,
+              "reactive_media #{kind}: #{selector} names the whole root — pass the selector of an element inside it"
+          end
+          return selector if selector.is_a?(String) && !selector.strip.empty?
+
+          raise ArgumentError,
+            "reactive_media #{kind}: values are CSS selectors (e.g. \"#logo-007\"), got #{selector.inspect}"
+        end
+      end
+    end
+  end
+end