phlex-reactive 0.12.5 → 0.12.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec14089cc43f0bf439305f48b9fca3ee8b0fe2ba83b44b341e22370ad11fc22d
-  data.tar.gz: 101ae52fce38a343185a2699082c79709dadf609d9401f199b9b9c5f181dda9c
+  metadata.gz: 7a9ece1128621af6ad4b9b8e249c1005bcfd063e0aa70235800292f156ac4419
+  data.tar.gz: f8613e2ec77fb55d1f9b5b0b30719382ef5e52c2a34d1ff6bcc29f9a017bafc7
 SHA512:
-  metadata.gz: '083b640658e403acc1bfeb311d0c22051cd3a2b275a4f44084dfb9c52755fab481eb63c7458e593eb43741d6b3726b8c8e7dadeb2059bcd9b9818cae64768937'
-  data.tar.gz: 3984b48e58eb838ed9bfb009d50444babd518831eb5d2fc7c0f77dc577060b146729f428e7bf1acead2281dd86547fc86130c43ba245b6a4956acf0d5e39d04f
+  metadata.gz: 19130860688333ec585f3da94ff25be2f8fc8c3fd103c023c98d4ac528921d7b02a7362448b864f81b435d35fc8946e0a3be7ba41f70f57751b115ed09b9a394
+  data.tar.gz: a6efc22b0270eb3e1f4cc7732cc1394acd40dd80de81b12a1dd792df9d2e3952bf5070872e21884cdcc9a5c91211791e74fc31e81f2f25cc1116587446a636c3

data/CHANGELOG.md

