phlex-reactive 0.2.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6b8ebca93e744e1c2fa3797de877cefc732db8a6cb950d95874c9e00e4dee76
-  data.tar.gz: 119b1373f8ade989791845fc9cf3206f7786eb97f6009faaabfadb1485c82b44
+  metadata.gz: 8811ee6a3c0f044fd7c9d16843a641296b33b8fcb5872f5bc8822257f837148e
+  data.tar.gz: 9398a1c088680e83b8bed3398342345ceb817703183df0985a1948e29df021cf
 SHA512:
-  metadata.gz: ee11a3bf0ac506cdbde2e97e9e47bad436a16050c0b150cd5340bbff9ae846586487bbf6a2bbf028ff20c44faa64f2e57953ddf15adcbafc82491d5e15a9f22f
-  data.tar.gz: 3bd5cd4a362ed18f59da8bf375474aa8beabd5cfdd0d62572d5fce043318c057b01afcf3942acaec30417dc16fd3b3d8d9e6ef9f7ec524f55cf411cc168b8003
+  metadata.gz: b17a5d83f62e801d0f8673f824f929a82d1c7efc2d0aa2274034639ed94b2c8c4723f11484427f051c7be15d523a0b99cd11594bed0d701e4ff2e07604a1edd8
+  data.tar.gz: b5990726c0531bd2d6bc2da23df8bb2dbf5220ee702306c86f8094690da8c4a1752fa8ffb7949261050858256e5fd70854491603ac2306221c9f7bf2078f943c

data/CHANGELOG.md

