phlex-reactive 0.11.4 → 0.11.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dec3134e528500e32143217e96b93da16da30322cdf883017db367f645ab1c7d
-  data.tar.gz: ff6d5f992ea6cb7a5558a447f4256b9885170e4e27e1171c62ecf9c92ac221f6
+  metadata.gz: a7758f95f9e1a35e71bf870416d6e042367b7ca19bb2a1c3b618939e72aa5775
+  data.tar.gz: 2203a04fcf550a95e828945e56d06ed1b335fc430a1fdb8669f566893aa17c7d
 SHA512:
-  metadata.gz: 8952c2437efb9f8d3d8dafd86c2a09658a178ed657e2e4c632a45bc3be17f965f38d518348dd4b8c17609e7937a1793474b40e68db208cec83ef6f50ce28e4c3
-  data.tar.gz: aaddf4f15bd7aa7da26f74e4aca681e4c07c0c3baee62bb9107baf8ea5ab5e244a80b84baeec14fdad79935bede5bb0cf00d7796d4c82eac0f01ace5f916371a
+  metadata.gz: 311c87cf131ec0db83082089133b32dcc0583aa49203950ff59495929a2b512d72bedff7ced52747b2074bbce16a6b32eac99249e2b985cb19acfb9afce3a1ab
+  data.tar.gz: 5856533fe3e2207246082a56f6709d732f32db50b8a8c6f1e2f3c8bd74b0f5b2c2330440e0c2b4c9bc078d785d33b85e95ae22f7edc91f746df959f86819fa37

data/CHANGELOG.md