@@ -8,6 +8,24 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **`reactive_persist` — client-only localStorage drafts (#239).** "Don't make
+  me start over": spread `reactive_persist(key:, ttl: 7.days)` on a root and
+  the generic controller keeps a `localStorage` draft of every **owned**
+  control — a debounced write on `input`, immediate on `change`, flushed on
+  disconnect — and restores it on the next connect, **first** among the
+  client bindings so `reactive_show` / `reactive_on_complete` (armed, never
+  fired) / `reactive_filter` / a compute root read the restored values on
+  first paint with no synthetic events. A draft lands only in controls the
+  server rendered blank (`restore: :always` lets it win); a morph is never
+  re-restored. Cleared by a successful `turbo:submit-end` of the containing
+  form, `ttl` expiry, or the new actor-only `js.persist_clear` op;
+  `js.persist_state(step: 2)` merges a flat state bag into the draft (restored
+  as `data-reactive-persist-state` + the `reactive:persist-restored` event).
+  `hidden`/`file`/`password`/`submit` controls, `reactive_persist_skip`
+  markers, nested roots and rich-text editors are never persisted; `fields:`
+  narrows the set. Storage failures are silent (a `console.info` under
+  `Phlex::Reactive.debug`). Works from `ClientBindings` (no token, no POST).
+
 - **Dev-mode warning when a client op resolves zero targets (#237).** A client
   op that matches nothing is indistinguishable from a working no-op, and the
   three documented scoping traps — the nested-root ownership filter, a selector

data/README.md

@@ -385,11 +385,13 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `busy_on(:save)` | Mark any element so it carries `data-reactive-busy` **only while `save` is in flight** — a spinner styled with pure CSS, zero Ruby. See [Loading states](#declarative-loading-states-loading--disable_with). |
 | `on(:action, once: true)` | Fire at most once, then unbind (Stimulus's native `:once`). |
 | `on_client(:click, js.toggle("#menu"))` | **Client-only** trigger: applies declared DOM ops with ZERO round trip — no token, no POST, ever. Takes the same `window:`/`once:`/`outside:` modifiers. See [Client-only ops](#client-only-ops-on_client--js--zero-round-trips). |
-| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form), and `paste_into` (read the clipboard into a field, gesture-gated) — chainable. |
+| `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form), `paste_into` (read the clipboard into a field, gesture-gated), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. |
 | `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
 | `reactive_show_targets(:field, "#id" => value)` | **Cross-root visibility**: the component that owns the field declares which **outside**, id-allowlisted elements it governs (a nav tab, a panel in another pane) — the visibility parallel of `mirror:`. Spread on the **root** via `mix(reactive_root, …)`, **once per root** — several fields go in one call via the hash form. The value uses the same `where`-style vocabulary (`"advanced"`, `%w[a b]`, `10..`); a `"#id"` **key** takes a full conditions Hash for a **multi-field** predicate (`"#warn" => { if: { type: "trade", price: ..0 } }`). Id selectors only (raise at render + client warn-skip); toggles `hidden` only. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
+| `reactive_persist(key:, ttl: 7.days)` | **Client-only drafts**: spread on the **root** (once) and the generic controller keeps a `localStorage` draft of every **owned** control — debounced write on `input`, immediate on `change`, flushed on disconnect, restored into **blank** controls on the next connect (`restore: :always` lets the draft win), cleared by a successful Turbo submit / `ttl` / `js.persist_clear`. Never hidden/file/password; `reactive_persist_skip` opts a control out; `fields:` narrows. See [Client-only drafts](#client-only-drafts-reactive_persist). |
+| `js.persist_state(step: 2)` / `js.persist_clear` | The draft ops (actor-only): merge a flat state bag into the draft (restored as `data-reactive-persist-state` + the `reactive:persist-restored` event) / forget the draft. |
 | `reactive_filter(:field, option: nil, group: nil, empty: nil)` | **Client-side option filtering** for a preloaded combobox: spread onto the root and name the **field** that drives it — `reactive_filter(:q)` compiles `:q` to `[name="q"]` (scope-aware) and typing shows/hides the options by their `data-reactive-filter-text` haystack, **zero round trips**. `option:` defaults to `[role=option]`; optional `group:` collapses an all-hidden group header; `empty:` reveals a no-matches node. `input:` is the escape hatch — a raw CSS selector for a **name-less** driving input (`input: "#tags_query"`), the form-builder case. See [Client-side option filtering](#client-side-option-filtering-reactive_filter). |
 | `reactive_listnav("[role=option]")` | The **standalone** combobox keyboard wiring (Arrow/Enter/Escape) for an input that fires **no action** — the preload-and-filter case. Same behavior as `on(…, listnav:)`, minus the POST. |
 | `reactive_tags(:tags)` | **Tag-chip input** (the combobox/tags widget): spread onto the root and name the hidden field that stores the **comma-joined** value — the client maintains that field + the chip list entirely client-side (form state, zero round trips), rebuilding chips from your server-owned `<template>`. Composes with `reactive_filter` (type to narrow) and `reactive_listnav` (Enter picks the highlighted option). `name:` is the escape hatch — a **verbatim** wire name (`name: "user[tags]"`, never re-scoped), the form-builder case. See [Tag-chip input](#tag-chip-input-reactive_tags). |
@@ -1103,6 +1105,82 @@ field; a missing owned field reads as blank — fail-closed). Every referenced
 field must be owned by the declaring root; a target whose fields are all
 unowned is left alone, like the single-field skip.
 
+### Client-only drafts (`reactive_persist`)
+
+"Don't make me start over": a public application form, a multi-step wizard,
+a long comment box — the user types, navigates away, comes back, and expects
+their draft. Nothing the server needs until submit, no signed-in user to
+autosave for. `reactive_persist` (#239) is the `reactive_show`-shaped answer:
+a **declared, client-only** binding over the fields the root **owns**, no
+token, no POST, no expression surface — the generic controller keeps a
+`localStorage` draft and every hand-rolled "local save" Stimulus controller
+goes away.
+
+```ruby
+class ApplicationForm < ApplicationComponent
+  include Phlex::Reactive::ClientBindings     # or the full Component
+  reactive_scope :apply
+
+  def view_template
+    form(action: "/applications", method: "post") do
+      div(**mix(reactive_root(id: "apply"), reactive_persist(key: "village-apply", ttl: 7.days))) do
+        input(**reactive_field(:name))                              # persisted
+        textarea(**reactive_field(:bio))                            # persisted
+        input(name: "fuckery", **reactive_persist_skip)             # honeypot — never
+        input(type: "hidden", name: "apply[tz]")                    # hidden — never (default)
+        button(**on_client(:click, js.persist_state(step: 2))) { "Next" }
+        button(**on_client(:click, js.persist_clear)) { "Discard draft" }
+        button(type: "submit") { "Apply" }
+      end
+    end
+  end
+end
+```
+
+Spread it on the **root** (`mix` with `reactive_root`), **once per root**. One
+wire attr: `data-reactive-persist='{"key":"village-apply","ttl":604800,"debounce":300}'`.
+
+- **Write** — on `input` (trailing-edge debounce, `debounce:` ms, default 300)
+  and immediately on `change`; a pending write is **flushed on disconnect**, so
+  a fast Turbo navigation never loses the last keystrokes. The snapshot is a
+  full pass over the owned controls: radios store the checked value, checkboxes
+  the checked state, `<select multiple>` an array, everything else `.value`.
+- **Restore** — on connect, **first** among the client bindings, so a
+  `reactive_show` section, `reactive_on_complete` (armed, never fired),
+  `reactive_filter` and a `reactive_compute` root all read the restored values
+  on first paint — no synthetic events. A morph or broadcast re-render is
+  server truth and is **never** re-restored.
+- **`restore: :blank`** (default) — a draft value lands only in a control the
+  server rendered **blank**, so a 422 re-render's submitted values beat an
+  older draft. `restore: :always` lets the draft win.
+- **Clear** — a successful `turbo:submit-end` of the form that contains the
+  root, `ttl` expiry (checked on read; default `7.days`), or `js.persist_clear`.
+  A successful *reactive* action does **not** clear on its own — chain
+  `reply.js(js.persist_clear)` from the action when it should.
+- **`fields:`** narrows the set to declared names (scope-aware symbols):
+  `reactive_persist(key: "k", fields: %i[name bio])`.
+- **Never persisted**: `type=hidden/file/password/submit/button/reset/image`,
+  anything carrying `reactive_persist_skip`, a nested reactive root's controls,
+  and rich-text/`contenteditable` editors (they aren't `input/select/textarea`).
+  `autocomplete="off"` is **not** an implicit skip — a wizard often sets it
+  form-wide. **Honeypots must opt out** (`reactive_persist_skip`) or sit outside
+  the root: an invisible-captcha text input looks like any other field.
+- **State bag** — `js.persist_state(step: 2)` merges a flat hash of scalars
+  into the same draft (a wizard's current step). On restore the root carries
+  `data-reactive-persist-state='{"step":2}'` and dispatches a bubbling
+  `reactive:persist-restored` event (`detail: { key, fields, state }`) — the
+  hook for your own wizard controller to jump to the saved step.
+- **Storage failures are silent** — a private window, a quota error or blocked
+  storage degrades to "no draft". Under `Phlex::Reactive.debug` the controller
+  prints one `console.info` naming the failure so a dev sees why nothing came
+  back.
+
+Threat model: values are replayed via `.value`/`.checked` only (never HTML) — a
+tampered draft can only fill what the user could type. PII sits in this
+browser's `localStorage` for `ttl`; the submit-clear and `ttl` are the
+shared-computer mitigation. `persist_state`/`persist_clear` are **actor-only**
+ops (refused by `broadcast_to(js:)`). See the [security page](docs/security.md).
+
 ### Client-side computes (`reactive_compute` + `reactive_text`)
 
 Some math should feel instant with **no round trip** — a NEW, unsaved record's

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

@@ -1055,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
@@ -1131,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
@@ -1675,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).
@@ -1716,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)
@@ -1895,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()
@@ -3978,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)