phlex-reactive 0.15.1 → 0.15.3

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,197 @@ 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
+}
+
+// --- An image fallback that recovers (issue #383) ---------------------------
+// data-reactive-image-fallback='{"hide":true,"alt":"#name"}' on an <img>. On
+// `error` it gets data-reactive-image-state="error" (plus `hidden` with hide,
+// and its alt shown in the `alt` node of its own reactive root); on `load`,
+// "loaded". A later src clears the error: copy_media and preview_file reset
+// it as they write (resetImage), any src that loads clears it on `load`, and
+// a morph that changes the src lets the browser try again. A morph that keeps
+// the src puts the state back. An error with no src is not an error (a
+// removed or emptied src). One document listener, capture phase (neither
+// event bubbles); nothing per root at connect.
+const IMAGE_FALLBACK = "data-reactive-image-fallback"
+const IMAGE_STATE = "data-reactive-image-state"
+// Marks the `hidden` the fallback set, so a reset removes only that one. On
+// the element, not in a WeakSet: a Turbo snapshot restores a NEW node.
+const IMAGE_HIDDEN = "data-reactive-image-hidden"
+let imageFallbackListeners = null
+
+function imageFallback(img) {
+  if (img?.localName !== "img") return null
+  const raw = img.getAttribute(IMAGE_FALLBACK)
+  if (raw == null) return null
+  try {
+    return JSON.parse(raw) || {}
+  } catch {
+    return {}
+  }
+}
+
+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
+  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
+  } catch {
+    return null
+  }
+}
+
+function setImageState(img, wire, value) {
+  if (value === "error") {
+    if (wire.hide && !img.hasAttribute("hidden")) {
+      img.setAttribute("hidden", "")
+      img.setAttribute(IMAGE_HIDDEN, "")
+    }
+    const node = imageAltNode(img, wire)
+    if (node) {
+      node.textContent = img.getAttribute("alt") ?? ""
+      node.hidden = false
+    }
+  } else resetImage(img, wire)
+  img.setAttribute(IMAGE_STATE, value)
+}
+
+// Undo what an error did — only what it did: `hidden` stays when the author
+// set it. Called by copy_media and preview_file when they change the src.
+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 node = imageAltNode(img, wire)
+    if (node) node.hidden = true
+  }
+  img.removeAttribute(IMAGE_STATE)
+  img.removeAttribute(IMAGE_HIDDEN)
+}
+
+function onImageEvent(event) {
+  const img = event.target
+  const wire = imageFallback(img)
+  if (!wire) return
+  if (event.type === "load") setImageState(img, wire, "loaded")
+  else if (hasImageSrc(img)) setImageState(img, wire, "error")
+  else resetImage(img, wire)
+}
+
+export function registerReactiveImageFallback() {
+  if (imageFallbackListeners) return
+  if (typeof document === "undefined" || typeof document.addEventListener !== "function") return
+  // A morph that keeps the src keeps the state: the render carries none, and
+  // the browser loads nothing new to tell us again. Put it back once the
+  // whole morph is done, so a later-morphed alt node is shown again too.
+  const kept = new WeakMap()
+  imageFallbackListeners = {
+    error: onImageEvent,
+    load: onImageEvent,
+    "turbo:before-morph-element": (event) => {
+      const img = event.target
+      const next = event.detail?.newElement
+      const value = img?.getAttribute?.(IMAGE_STATE)
+      if (value == null || !next || !imageFallback(img)) return
+      const same = (name) => img.getAttribute(name) === next.getAttribute?.(name)
+      if (same("src") && same("srcset")) kept.set(img, value)
+    },
+    "turbo:morph-element": (event) => {
+      const img = event.target
+      const value = kept.get(img)
+      if (value === undefined) return
+      kept.delete(img)
+      queueMicrotask(() => {
+        const wire = imageFallback(img)
+        if (wire) setImageState(img, wire, value)
+      })
+    },
+  }
+  for (const [name, fn] of Object.entries(imageFallbackListeners)) document.addEventListener(name, fn, true)
+  // An image that finished before this ran (a cached 404) fired its event
+  // unheard: read it off the element once. naturalWidth 0 is also a loaded
+  // SVG with only a viewBox, so decode() decides (it rejects a broken image).
+  for (const img of document.querySelectorAll?.(`img[${IMAGE_FALLBACK}]`) ?? []) {
+    if (!img.complete || !hasImageSrc(img)) continue
+    // A decode() that settles after the src changed decoded the OLD one: ignore it.
+    const was = `${img.getAttribute("src")} ${img.getAttribute("srcset")}`
+    const mark = (value) => `${img.getAttribute("src")} ${img.getAttribute("srcset")}` === was && setImageState(img, imageFallback(img) ?? {}, value)
+    if (img.naturalWidth > 0) mark("loaded")
+    else if (typeof img.decode === "function") img.decode().then(() => mark("loaded"), () => mark("error"))
+    else mark("error")
+  }
+}
+
+export function __resetReactiveImageFallbackForTest() {
+  for (const [name, fn] of Object.entries(imageFallbackListeners ?? {})) document.removeEventListener(name, fn, true)
+  imageFallbackListeners = null
+}
+
 // 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 +662,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,8 +685,108 @@ 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() {
