phlex-reactive 0.13.4 → 0.14.0

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

@@ -27,6 +27,8 @@ module Phlex
       wrap_parameters false if respond_to?(:wrap_parameters)
 
       def create
+        return materialize if reactive_action_name == Phlex::Reactive::Component::Lazy::MATERIALIZE_ACTION
+
         # ONE action.phlex_reactive event per request (issue #107). The event
         # payload carries the component/action NAMES + outcome ONLY (never the
         # token, params, or state); we fill it as those become known and set
@@ -48,7 +50,11 @@ module Phlex
         Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
           Phlex::Reactive.with_defer_binding(Phlex::Reactive.defer_binding_for(request)) do
             Phlex::Reactive.instrument("action", event) do
-              create_action(event)
+              # The actor's reply renders dormant roots AWAKE (issue #274): this
+              # page's controller is loaded, so a dormant replacement would only
+              # cost one more wake. Broadcasts fired inside the action are
+              # exempted at their render, like the url_options above.
+              Phlex::Reactive::Dormant.awake { create_action(event) }
             end
           end
         end
@@ -84,22 +90,62 @@ module Phlex
 
       private
 
+      # `__materialize` (issue #276): a reactive_lazy(on:) shell's trigger. It
+      # arrives on the ACTION endpoint with the identity token (no TTL — the
+      # shell may sit in a page far longer than defer_token_ttl), but it is a
+      # READ: no action runs, no transaction opens, no params are read. It
+      # renders exactly what the defer endpoint renders, through the same
+      # authorization step, and is instrumented as a defer. Routed here before
+      # the action registry is consulted; `action :__materialize` is refused at
+      # declaration, so it can't be shadowed. CSRF/auth come from the base
+      # controller exactly as for any action.
+      def materialize
+        event = { component: nil, outcome: nil }
+        Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
+          Phlex::Reactive.instrument("defer", event) do
+            render_real_component(event, permit: :reactive_lazy_trigger, empty: :stream) { verified_payload }
+          end
+        end
+      end
+
       # The defer body, mirroring create_action's shape: fill the event payload
       # on every exit path, reuse the shared rescue → reactive_error plumbing.
       def deferred_action(event)
-        payload = verified_defer_payload
+        render_real_component(event) { verified_defer_payload }
+      end
+
+      # The lazy/defer READ leg, shared by the defer endpoint and __materialize
+      # (and the seam for any other signed-identity → real-render route). The
+      # block verifies and returns the payload INSIDE this method's rescues, so
+      # every token failure maps the same way. `permit:` names a class-level
+      # predicate the component must answer truthy (default-deny for an opt-in
+      # route); `empty:` picks the render? false reply — :no_content for the
+      # defer client (it clears pending on 204), :stream (an empty turbo-stream)
+      # for the action client, which treats a non-stream body as an error.
+      # `denied:` is the status for a class that fails `permit:` — :forbidden for
+      # an undeclared act, :not_found for a GET route the class never opted into.
+      def render_real_component(event, permit: nil, empty: :no_content, denied: :forbidden)
+        payload = yield
         component_class = resolve_component(payload["c"])
         event[:component] = component_class.name
+
+        if permit && !(component_class.respond_to?(permit) && component_class.public_send(permit))
+          event[:outcome] = :denied_undeclared
+          return reactive_error(denied, unpermitted_render_message(component_class), kind: denied)
+        end
+
         component = component_class.from_identity(payload)
 
         if component.respond_to?(:render?) && !component.render?
           event[:outcome] = :no_content
-          return head :no_content
+          return empty == :stream ? render(turbo_stream: "") : head(:no_content)
         end
 
         event[:outcome] = :ok
-        stream = component.to_stream_replace(morph: payload["m"] == "morph")
-        render turbo_stream: stream
+        # Awake (issue #274): the client that asked for this render is loaded
+        # and connected, so a dormant root would only cost one more wake.
+        stream = Phlex::Reactive::Dormant.awake { component.to_stream_replace(morph: payload["m"] == "morph") }
+        render_real_stream(stream, component)
       rescue Phlex::Reactive::InvalidToken => e
         event[:outcome] = :invalid_token
         reactive_error(:bad_request, e.message, kind: e.diagnostic || :tampered)
