phlex-reactive 0.16.0 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b96289b4a91d050b1631c5c31663714e3aba33370f1a4e8d87d04c662fa3ed81
-  data.tar.gz: 55c7126c343c696e66f4baf5d4c62d09a2e8fa8861c1bbe04b9b5f67c265c42c
+  metadata.gz: 860b397593c4d0a2d05d2485345bfc78564e784942c8413db1b67fbbacea6b41
+  data.tar.gz: '059b1148284859d6a69afdd4f62693f4dbedb0eab41370af843e30a4f3d27e4f'
 SHA512:
-  metadata.gz: c4298ac14bf00c485324d9b61ae72fb812e0c87f1afd66cc09a24c2f0dd0917b7bf40458dd37223ba79650b4cf8a3bd44745cb7bf66d74f27f19021a3969b1a5
-  data.tar.gz: a652652cfd5a2c7439c846afb421c8d99ff3cf902276da910e05228c7313cf9c3662c8c5391cfaab1316ec4399115d96cd5441fa9d4a8dbee74e032831d419d5
+  metadata.gz: 0500ccbf1d82ea1039cf078dbe62e67efd6da9c9a2ecbeaace46d7d316f4a6c62ef479ea8b1a81e263ad1f738c25d9aa64f0dc53fc7af7a1bbadd6dab49e5021
+  data.tar.gz: eae4009ae39fba74bc6219c4b90df31589bed31ed70a457c7f240075ffd50b84662a39af475d878bc339d2e538611e248a287e11a5bbdacd52cb47d1bf73d45e

data/CHANGELOG.md