@@ -693,6 +988,8 @@ export function registerReactiveActions() {
   registerReactiveStreamRender()
   registerReactiveMorphFocus()
   registerReactiveModals()
+  registerReactiveKeep()
+  registerReactiveImageFallback()
   registerReactivePlaintext()
   registerReactiveOffline()
   registerReactiveDev()
@@ -767,7 +1064,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 +1262,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 +1344,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 +1396,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 +1405,109 @@ 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"}`)
+  }
+  // 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/"))
+  forgetPreview(img)
+  if (file) {
+    const url = URL.createObjectURL(file)
+    previews.set(img, url)
+    img.setAttribute("src", url)
+    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 : ""
+}
+
+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 +1535,35 @@ 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 or not an <img> clears the target. An <img> source without src is
+// a hit with no image (issue #381): the target loses src and srcset but takes
+// the alt, so a known entry without a logo keeps its name. 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 img = source?.localName === "img" ? source : null
+  const src = img?.getAttribute("src")
+  let changed = false
+  for (const name of ["srcset", "src"]) {
+    const value = src ? img.getAttribute(name) : null
+    if (value == null) {
+      if (target.hasAttribute(name)) changed = target.removeAttribute(name) ?? true
+    } else if (target.getAttribute(name) !== value) changed = target.setAttribute(name, value) ?? true
+  }
+  if (changed) resetImage(target)
+  const alt = img?.getAttribute("alt") ?? ""
+  if (target.getAttribute("alt") !== alt) target.setAttribute("alt", alt)
+  return img ? 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 +1806,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 +1954,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 +1965,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 +2799,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 +3799,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 +3883,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 +3914,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,8 @@ module Phlex
         include Selection
         include Sortable
         include Editable
+        include MediaBinding
+        include ImageFallbackBinding
 
         # 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 +33,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
@@ -1751,13 +1767,16 @@ module Phlex
 
         private_constant :REMOVED_ON_KWARGS, :PENDING_CLASS_OPS
 
+        # Runs on every on() (a hot path): a key lookup per removed name, no arrays.
         def reject_removed_on_kwargs!(action_name, params)
-          removed = params.keys & REMOVED_ON_KWARGS.keys
-          return if removed.empty?
+          return if params.empty?
 
-          key = removed.first
-          raise ArgumentError,
-            "on(#{action_name.inspect}) #{key}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[key]}"
+          REMOVED_ON_KWARGS.each_key do
+            next unless params.key?(it)
+
+            raise ArgumentError,
+              "on(#{action_name.inspect}) #{it}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[it]}"
+          end
         end
 
         # Issue #357: parse on()'s shortcut: (nil when absent). A shortcut