@@ -118,6 +164,12 @@ module Phlex
         raise
       end
 
+      # The read leg's success reply. A seam: the fragment endpoint (issue #277)
+      # overrides it to add its cache headers and conditional GET.
+      def render_real_stream(stream, _component)
+        render turbo_stream: stream
+      end
+
       def verified_defer_payload
         token = params.require(:token)
         Phlex::Reactive.verify_defer(token) || raise(Phlex::Reactive::InvalidToken.new(
@@ -127,6 +179,11 @@ module Phlex
         ))
       end
 
+      def unpermitted_render_message(component_class)
+        "#{component_class.name} is not reactive_lazy(on:) — __materialize is the lazy shell's " \
+          "trigger, not a declarable action"
+      end
+
       def deferred_authorization_message(error, component_class)
         "#{error.class.name} raised rebuilding/rendering #{component_class&.name} for a deferred " \
           "segment — the signature proves identity, not permission"
@@ -563,22 +620,32 @@ module Phlex
         coerced
       end
 
-      # Issue #184: a scoped component's fields POST bracketed (todo[title]), which
-      # Rails expands to { "todo" => { "title" => … } } before the action runs. Peel
+      # Issue #184: a scoped component's fields POST bracketed (todo[title]); peel
       # exactly ONE scope level so the FLAT schema { title: :string } matches (the
       # #67 bracket-drop footgun). Only when the component declares reactive_scope
-      # AND the raw params carry that single key mapping to a Hash — otherwise the
-      # raw params pass through untouched (unscoped components + nested_attributes
-      # shapes are unaffected).
+      # AND the scope key maps to a Hash — otherwise the params pass through
+      # (unscoped components + nested_attributes shapes are unaffected).
+      #
+      # Issue #337: expand the bracketed keys FIRST. A multipart body arrives
+      # expanded (Rails parses the brackets), but the client's default JSON body
+      # keeps "todo[title]" as one literal key, so a peel that looked for "todo"
+      # before expanding found nothing and the flat schema dropped every field.
+      #
+      # Bare siblings of the scope key (a trigger's on(:save, note: "x") param,
+      # an unscoped file input) stay beside the peeled fields on BOTH encodings;
+      # a bare param wins a collision, as an explicit on() param wins over a
+      # collected field on the client (runtime.js allParams). Still only the declared schema reaches
+      # the action — the peel moves keys, coerce decides what survives.
       def unwrap_scope(raw, component_class)
         scope = reactive_scope_of(component_class)
         return raw unless scope
 
-        # At the endpoint `raw` is ActionController::Parameters, so `raw[scope]` is
-        # too — NOT a Hash. Accept either shape (both answer to the schema's
-        # coerce): unwrap only when the scope key maps to a nested params/hash.
-        nested = raw[scope.to_s]
-        nested.is_a?(Hash) || nested.is_a?(ActionController::Parameters) ? nested : raw
+        expanded = Phlex::Reactive::ParamSchema.expand(raw)
+        nested = expanded[scope.to_s]
+        return expanded unless nested.is_a?(Hash)
+
+        expanded.delete(scope.to_s)
+        nested.merge(expanded)
       end
 
       # Issue #258: a form body cannot carry an empty array, so the client
@@ -609,7 +676,9 @@ module Phlex
           # nesting the group under it. `dropped` is nil unless verbose_errors.
           next dropped&.<<(["empty_groups #{it}", ANNOUNCED_UNDECLARED]) unless key
 