@@ -8,6 +8,191 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **File / multipart params in a reactive action (#34).** An action can now accept
+  an uploaded file: declare `params: { file: :file }` (or `[:file]` for multiple).
+  When the reactive root holds a populated `<input type="file">`, the client sends
+  the action as multipart `FormData` instead of JSON — `token` + `act` + scalar
+  params as fields, the file(s) appended — and the endpoint coerces `:file` to the
+  `ActionDispatch::Http::UploadedFile`, passed through untouched. A non-file value
+  sent to a `:file` param is dropped (the keyword default applies), consistent with
+  the #16 coercion rules — and for a `[:file]` array, a non-file *element* (a
+  forged/mixed payload) is rejected from the array too, so the internal coercion
+  sentinel never leaks to the action. A `<input type="file" multiple>` keeps its
+  array shape (`params[name][]`) even when the user picks exactly one file, so a
+  `[:file]` schema still coerces it. Token threading and the re-render/morph are
+  identical; only the request encoding changes when a file is present — so
+  attaching a document/receipt/image stays a reactive action instead of dropping
+  out to a bespoke controller + upload Stimulus controller. Covered end-to-end:
+  server coercion (request specs), the FormData wire shape (bun unit tests), and a
+  real browser upload under Puma + Falcon (system spec).
+
+### Changed
+
+- **Linter: Standard → RuboCop.** The gem now lints with RuboCop (all new cops
+  enabled, `NewCops: enable`) instead of StandardRB, so the suite teaches and
+  enforces newer Ruby idioms that Standard leaves alone — chiefly the Ruby 3.4
+  `it` implicit single block parameter (`map { it.foo }`) via
+  `Style/ItBlockParameter: always`. The whole tree was autocorrected; the
+  lib/app changes were the `|x| x.foo` → `it.foo` rename plus hash-brace
+  spacing — behavior is unchanged and all specs are green. The gemspec and
+  Rakefile are excluded from `Style/ItBlockParameter` (their `do |spec| … end`
+  config blocks read better named); a nested Phlex content block and a scope
+  lambda carry inline disables where blanket `it` would collapse two parameters
+  or break a `where(room:)` kwarg shorthand; and blocks that fed a
+  keyword-argument shorthand (`Component.new(todo:)`) were rewritten to an
+  explicit `Component.new(todo: it)` so the `it` rename can't silently change
+  the keyword. Component-
+  aware relaxations (line length, `Lint/MissingSuper`, unused action params)
+  are scoped to `spec/dummy/app/components/**`. `bundle exec standardrb` is now
+  `bundle exec rubocop`; `rake`'s default runs `spec + rubocop`.
+- **Added `rubocop-capybara` and `rubocop-thread_safety`.** Capybara lints the
+  browser specs (clean today — the suite already uses waiting matchers).
+  thread_safety stays on as a tripwire for unsafe shared mutable state on the
+  request/broadcast path; its `ClassInstanceVariable` /
+  `ClassAndModuleAttributes` cops are scoped off only in the three files whose
+  flagged class-level state is deliberate and audited — module-level config
+  (`lib/phlex/reactive.rb`, set once at boot), class-definition-time DSL
+  registries (`component.rb`), and the per-thread view-context cache's integer
+  generation counter (`streamable.rb`). An adversarial audit confirmed none are
+  request-path hazards; the lazy `||=` config defaults are idempotent. (A
+  follow-up may warm `verifier`/`renderer` at boot to remove even the
+  benign-by-idempotency first-call race — out of scope for this lint change.)
+
+### Removed
+
+- **Dropped the `standard` development dependency** in favor of `rubocop`,
+  `rubocop-capybara`, `rubocop-performance`, `rubocop-rake`, `rubocop-rspec`,
+  and `rubocop-thread_safety`.
+
+### BREAKING
+
+- **Minimum Ruby is now 3.4** (was 3.2). Enabling the `it` block parameter
+  requires Ruby 3.4, so `required_ruby_version` is `>= 3.4.0` and the CI matrix
+  drops 3.2 and 3.3. Stay on phlex-reactive 0.3.x if you need Ruby 3.2/3.3.
+
+### Fixed
+
+- **Multipart path silently dropped an explicit nested-hash / array param (#39).**
+  When an action declared a `:file` param alongside an explicit nested (hash/array)
+  param, the nested param was dropped on the multipart path while the JSON path
+  handled it correctly — the two encodings were asymmetric. The client's
+  `#buildFormData` `JSON.stringify`'d a non-scalar param into one
+  `params[key]='<json>'` field, which the server received as an un-decodable
+  `String` leaf and dropped (nested hash → `{}`, array → key removed). Fixed
+  client-side: `#buildFormData` now bracket-expands a nested object/array into
+  `params[key][sub]` / `params[key][index][...]` fields (arrays use numeric
+  indices) — the same Rails-form shape the server's `expand_bracket_keys` /
+  `array_values` already parse, so a JSON body and a multipart body now coerce
+  identically. The server is unchanged. One intentional divergence: an empty
+  array/object as a whole param can't be carried by `FormData`, so the multipart
+  path omits the key (the action's keyword default applies) rather than sending an
+  explicit-clear `[]`/`{}`. Covered end-to-end: the bracketed multipart shape
+  coerces correctly (request specs), a `:file` alongside a nested param both
+  survive (request spec), and the FormData wire shape (bun unit tests).
+
+- **`to_stream_token` emitted an EMPTY token, making non-self-rendering replies
+  add-once-only (cosmos#1939).** `Streamable#to_stream_token` guarded on
+  `respond_to?(:reactive_token)`, but `Component#reactive_token` is **private**, so
+  the guard was false for every component and the refresh stream carried
+  `data-reactive-token-value=""`. Any reply that opts out of the full-self replace
+  but relies on the token-only refresh — `reply.streams` (#30) and the new
+  `reply.append`/`reply.remove` (#35) — therefore rolled an empty token forward:
+  the first action worked, then the next dispatch from that root was rejected (the
+  stale/empty token fails verification) with no error. Fixed by checking private
+  methods (`respond_to?(:reactive_token, true)`); a bare Streamable (genuinely no
+  token) still skips correctly. The `reactive_collection` builders also now bind the
+  **container** as the `token_component`, so an add/remove rolls the list root's
+  token forward (the load-bearing part for repeated add/remove). Regression tests
+  assert the token is non-empty AND re-verifies, and that a second add using the
+  first reply's token succeeds.
+
+### Changed
+
+- **The browser suite now runs under two real servers — Puma and Falcon.** The
+  `system` CI job runs as a matrix (`CAPYBARA_SERVER=puma` and `=falcon`), and a
+  new `rake spec:system_servers` task runs both locally, so a reactive round trip
+  is proven transport-agnostic across a sync (Puma, thread-pool) and an async
+  (Falcon, fiber-per-request) server. `webrick` is **removed** as a test server
+  (it isn't a real server) — `falcon` (with `protocol-rack`) replaces it as the
+  alternative, registered via `Capybara.register_server(:falcon)`. No production
+  dependency change; this is test infrastructure only.
+
+- **CI now tests against Ruby 4.0** (added to the test matrix in `main.yml` and
+  the pre-release matrix in `release.yml`, alongside 3.2/3.3/3.4; the lint and
+  browser-system jobs also run on 4.0 now). Ruby 4.0 shipped December 2025 and is
+  the current stable line. The gem requires no code changes for 4.0 — its
+  dependencies and the patterns it uses (ObjectSpace::WeakMap, Data.define,
+  Thread-locals, the MessageVerifier path) are stable across 3.4 → 4.0, and it
+  directly requires none of the gems 4.0 moved from default to bundled.
+  `required_ruby_version` stays `>= 3.2.0` (no upper bound, already permits 4.0).
+  Verified empirically: the full unit/request/generator suite is green on Ruby
+  4.0.5 with zero deprecation or unbundled-gem warnings.
+
+### Added
+
+- **`reactive_collection` — add/remove-row lists in one declaration (issue #35).**
+  An add/remove-row list (line items, tags, comments, a notifications list) is one
+  of the most common reactive surfaces, and every one re-implements the same
+  orchestration by hand: append the row to the right container, remove it on
+  delete, keep a count badge in sync, and swap an empty-state in/out as the list
+  crosses 0↔1. `reactive_collection :items, item:, container:, count:, empty:,
+  size:` declares that contract **once** on the container component, so each action
+  is a single call: `reply.append(:items, model)` (row + count + empty-state
+  clear), `reply.prepend(:items, model)`, and `reply.remove(:items, model_or_id)`
+  (row + count + empty-state restore). The size badge and empty-state toggle are
+  driven by the declared `size:` resolver, **re-counted server-side after the
+  mutation** — so they're correct-by-construction (no off-by-one, no client-held
+  count, consistent between the first render and the deltas). `count:`/`empty:`/
+  `size:` are optional (omit them and only the row stream is emitted), and the new
+  builders compose with `.flash`/`.stream` like any other reply. Reply governs the
+  actor's HTTP response only; a cross-tab live list still broadcasts the row with
+  `broadcast_append_to(..., exclude: reactive_connection_id)`. New
+  `Phlex::Reactive::Component::CollectionDefinition`,
+  `reactive_collection`/`reactive_collection_def`/`reactive_collection?` macros,
+  and `Response.collection_append`/`collection_prepend`/`collection_remove` behind
+  the `reply.*` surface.
+
+- **`reply.streams` — partial update with a token-only refresh (issue #30).**
+  `reply.streams(Totals.update(@item))` emits **exactly** the streams you pass —
+  no forced full-self replace — so an action can re-render only part of a
+  component (one total cell, one sub-region) while the rest of the DOM, including
+  a sibling `<input>` the user is mid-typing in, is left untouched. The signed
+  identity token still rolls forward: the endpoint appends a tiny
+  `<turbo-stream action="reactive:token">` (new `Streamable#to_stream_token`) that
+  carries the fresh `data-reactive-token-value` and is applied by an inert client
+  action — a pure attribute write on the root, so the focused field + caret
+  survive. This unblocks spreadsheet-like per-field grid editing that the old
+  "every reply re-renders the whole component" behavior made unusable (you had to
+  reach for `data-turbo-permanent`). `Response.streams(self, *)` is the underlying
+  builder; `reply.streams(*)` is the bound form. Backed by a new `render_self:
+  false` + `token_component` path in the endpoint — the legacy full-self-replace
+  refresh (`reply.replace` / `reply.with`) is unchanged.
+
+- **`reply` — the action-reply builder.** Control an action's reply with
+  `reply.replace` / `reply.morph` / `reply.update` / `reply.remove` /
+  `reply.redirect(url)` / `reply.with(*)`, chaining `.flash` / `.stream` /
+  `.also_update` / `.also_replace` as before. `reply` is a subject-bound facade on
+  the component, so the two warts of the old form disappear: no `self` to thread
+  (`reply.morph`, not `Response.morph(self)`) and no constant to qualify — a
+  namespaced component no longer needs a per-file `Response = …` alias, because
+  `reply` is a method resolved on the component, not a lexical constant. It
+  returns the same immutable value object the endpoint reads, so the return-value
+  contract, immutability, and chaining are unchanged. `Phlex::Reactive::Response`
+  remains fully functional but is now an internal detail — `reply` is the
+  documented surface.
+
+- **Morph response — focus-preserving re-render (issue #28).**
+  `reply.morph` (and the opt-in `reply.replace(morph: true)`)
+  re-renders a component in place via Turbo 8's bundled Idiomorph
+  (`<turbo-stream action="replace" method="morph">`) instead of an outerHTML
+  swap. The focused `<input>` and its caret survive the save, making per-field
+  reactive editing — a "spreadsheet" grid where a debounced save fires while the
+  user is still typing/tabbing — actually viable. Backed by the new
+  `Streamable#to_stream_morph` primitive and a `morph:` flag on the
+  `.replace` / `.broadcast_replace_to` class builders and `#also_replace`
+  (live cross-tab updates can morph too). The default everywhere stays the plain
+  replace (no `method="morph"` attribute), so existing components are unchanged.
+  No new dependency — Idiomorph ships with `turbo-rails >= 2.0`.
 - **Input/select param-binding helpers (issue #23).** `reactive_input(:value,
   …)` and `reactive_select(:status, …) { … }` render a form control already bound
   to an action param — no hand-written `name: "value"` magic string to forget
@@ -59,6 +244,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   trip still goes through the per-component queue so token threading holds.
   Omitting `debounce:` keeps the immediate-dispatch default.
 
+### Performance
+
+- **Re-render is ~2× faster with ~half the allocations.** `render_component` now
+  renders through phlex-rails' lightweight `#render_in` against a memoized
+  off-request view context, instead of `ActionController.renderer.render` (which
+  dragged in ActionView's `TemplateRenderer`/`LookupContext`/log subscriber).
+  Measured same-machine before/after: `render_component` 6.99k→14.1k i/s (212→99
+  obj/call); `to_stream_replace` 4.60k→8.00k i/s (331→191 obj/call). HTML is
+  byte-identical and the full Rails helper set (`dom_id`/`url_for`/`t`/CSRF) still
+  works. The biggest win is on the **broadcast** path (N subscribers = N renders,
+  no HTTP to amortize against); at the full-request level the Rails stack + DB
+  dominate, so request throughput is roughly unchanged.
+
+- **View context, Turbo `TagBuilder`, and flash builder are memoized** per
+  component class (the comment used to claim this; now it's true). Keyed on the
+  configured renderer's identity so swapping `Phlex::Reactive.renderer` rebuilds,
+  and reset on Rails code reload (`config.to_prepare`) so a reloaded controller
+  is never served stale.
+
+- **Smaller per-render allocations on the token path.** `reactive_token`
+  precomputes its ivar symbols + state string-keys per class (14→11 obj/call,
+  state-backed), and `on(:action)` skips re-serializing an empty params hash
+  (6→5 obj/call). The bracket-key regex in param coercion is hoisted to a frozen
+  constant.
+
+- **Client: the page-stable action path is resolved once per controller** instead
+  of a `querySelector` per dispatch. CSRF token and pgbus connection id stay live
+  (they can rotate).
+
+- **Benchmark harness + CI report.** `rake bench` (micro: render/token/coerce) and
+  `rake bench:request` (end-to-end via derailed) measure the hot paths; a CI
+  `bench` job runs them on every PR and uploads the report as an artifact
+  (run-and-report, not a hard gate). See `docs/performance.md` and the `/perf`
+  command.
+
 ### Fixed
 
 - **Model-scoped form fields feed a nested param (issue #21).** A Rails

data/README.md

@@ -191,8 +191,8 @@ data-controller="reactive" but the reactive controller never connected …`).
    │                                          rebuild component (record from DB)
    │                                          run the whitelisted action
    │                                          re-render → <turbo-stream replace id>   (default; an action
-   │                                          may return a Response — see "Controlling the action's reply")
-   └──────── Turbo morphs it in ◀───────────────────────────────┘
+   │                                          may return reply.<verb> — see "Controlling the action's reply")
+   └──────── Turbo applies it in ◀──────────────────────────────┘
 
    ...and for OTHER tabs/users:
    model change → Component.broadcast_replace_to(stream) → pgbus SSE → same morph
@@ -292,11 +292,11 @@ The cross-tab chat in ~60 lines of Ruby (and zero JS) is the showcase — see
 | Method | Use |
 |---|---|
 | `#id` (you implement) | Stable DOM id == Turbo Stream target. Must match the root element's `id`. |
-| `.replace(model = nil, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component |
+| `.replace(model = nil, morph: false, **opts)` | `<turbo-stream action=replace target=id>` of a freshly built component; `morph: true` adds `method="morph"` |
 | `.update` / `.append(target:)` / `.prepend(target:)` / `.remove` | The other Turbo Stream actions |
-| `.broadcast_replace_to(*streamables, model:)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable) |
+| `.broadcast_replace_to(*streamables, model:, morph: false)` | Broadcast a replace over the stream transport (pgbus SSE / Action Cable); `morph: true` morphs in place |
 | `.broadcast_append_to(*streamables, target:, model:)` / `_update_` / `_prepend_` / `_remove_` | The broadcast variants |
-| `#to_stream_replace` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `Response`) |
+| `#to_stream_replace` / `#to_stream_morph` / `#to_stream_update` / `#to_stream_remove` | Stream the *already-built* instance (used internally after an action / by `reply`); `#to_stream_morph` morphs in place |
 
 Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 
@@ -313,9 +313,52 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_input(:param, **attrs)` / `reactive_select(:param, **attrs)` | Render a control already bound to an action param (no magic `name:`). |
 | `reactive_field(:param, **attrs)` | The attribute hash behind the above — spread onto any control. |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
+| `reactive_collection :name, item:, container:, count:, empty:, size:` | Declare an add/remove-row list once; actions call `reply.append`/`prepend`/`remove`. See [Reactive collections](#reactive-collections-addremove-rows--count--empty-state). |
+| `reply.replace` / `.morph` / `.update` / `.remove` / `.redirect(url)` / `.with(*)` | Return from an action to control the reply (flash, remove, redirect, multi-stream). See [Controlling the action's reply](#reply--controlling-the-actions-reply). |
+| `reply.append(name, model)` / `.prepend(...)` / `.remove(name, model)` | Add/remove a row in a declared `reactive_collection` (row + count + empty-state in one reply). |
+
+Param types: `:string` (default), `:integer`, `:float`, `:boolean`, `:file`.
+Anything not in the schema is dropped before reaching your method.
+
+**File uploads (`:file`).** Declare `:file` (or `[:file]` for multiple) to accept
+an uploaded file in a reactive action — attach a document/receipt/image to the
+record without dropping out to a bespoke controller. When the reactive root holds
+a populated `<input type="file">`, the client sends the action as multipart
+`FormData` (instead of JSON) — `token` + `act` as fields, scalar params as fields,
+any nested/array params bracket-expanded into `params[key][sub]` /
+`params[key][index]` fields (the same Rails-form shape, so a JSON body and a
+multipart body coerce identically — #39), and the file(s) appended; the endpoint
+coerces `:file` to the `ActionDispatch::Http::UploadedFile`, passed through
+untouched. A non-file value sent to a `:file` param is dropped (the keyword
+default applies — never a fabricated file). Token threading and the
+re-render/morph are identical; only the request encoding changes when a file is
+present.
 
-Param types: `:string` (default), `:integer`, `:float`, `:boolean`. Anything not
-in the schema is dropped before reaching your method.
+```ruby
+reactive_record :document
+action :upload, params: { file: :file, caption: :string } # single (has_one_attached)
+action :upload_pages, params: { pages: [:file] }           # multiple (has_many_attached)
+
+def upload(file: nil, caption: nil)
+  @document.file.attach(file) if file
+  @document.update!(title: caption) if caption.present?
+end
+
+def view_template
+  form(**on(:upload, event: "submit")) do
+    input(type: "file", name: "file")
+    input(name: "caption")
+    button(type: "submit") { "Upload" }
+  end
+end
+```
+
+> **One multipart caveat:** `FormData` can't carry an *empty* array or hash, so on
+> the multipart (file-present) path an empty `[]`/`{}` param is **omitted** and the
+> action's keyword default applies — it does **not** arrive as an explicit empty
+> collection the way it does over JSON. If you rely on sending `tags: []` to clear
+> a collection, send that action *without* a file (the JSON path). A non-empty
+> nested/array param rides along fine next to a file.
 
 **Array & nested params.** Wrap a type in an array for an array param, or a hash
 schema in an array for Rails-style nested attributes — so one reactive action can
@@ -422,52 +465,139 @@ end
 `nested_attributes(:address, address)` returns the id-merged hash without
 updating, if you need to combine it with other attributes.
 
-### `Phlex::Reactive::Response` — controlling the action's reply
+### `reply` — controlling the action's reply
 
-By default an action re-renders its component in place. **Return** a
-`Phlex::Reactive::Response` to do more (it governs only the actor's HTTP reply —
-cross-tab updates still use `broadcast_*_to(..., exclude: reactive_connection_id)`).
-Returning anything else keeps the default, so existing actions are unaffected.
+By default an action re-renders its component in place. To do more, **return**
+`reply.<verb>` — a subject-bound builder available in every component. It governs
+only the actor's HTTP reply (cross-tab updates still use
+`broadcast_*_to(..., exclude: reactive_connection_id)`). Returning anything else
+keeps the default, so existing actions are unaffected.
 
-The snippets below alias the constant for brevity (`Response.replace(self)` won't
-resolve to `Phlex::Reactive::Response` inside a namespaced component — fully
-qualify it, or add the alias shown):
+`reply` reads cleanly: the component is the implicit subject (no `self` to
+thread) and there's no constant to qualify (it's a method, so a namespaced
+component needs no alias):
 
 ```ruby
-Response = Phlex::Reactive::Response # or qualify each call below
-
 def rename(title:)
-  return Response.replace(self).flash(:error, @todo.errors.full_messages.to_sentence) unless @todo.update(title:)
-  Response.replace(self)
+  return reply.replace.flash(:error, @todo.errors.full_messages.to_sentence) unless @todo.update(title:)
+  reply.replace
 end
 
-def approve   = (@row.approve!; Response.remove(self))          # drop the element
-def publish   = (@article.publish!; Response.redirect(article_url(@article)))  # slug changed → Turbo.visit
-def add(item:) = Response.replace(self).stream(Totals.update(@order))           # multi-stream
+def approve   = (@row.approve!; reply.remove)          # drop the element
+def publish   = (@article.publish!; reply.redirect(article_url(@article)))  # slug changed → Turbo.visit
+def add(item:) = reply.replace.stream(Totals.update(@order))               # multi-stream
+
+# Per-field reactive editing (a "spreadsheet" grid): a debounced save fires
+# while the user is still typing/tabbing. Morph in place so the focused <input>
+# and its in-progress value survive the re-render (issue #28). Note the action is
+# named `update`, yet `reply.morph` is unambiguous — the verb is on `reply`:
+def update(name:) = (@row.update!(name:); reply.morph)
 
 # Re-render a COMPANION element (a heading mirroring the edited name) alongside self:
-def rename(value:) = (@account.update!(name: value); Response.replace(self).also_update("page_heading", html: @account.name))
+def rename(value:) = (@account.update!(name: value); reply.replace.also_update("page_heading", html: @account.name))
+
+# Update ONLY part of the component (issue #30): re-stream just the total cell,
+# NOT the whole row. reply.streams emits exactly your streams plus a tiny
+# token-only refresh — no full-self replace — so a sibling <input> the user is
+# mid-typing in is never torn down. The signed token still rolls forward.
+def update(quantity:, price:) = (@item.update!(quantity:, price:); reply.streams(Totals.update(@item)))
 ```
 
 | Builder | Reply |
 |---|---|
-| `Response.replace(self)` / `.update(self)` | re-render in place (explicit default) |
+| `reply.replace` / `reply.update` | re-render in place (default; `replace` is an outerHTML swap, `update` morphs inner HTML) |
+| `reply.morph` / `reply.replace(morph: true)` | re-render in place via Idiomorph (`method="morph"`) — preserves the focused `<input>` + caret; for per-field reactive editing (issue #28) |
 | `.also_update(target, html:)` | also re-render a companion element by DOM id; `html` is a plain string (escaped) or a Phlex component |
-| `.also_replace(component)` | also re-render another Streamable component, targeting its own `#id` |
+| `.also_replace(component, morph: false)` | also re-render another Streamable component, targeting its own `#id`; `morph: true` morphs it in place |
 | `.flash(level, content, target: …)` | append a flash; `content` is a plain string (escaped) or a Phlex component (off-request — no Rails `flash`); target defaults to `Phlex::Reactive.flash_target` (`"flash"`) |
-| `Response.remove(self)` | remove the element (backed by `Streamable#to_stream_remove`) |
-| `Response.redirect(url)` | client-side `Turbo.visit` (pass a `*_url`); rides a `reactive:visit` turbo-stream, not an HTTP 3xx |
-| `Response.with(*streams)` / `#stream(*more)` | multi-stream |
+| `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) |
+| `reply.with(*streams)` / `#stream(*more)` | multi-stream (self re-render still injected for the token) |
 
 `.flash`/`.stream`/`.also_*` are additive on a self-replace, so the component's
-signed token always refreshes.
-
+signed token always refreshes. **`reply.streams`** is the exception that proves
+the rule: it deliberately skips the full-self replace (so your hand-built streams
+update only the targets you name) and refreshes the token via a tiny inert
+`reactive:token` stream instead — the token rolls forward without re-rendering
+(and clobbering) the component's live inputs.
+
+> **Under the hood.** `reply.<verb>` returns a `Phlex::Reactive::Response` — the
+> immutable value object the endpoint reads. You can build one directly
+> (`Phlex::Reactive::Response.replace(self)`) and it still works, but `reply` is
+> the preferred surface; treat `Response` as an internal detail.
 > **`html:`/`content` escaping.** A plain string is **HTML-escaped** by Turbo, so
 > `html: @account.name` is safe even for user-supplied values. To emit intentional
 > markup, pass a **Phlex component** (`html: Heading.new(name: @record.name)`) —
 > rendered and auto-escaped through the renderer — or an `html_safe` string for
 > raw HTML you control.
 
+### Reactive collections (add/remove rows + count + empty-state)
+
+An add/remove-row list — line items, attachments, tags, comments, a
+notifications list — is one of the most common reactive surfaces, and every one
+re-implements the same orchestration by hand: append the row to the right
+container, remove it on delete, keep a **count badge** in sync, and swap an
+**empty-state** in/out as the list crosses 0↔1. `reactive_collection` declares
+that contract **once** on the container so each action is a single call.
+
+Declare the collection on the container component, then `reply.append` /
+`reply.prepend` / `reply.remove` in the actions:
+
+```ruby
+class NotificationsList < ApplicationComponent
+  include Phlex::Reactive::Streamable
+  include Phlex::Reactive::Component
+
+  reactive_collection :notifications,
+    item: NotificationRow,        # the per-row Streamable component
+    container: "notifications",    # the DOM id rows live in
+    count: "notifications-count",  # optional companion id (the size badge)
+    empty: NotificationsEmpty,     # optional empty-state component
+    size: -> { Todo.count }        # resolves the live size (re-counted, never client state)
+
+  action :add, params: {title: :string}
+  action :dismiss, params: {id: :integer}
+
+  def add(title:)
+    todo = Todo.create!(title:)
+    reply.append(:notifications, todo)   # append row + bump count + clear empty-state
+  end
+
+  def dismiss(id:)
+    Todo.find(id).destroy!
+    reply.remove(:notifications, id)     # remove row + bump count + restore empty-state at 0
+  end
+
+  # view_template renders the count, the container <ul>, and the empty-state on
+  # first paint — the same components the helper streams in/out on each delta.
+end
+```
+
+| Builder | Reply (one `Response`) |
+|---|---|
+| `reply.append(name, model)` | append the row into the container + update the count + remove the empty-state when the list crosses 0→1 |
+| `reply.prepend(name, model)` | as `append`, but the row goes to the top |
+| `reply.remove(name, model)` | remove the row by its `dom_id` + update the count + append the empty-state back when the list crosses →0 |
+
+- **`size:` is the source of truth** — it's *re-counted* server-side after the
+  mutation, so the badge and the empty-state are correct-by-construction (no
+  off-by-one, no client-held count). `count:`, `empty:`, and `size:` are all
+  optional: omit them and only the row stream is emitted.
+- **Repeated add/remove just works** — each reply rolls the **container's** signed
+  token forward (via the inert `reactive:token` refresh), so the second click from
+  the list root is accepted. Without this an add/remove list would be add-once-only
+  (correct on the first click, silently rejected after); the helper bakes the
+  refresh in so you never hit it.
+- **`remove` takes the record or its `dom_id` string** — a just-destroyed
+  ActiveRecord still answers `dom_id` correctly, so `reply.remove(:items, todo)`
+  works; pass the raw id only if your row `#id` matches `ActiveRecord::RecordIdentifier`.
+- **Reply governs the actor's HTTP response only.** For a *cross-tab* live list
+  (other viewers see the row appear) keep broadcasting the row with
+  `NotificationRow.broadcast_append_to(..., exclude: reactive_connection_id)` —
+  `reactive_collection` is the per-actor add/remove + count + empty-state wrapper,
+  not a replacement for the broadcast.
+
 ### Configuration (`config/initializers/phlex_reactive.rb`)
 
 ```ruby
@@ -638,6 +768,7 @@ See [docs/broadcasting.md](docs/broadcasting.md) and
 - [Broadcasting & live updates](docs/broadcasting.md)
 - [Transport: pgbus vs Action Cable](docs/transport-pgbus.md)
 - [Testing reactive components](docs/testing.md)
+- [Performance & benchmarking](docs/performance.md)
 - Examples: [counter](docs/examples/counter.md) ·
   [chat](docs/examples/chat.md) · [todo list](docs/examples/todo_list.md) ·
   [inline edit](docs/examples/inline_edit.md) ·