@@ -8,6 +8,53 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Turnkey APM adapters — `Phlex::Reactive.apm = :appsignal` (#207).** The gem
+  already emits `*.phlex_reactive` `ActiveSupport::Notifications` events (#107), but
+  every reactive action still POSTs to the same endpoint, so an APM rolled all
+  reactive traffic into one blurry `ActionsController#create` transaction and an
+  action-body crash surfaced as an anonymous 500. One config line closes both gaps:
+  - **`Phlex::Reactive.apm = :appsignal` (or `:sentry`, `:datadog`, or a custom
+    object)** names each action as its own `Component#action` transaction/span in the
+    APM, tagged with the component, action, and outcome. The vendor SDK is
+    **runtime-detected** (`defined?(::Appsignal)` …) — never a gemspec dependency, the
+    same optionality invariant as pgbus — so a set-but-absent SDK logs one warning and
+    no-ops. A custom object need only respond to `record_action(payload, duration_ms)`
+    and `record_error(error, payload)`.
+  - **Action-body errors are reported with context.** A previously-uncaught error from
+    an action body (a genuine 500, not a registered 4xx) is now OBSERVED at the
+    endpoint: the `action.phlex_reactive` event is tagged `outcome: :error` (filling the
+    #107 nil-outcome gap), the exception is reported to the APM adapter AND every
+    registered `Phlex::Reactive.on_action_error { |error, ctx| … }` hook WITH the
+    name-only `{ component:, action: }` context, the `error_flash` renders so the actor
+    sees a flash on a crash (500s now flow through the same path the 4xx errors used) —
+    and THEN the error is **re-raised unchanged**, so Rails' own error reporting and the
+    app's middleware fire exactly as before. Each reporter is isolated: a broken reporter
+    (or a raising `error_flash` lambda) can never turn one 500 into a different 500 or
+    swallow the original. The status never changes; the existing 4xx rescues, their
+    statuses, and their outcomes (`invalid_token`/`denied_undeclared`/`not_found`/
+    `unauthorized`/`unverified`) are untouched. Payloads and error tags stay name-only —
+    never the token, params, or state.
+
+- **Draft nested-attribute rows — the "new parent + child rows" form (#208).**
+  A collection whose PARENT isn't persisted yet (a new order accumulating line
+  items) can't be a reactive collection — an unsaved parent has no gid to sign.
+  The pre-save window is now a client-side primitive, the `reactive_tags`
+  posture: `reactive_nested_list(:assoc)` / `reactive_nested_template(:assoc)`
+  mark the container + the server-owned `<template>` holding ONE row's markup;
+  `reactive_nested_add(:assoc)` clones it, swapping every `NEW_ROW` placeholder
+  in the clone's `name`/`id`/`for` for a fresh unique index (clock-seeded
+  monotonic — server-rendered `0..n` and same-millisecond double clicks can't
+  collide) and focusing the new row's first field; `reactive_nested_remove`
+  deletes a draft row from the DOM, or `_destroy`-marks + hides a row carrying
+  a hidden `[_destroy]` input (an edit form's persisted row) so Rails destroys
+  it on save. `nested_field_name(:assoc, :field, index:)` builds the
+  scope-aware Rails wire name (`order[line_items_attributes][i][quantity]`).
+  Zero round trips, no token (works in a `ClientBindings` component); the REAL
+  form submit reconciles parent + rows in ONE request via
+  `accepts_nested_attributes_for`. Several collections can share a root
+  (association-keyed); the row markup is authored ONCE and serves the template,
+  server-rendered edit rows, and the persisted `reactive_collection` flow.
+
 - **`reactive_tags` — the tag-chip input primitive (#203).** The composed
   combobox/tags widget (preload suggestions, type to narrow, Enter/click to add,
   remove chips) with zero bespoke JavaScript and zero round trips. The value is
@@ -67,6 +114,16 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **A draft (unsaved-parent) token can now round-trip real server actions (#208).**
+  `Component::Identity` already signed a gid-less `{c, state}` token for an
+  unpersisted (or nil) record, but `from_identity` still `fetch`ed the absent
+  `gid` — the FIRST action against a draft crashed with an uncaught `KeyError`
+  (500). It now rebuilds through the record kwarg's **initialize default**
+  (e.g. `def initialize(order: Order.new, …)`), with the declared
+  `reactive_state` riding the token as before; a component whose initialize
+  REQUIRES the record kwarg raises a guided `Phlex::Reactive::Error` naming the
+  fix instead of a bare missing-keyword `ArgumentError`.
+
 - **`have_reactive_value` now reads the field's `.value` property, so it can verify a
   reducer-set disabled/computed field (#204).** The matcher (added in #201) delegated to
   Capybara's `have_field(with:)`, which matches the value **attribute** — but a

data/README.md

@@ -396,6 +396,9 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `reactive_compute :name, ..., mirror: { sum: "#summary-sum" }` | **Cross-root text mirrors**: paint a compute value into declared, id-allowlisted nodes **outside** the reactive root (a recap in another tab pane) via `textContent` — no bespoke listener. See [Cross-root mirrors](#cross-root-mirrors-mirror--painting-a-recap-outside-the-root). |
 | `reactive_dirty` / `reactive_dirty warn_unsaved: true` / `reactive_dirty only: %i[...]` | **Dirty tracking**, declared once at the class level, against the DOM's own `defaultValue`/`defaultChecked`/`defaultSelected` — no client state. Marks changed fields + the root `data-reactive-dirty`; `warn_unsaved:` arms a `beforeunload`/`turbo:before-visit` guard; `only:` scopes tracking to named fields. Style with `[data-reactive-dirty]`. See [Dirty-field tracking](#dirty-field-tracking-reactive_dirty). |
 | `nested_update!(:assoc, attrs)` | Map a nested param onto `<assoc>_attributes` with id preservation; update the record. |
+| `reactive_nested_list(:assoc)` / `reactive_nested_template(:assoc)` / `reactive_nested_row` | **Draft nested-attribute rows** (the "new parent + child rows" form): the container rows land in, the `<template>` holding ONE row's markup, and the row wrapper marker — all **client-only** form state, keyed by association (several collections per root). See [Draft rows for a new parent](#draft-rows-for-a-new-parent-reactive_nested_). |
+| `reactive_nested_add(:assoc)` / `reactive_nested_remove` | The row triggers, client-only (zero round trips): add clones the template and renumbers its placeholder index; remove deletes a draft row from the DOM, or `_destroy`-marks + hides a persisted row (a hidden `[_destroy]` input present). |
+| `nested_field_name(:assoc, :field, index: nil)` | The Rails `accepts_nested_attributes_for` wire name for one row field — `order[line_items_attributes][NEW_ROW][quantity]` (the template placeholder) by default, a real index when given. Scope-aware under `reactive_scope`. |
 | `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(*)` / `.js(ops)` | Return from an action to control the reply (flash, remove, redirect, multi-stream, server-pushed client ops). 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). |
@@ -1252,6 +1255,92 @@ The styled, form-builder-integrated version of this widget (label/errors/
 theming) belongs in your form layer — these helpers are deliberately the
 unstyled primitives, like `reactive_filter` before them.
 
+### Draft rows for a new parent (`reactive_nested_*`)
+
+The "new order + line items" form: the user builds up child rows **before the
+parent exists**. An unsaved parent has no GlobalID to sign, so this pre-save
+window can't be a reactive collection — and every app ends up hand-writing the
+same imperative JS (clone a row, renumber indexes, serialize on submit).
+`reactive_nested_*` is that pattern as a primitive, the `reactive_tags`
+posture: the rows are **form state**, add/remove run **entirely client-side**
+(zero round trips, no token — works in a `ClientBindings` component), and the
+surrounding **real form submit** posts standard Rails
+`parent[assoc_attributes][<index>][field]` names, so
+`accepts_nested_attributes_for` creates the parent + rows in **one request**.
+
+```ruby
+class DraftOrderForm < ApplicationComponent
+  include Phlex::Reactive::ClientBindings
+
+  reactive_scope :order   # names post as order[line_items_attributes][…]
+
+  def view_template
+    div(**reactive_root(id: "draft_order_form")) do
+      form(action: orders_path, method: "post", data: { turbo: "false" }) do
+        input(**reactive_field(:total, type: "number", value: "0"))
+
+        div(**reactive_nested_list(:line_items)) { }             # rows land here
+        template(**reactive_nested_template(:line_items)) { row_fields }
+        button(**reactive_nested_add(:line_items)) { "Add item" }
+
+        button(type: "submit") { "Create order" }
+      end
+    end
+  end
+
+  private
+
+  # ONE row's markup, authored once. The default renders the template
+  # prototype (NEW_ROW placeholder names — the client swaps in a fresh index
+  # per add); pass index: to server-render an edit form's persisted rows.
+  def row_fields(index: nil)
+    kwargs = index.nil? ? {} : { index: }
+    div(**reactive_nested_row) do
+      input(name: nested_field_name(:line_items, :quantity, **kwargs), type: "number")
+      input(name: nested_field_name(:line_items, :price, **kwargs), type: "number")
+      button(**reactive_nested_remove) { "×" }
+    end
+  end
+end
+```
+
+```ruby
+# The model + controller side is plain Rails — the reconcile is one create:
+class Order < ApplicationRecord
+  has_many :line_items, dependent: :destroy
+  accepts_nested_attributes_for :line_items, allow_destroy: true
+end
+
+Order.create!(params.require(:order).permit(:total,
+  line_items_attributes: %i[id quantity price _destroy]))
+```
+
+Clicking add clones your `<template>` row and swaps every `NEW_ROW` in the
+clone's `name`/`id`/`for` attributes for a fresh unique index (clock-seeded and
+strictly monotonic — server-rendered `0..n` indexes and same-millisecond double
+clicks can't collide), then focuses the new row's first field. Remove on a
+draft row deletes it from the DOM — it was never persisted, so removing its
+fields *is* the removal. Remove on a row carrying a hidden `[_destroy]` input
+(an **edit** form's persisted row, rendered with `nested_field_name(:line_items,
+:_destroy, index: i)`) marks it `"1"` and hides the row instead — Rails destroys
+it on save. Several collections can share one root (everything is keyed by the
+association name); nesting a collection inside another's template is not
+supported.
+
+Two boundaries to respect: the DOM is the single source of truth for unsent
+draft rows, so a **server re-render of the root replaces them** — keep
+replace-shaped actions out of a root holding unsent rows. And once the parent
+is saved, the persisted flow takes over: the same row markup renders with real
+indexes, or the list graduates to a [reactive collection](#reactive-collections-addremove-rows--count--empty-state)
+(`reactive_collection` + `reply.append`/`reply.remove`).
+
+Relatedly, a **draft parent can now run real server actions too** (issue #208):
+an unsaved record signs a gid-less `{c, state}` token, and the endpoint rebuilds
+the component through the record kwarg's **initialize default** —
+`def initialize(order: Order.new, …)` — with the declared `reactive_state`
+riding the token. A component whose initialize *requires* the record kwarg
+raises a guided error on the first draft action, telling you to add the default.
+
 **Combining `on(...)` / `reactive_attrs` with your own attributes.** Both return
 a hash that includes a `data:` key. Spreading them *and* passing another `data:`
 (or `class:`, `id:`) would clobber it — use Phlex's `mix` to deep-merge. For the
@@ -2002,10 +2091,11 @@ Phlex::Reactive.action_path = "/_r/actions"
 Phlex::Reactive.verbose_errors = true
 
 # User-visible flash on endpoint failures (default nil = off). When set, every
-# rescue path (400/403/404) ALSO renders a turbo-stream flash the user sees — at
-# the SAME status it returns today (statuses never change). The lambda receives
-# the failure kind (:tampered/:unknown_class/:not_reactive_class/:forbidden/
-# :not_found), so you can map it to a friendly message:
+# rescue path (400/403/404 AND a 500 crash) ALSO renders a turbo-stream flash the
+# user sees — at the SAME status it returns today (statuses never change). The
+# lambda receives the failure kind (:tampered/:unknown_class/:not_reactive_class/
+# :forbidden/:not_found, or :error for an action-body crash), so you can map it to
+# a friendly message:
 Phlex::Reactive.error_flash = ->(kind) do
   case kind
   when :not_found  then "That item is no longer available."
@@ -2014,6 +2104,17 @@ Phlex::Reactive.error_flash = ->(kind) do
   end
 end
 
+# Turnkey APM integration. Names each action Component#action in AppSignal/Sentry/
+# Datadog and reports action-body crashes with component/action tags. SDK is
+# runtime-detected (no gem dependency); a custom object responding to
+# record_action/record_error works too. See "Observability" above.
+Phlex::Reactive.apm = :appsignal
+
+# Report action-body crashes to any tracker yourself (the DIY escape hatch):
+Phlex::Reactive.on_action_error do |error, ctx|
+  Honeybadger.notify(error, context: { component: ctx[:component], action: ctx[:action] })
+end
+
 # Component-aware wrapper around every action (audit / rate-limit / assert).
 # Sees the resolved component, action name, and COERCED params; runs inside
 # the connection-id scope but OUTSIDE the transaction. See "Two seams" below.
@@ -2293,6 +2394,50 @@ The events fire whether or not you enable the LogSubscriber; the flag only
 controls the gem's own log lines. See
 [docs/performance.md](https://phlex-reactive.zoolutions.llc/docs/performance).
 
+### Turnkey APM adapters (AppSignal, Sentry, Datadog)
+
+Subscribing by hand is the DIY path. For the common trackers there's a one-liner
+that both names the transaction and reports errors — so reactive traffic stops
+rolling into one blurry `ActionsController#create` and a crash arrives at your
+tracker with context:
+
+```ruby
+# config/initializers/phlex_reactive.rb
+Phlex::Reactive.apm = :appsignal   # or :sentry, :datadog, or a custom object
+```
+
+With it set:
+
+- Each reactive action shows in the APM as its OWN transaction/span —
+  `Counter#increment`, not `Phlex::Reactive::ActionsController#create` — tagged
+  with the component, action, and outcome.
+- An action body that raises a genuine error (a 500, not a registered 4xx) is
+  **reported to the tracker with `component`/`action` tags**, then re-raised
+  unchanged so Rails' own error reporting still fires.
+
+The SDK is **runtime-detected** — no gem dependency is added. If the named SDK
+isn't loaded, `apm =` logs one warning at boot and no-ops (the same optionality
+invariant as pgbus). A custom object works too — anything responding to
+`record_action(payload, duration_ms)` and `record_error(error, payload)`.
+
+For a tracker with no built-in adapter, report errors yourself — this hook fires
+on any previously-uncaught action-body error, with the name-only context:
+
+```ruby
+Phlex::Reactive.on_action_error do |error, ctx|
+  Honeybadger.notify(error, context: { component: ctx[:component], action: ctx[:action] })
+end
+```
+
+And to show the user a flash when an action crashes (the SAME hook the 4xx errors
+already use — `kind` is `:error` for a crash):
+
+```ruby
+Phlex::Reactive.error_flash = ->(kind) { "Something went wrong — please retry." }
+```
+
+See [docs/observability.md](https://phlex-reactive.zoolutions.llc/docs/observability).
+
 ### Client debug mode (devtools-lite)
 
 The `LogSubscriber` above is the **server** lens. The client lens is

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -96,6 +96,13 @@ module Phlex
       rescue *authorization_errors => e
         event[:outcome] = :unauthorized
         reactive_error(:forbidden, deferred_authorization_message(e, component_class), kind: :forbidden)
+      rescue => e # rubocop:disable Style/RescueStandardError
+        # Issue #207, the defer (read) leg: a render that raises uncaught is
+        # OBSERVED (tag + report + flash) then re-raised unchanged, mirroring the
+        # action leg. The defer payload has no `action:` — report_error/the
+        # adapters treat a nil action gracefully (transaction is the component).
+        report_action_error(e, event)
+        raise
       end
 
       def verified_defer_payload
@@ -156,6 +163,42 @@ module Phlex
       rescue *authorization_errors => e
         event[:outcome] = :unauthorized
         reactive_error(:forbidden, authorization_error_message(e, component_class, action_def), kind: :forbidden)
+      rescue => e # rubocop:disable Style/RescueStandardError
+        # Turnkey APM error reporting (issue #207). A previously-UNCAUGHT
+        # action-body error — NOT one of the specific 4xx cases above (those still
+        # win by ordering) — is OBSERVED here and then re-raised UNCHANGED, so
+        # Rails' own error reporting and the app's middleware fire exactly as
+        # today. The status never changes: this catch adds no new 4xx.
+        #   1. tag the event outcome (fills the #107 nil-outcome gap),
+        #   2. report to the APM adapter + on_action_error hooks WITH the name-only
+        #      component/action context (each reporter isolated — see report_error),
+        #   3. render the error_flash for the crash so the actor SEES a flash (500s
+        #      now flow through the same error_flash path 4xx already used), THEN
+        #   4. re-raise. The flash is built but MUST NOT swallow the raise.
+        report_action_error(e, event)
+        raise
+      end
+
+      # OBSERVE a previously-uncaught action-body error (issue #207) without
+      # altering what propagates. Tag the outcome, fan the error out to the APM
+      # adapter + on_action_error hooks (report_error isolates each reporter), and
+      # render the error_flash for the crash. Every step is best-effort and MUST
+      # NOT raise (the caller re-raises the ORIGINAL error immediately after): a
+      # broken reporter is swallowed inside report_error; the flash render is
+      # guarded here. The flash reuses the SAME 4xx machinery — error_flash_stream
+      # degrades to nil on its own failure, and we render at :internal_server_error
+      # so the body (if any) matches the 500 the re-raise ultimately yields.
+      def report_action_error(error, event)
+        event[:outcome] = :error
+        Phlex::Reactive.report_error(error, event)
+
+        flash = error_flash_stream(:error)
+        render turbo_stream: flash, status: :internal_server_error if flash
+      rescue => e # rubocop:disable Style/RescueStandardError
+        # The observation path itself failed — log it, but NEVER let it replace the
+        # action-body error the caller is about to re-raise.
+        ::Rails.logger&.warn("[phlex-reactive] error observation failed: #{e.class}: #{e.message}") if
+          defined?(::Rails) && ::Rails.respond_to?(:logger)
       end
 
       # Reply to an endpoint failure. The status NEVER changes with any flag —

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

@@ -1137,6 +1137,11 @@ export default class extends Controller {
   // missing-template warning latch.
   #boundSyncTags
   #tagsWarnedTemplate = false
+  // Draft nested-attribute rows (issue #208): the strictly-monotonic index
+  // counter (clock-seeded so it never collides with server-rendered 0..n
+  // indexes) plus the once-only missing-list/template warning latch.
+  #nestedIndex = 0
+  #nestedWarned = false
   // Connect-time compute seed (issue #199): the bound re-seed attached to
   // turbo:morph-element so an in-place morph re-runs the compute, held for teardown.
   #boundSeedCompute
@@ -1793,6 +1798,67 @@ export default class extends Controller {
     this.#tagsWrite(field, next)
   }
 
+  // Draft nested-attribute rows (issue #208) — the "new parent + child rows"
+  // window. The rows are FORM state (the reactive_tags posture): no token, no
+  // POST, ever — the surrounding REAL form submit carries Rails'
+  // accepts_nested_attributes_for names and the server reconciles parent +
+  // rows in ONE create. Add clones the association's server-owned
+  // <template data-reactive-nested-template="assoc"> row, swaps every NEW_ROW
+  // in the clone's name/id/for for a fresh unique index (each row posts as its
+  // own `…_attributes[<index>][field]` group), appends it to the owned
+  // [data-reactive-nested-list="assoc"] container, and focuses the new row's
+  // first field. Several collections can share one root — everything is keyed
+  // by the association name the trigger carries.
+  nestedAdd(event) {
+    event?.preventDefault?.()
+    const trigger = event?.currentTarget ?? event?.target
+    const assoc = trigger?.getAttribute?.("data-reactive-association-param")
+    if (!assoc) return
+    if (typeof this.element?.querySelectorAll !== "function") return
+
+    const owns = this.#ownershipFilter()
+    const list = [...this.element.querySelectorAll(`[data-reactive-nested-list="${assoc}"]`)].find(owns)
+    const template = [...this.element.querySelectorAll(`[data-reactive-nested-template="${assoc}"]`)].find(owns)
+    const proto = template?.content?.firstElementChild
+    if (!list || !proto) {
+      this.#warnNestedOnce(assoc)
+      return
+    }
+
+    const row = proto.cloneNode(true)
+    this.#renumberNestedRow(row, this.#nextNestedIndex())
+    list.appendChild(row)
+    const first = [...(row.querySelectorAll?.("input, select, textarea") ?? [])][0]
+    first?.focus?.()
+  }
+
+  // Remove the trigger's closest row wrapper. A DRAFT row (no [_destroy]
+  // input) leaves the DOM — it was never persisted, so removing its fields IS
+  // the removal. A PERSISTED row (an edit form rendered a hidden [_destroy]
+  // input via nested_field_name) is marked "1" and hidden instead — Rails
+  // destroys it on save. The mark dispatches a real bubbling `input` (the
+  // set-value + dispatch contract, issue #183) so dirty tracking/compute see it.
+  nestedRemove(event) {
+    event?.preventDefault?.()
+    const trigger = event?.currentTarget ?? event?.target
+    const row = trigger?.closest?.("[data-reactive-nested-row]")
+    if (!row) return
+    // The closest() walk must not escape this root — a root can itself sit
+    // inside ANOTHER collection's row (the issue #15 closest-form posture).
+    if (row.closest?.('[data-controller~="reactive"]') !== this.element) return
+
+    const destroy = [...(row.querySelectorAll?.('input[name$="[_destroy]"]') ?? [])][0]
+    if (destroy) {
+      destroy.value = "1"
+      if (typeof destroy.dispatchEvent === "function") {
+        destroy.dispatchEvent(new Event("input", { bubbles: true }))
+      }
+      row.hidden = true
+    } else {
+      row.parentNode?.removeChild?.(row)
+    }
+  }
+
   // Parse a JSON string list from a root data attr; [] on absence/parse error so
   // a malformed binding degrades to "no fields" rather than throwing on input.
   #parseComputeList(attr) {
@@ -3180,6 +3246,39 @@ export default class extends Controller {
     if (this.#filterEnabled()) this.#syncFilter()
   }
 
+  // A fresh index per nested-row add (issue #208) — strictly monotonic and
+  // clock-seeded, so it can never collide with server-rendered integer indexes
+  // (0..n) NOR with a rapid same-millisecond double add.
+  #nextNestedIndex() {
+    this.#nestedIndex = Math.max(this.#nestedIndex + 1, Date.now())
+    return this.#nestedIndex
+  }
+
+  // Swap every NEW_ROW in the clone's name/id/for for the fresh index, so the
+  // row posts as its own `…_attributes[<index>][field]` group and labels keep
+  // pointing at their (renumbered) inputs.
+  #renumberNestedRow(row, index) {
+    const nodes = [row, ...(row.querySelectorAll?.("*") ?? [])]
+    for (const el of nodes) {
+      for (const attr of ["name", "id", "for"]) {
+        const value = el.getAttribute?.(attr)
+        if (value && value.includes("NEW_ROW")) el.setAttribute?.(attr, value.replaceAll("NEW_ROW", String(index)))
+      }
+    }
+  }
+
+  // A half-built nested-rows binding should be loud, but never per-click.
+  #warnNestedOnce(assoc) {
+    if (this.#nestedWarned) return
+    console.warn(
+      `[phlex-reactive] nested rows: no owned [data-reactive-nested-list="${assoc}"] container + ` +
+        `<template data-reactive-nested-template="${assoc}"> pair found in this root — the add ` +
+        "trigger did nothing. Render both inside the same reactive root (reactive_nested_list / " +
+        "reactive_nested_template)."
+    )
+    this.#nestedWarned = true
+  }
+
   // Remove the tags morph listener on disconnect, so a stray morph event after
   // the element leaves the DOM never re-projects against a detached root.
   #teardownTagsSync() {