-          raw[key] = [] unless raw.key?(key)
+          # String-keyed: a scoped `raw` is the expanded plain Hash (no
+          # indifferent access), and `key` is the declaration's (often a Symbol).
+          raw[key.to_s] = [] unless raw.key?(key.to_s)
         end
         raw
       end

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

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The privately cacheable lazy render (issue #277):
+    #
+    #   GET <Phlex::Reactive.fragment_path>/<signed id>[?v=<version>][&u=<viewer>]
+    #
+    # renders a `reactive_lazy cache: { max_age: }` component's REAL template as
+    # its replace stream, with `Cache-Control: private, max-age=<n>` and an
+    # ETag, so the browser reuses it instead of asking again.
+    #
+    # It is a READ, the defer endpoint's twin: the id is verified, the component
+    # is rebuilt from its signed identity and rendered through the same
+    # authorization step (the base controller's auth, then whatever
+    # from_identity / the render raise). No action runs, no around_action
+    # wrapper, no transaction, no params reach the render — `v` and `u` only
+    # shape the browser's cache key. Subclassing ActionsController shares that
+    # read leg and its error plumbing; only the token, the opt-in gate and the
+    # reply's headers differ.
+    #
+    # What keeps a private cache safe here:
+    #   * the id names no viewer — who it renders for always comes from the session;
+    #   * only a component that declared `cache:` is reachable (404 otherwise);
+    #   * a cached copy is never replayed to another viewer: by default the
+    #     reply says `Vary: Cookie`; a component that names its viewer
+    #     (reactive_cache_viewer) is keyed on it in the URL instead, and the
+    #     reply is cacheable only when that URL names the viewer of THIS session;
+    #   * the reply is cacheable ONLY on the success path; every other response
+    #     this controller produces — including one a base-controller filter
+    #     rendered before the action ran — is `no-store`;
+    #   * a cacheable reply carries no Set-Cookie: an unchanged session is not
+    #     re-issued, and a request that changed the session or wrote any cookie
+    #     — in any callback, before or after the action, or in one of the
+    #     writes Rails defers until the controller has returned (see
+    #     commit_deferred_writes) — is not cacheable;
+    #   * a render whose markup has a field or meta NAMED like a CSRF token
+    #     (`name="authenticity_token"`, `name="csrf-token"`, or the controller's
+    #     request_forgery_protection_token) is not made cacheable. A name match
+    #     only: a token placed anywhere else is not detected.
+    class FragmentsController < ActionsController
+      # The names a CSRF token is rendered under (a form's hidden field, or
+      # csrf_meta_tags), besides the controller's own
+      # request_forgery_protection_token. Cached, such a token would outlive
+      # the session it was minted for.
+      CSRF_TOKEN_NAMES = %w[authenticity_token csrf-token].freeze
+      # One compiled pattern per forgery-protection field name (it is a
+      # class-level setting, so in practice one entry), not one per request.
+      CSRF_TOKEN_PATTERNS = Concurrent::Map.new
+
+      # Stands in for the response when asking the cookie jar what it WOULD
+      # write (CookieJar#write calls set_cookie / delete_cookie per pending
+      # write), so pending writes are read through the jar's own public method.
+      class CookieWrites < ::Hash
+        def set_cookie(name, *) = store(name.to_s, :set)
+        def delete_cookie(name, *) = store(name.to_s, :delete)
+      end
+
+      def show
+        event = { component: nil, outcome: nil }
+        Phlex::Reactive.with_url_options(Phlex::Reactive.url_options_for(request)) do
+          Phlex::Reactive.instrument("defer", event) do
+            render_real_component(event, permit: :reactive_lazy_cache, denied: :not_found) do
+              verified_fragment_payload
+            end
+          end
+        end
+      end
+
+      private
+
+      # Wraps the WHOLE action — every before/around/after callback included —
+      # so the cacheability decision is made last: a response the base
+      # controller's filters produced (a 401, a redirect to sign-in) is
+      # no-store, and so is a reply during which ANY callback wrote the session
+      # or a cookie, however late.
+      def process_action(*)
+        @session_before = begin
+          session_data
+        rescue StandardError
+          Object.new # unreadable: equal to nothing, so the reply stays no-store
+        end
+        super
+      ensure
+        settle_caching
+      end
+
+      # The single place a reply becomes cacheable: the success path asked for
+      # it AND this request leaves the browser's cookies exactly as they were.
+      def settle_caching
+        return forbid_caching unless @fragment_cacheable && !caching_forbidden? && cookies_untouched?
+
+        # Re-assert the policy: an inherited after_action may have LOOSENED it
+        # (expires_in …, public: true would let a shared cache keep a viewer's
+        # fragment) or overwritten the Vary. Tightening was honoured above.
+        apply_cache_policy
+        # Nothing changed, so don't re-issue the session: the cookie store
+        # would otherwise send a freshly encrypted Set-Cookie with this very
+        # reply — on a stored response, and changing the Cookie the next
+        # request sends (defeating `Vary: Cookie` within the page).
+        request.session_options[:skip] = true
+      end
+
+      def forbid_caching
+        response.cache_control.clear
+        response.headers["Cache-Control"] = "no-store"
+        response.headers.delete("ETag")
+      end
+
+      # Did the app itself forbid caching this reply — `no_store`, `expires_now`
+      # or a max-age of zero in a base-controller filter, or the header set by
+      # hand? The app may always tighten the policy; this endpoint only refuses
+      # to let it be loosened. (This endpoint's OWN max-age can be zero — a
+      # fragment_cache_max_age_limit of 0 — which is revalidate-always, not this.)
+      def caching_forbidden?
+        control = response.cache_control
+        return true if control[:no_store] || control[:no_cache]
+        return true if response.headers["Cache-Control"].to_s.match?(/\bno-(?:store|cache)\b/i)
+
+        app_max_age = app_cache_directives[:max_age]
+        !app_max_age.nil? && app_max_age.zero?
+      end
+
+      # What the app's own filters asked for, from expires_in (the response's
+      # cache_control hash) or a header set by hand: the smallest max-age, and
+      # whether must-revalidate was requested. Empty while the policy on the
+      # response is still exactly the one this endpoint applied — so its OWN
+      # max-age (which may be 0) is never mistaken for the app's.
+      def app_cache_directives
+        control = response.cache_control
+        header = response.headers["Cache-Control"].to_s
+        return {} if @applied_policy && control == @applied_policy && header.empty?
+
+        # EVERY max-age in a hand-set header counts (the smallest wins — never
+        # looser than what the app wrote), and a negative one means zero.
+        ages = [control[:max_age], *header.scan(/\bmax-age=(-?\d+)/i).flatten].compact.map { [it.to_i, 0].max }
+        { max_age: ages.min, must_revalidate: control[:must_revalidate] || header.match?(/\bmust-revalidate\b/i) }
+      end
+
+      # True only when it is KNOWN that this request writes no cookie: the
+      # session's data is what it was, it is not being renewed or dropped, and
+      # the cookie jar has no pending write or delete. Anything unreadable
+      # counts as touched — the reply fails closed.
+      def cookies_untouched?
+        options = request.session_options
+        return false if options[:renew] || options[:drop]
+        # A cookie written straight onto the response (response.set_cookie),
+        # which never passes through the jar.
+        return false if response.headers["Set-Cookie"].present?
+
+        commit_deferred_writes
+
+        session_data == @session_before && pending_cookie_writes.empty?
+      rescue StandardError
+        false
+      end
+
+      # Rails performs some session/cookie writes only AFTER the controller has
+      # returned — too late for the comparison in cookies_untouched?, and (the
+      # session being skipped on a cacheable reply) they would then be LOST.
+      # Each is pulled forward here, so it shows up in the comparison: the write
+      # is kept and the reply is not stored. All of them are idempotent — Rails
+      # running them again afterwards changes nothing.
+      #
+      # THIS LIST IS THE AUDIT of actionpack 7.1 – 8.1 (the versions the gemspec
+      # supports; identical in all of them) for writes made after process_action:
+      #
+      #   * ActionController::Metal#dispatch → request.commit_flash
+      #       writes session["flash"]: a flash set this request, or the sweep of
+      #       one that was read. A no-op when nothing loaded the flash.
+      #   * ActionDispatch::Session::AbstractStore#commit_session
+      #       → request.commit_csrf_token → the csrf_token_storage_strategy's
+      #       #store: a CSRF token handed out this request (form_authenticity_
+      #       token in a filter). SessionStore writes session[:_csrf_token];
+      #       CookieStore writes an encrypted cookie to the cookie JAR (so it
+      #       shows up as a pending cookie write). A no-op when no token was
+      #       asked for.
+      #       → then Rack's own commit: only persists the session, and honours
+      #       :renew / :drop — both checked in cookies_untouched?.
+      #   * ActionDispatch::Cookies (middleware) → cookie_jar.write(response)
+      #       nothing new: it flushes the jar's pending writes, which
+      #       pending_cookie_writes reads through that same method.
+      #   * Response#before_committed, Rack::ETag / ConditionalGet, the
+      #       permissions-policy middleware, request id, runtime, server timing
+      #       → response headers only; none touches the session or cookies.
+      #   * ActionDispatch::ContentSecurityPolicy::Middleware
+      #       → response headers, but it calls the APP's nonce generator after
+      #       the controller returned. The stock generator
+      #       (request.session.id.to_s) only reads. A generator that WRITES the
+      #       session is app code running outside the controller — see below.
+      #
+      # Not covered, and cannot be from here: a session write made outside the
+      # controller — third-party Rack middleware, or a CSP nonce generator that
+      # writes the session. Such a write is dropped on a cacheable reply.
+      def commit_deferred_writes
+        request.commit_flash
+        request.commit_csrf_token if request.respond_to?(:commit_csrf_token)
+      end
+
+      # The session's data without creating a session: {} when the request has
+      # none. Deep-copied, so an in-place change shows up.
+      def session_data
+        session = request.session
+        session.respond_to?(:exists?) && !session.exists? && !session.loaded? ? {} : session.to_h.deep_dup
+      end
+
+      # What the cookie jar will write when the response leaves — including a
+      # cookie re-set to the same value with a new expiry, and deletes.
+      def pending_cookie_writes
+        CookieWrites.new.tap { request.cookie_jar.write(it) }
+      end
+
+      def verified_fragment_payload
+        Phlex::Reactive.verify_fragment(params.require(:id)) || raise(Phlex::Reactive::InvalidToken.new(
+          "fragment id invalid — tampered, or a token of another purpose (identity and defer tokens " \
+          "do not resolve at the fragment endpoint)",
+          diagnostic: :tampered
+        ))
+      end
+
+      # The success reply: private, bounded, revalidatable — provisionally; see
+      # settle_caching. The ETag is derived from the rendered body (never from
+      # `v`/`u`), so a 304 is only ever answered for the exact render this
+      # viewer would get.
+      def render_real_stream(stream, component)
+        return render_uncacheable(stream, component.class) if stream.match?(csrf_token_markup)
+
+        viewer = component.send(:fragment_viewer_param)
+        # The URL must name exactly the viewer of THIS session — or nobody, when
+        # the session has none. Anything else (a page rendered before the viewer
+        # changed, a hand-built URL) still renders for this session, but must
+        # never be stored under another viewer's key.
+        return super unless ActiveSupport::SecurityUtils.secure_compare(viewer.to_s, params[:u].to_s)
+
+        # With no viewer named, the cookie is the only thing that tells two
+        # viewers apart; with one, the URL does (and was just checked).
+        @fragment_policy = { max_age: Phlex::Reactive::Fragment.max_age_for(component.class), vary: viewer.nil? }
+        # A filter that already forbade caching (an app-wide no_store) wins.
+        return super if caching_forbidden?
+
+        apply_cache_policy
+        render_conditional(stream)
+        # Only now: anything that raised above leaves the reply no-store.
+        @fragment_cacheable = true
+      end
+
+      # The conditional GET, with the ETag set from the BODY ALONE. Not
+      # stale?/fresh_when: those run the controller's etaggers, and Rails' own
+      # flash etagger LOADS the flash — which marks a pending flash as used, so
+      # a fragment GET would eat a notice meant for the next page view. (An
+      # app's `etag { }` blocks are skipped for the same reason; vary a cached
+      # fragment through reactive_cache_version / reactive_cache_viewer.)
+      def render_conditional(stream)
+        response.weak_etag = stream
+        request.fresh?(response) ? head(:not_modified) : render(turbo_stream: stream)
+      end
+
+      # A `name=` attribute, in any quoting, that names a CSRF token — the
+      # well-known names plus this controller's forgery-protection field.
+      def csrf_token_markup
+        # An API base controller has no forgery protection (and so no such
+        # setting): the built-in names alone are checked then.
+        token_name = respond_to?(:request_forgery_protection_token, true) ? request_forgery_protection_token.to_s : ""
+        CSRF_TOKEN_PATTERNS.compute_if_absent(token_name) do
+          names = (CSRF_TOKEN_NAMES | [token_name]).reject(&:empty?).map { Regexp.escape(it) }
+          /\bname\s*=\s*["']?(?:#{names.join("|")})(?![\w-])/i
+        end
+      end
+
+      # `private, max-age=<n>` plus Vary: Cookie in the default mode — tightened
+      # by whatever the app's filters asked for (a SHORTER max-age,
+      # must-revalidate), never loosened (public, s-maxage,
+      # stale-while-revalidate and a longer max-age are dropped). Applied before
+      # the render (the 304 carries it) and again after every callback ran
+      # (settle_caching).
+      def apply_cache_policy
+        app = app_cache_directives
+        @fragment_policy[:max_age] = [@fragment_policy[:max_age], app[:max_age]].compact.min
+        @fragment_policy[:must_revalidate] ||= app[:must_revalidate]
+        policy = { max_age: @fragment_policy[:max_age], public: false }
+        policy[:must_revalidate] = true if @fragment_policy[:must_revalidate]
+        response.headers.delete("Cache-Control")
+        response.cache_control.replace(policy)
+        @applied_policy = policy.dup
+        vary_on_cookie if @fragment_policy[:vary]
+      end
+
+      # Add Cookie to whatever the base controller or a middleware already
+      # varies on — replacing it could let the browser reuse the wrong variant.
+      def vary_on_cookie
+        fields = response.headers["Vary"].to_s.split(",").map(&:strip).reject(&:empty?)
+        response.headers["Vary"] = (fields | ["Cookie"]).join(", ")
+      end
+
+      def render_uncacheable(stream, component_class)
+        ::Rails.logger&.warn(
+          "[phlex-reactive] #{component_class.name} is reactive_lazy(cache:) but its render embeds a CSRF " \
+          "token (a form authenticity token or csrf_meta_tags) — served no-store: a cached token outlives its " \
+          "session. Read the token from the page's csrf-token meta tag at submit time, or drop cache:."
+        )
+        render turbo_stream: stream
+      end
+
+      def unpermitted_render_message(component_class)
+        "#{component_class.name} is not reactive_lazy(cache:) — only a component that opted in is " \
+          "reachable at the fragment endpoint"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+// phlex/reactive/core — the OPT-IN client: the reactive controller without
+// its feature modules, which it imports when a root on the page needs one
+// (issue #275). The default is phlex/reactive/reactive_controller: one file
+// with every feature inside, nothing imported later. An app imports ONE of
+// the two, never both.
+//
+// The controller itself is the shared runtime (runtime.js); the shipped
+// core.min.js is this file BUNDLED with it. All this entry adds is where each
+// feature module lives: one LITERAL import() per feature, by the bare
+// specifier the engine pins (phlex/reactive/features/<name>) — literal so a
+// bundler can see it and split the feature into its own chunk, bare so the
+// import map resolves it to that module's own digested file (issue #57).
+//
+// What the opt-in costs a page is documented in the README ("The split
+// client"): the first root that needs a feature waits for its import.
+import ReactiveController, {
+  loadReactiveFeature,
+  onReactiveStreamWithoutEffects,
+  registerReactiveDev,
+  registerReactiveFeatureLoader,
+  unloadedFeaturesFor,
+} from "phlex/reactive/runtime"
+
+registerReactiveFeatureLoader("persist", () => import("phlex/reactive/features/persist"), waitingForPersist)
+registerReactiveFeatureLoader("defer", () => import("phlex/reactive/features/defer"))
+registerReactiveFeatureLoader("form", () => import("phlex/reactive/features/form"))
+registerReactiveFeatureLoader("bindings", () => import("phlex/reactive/features/bindings"))
+registerReactiveFeatureLoader("compute", () => import("phlex/reactive/features/compute"), waitingForEdit)
+registerReactiveFeatureLoader("effects", () => import("phlex/reactive/features/effects"))
+registerReactiveFeatureLoader("hints", () => import("phlex/reactive/features/hints"))
+registerReactiveFeatureLoader("devtools", () => import("phlex/reactive/features/devtools"))
+// The runtime registered with Turbo before this file ran: now it knows where
+// the dev module is, a development page can have it.
+registerReactiveDev()
+
+// --- While the persist module is on its way ---------------------------------------
+// What the draft code must not miss while it is on its way: that the
+// user edited a field (the edit must be drafted once the module is here)
+// and that the form around the root was submitted successfully (the
+// draft must be forgotten, not restored). The feature listens for both
+// itself once it has connected.
+function waitingForPersist(root, pending) {
+  const edited = () => {
+    pending.edited = true
+  }
+  const submitted = (event) => {
+    const form = event.target
+    if (event.detail?.success && form?.tagName === "FORM" && form.contains?.(root)) pending.submitted = true
+  }
+  // (Lexical and Trix swallow the native `input` of their editor; their
+  // own bubbling change events are the keystroke signal.)
+  const edits = ["input", "change", "lexxy:change", "trix-change"]
+  for (const type of edits) root.addEventListener?.(type, edited)
+  document.addEventListener("turbo:submit-end", submitted)
+  return () => {
+    for (const type of edits) root.removeEventListener?.(type, edited)
+    document.removeEventListener("turbo:submit-end", submitted)
+  }
+}
+
+// --- While the compute module is on its way --------------------------------------
+// An edit the user made before the module could recompute: it runs one pass
+// when it connects, over the fields as the user left them.
+function waitingForEdit(root, pending) {
+  const edited = () => {
+    pending.edited = true
+  }
+  root.addEventListener?.("input", edited)
+  root.addEventListener?.("change", edited)
+  return () => {
+    root.removeEventListener?.("input", edited)
+    root.removeEventListener?.("change", edited)
+  }
+}
+
+// --- A stream that needs a module before it is loaded ------------------------------
+// A stream can bring the page's first use of a feature: a broadcast appends
+// the first dismissing flash, a reply removes a row with an exit effect or
+// swaps in a form with show bindings and tag chips. Stream effects are
+// document-level (features/effects.js) and an exit effect runs BEFORE the
+// render; a swapped-in root connects AFTER it and would start its import
+// then, showing the server's rendering until the module arrives. Both are
+// avoided the same way: the render WAITS for the imports (`hold`), so the
+// stream is animated and the new root connects with its modules present.
+// Which modules a stream needs is read off the runtime's feature table
+// (unloadedFeaturesFor: every incoming reactive root's marker checks), plus
+// the effects module's own stream-level checks — no per-feature copy here.
+//
+// Turbo renders each <turbo-stream> on its own, so one waiting render would
+// let a later stream to the same target overtake it: while the hold is open
+// EVERY stream's render waits on the same promise, and so they resume in
+// arrival order. The hold is an animation's worth of patience, never the
+// import timeout: after STREAM_HOLD_MS the streams render plain, a root
+// connects and imports as usual, and the effects module, when it does arrive,
+// sweeps up the flashes it missed (their timers then start at arrival, not at
+// render). A module already loaded is never waited for.
+const STREAM_HOLD_MS = 1000
+let hold = null
+let effects
+const holding = new Set() // the modules the open hold is waiting for
+
+function loadIntoHold(name) {
+  return loadReactiveFeature(name).then((feature) => {
+    if (name !== "effects") return
+    effects = feature
+    feature?.sweep()
+  })
+}
+
+onReactiveStreamWithoutEffects((event, loadedEffects) => {
+  const detail = event.detail
+  const render = detail?.render
+  if (typeof render !== "function") return
+  const streamEl = detail.newStream ?? event.target
+  const names = unloadedFeaturesFor(incomingRoots(streamEl)).filter((name) => !holding.has(name))
+  if (!loadedEffects && !holding.has("effects") && streamNeedsEffects(streamEl)) names.push("effects")
+  // Nothing to wait for, and no hold open: a loaded effects module wraps the
+  // stream now, as it would without this entry.
+  if (names.length === 0 && !hold) return loadedEffects?.wrap(event)
+  // A hold that is open grows: a later stream's modules join it (the hold
+  // then lasts up to another STREAM_HOLD_MS from now), so a second stream is
+  // never left to render without the module it asked for.
+  if (names.length > 0) {
+    for (const name of names) holding.add(name)
+    const opened = (hold = Promise.race([
+      Promise.all([hold, ...names.map(loadIntoHold)]),
+      new Promise((resolve) => setTimeout(resolve, STREAM_HOLD_MS)),
+    ]).then(() => {
+      if (hold !== opened) return
+      hold = null
+      holding.clear()
+    }))
+  }
+  const waiting = hold
+  detail.render = async (streamElement) => {
+    await waiting
+    // Wrapped now, not when the event fired: nothing has rendered meanwhile.
+    // On a copy: the event's detail.render is not ours to set back — a defer
+    // reply has already rendered it, and leaves Turbo a no-op (issue #336).
+    const held = { target: event.target, detail: { newStream: detail.newStream, render } }
+    ;(loadedEffects ?? effects)?.wrap(held)
+    await held.detail.render(streamElement)
+  }
+})
+
+// The reactive roots a stream is about to put on the page: the roots in its
+// template (the template's own root element included).
+function incomingRoots(streamEl) {
+  const content = streamEl?.querySelector?.("template")?.content
+  if (!content) return []
+  const roots = [...(content.querySelectorAll?.('[data-controller~="reactive"]') ?? [])]
+  for (const child of content.children ?? []) {
+    if (child.matches?.('[data-controller~="reactive"]') && !roots.includes(child)) roots.unshift(child)
+  }
+  return roots
+}
+
+// Does this stream need the effects module? A cheap superset of what the
+// module itself resolves: a per-call effect, an effect declared on the target
+// or on incoming content, a dismissing flash arriving or already on the page.
+function streamNeedsEffects(streamEl) {
+  return Boolean(
+    streamEl?.hasAttribute?.("data-reactive-effect") ||
+      document
+        .getElementById?.(streamEl?.getAttribute?.("target"))
+        ?.matches?.("[data-reactive-effect-update],[data-reactive-effect-exit]") ||
+      streamEl
+        ?.querySelector?.("template")
+        ?.content?.querySelector?.("[data-reactive-effect-enter],[data-reactive-dismiss-after]") ||
+      document.querySelector?.("[data-reactive-dismiss-after]:not([data-reactive-dismiss-scheduled])"),
+  )
+}
+
+export function __resetReactiveStreamHoldForTest() {
+  hold = null
+  effects = undefined
+  holding.clear()
+}
+
+export * from "phlex/reactive/runtime"
+export default ReactiveController