@@ -6,7 +6,67 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-## [0.16.0]
+### Added
+
+- **Draggable regions: move and resize a box, or move a point, inside a
+  frame, with the result in fields (#416).** `reactive_frame` marks the
+  coordinate space, `reactive_box(fields:, value:, aspect:, min:, action:,
+  busy:, messages:)` a box in it, `reactive_box_handle(edge)` an edge or corner
+  to resize from, and `reactive_point(fields:, value:, within:, …)` a point,
+  inside the frame or inside a box. The helpers render the position as
+  percentages from `value:`, so the first paint needs no JavaScript and a
+  re-render with new values moves the box. The box moves and resizes with a
+  mouse, a pen, a finger or the keyboard (arrows 1%, Shift 10%, Alt resizes,
+  Escape puts it back, each step announced in the words of `messages:`). It
+  stays inside the frame and never goes below `min:`. `aspect:` locks the
+  ratio (a Numeric, or a field such as a row of preset radios, which re-fits
+  the box when it changes). The fields hold fractions rounded to 4 decimals,
+  with `input` as the box moves (at most once per field a frame) and one
+  `change` on release. `action:` is sent once per release through the root's
+  pipeline, with `x`, `y`, `width`, `height`. Without it the binding is
+  client-only and works on a `ClientBindings` root. A morph that lands
+  mid-drag does not interrupt it. The helpers check their arguments' keys,
+  types and ranges at render (an undeclared action under `verbose_errors`).
+  Client: a new `drag` feature module (3,576 B gzipped): +2,789 B in the
+  default bundle, +51 B in the split core, which loads it only on a page with
+  a frame, a box or a point. Docs: a "Draggable regions" guide with a live demo.
+
+- **Fields that feed CSS custom properties: `reactive_css_vars` (#417).** A
+  preview that follows a control (a slider that brightens an image, a select
+  that rotates it) needed app JavaScript or a request per input event.
+  `reactive_css_vars(to: "#sample", vars: { "--light" => "light",
+  "--turn" => { field: "turn", unit: "deg" } })` reads each field as
+  `reactive_show` does (a checkbox gives `1` or `0`, a radio group its checked
+  value), parses it as a finite number and writes `number + unit` on every
+  `to:` element with `style.setProperty`, on connect, on `input`/`change` and
+  after a morph, with no request. Anything that is not a number removes the
+  property, so the `var()` fallback applies: no text from a field reaches CSS.
+  Units come from a fixed list (`""`, `px`, `%`, `deg`, `turn`, `ms`, `s`,
+  `em`, `rem`, `fr`) and names match `--[a-zA-Z0-9-]+`, checked at render and in
+  the browser. `to:` resolves like a client op's (`:root`, inside the root,
+  `global: true`, an Array). It goes on the root or on any element inside it,
+  and works on a `ClientBindings` view. Client: +460 B gzipped in the default
+  bundle; +462 B in `features/bindings` and +16 B in the split core.
+  Docs: "Live CSS properties" on the client-ops page, with a demo.
+
+### Fixed
+
+- **A reply that refuses the posted values keeps the held marks (#413).**
+  Every reply to a root's own request released the fields a morph held
+  (#370), so after an action refused a save the user's next keystroke posted
+  no held names and went through over the other change. Return
+  `reply.morph.refused` (every mark) or `reply.morph.refused("title")` (only
+  those fields) and the client keeps the marks: the root's next action names
+  them in `reactive_held_fields` again, until the action stores the field or
+  the user takes the other value. The endpoint sends it as the
+  `X-Reactive-Refused` response header; the reply stays a 200, with no error
+  marker and no `reactive:error`. `run_reactive(…).refused?` and
+  `response.refused?` / `response.refused_fields` assert it in a unit test.
+  Client: +65 B gzipped in the default bundle, +60 B in the split core.
+  Docs: "Knowing what was held" on the architecture page, the `reply` table
+  in the README.
+
+## [0.16.0] - 2026-10-16
 
 ### Upgrading from 0.15.x
 
@@ -103,8 +163,25 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.15.5] - 2026-10-15
 
-Consolidates everything since 0.14.1; tags 0.14.2–0.15.4 shipped without
-changelog sections, so this section spans the whole run to 0.15.5.
+### Fixed
+
+- **A server trigger inside a client-only root reaches the component around it
+  (#410).** A `ClientBindings` component (a `reactive_filter` list, a
+  `reactive_show` wrapper, an `on_client` menu) renders a root with no token.
+  Rendered inside a server component, it swallowed that component's `on(...)`
+  triggers: Stimulus sends the action to the nearest root, which had no token,
+  and the outer root's field collection skipped every control under it (the
+  #15 rule). A tokenless client-only root is now transparent to server round
+  trips: `dispatch` forwards to the nearest token-bearing root above (skipping
+  further client-only roots, waking a dormant one), and that root's action
+  collects the controls under nested client-only roots. A nested server
+  component keeps its own fields and triggers, and client bindings stay on
+  their own root. With no token-bearing root above, nothing is sent, and
+  `verbose_errors`/debug logs one warning. Lazy and deferred shells are not
+  client-only. Client: +414 B gzipped in the default bundle, +415 B in the
+  split core.
+
+## [0.15.4] - 2026-10-14
 
 ### Added
 
@@ -276,6 +353,10 @@ changelog sections, so this section spans the whole run to 0.15.5.
   anything else raises at render. Client: +27 B gzipped in the default
   bundle, +20 B in the persist module; the split core unchanged.
 
+## [0.15.3] - 2026-10-13
+
+### Added
+
 - **An image fallback that recovers — `reactive_image_fallback(hide: true, show_alt: nil)` (#383).**
   `img(**reactive_image_fallback)` marks an `<img>` whose `src` fails with
   `data-reactive-image-state="error"` and hides it; `show_alt: "#bank-name"`
@@ -296,6 +377,91 @@ changelog sections, so this section spans the whole run to 0.15.5.
   +550 B in the split core. Docs: "An image that falls back, and recovers" on
   the client-ops example.
 
+### Fixed
+
+- **`reactive_media` waits for `take` characters before calling a key a miss
+  (#380).** A value shorter than `take:` sliced to a short key, missed the
+  pool and wrote `blank_label` while the user was still typing. It is now
+  *pending*: `blank_label` only names a full-length key that misses. New
+  options: `match:` (a Regexp, anchored to the whole key; a key it rejects is
+  pending too) and `pending: :clear` (default: clear the preview, empty the
+  label) or `:keep` (leave both alone). The preview carries
+  `data-reactive-media-state="pending|hit|miss"`, so a row can hide itself
+  with CSS. `match:` reaches the browser as a JS pattern: its `\A`/`\z`
+  anchors are dropped (a trailing `\Z` becomes `\n?`), and what JS reads
+  differently raises at render (options, escapes such as `\h`/`\p{…}`/`\s`/
+  `\u{…}`, POSIX and nested classes, `&&`, `(?i)`/`(?>…)`, characters above
+  U+FFFF). **Behaviour change:** with `take:`, a short value now leaves the
+  label empty instead of writing `blank_label`. Without `take:` or `match:`
+  nothing changes. Client: +160 B gzipped in the default bundle (+152 B on
+  top of #381/#382), +152 B in the bindings module, the split core unchanged. Docs: "Media
+  previews" on the client-ops example.
+
+- **A pool `<img>` with an `alt` and no `src` keeps its name (#381).**
+  `js.copy_media` and `reactive_media` treated a source `<img>` without `src`
+  as a clear: the preview's `alt` was emptied and `label:` got `blank_label`,
+  so a known entry with no logo file lost its name. Such a source is now a hit
+  without an image: the target's `src` and `srcset` are removed, its `alt` is
+  set, and `label:` gets that `alt`. Only a pool miss, a selector that matches
+  nothing, or a source that is not an `<img>` clears. Client: +1 B gzipped in
+  the default bundle, −2 B in the split core; the bindings module is
+  unchanged.
+
+- **`js.preview_file` follows an app's upload validation (#382).** A preview
+  ran once, on `change`, so a file the app then rejected (cleared with
+  `input.value = ""`, no new `change`) stayed on screen. Two pieces fix it.
+  `js.preview_file(…, valid: true)` treats an input whose `validity.valid` is
+  false (`setCustomValidity`, `required`) as empty: it never gets a preview,
+  and one it had is cleared and its URL revoked. And `reactive:file-changed`
+  is the documented event for "the app changed this input's files without a
+  `change` event": bind the op to it as well,
+  `mix(on_client(:change, op), on_client("reactive:file-changed", op))`, and
+  the app dispatches it after it clears or invalidates the field. That works
+  whichever `change` listener runs first. Without `valid:` the op behaves as
+  before. Client: +22 B gzipped in the default bundle, +34 B in the split
+  core (on top of #381). Docs: "Preview a chosen image" on the client-ops example.
+
+### Performance
+
+- **Guarded and persisted forms connect in linear time.** Each `warn_unsaved`
+  root added its own `beforeunload` / `turbo:before-visit` pair on `window`,
+  and each persisted root its own `turbo:submit-end` listener on `document`.
+  A browser scans a target's listeners on every add and remove, so connecting
+  and disconnecting N of them was quadratic. One shared listener per window or
+  document now serves them all, added with the first root and removed with
+  the last; behaviour is unchanged (live dirty count, one prompt per visit,
+  #298). Headless Chromium, insert + connect: 4,000 guarded roots ~306 ->
+  ~227 ms, 4,000 persisted roots ~280 -> ~230 ms. +194 B gzipped in the
+  default bundle (110 B for the guard, 84 B for persist).
+- **A record-backed token no longer builds a GlobalID URI.** For a record
+  whose `to_gid` is GlobalID's own and whose id is an Integer, the gid is
+  built directly as `gid://<app>/<Class>/<id>` (byte-identical, pinned by
+  `identity_gid_spec.rb`); anything else still calls `to_gid`. The token goes
+  from ~11.4 µs and 54 objects to ~5.2 µs and 20 (in-place A/B).
+- **`rake bench:browser`.** Connect, disconnect and a heap soak for the
+  shipped client in headless Chromium. The happy-dom connect bench is
+  engine-relative and missed the quadratic above; this is the one to trust.
+- **The doctor's authorization check is linear, not quadratic.** It rebuilt
+  the Inspector's whole component list (a Prism scan per action) once for
+  every component. It now reads it once: `doctor.checks` over the dummy app's
+  90 components drops from 1,337 ms to 55 ms, and an app with a few hundred
+  components no longer waits tens of seconds on `rake phlex_reactive:doctor`.
+- **`on()` checks for removed keywords without building arrays.** Every
+  trigger ran `params.keys & REMOVED_ON_KWARGS.keys`. It now returns at once
+  when there are no extra keywords. `on(:increment)` allocates 5 objects
+  instead of 8; a 7-trigger component's `render_component` 118 instead of 136
+  (~5% faster in an in-place A/B, a method-level win that shows on broadcast
+  fan-out, not request latency).
+- **The request bench measures production, not a file watcher.** The dummy
+  app's test env left code reloading on, so every request globbed `app/`:
+  `rake bench:request` read ~1.7-2.0 ms and 1,272 objects per state-backed
+  action, against ~0.30-0.35 ms and 824 objects with it off (same machine,
+  interleaved). Test-env only; the gem is unchanged.
+
+## [0.15.2] - 2026-10-13
+
+### Added
+
 - **Media previews — `js.copy_media` and `reactive_media` (#373).**
   `js.copy_media("#logo", from: "#logo-007")` copies `src`, `srcset` and `alt`
   from an `<img>` the server rendered onto a preview `<img>`; the URL is read
@@ -385,6 +551,10 @@ changelog sections, so this section spans the whole run to 0.15.5.
   Client: +251 B gzipped in the default bundle, +247 B in the split core.
   Docs: "Keeping client state through a morph" on the client-ops example.
 
+## [0.15.1] - 2026-10-12
+
+### Added
+
 - **Modal dialogs — `js.show_modal` / `js.close_dialog` and
   `data-reactive-modal` (#365).** `js.show_modal("#picker")` calls
   `HTMLDialogElement#showModal()`, so an `on_client` dialog gets the browser's
@@ -410,6 +580,10 @@ changelog sections, so this section spans the whole run to 0.15.5.
   every other key alone (+134 B gzipped). `once:` raises on these keys. Existing
   chords render unchanged.
 
+## [0.15.0] - 2026-10-12
+
+### Added
+
 - **Presence — `reactive_presence`, `presence`, `js.presence` (#358).** A
   roster component declares the presence stream it shows
   (`reactive_presence :viewers, state: { selected: :integer }, ttl: 45`) and
@@ -453,6 +627,40 @@ changelog sections, so this section spans the whole run to 0.15.5.
   true` without `shortcut:` behaves exactly as before (never prevented, no
   editable guard).
 
+### Fixed
+
+- **A stream that renders into a connected root wires what its content needs
+  (#356).** A root read its feature markers only at connect and after a morph
+  of itself, so a `reactive_show` target, select-all/count group, filter,
+  nested list, dirty field or paste trigger that an `append`, `prepend`,
+  `update`, `before`, `after` or child `replace` brought into it stayed dead
+  until the root reconnected. Now, once such a stream has rendered, the root
+  re-runs the seeds of the features it has (a new show target takes the
+  field's current value) and connects any feature its new content needs, in
+  both clients; bindings and form also wire a binding whose gate reads true
+  only then. As after a morph, this covers a root with an action token or a
+  lazy shell; a tokenless, client-only root does not re-read. On the split
+  client the stream's render waits for the module the content needs, as it
+  already did for an incoming root, so the content lands wired; the wait is
+  capped at 1 s, after which Turbo renders and the root connects the module
+  when it arrives. A draft
+  restore no longer marks fields `data-reactive-dirty` on a root that never
+  opted into dirty tracking (one that only gates a paste trigger).
+
+- **An editable is editable in an engine without `contenteditable="plaintext-only"`,
+  however it reaches the page (#355).** Such an engine reads the server's
+  `plaintext-only` as invalid, so the element cannot even be focused. The
+  bindings feature switched it to `"true"` only when it connected, or after a
+  morph of the root, which left an editable that a stream appended, a frame
+  loaded or an unfocused morph rewrote uneditable. The runtime now does the
+  switch with one observer, installed only in such an engine (elsewhere the
+  probe is all that runs). Bundle: default +157 B gzip, split core +241 B,
+  `features/bindings` -138 B.
+
+## [0.14.4] - 2026-10-11
+
+### Added
+
 - **Sortable lists — `reactive_sortable`, `reactive_sortable_source`,
   `reactive_sortable_item` (#350).** Rows drag to reorder a list with a mouse,
   a finger (a 200 ms press) or the keyboard (Space picks up, arrows move,
@@ -490,104 +698,10 @@ changelog sections, so this section spans the whole run to 0.15.5.
   client the stream that brings it starts the import). Bundle: default
   +977 B gzip, split core +412 B, `features/bindings` +524 B.
 
-- **`on_client(…, detail: { success: true })` — run ops only when the event's
-  payload qualifies (#346).** A binding can require top-level `event.detail`
-  keys to strictly equal JSON scalars, so `on_client("turbo:submit-end",
-  js.check_group("ids[]", false), detail: { success: true })` clears a bulk
-  selection after a successful submit and keeps it after a failed one. A
-  missing detail or key never matches; a miss runs no confirm and no
-  `preventDefault`. Each binding record carries its own filter, so two bindings
-  on one element can split success and failure. A non-scalar value, an empty
-  Hash, or `detail:` with `once:` raises at render. Records without `detail`
-  are byte-identical.
+## [0.14.3] - 2026-10-07
 
 ### Fixed
 
-- **A server trigger inside a client-only root reaches the component around it
-  (#410).** A `ClientBindings` component (a `reactive_filter` list, a
-  `reactive_show` wrapper, an `on_client` menu) renders a root with no token.
-  Rendered inside a server component, it swallowed that component's `on(...)`
-  triggers: Stimulus sends the action to the nearest root, which had no token,
-  and the outer root's field collection skipped every control under it (the
-  #15 rule). A tokenless client-only root is now transparent to server round
-  trips: `dispatch` forwards to the nearest token-bearing root above (skipping
-  further client-only roots, waking a dormant one), and that root's action
-  collects the controls under nested client-only roots. A nested server
-  component keeps its own fields and triggers, and client bindings stay on
-  their own root. With no token-bearing root above, nothing is sent, and
-  `verbose_errors`/debug logs one warning. Lazy and deferred shells are not
-  client-only. Client: +414 B gzipped in the default bundle, +415 B in the
-  split core.
-
-- **`reactive_media` waits for `take` characters before calling a key a miss
-  (#380).** A value shorter than `take:` sliced to a short key, missed the
-  pool and wrote `blank_label` while the user was still typing. It is now
-  *pending*: `blank_label` only names a full-length key that misses. New
-  options: `match:` (a Regexp, anchored to the whole key; a key it rejects is
-  pending too) and `pending: :clear` (default: clear the preview, empty the
-  label) or `:keep` (leave both alone). The preview carries
-  `data-reactive-media-state="pending|hit|miss"`, so a row can hide itself
-  with CSS. `match:` reaches the browser as a JS pattern: its `\A`/`\z`
-  anchors are dropped (a trailing `\Z` becomes `\n?`), and what JS reads
-  differently raises at render (options, escapes such as `\h`/`\p{…}`/`\s`/
-  `\u{…}`, POSIX and nested classes, `&&`, `(?i)`/`(?>…)`, characters above
-  U+FFFF). **Behaviour change:** with `take:`, a short value now leaves the
-  label empty instead of writing `blank_label`. Without `take:` or `match:`
-  nothing changes. Client: +160 B gzipped in the default bundle (+152 B on
-  top of #381/#382), +152 B in the bindings module, the split core unchanged. Docs: "Media
-  previews" on the client-ops example.
-
-- **A pool `<img>` with an `alt` and no `src` keeps its name (#381).**
-  `js.copy_media` and `reactive_media` treated a source `<img>` without `src`
-  as a clear: the preview's `alt` was emptied and `label:` got `blank_label`,
-  so a known entry with no logo file lost its name. Such a source is now a hit
-  without an image: the target's `src` and `srcset` are removed, its `alt` is
-  set, and `label:` gets that `alt`. Only a pool miss, a selector that matches
-  nothing, or a source that is not an `<img>` clears. Client: +1 B gzipped in
-  the default bundle, −2 B in the split core; the bindings module is
-  unchanged.
-
-- **`js.preview_file` follows an app's upload validation (#382).** A preview
-  ran once, on `change`, so a file the app then rejected (cleared with
-  `input.value = ""`, no new `change`) stayed on screen. Two pieces fix it.
-  `js.preview_file(…, valid: true)` treats an input whose `validity.valid` is
-  false (`setCustomValidity`, `required`) as empty: it never gets a preview,
-  and one it had is cleared and its URL revoked. And `reactive:file-changed`
-  is the documented event for "the app changed this input's files without a
-  `change` event": bind the op to it as well,
-  `mix(on_client(:change, op), on_client("reactive:file-changed", op))`, and
-  the app dispatches it after it clears or invalidates the field. That works
-  whichever `change` listener runs first. Without `valid:` the op behaves as
-  before. Client: +22 B gzipped in the default bundle, +34 B in the split
-  core (on top of #381). Docs: "Preview a chosen image" on the client-ops example.
-
-- **A stream that renders into a connected root wires what its content needs
-  (#356).** A root read its feature markers only at connect and after a morph
-  of itself, so a `reactive_show` target, select-all/count group, filter,
-  nested list, dirty field or paste trigger that an `append`, `prepend`,
-  `update`, `before`, `after` or child `replace` brought into it stayed dead
-  until the root reconnected. Now, once such a stream has rendered, the root
-  re-runs the seeds of the features it has (a new show target takes the
-  field's current value) and connects any feature its new content needs, in
-  both clients; bindings and form also wire a binding whose gate reads true
-  only then. As after a morph, this covers a root with an action token or a
-  lazy shell; a tokenless, client-only root does not re-read. On the split
-  client the stream's render waits for the module the content needs, as it
-  already did for an incoming root, so the content lands wired; the wait is
-  capped at 1 s, after which Turbo renders and the root connects the module
-  when it arrives. A draft
-  restore no longer marks fields `data-reactive-dirty` on a root that never
-  opted into dirty tracking (one that only gates a paste trigger).
-- **An editable is editable in an engine without `contenteditable="plaintext-only"`,
-  however it reaches the page (#355).** Such an engine reads the server's
-  `plaintext-only` as invalid, so the element cannot even be focused. The
-  bindings feature switched it to `"true"` only when it connected, or after a
-  morph of the root, which left an editable that a stream appended, a frame
-  loaded or an unfocused morph rewrote uneditable. The runtime now does the
-  switch with one observer, installed only in such an engine (elsewhere the
-  probe is all that runs). Bundle: default +157 B gzip, split core +241 B,
-  `features/bindings` -138 B.
-
 - **A `checked:`-only `reactive_show_targets` entry hides at zero boxes
   (#348).** `"#bulk-bar" => { if: { "ids[]" => { checked: 1.. } } }` was left
   visible once the owning root held no box of the group (the last ticked row
@@ -597,42 +711,20 @@ changelog sections, so this section spans the whole run to 0.15.5.
   first paint already were. A target with any value term keeps the skip when
   none of its fields is owned.
 
-### Performance
+## [0.14.2] - 2026-10-07
 
-- **Guarded and persisted forms connect in linear time.** Each `warn_unsaved`
-  root added its own `beforeunload` / `turbo:before-visit` pair on `window`,
-  and each persisted root its own `turbo:submit-end` listener on `document`.
-  A browser scans a target's listeners on every add and remove, so connecting
-  and disconnecting N of them was quadratic. One shared listener per window or
-  document now serves them all, added with the first root and removed with
-  the last; behaviour is unchanged (live dirty count, one prompt per visit,
-  #298). Headless Chromium, insert + connect: 4,000 guarded roots ~306 ->
-  ~227 ms, 4,000 persisted roots ~280 -> ~230 ms. +194 B gzipped in the
-  default bundle (110 B for the guard, 84 B for persist).
-- **A record-backed token no longer builds a GlobalID URI.** For a record
-  whose `to_gid` is GlobalID's own and whose id is an Integer, the gid is
-  built directly as `gid://<app>/<Class>/<id>` (byte-identical, pinned by
-  `identity_gid_spec.rb`); anything else still calls `to_gid`. The token goes
-  from ~11.4 µs and 54 objects to ~5.2 µs and 20 (in-place A/B).
-- **`rake bench:browser`.** Connect, disconnect and a heap soak for the
-  shipped client in headless Chromium. The happy-dom connect bench is
-  engine-relative and missed the quadratic above; this is the one to trust.
-- **The doctor's authorization check is linear, not quadratic.** It rebuilt
-  the Inspector's whole component list (a Prism scan per action) once for
-  every component. It now reads it once: `doctor.checks` over the dummy app's
-  90 components drops from 1,337 ms to 55 ms, and an app with a few hundred
-  components no longer waits tens of seconds on `rake phlex_reactive:doctor`.
-- **`on()` checks for removed keywords without building arrays.** Every
-  trigger ran `params.keys & REMOVED_ON_KWARGS.keys`. It now returns at once
-  when there are no extra keywords. `on(:increment)` allocates 5 objects
-  instead of 8; a 7-trigger component's `render_component` 118 instead of 136
-  (~5% faster in an in-place A/B, a method-level win that shows on broadcast
-  fan-out, not request latency).
-- **The request bench measures production, not a file watcher.** The dummy
-  app's test env left code reloading on, so every request globbed `app/`:
-  `rake bench:request` read ~1.7-2.0 ms and 1,272 objects per state-backed
-  action, against ~0.30-0.35 ms and 824 objects with it off (same machine,
-  interleaved). Test-env only; the gem is unchanged.
+### Added
+
+- **`on_client(…, detail: { success: true })` — run ops only when the event's
+  payload qualifies (#346).** A binding can require top-level `event.detail`
+  keys to strictly equal JSON scalars, so `on_client("turbo:submit-end",
+  js.check_group("ids[]", false), detail: { success: true })` clears a bulk
+  selection after a successful submit and keeps it after a failed one. A
+  missing detail or key never matches; a miss runs no confirm and no
+  `preventDefault`. Each binding record carries its own filter, so two bindings
+  on one element can split success and failure. A non-scalar value, an empty
+  Hash, or `detail:` with `once:` raises at render. Records without `detail`
+  are byte-identical.
 
 ## [0.14.1] - 2026-10-07
 
@@ -664,7 +756,7 @@ changelog sections, so this section spans the whole run to 0.15.5.
 
 ## [0.14.0] - 2026-10-07
 
-This section also covers 0.10.0 through 0.13.4, which were released without
+This section also covers 0.9.1 through 0.13.4, which were released without
 changelog sections of their own.
 
 ### Added
@@ -2424,7 +2516,7 @@ changelog sections of their own.
   (`spec/requests/deferred_latency_spec.rb`) pins that a 120 ms segment cost
   moves OFF the actor's reply and onto the deferred leg; it never disappears.
 
-## [0.9.0] - 2026-07-03
+## [0.9.0] - 2026-07-04
 
 Consolidates everything since 0.2.6; tags 0.2.7–0.4.8 shipped without changelog
 sections, so this section spans the whole run to 0.9.0. The jump from 0.4.8 to
@@ -3860,7 +3952,7 @@ room for dogfood fixes.
   Outer flat fields and per-row reactive editing compose cleanly, with no
   name-disjointness workarounds.
 
-## [0.2.6]
+## [0.2.6] - 2026-06-25
 
 ### Added
 
@@ -3887,7 +3979,7 @@ room for dogfood fixes.
   for non-remove/redirect responses, and never double-prepends when the action
   already included a self-targeted stream.
 
-## [0.2.5]
+## [0.2.5] - 2026-06-25
 
 ### Fixed
 
@@ -3903,7 +3995,7 @@ room for dogfood fixes.
   bun unit test (`spec/javascript/reactive_controller.test.js`) that asserts the
   synchronous call and fails on the pre-fix deferred code. Closes #11.
 
-## [0.2.4] - 2026-06-24
+## [0.2.4] - 2026-06-25
 
 ### Fixed
 
@@ -3921,6 +4013,12 @@ room for dogfood fixes.
   byte-identical to source by a guard spec, so the browser tests never validate
   stale client code again. Closes #8.
 
+### Documentation
+
+- Documented the combined record + state identity (the `{c, gid, s}` token
+  shape): the README, `docs/architecture.md`, and `docs/security.md` no longer
+  frame `reactive_record` and `reactive_state` as mutually exclusive. (#9)
+
 ## [0.2.3] - 2026-06-24
 
 ### Fixed
@@ -3940,12 +4038,6 @@ room for dogfood fixes.
   round trip (only a genuinely absent value falls back to the `initialize`
   default). No API changes. Closes #6.
 
-### Documentation
-
-- Documented the combined record + state identity (the `{c, gid, s}` token
-  shape): the README, `docs/architecture.md`, and `docs/security.md` no longer
-  frame `reactive_record` and `reactive_state` as mutually exclusive. (#9)
-
 ## [0.2.2] - 2026-06-24
 
 ### Fixed
@@ -4022,7 +4114,17 @@ room for dogfood fixes.
   scaffolds a reactive component (and an RSpec spec when the app uses RSpec),
   state-backed by default or record-backed with `--record`.
 
-[Unreleased]: https://github.com/mhenrixon/phlex-reactive/compare/v0.14.1...HEAD
+[Unreleased]: https://github.com/mhenrixon/phlex-reactive/compare/v0.16.0...HEAD
+[0.16.0]: https://github.com/mhenrixon/phlex-reactive/compare/v0.15.5...v0.16.0
+[0.15.5]: https://github.com/mhenrixon/phlex-reactive/compare/v0.15.4...v0.15.5
+[0.15.4]: https://github.com/mhenrixon/phlex-reactive/compare/v0.15.3...v0.15.4
+[0.15.3]: https://github.com/mhenrixon/phlex-reactive/compare/v0.15.2...v0.15.3
+[0.15.2]: https://github.com/mhenrixon/phlex-reactive/compare/v0.15.1...v0.15.2
+[0.15.1]: https://github.com/mhenrixon/phlex-reactive/compare/v0.15.0...v0.15.1
+[0.15.0]: https://github.com/mhenrixon/phlex-reactive/compare/v0.14.4...v0.15.0
+[0.14.4]: https://github.com/mhenrixon/phlex-reactive/compare/v0.14.3...v0.14.4
+[0.14.3]: https://github.com/mhenrixon/phlex-reactive/compare/v0.14.2...v0.14.3
+[0.14.2]: https://github.com/mhenrixon/phlex-reactive/compare/v0.14.1...v0.14.2
 [0.14.1]: https://github.com/mhenrixon/phlex-reactive/compare/v0.14.0...v0.14.1
 [0.14.0]: https://github.com/mhenrixon/phlex-reactive/compare/v0.9.0...v0.14.0
 [0.9.0]: https://github.com/mhenrixon/phlex-reactive/compare/v0.2.6...v0.9.0

data/README.md

@@ -299,9 +299,10 @@ imports one the first time a root on the page needs it:
 | `phlex/reactive/features/defer` (`reply.defer`, `reactive_lazy`) | 2.8 KB | inside the one file | fetched when a root is a `reactive_lazy` shell, a morph turns one into a shell, or a `reply.defer` arrives |
 | `phlex/reactive/features/form` (dirty tracking, `warn_unsaved`, the paste-trigger gate) | 1.0 KB | inside the one file | fetched when a root tracks dirty fields or holds a `paste_into` trigger |
 | `phlex/reactive/features/effects` (`reactive_effects`, `dismiss_after`) | 1.7 KB | inside the one file | fetched when a root declares an effect, or when the first stream that needs it arrives: one with an effect, or with a dismissing flash |
-| `phlex/reactive/features/bindings` (`reactive_show`, show targets, `reactive_on_complete`, `reactive_filter`, `reactive_tags`, nested rows, the conditional `confirm:`) | 5.4 KB | inside the one file | fetched when a root declares one of them, or holds a trigger with a conditional confirm |
+| `phlex/reactive/features/bindings` (`reactive_show`, show targets, `reactive_on_complete`, `reactive_filter`, `reactive_tags`, `reactive_css_vars`, nested rows, the conditional `confirm:`) | 8.2 KB | inside the one file | fetched when a root declares one of them, or holds a trigger with a conditional confirm |
 | `phlex/reactive/features/compute` (`reactive_compute`, `reactive_text`) | 2.1 KB | inside the one file | fetched when a root carries a compute binding |
 | `phlex/reactive/features/sortable` (`reactive_sortable` drag and drop) | 3.1 KB | inside the one file | fetched when a root is or holds a sortable or source list |
+| `phlex/reactive/features/drag` (`reactive_box`, `reactive_point` draggable regions) | 3.5 KB | inside the one file | fetched when a root is or holds a frame, a box or a point |
 | `phlex/reactive/features/countdown` (`reactive_countdown`) | 1.0 KB | inside the one file | fetched when a root is or holds a countdown |
 | `phlex/reactive/features/hints` (`optimistic:`, `busy:`) | 1.0 KB | inside the one file | fetched when a root holds a trigger that declares a hint |
 | `phlex/reactive/features/devtools` (the latency simulator, the zero-target warnings, the debug trace) | 1.6 KB | inside the one file | fetched with the core on a page that carries `<meta name="phlex-reactive-env" content="development">` or while a delay is stored for the tab; at connect for a root in debug mode; otherwise the first time a verbose root has something to warn about. In production with none of these, never |
@@ -693,6 +694,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_media(from:, pool:, take:, match:, when:, pending:, label:, blank_label:)` | A preview `<img>` that **follows a field** (#373): the field's value (its first `take:` characters, or all of it) is a key into `pool`, whose values are **selectors** for `<img>` elements the server rendered — never URLs. A hit copies that image's `src`/`srcset`/`alt` like `js.copy_media` (a pool `<img>` with an `alt` and no `src` is a hit without an image, #381); a miss clears the preview. `label:` gets the `alt` (or `blank_label`) as `textContent`. Below `take:` characters, or while `match:` (a JavaScript-compatible Regexp over the whole key) rejects the key, the binding is **pending** (#380) — never `blank_label` (Regexp options or Ruby-only syntax raise at render); `when:` (same rules) tests the **whole field** before the pool lookup while the key stays the prefix, so `take: 3, when: /\A\d{3,24}\z/` keeps `007bad` pending (#390); `pending: :clear` (default) clears the preview and label, `:keep` leaves them. The preview's `data-reactive-media-state` reads `pending`/`hit`/`miss`, so CSS can hide its row. See [Media previews](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
 | `reactive_image_fallback(hide: true, show_alt: nil, wrap: nil)` | An `<img>` that **falls back and recovers** (#383): on `error` it gets `data-reactive-image-state="error"`; `hide:` (default `true`) also hides it, and `show_alt:`, independently, writes its `alt` into that node and shows it; `wrap:` (#392) hides the box around it (marked `data-reactive-wrap-hidden`, shown again only when it carries that mark, its text never written); `load` sets `"loaded"`. A later `src` (from `copy_media`, `reactive_media`, `preview_file`, a morph, or any `src` that loads) shows it again; removing the `src` is not an error. Composes with `reactive_media(…, **reactive_image_fallback)`. See [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
 | `reactive_countdown(until:, format: :ms, waiting:, done:)` | A server **deadline counted down** on the client (#400): `until:` is an ISO8601 date-time with a zone (or a `Time`); the text is the time left from `Date.now` (`1:30`), as `textContent`, once a second and again when a hidden tab is shown. At zero (or already past on connect) it reads `0:00`, `data-reactive-countdown-state="done"`, `waiting:` hides, `done:` shows and `reactive:countdown-done` fires **once per deadline** (a morph that keeps `until:` does not fire again; a new `until:` restarts). The server renders the first text and visibility. No request, no frame reload. See [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
+| `reactive_css_vars(to:, vars:, global: false)` | Fields that **feed CSS custom properties** on an element (#417), for a preview that follows a control with no request: `vars: { "--light" => "light", "--turn" => { field: "turn", unit: "deg" } }`. Each field is read as `reactive_show` reads one (a checkbox gives `1`/`0`, a radio group its checked value) and parsed as a **finite number**; the client writes `number + unit` with `style.setProperty`, and anything else (empty, text) removes the property so the `var()` fallback applies. No text from a field reaches CSS. Units: `""`, `px`, `%`, `deg`, `turn`, `ms`, `s`, `em`, `rem`, `fr`; names match `--[a-zA-Z0-9-]+`; a bad name or unit or a blank field raises at render. Runs on connect, on `input`/`change` and after a morph. `to:` resolves like a client op's (`:root`, inside the root, `global: true`, an Array). Render the same properties inline for the first paint. See [Client-only ops](https://phlex-reactive.zoolutions.llc/docs/example-client-ops). |
 | `reactive_enable(if:/if_any:/unless:)` | The sibling of `reactive_show` that flips the element's **own `disabled`** (a button, a fieldset) instead of `hidden` — same conditions, same `reactive_values` first paint. `button(**reactive_enable(if: { "ids[]" => { checked: 1.. } }))`. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
 | `reactive_select_all("ids[]")` / `reactive_count("ids[]")` | A checkbox **group**'s header box (ticks/unticks every owned box; shows checked / indeterminate / unchecked) and its ticked count as text — re-synced on every change and when rows are appended or removed. `under: "a.b"` makes a nested header over the leaves whose `data-reactive-group` is in that path. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
 | `reactive_group_targets("ids[]", count: "#c", enable: { "#b" => 1.. })` | Spread on the root that **owns** a checkbox group: drives a count and an enable on outside, id-allowlisted elements (a bulk bar the page renders). `reactive_group_target_attrs` gives that outside markup its first paint. See [A bulk bar outside the list's root](#a-bulk-bar-outside-the-lists-root-reactive_group_targets). |
@@ -1900,6 +1902,87 @@ list; a reply that morphs the list puts the rows in the server's order.
 
 Full guide: [Sortable lists](https://phlex-reactive.zoolutions.llc/docs/sortable-lists).
 
+### Draggable regions (`reactive_box`, `reactive_point`)
+
+Move and resize a box, or move a point, over an image, a chart or a diagram —
+with a mouse, a pen, a finger or the keyboard — and its fields always hold
+where it is, as fractions of the frame (0..1 on each axis). A crop box, a
+focal point, a hotspot, a selection: no Stimulus controller of your own.
+
+```ruby
+class CropPicker < Phlex::HTML
+  include Phlex::Reactive::Component
+
+  reactive_record :photo
+  action :crop, params: { x: :float, y: :float, width: :float, height: :float }
+
+  def crop(x:, y:, width:, height:)
+    authorize! @photo, :update?
+    # The schema casts; it does not range-check. A forged box outside the frame changes nothing.
+    return reply.morph unless inside?(x, width) && inside?(y, height)
+
+    @photo.update!(crop: { x:, y:, width:, height: })
+    reply.morph
+  end
+
+  def view_template
+    div(**reactive_root) do
+      div(**mix(reactive_frame, class: "relative")) do
+        img(src: @photo.url, alt: "", class: "block w-full")
+        div(**reactive_box(fields: { x: "crop[x]", y: "crop[y]", width: "crop[width]", height: "crop[height]" },
+                           value: @photo.crop, aspect: "aspect", min: 0.05, action: :crop)) do
+          %i[nw n ne e se s sw w].each { span(**reactive_box_handle(it)) }
+          span(**reactive_point(fields: { x: "focus[x]", y: "focus[y]" }, value: @photo.focus,
+                                within: "[data-reactive-box]"))
+        end
+      end
+      # the fields: hidden inputs named crop[x] … focus[y], and the aspect radios
+    end
+  end
+
+  private
+
+  # The fields round to 4 decimals, so x + width may reach 1.0001.
+  def inside?(at, size) = at.between?(0, 1) && size.positive? && at + size <= 1.0001
+end
+```
+
+The helpers render the box's `left`/`top`/`width`/`height` (and the point's
+`left`/`top`) as percentages from `value:`, so the first paint is right with
+no JavaScript and a re-render with new values moves them. The frame must be
+positioned (`relative`, or `absolute` for an overlay); its padding box is the
+coordinate space.
+
+- **Pointer**: a press on the box moves it, a press on a handle resizes from
+  that edge or corner; the box stays inside the frame and never goes below
+  `min:`. A drag starts after a 4 px move; `touch-action: none` keeps a finger
+  drag from scrolling the page.
+- **Fields**: written as `set_value` writes them (the live `.value`, rounded to
+  4 decimals, a bubbling `input` at most once per field per frame), so
+  `reactive_show`, compute reducers and other bindings follow the box. One
+  `change` fires on release.
+- **`aspect:`**: a Numeric (`16/9r`) or the name of a field holding `"16:9"`, a
+  decimal or `""` (free), read at drag start. When the field changes (a preset
+  radio), the box re-fits to the new ratio around its centre.
+- **`action:`** (optional): sent once on release through the root's pipeline,
+  with `x`, `y`, `width`, `height` (a point: `x`, `y`). Without it the binding
+  is client-only and works on a `ClientBindings` root. The `:float` schema casts
+  but does not range-check: refuse values outside 0..1, a `width` or `height`
+  of 0, and `x + width` or `y + height` past 1.0001 (the fields' rounding)
+  before you store them, since `reactive_box` refuses to render such a box.
+- **Points**: `reactive_point` moves within the frame, or — placed inside a box
+  with `within:` — within that box, its fractions of the box.
+- **Keyboard**: the box and the point are focusable; arrows move 1% (Shift:
+  10%), Alt+arrows resize from the bottom-right corner or the focused handle,
+  Escape puts it back. Each step is announced through a live region; translate
+  the words with `messages:` (`{x}`, `{y}`, `{width}`, `{height}` as whole
+  percents). Letting go of the key is the release.
+- **Styling**: `data-reactive-frame-active` (the frame) and
+  `data-reactive-dragging` (the pressed box, handle or point). A morph that
+  lands mid-drag does not interrupt it.
+
+Full guide: [Draggable regions](https://phlex-reactive.zoolutions.llc/docs/draggable-regions).
+
 ### Presence (`reactive_presence`)
 
 Who is viewing a stream, one entry per browser tab, each tab with a small
@@ -2857,6 +2940,7 @@ def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams
 | `.also(target => content, …)` | **UPDATE** (inner HTML) companion elements by DOM id; `content` is a plain string (escaped) or a Phlex component. The argument *type* picks the action — pairs mean `update` |
 | `.also(component, morph: false)` | **REPLACE** another Streamable component at its own `#id` (`morph: true` morphs in place). A component argument means `replace` |
 | `.flash(level, content, target: …)` | append a flash; `content` is a plain string (escaped, wrapped in a level-carrying `<div>` — see [Flash levels](#flash-levels)) or a Phlex component (rendered verbatim; off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
+| `.refused(*names)` | the reply **answers the posted values without storing them**: the client keeps the fields a morph held (`data-reactive-held`, #370), so the root's next action names them in `reactive_held_fields` again instead of saving over the other change. No names keeps every mark; names (the fields' `name` attributes) keep only those. Chain it on a morph (`reply.morph.refused`): a plain `replace` swaps the marked field out. Still a 200: no error marker, no `reactive:error` (#413) |
 | `reply.remove` | remove the element (backed by `Streamable#to_stream_remove`) |
 | `reply.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
 | `reply.streams(*streams)` | **partial update** — emit exactly these streams (no full-self replace) + a tiny token-only refresh, so live inputs survive; for per-field grid editing (issue #30) |