phlex-reactive 0.15.4 → 0.16.0

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

@@ -2021,6 +2021,30 @@ function deferNeeded(root) {
   )
 }
 
+// Issue #410: a tokenless CLIENT-ONLY root (a ClientBindings component: filter,
+// show, on_client) has no action of its own. It is transparent to server round
+// trips: a server trigger inside it dispatches on the nearest token-bearing root
+// above, and that root's #collectFields looks through it. A lazy or deferred
+// shell is tokenless by design and is NOT client-only.
+const AWAKE_ROOT = '[data-controller~="reactive"]'
+const ANY_ROOT = '[data-controller~="reactive"],[data-reactive-dormant~="reactive"]'
+
+const clientOnlyRoot = (root) => root.getAttribute?.("data-reactive-token-value") == null && !deferNeeded(root)
+
+// The first `selector` root at or above `from` that is not client-only, or
+// `stop` when the walk reaches it first, or null.
+function serverRoot(from, selector, stop) {
+  let root = from?.closest?.(selector)
+  while (root && root !== stop && clientOnlyRoot(root)) root = root.parentElement?.closest?.(selector)
+  return root ?? null
+}
+
+// Connected controllers by root element, so a client-only root can hand a
+// dispatch to the server root above it. A dispatch for a root that has not
+// connected yet (a dormant root being woken) waits here until it does.
+const rootControllers = new WeakMap()
+const heldForwards = new WeakMap()
+
 // Dirty tracking with its navigate-away guard, and the paste-trigger gate:
 // the root or anything inside it carries one of the two markers. (A nested
 // root's marker loads the module for its parent too; the module then checks
@@ -2574,6 +2598,7 @@ export default class extends Controller {
     // queueing them NOW — a connect-time seed below (a compute output write)
     // dispatches real input events. The queue itself drains at the very end.
     earlyState().connected.add(this.element)
+    rootControllers.set(this.element, this)
 
     // Root-id guard (issue #48). The token round trip assumes the reactive root
     // element's id == component.id: the server targets component.id and the client
@@ -2999,6 +3024,14 @@ export default class extends Controller {
       )
     }
     this.#drainEarly()
+    // Issue #410: dispatches a client-only root inside handed over before this
+    // root connected (a dormant root woken by that very trigger).
+    // currentTarget is null once propagation ended: pin the trigger back on.
+    for (const [event, target] of heldForwards.get(this.element) ?? []) {
+      if (event.currentTarget !== target) Object.defineProperty(event, "currentTarget", { value: target, configurable: true })
+      this.dispatch(event)
+    }
+    heldForwards.delete(this.element)
   }
 
   // The trigger elements whose :once descriptor THIS connection replayed —
@@ -3099,6 +3132,7 @@ export default class extends Controller {
     }
     // Early triggers (issue #273): a disconnected root records again.
     earlyState().connected.delete(this.element)
+    if (rootControllers.get(this.element) === this) rootControllers.delete(this.element)
     this.element.removeAttribute?.("data-reactive-connected")
     // A spent :once replay is remembered per element so a morph REPLY (root
     // still connected) cannot re-arm it. A disconnect drops Stimulus's own
@@ -3116,6 +3150,12 @@ export default class extends Controller {
   // a per-controller promise makes each dispatch wait for the previous one, so
   // it always uses the freshest token.
   dispatch(event) {
+    // Issue #410: a client-only root has no action of its own — a server
+    // trigger inside it belongs to the token-bearing root above. FIRST, so that
+    // root runs every check below with its own element.
+    if (event.params?.action && event.params.action !== LAZY_MATERIALIZE_ACTION && this.#clientOnly()) {
+      return this.#forwardToServerRoot(event)
+    }
     // A shortcut (issue #357) that is the other platform's twin, or pressed
     // in a field the user is typing in, is a complete no-op: the native
     // default (text undo) proceeds and nothing is announced. Checked FIRST: a
@@ -3280,6 +3320,37 @@ export default class extends Controller {
   }
 
 
+  // A tokenless client-only root (issue #410). tokenValue is the Stimulus view
+  // of data-reactive-token-value; the attribute check also rules out a shell.
+  #clientOnly() {
+    return !this.tokenValue && clientOnlyRoot(this.element)
+  }
+
+  // Hand a server trigger to the nearest token-bearing root above (issue #410).
+  // A dormant one is woken (as early.js wakes a root on its own trigger) and
+  // runs the dispatch when it connects. With no such root nothing is sent.
+  #forwardToServerRoot(event) {
+    const root = serverRoot(this.element.parentElement, ANY_ROOT)
+    if (!root) {
+      if (this.element.closest?.('[data-reactive-verbose="true"], [data-reactive-debug="true"]'))
+        console.warn(`[phlex-reactive] "${event.params.action}": no token on this root or above, nothing sent`)
+      return
+    }
+    const controller = rootControllers.get(root)
+    if (controller) return controller.dispatch(event)
+    // Held past this event's dispatch: cancel its native default NOW, by
+    // dispatch()'s own rule, or a submit/link would act before the request.
+    const { shortcut, window: windowBound, optimistic } = event.params
+    const target = event.currentTarget ?? event.target
+    if ((shortcut != null || !windowBound) && !this.#keepsNativeToggle(optimistic, target)) event.preventDefault()
+    heldForwards.set(root, [...(heldForwards.get(root) ?? []), [event, target]])
+    const data = root.dataset
+    if (data.reactiveDormant) {
+      data.controller = `${data.controller ?? ""} ${data.reactiveDormant}`.trim()
+      delete data.reactiveDormant
+    }
+  }
+
   // CLIENT-ONLY trigger entry point (issue #95) — the zero-round-trip sibling
   // of dispatch(). Wired by on_client: applies the declared op chain
   // (data-reactive-ops-param, built by Phlex::Reactive::JS) locally. NO token,
@@ -4218,6 +4289,17 @@ export default class extends Controller {
     return (el) => this.#ownsField(el)
   }
 
+  // #ownershipFilter for SERVER params (issue #410): nested client-only roots
+  // are transparent, so a control under one is this root's when the first
+  // token-bearing root above it is this.element. A nested token-bearing root
+  // keeps its own fields (issue #15). Bindings, computes and listnav keep the
+  // strict nearest-root #ownershipFilter.
+  #serverFieldFilter() {
+    const nested = this.element.querySelectorAll(AWAKE_ROOT)
+    if (nested.length === 0 || [...nested].every(clientOnlyRoot)) return () => true
+    return (el) => serverRoot(el, AWAKE_ROOT, this.element) === this.element
+  }
+
   // One walk over THIS root's named controls (not a nested reactive root's),
   // returning both the scalar `fields` and any chosen `files`. The ownership
   // predicate is hoisted ONCE (issue #117) via #ownershipFilter — in the common
@@ -4229,7 +4311,7 @@ export default class extends Controller {
   #collectFields() {
     const fields = {}
     const files = []
-    const owns = this.#ownershipFilter() // compute ONCE per dispatch (issue #117)
+    const owns = this.#serverFieldFilter() // compute ONCE per dispatch (issue #117)
     const controls = []
     this.element.querySelectorAll("input[name], select[name], textarea[name]").forEach((field) => {
       if (!owns(field)) return

data/lib/generators/phlex/reactive/install/templates/phlex_reactive.rb.erb

@@ -9,7 +9,8 @@
 # Phlex::Reactive.base_controller_name = "ApplicationController"
 
 # Render components with your app's view context (helpers, Current, etc.).
-# Phlex::Reactive.renderer = ApplicationController
+# By name, so it follows code reloading in development.
+# Phlex::Reactive.renderer = "ApplicationController"
 
 # Render your authorization library's error as 403 from a reactive action.
 # Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]

data/lib/phlex/reactive/apm/subscriber.rb

@@ -19,6 +19,11 @@ module Phlex
         # adapter can subscribe to them itself) — the action IS the transaction.
         EVENTS = /\A(?:action|defer)\.phlex_reactive\z/
 
+        # The one subscription and its adapter, class ivars on purpose and
+        # safe: install/uninstall run at boot, from the engine's
+        # after_initialize on the main Ractor (APM.attach!), and between
+        # examples in a test suite; the request path never touches them.
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable
         class << self
           # Install a single bus subscription for `adapter`. Idempotent for the
           # SAME adapter: a repeat call is a no-op. A DIFFERENT adapter replaces

data/lib/phlex/reactive/apm.rb

@@ -41,7 +41,7 @@ module Phlex
           # Memoize the instance PER SYMBOL so repeated detect/attach! calls return
           # the SAME object — Subscriber.install keys idempotency on adapter
           # identity (equal?), so a fresh klass.new each time would double-subscribe.
-          return (built_in_instances[apm] ||= klass.new) if klass.available?
+          return built_in_instances.fetch(apm) { klass.new } if klass.available?
 
           warn_and_nil("apm = #{apm.inspect} set but #{apm} is not loaded — no-op. " \
                        "Require the SDK (or remove the setting).")
@@ -68,17 +68,16 @@ module Phlex
         def reset!
           Subscriber.uninstall
           Phlex::Reactive.resolved_apm_adapter = nil
-          @built_in_instances = nil
+          built_in_instances.clear
         end
 
         private
 
         # Symbol => memoized built-in adapter instance. One instance per flavour for
         # the life of the process (cleared only by reset! in tests), so detect is
-        # identity-stable and attach! stays idempotent.
-        def built_in_instances
-          @built_in_instances ||= {}
-        end
+        # identity-stable and attach! stays idempotent. Per-Ractor state
+        # (Phlex::Reactive::Store), not a module ivar (zoolutions/phlex-reactive#364).
+        def built_in_instances = Phlex::Reactive::Store.table(:phlex_reactive_apm_adapters)
 
         def warn_and_nil(message)
           logger = Phlex::Reactive.send(:default_logger)

data/lib/phlex/reactive/authorization.rb

@@ -25,6 +25,10 @@ module Phlex
       MODULE_PREPEND = ::Module.instance_method(:prepend)
       private_constant :MODULE_PREPEND
 
+      # The per-Ractor lock (Phlex::Reactive::Store) the lazy instrument! path
+      # holds: one per Ractor, never shared across Ractors.
+      INSTRUMENT_LOCK_KEY = :phlex_reactive_authorization_instrument_lock
+
       class << self
         # Open a fresh tracking window, run the block, and restore the previous
         # cell — exactly the with_connection_id save/restore shape, so nesting is
@@ -73,14 +77,36 @@ module Phlex
         # a Zeitwerk reload's fresh class re-instruments naturally and a repeated
         # call in one process is a no-op. Re-reads authorization_methods each first
         # call, so an initializer that widened the list is honored.
+        #
+        # When the app eager-loads, the engine instruments every component class
+        # at boot (instrument_all!, zoolutions/phlex-reactive#364), so the
+        # endpoint's call is a bare "already instrumented" read and a request
+        # never mutates a class. The lazy path (development, or a class defined
+        # after boot) holds a lock across the check and the prepend, so two
+        # threads first-calling it for one class prepend ONE interceptor.
         def instrument!(component_class)
-          return if component_class.instance_variable_get(:@reactive_authorization_instrumented)
+          return if instrumented?(component_class)
 
-          names = Phlex::Reactive.authorization_methods.select do
-            component_class.method_defined?(it) || component_class.private_method_defined?(it)
+          Phlex::Reactive::Store.fetch(INSTRUMENT_LOCK_KEY) { Mutex.new }.synchronize do
+            next if instrumented?(component_class)
+
+            names = Phlex::Reactive.authorization_methods.select do
+              component_class.method_defined?(it) || component_class.private_method_defined?(it)
+            end
+            MODULE_PREPEND.bind_call(component_class, interceptor_for(names)) if names.any?
+            component_class.instance_variable_set(:@reactive_authorization_instrumented, true)
           end
-          MODULE_PREPEND.bind_call(component_class, interceptor_for(names)) if names.any?
-          component_class.instance_variable_set(:@reactive_authorization_instrumented, true)
+        end
+
+        # Instrument every reactive component class among `classes` (the
+        # engine passes Streamable.registered_classes at boot, after eager
+        # loading). Plain Streamable classes have no actions to guard.
+        def instrument_all!(classes)
+          classes.each { instrument!(it) if it.include?(Phlex::Reactive::Component) }
+        end
+
+        def instrumented?(component_class)
+          component_class.instance_variable_get(:@reactive_authorization_instrumented) ? true : false
         end
 
         private

data/lib/phlex/reactive/client_bindings.rb

@@ -52,6 +52,25 @@ module Phlex
 
       include Component::DSL
       include Component::Helpers
+
+      # Tracked so the engine warms every class with the DSL at boot, a
+      # client-only one too (zoolutions/phlex-reactive#364). A subclass
+      # inherits the module rather than including it, so `included` never
+      # fires for it.
+      included do
+        Phlex::Reactive::Component::Registry.track(self)
+      end
+
+      class_methods do
+        def inherited(subclass)
+          super
+          Phlex::Reactive::Component::Registry.track(subclass)
+        end
+      end
+
+      # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+      # the body has loaded (zoolutions/phlex-reactive#364).
+      Phlex::Reactive::Shareable.seal_concern(self)
     end
   end
 end

data/lib/phlex/reactive/component/dsl.rb

@@ -174,6 +174,13 @@ module Phlex
           # and the registry generation (any declaration) — as two integer
           # compares, because reactive_attrs is the token-signing hot path.
           # The race on a concurrent first call is benign (idempotent rebuild).
+          #
+          # A per-class memo of class-definition data, safe as a class ivar:
+          # Registry.warm! builds it at boot on the main Ractor when the app
+          # eager-loads (so a request only reads it), and it is rebuilt only
+          # after a declaration or an effects= write (boot, a development
+          # reload, a spec).
+          # rubocop:disable-next ThreadSafety/ClassInstanceVariable
           def reactive_effect_attrs
             effects_gen = Phlex::Reactive.effects_generation
             registry_gen = Registry.generation
@@ -583,7 +590,10 @@ module Phlex
           # frozen array of { any:, ops: } bindings, or nil when undeclared
           # (byte-stable wire). Memoized per class against the registry
           # generation (one integer compare) because reactive_attrs is the
-          # token-signing hot path — the reactive_effect_attrs precedent.
+          # token-signing hot path — the reactive_effect_attrs precedent. A
+          # class ivar for the same reason as that one: warmed at boot,
+          # rebuilt only after a declaration.
+          # rubocop:disable-next ThreadSafety/ClassInstanceVariable
           def reactive_on_complete_attr
             registry_gen = Registry.generation
             return @reactive_on_complete_attr if @reactive_on_complete_attr_gen == registry_gen
@@ -754,6 +764,10 @@ module Phlex
               "can rebuild through it."
           end
         end
+
+        # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+        # the body has loaded (zoolutions/phlex-reactive#364).
+        Phlex::Reactive::Shareable.seal_concern(self)
       end
     end
   end

data/lib/phlex/reactive/component/helpers.rb

@@ -1963,6 +1963,10 @@ module Phlex
 
           instance_variable_get(:"@#{key}")
         end
+
+        # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+        # the body has loaded (zoolutions/phlex-reactive#364).
+        Phlex::Reactive::Shareable.seal_concern(self)
       end
     end
   end

data/lib/phlex/reactive/component/identity.rb

@@ -20,15 +20,21 @@ module Phlex
 
         # Whether the installed GlobalID gives a class its own app
         # (global_id_app, then GlobalID.app — rails/globalid after 1.4).
-        # Read once: it is a fact about the loaded gem.
-        def self.per_class_gid_app?
-          return @per_class_gid_app if defined?(@per_class_gid_app)
+        # Read once, when this file loads: it is a fact about the loaded gem.
+        PER_CLASS_GID_APP = (::GlobalID::Identification.const_defined?(:ClassMethods, false) &&
+                             ::GlobalID::Identification::ClassMethods.method_defined?(:global_id_app)) == true
 
-          @per_class_gid_app = ::GlobalID::Identification.const_defined?(:ClassMethods, false) &&
-                               ::GlobalID::Identification::ClassMethods.method_defined?(:global_id_app)
-        end
+        def self.per_class_gid_app? = PER_CLASS_GID_APP
 
         class_methods do
+          # Both memos are class ivars by design (the hot-path contract above),
+          # and safe as such: Registry.warm! builds them at boot on the main
+          # Ractor when the app eager-loads, so a request only reads them, and
+          # Registry.bump! clears them only when a declaration lands (boot, a
+          # development reload). A first-render race in development rebuilds
+          # an equal value.
+          # rubocop:disable ThreadSafety/ClassInstanceVariable
+
           # The record's instance-variable symbol (e.g. :@todo), computed once.
           # reactive_token reads it on every render; interpolating :"@#{key}" each
           # time would allocate a symbol per render. Nil when record-less.
@@ -44,6 +50,7 @@ module Phlex
           def reactive_state_ivars
             @reactive_state_ivars ||= reactive_state_keys.map { [it.to_s, :"@#{it}"] }
           end
+          # rubocop:enable ThreadSafety/ClassInstanceVariable
         end
 
         private
@@ -128,6 +135,10 @@ module Phlex
         def reactive_gid_app(klass)
           (Identity.per_class_gid_app? && klass.global_id_app) || ::GlobalID.app
         end
+
+        # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+        # the body has loaded (zoolutions/phlex-reactive#364).
+        Phlex::Reactive::Shareable.seal_concern(self)
       end
     end
   end

data/lib/phlex/reactive/component/lazy.rb

@@ -209,6 +209,10 @@ module Phlex
             value.html_safe? ? raw(value) : plain(value.to_s)
           end
         end
+
+        # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+        # the body has loaded (zoolutions/phlex-reactive#364).
+        Phlex::Reactive::Shareable.seal_concern(self)
       end
     end
   end

data/lib/phlex/reactive/component/presence_declaration.rb

@@ -112,6 +112,10 @@ module Phlex
               "would never join the stream. Drop reactive_dormant on this component."
           end
         end
+
+        # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+        # the body has loaded (zoolutions/phlex-reactive#364).
+        Phlex::Reactive::Shareable.seal_concern(self)
       end
     end
   end

data/lib/phlex/reactive/component/registry.rb

@@ -75,11 +75,48 @@ module Phlex
         # above). Owned by Component::Identity; invalidated here.
         HOT_PATH_MEMOS = %i[@reactive_record_ivar @reactive_state_ivars].freeze
 
+        # The public reader each registry kind resolves through: what warm!
+        # calls, so a kind added to OWN_IVARS needs its reader here too (the
+        # warm spec fails otherwise).
+        READERS = {
+          actions: :reactive_actions,
+          state_keys: :reactive_state_keys,
+          collections: :reactive_collections,
+          computes: :reactive_computes,
+          on_completes: :reactive_on_completes,
+          record_key: :reactive_record_key,
+          scope: :reactive_scope,
+          dirty: :reactive_dirty_config,
+          lazy: :reactive_lazy_declaration,
+          dormant: :reactive_dormant?,
+          effects: :reactive_effects_config,
+          skip_all: :reactive_skip_all_authorization?,
+          skip_actions: :reactive_skip_authorization_actions,
+          presence: :reactive_presence_declaration
+        }.freeze
+
+        # The per-class memos the render path reads (Identity's token memos,
+        # the DSL's root-attrs fragments): warm! builds them too.
+        MEMO_READERS = %i[reactive_record_ivar reactive_state_ivars reactive_effect_attrs reactive_on_complete_attr].freeze
+
+        # Where those readers memoize: the gem's own plain data (ivar names,
+        # attribute fragments), shared by warm! so a non-main Ractor can read it.
+        MEMO_IVARS = %i[@reactive_record_ivar @reactive_state_ivars @reactive_effect_attrs @reactive_on_complete_attr].freeze
+
+        # Every class with the reactive DSL, a ClientBindings-only view
+        # included (Streamable's registry has only the token-bearing ones):
+        # what the engine warms at boot. Per-Ractor (Phlex::Reactive::Store);
+        # classes are defined on the main Ractor.
+        CLASSES_KEY = :phlex_reactive_component_classes
+
         # Serializes generation bumps so two concurrent class definitions can't
         # lose an increment (a resolution memoized between the two writes must
         # see a THIRD generation, not the second one again). Reads stay bare —
-        # the resolution compare tolerates staleness (it just recomputes).
-        WRITE_MUTEX = Mutex.new
+        # the resolution compare tolerates staleness (it just recomputes). The
+        # lock is per-Ractor state (Phlex::Reactive::Store) rather than a Mutex
+        # constant, which no other Ractor could read (zoolutions/phlex-reactive#364);
+        # classes are declared on the main Ractor, so it is one lock in practice.
+        WRITE_LOCK_KEY = :phlex_reactive_registry_write_lock
 
         # Frozen empties for the no-declaration branches of resolve_* — the
         # merge/+ still returns a fresh, per-class copy.
@@ -120,6 +157,26 @@ module Phlex
             value
           end
 
+          # -- boot warm-up (zoolutions/phlex-reactive#364) --------------------
+
+          # Resolve every registry kind and build the render path's per-class
+          # memos for each reactive component class among `classes`, then
+          # freeze each class's resolution cache. The engine runs it at boot
+          # when the app eager-loads (every class is loaded by then), so a
+          # request reads memos and never writes the class. A declaration
+          # after it (a development reload) bumps the generation and the next
+          # read rebuilds a fresh cache, as before.
+          def warm!(classes)
+            classes.each { warm_class(it) if it.respond_to?(:reactive_actions) }
+          end
+
+          # Called when a class gains the DSL (ClientBindings' included and
+          # inherited hooks), at class definition.
+          def track(klass) = class_registry.add(klass)
+
+          # A snapshot of every tracked class still loaded.
+          def registered_classes = class_registry.to_a
+
           # -- resolution (all memoized against the generation) -----------------
           #
           # `reader` is the PUBLIC reader to walk the superclass through
@@ -179,7 +236,7 @@ module Phlex
           # and sweep the hot-path identity memos off the writing class's
           # family (see the contract in the module doc).
           def bump!(klass)
-            WRITE_MUTEX.synchronize { @generation += 1 }
+            Phlex::Reactive::Store.fetch(WRITE_LOCK_KEY) { Mutex.new }.synchronize { @generation += 1 }
             sweep_hot_path_memos(klass)
           end
 
@@ -191,14 +248,27 @@ module Phlex
           end
 
           # The generation-checked per-class memo: a cache built at an older
-          # generation is discarded wholesale and rebuilt lazily per kind.
+          # generation is discarded wholesale and rebuilt lazily per kind. A
+          # cache warm! froze answers a kind it lacks without memoizing it.
           def fetch(klass, kind)
             cache = resolution_cache(klass)
-            cache.fetch(kind) { cache[kind] = yield }
+            cache.fetch(kind) { cache.frozen? ? yield : (cache[kind] = yield) }
           end
 
+          def warm_class(klass)
+            [*READERS.values, *MEMO_READERS].each { klass.public_send(it) if klass.respond_to?(it) }
+            klass.instance_variable_get(:@reactive_registry_cache)&.freeze
+            MEMO_IVARS.each do
+              next unless klass.instance_variable_defined?(it)
+
+              klass.instance_variable_set(it, Phlex::Reactive::Shareable.share(klass.instance_variable_get(it)))
+            end
+          end
+
+          def class_registry = Phlex::Reactive::Store.fetch(CLASSES_KEY) { Phlex::Reactive::Streamable::ClassRegistry.new }
+
           def resolution_cache(klass)
-            generation = @generation
+            generation = self.generation
             if klass.instance_variable_get(:@reactive_registry_generation) == generation
               klass.instance_variable_get(:@reactive_registry_cache)
             else

data/lib/phlex/reactive/component/sortable.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# SORTABLE_MESSAGES_JSON is built with Hash#to_json while this file loads.
+require "json"
+
 module Phlex
   module Reactive
     module Component

data/lib/phlex/reactive/component.rb

@@ -147,6 +147,10 @@ module Phlex
       include Identity
       include Lazy
       include PresenceDeclaration
+
+      # ActiveSupport::Concern's bookkeeping on this module, sealed now that
+      # the body has loaded (zoolutions/phlex-reactive#364).
+      Phlex::Reactive::Shareable.seal_concern(self)
     end
   end
 end

data/lib/phlex/reactive/defer.rb

@@ -350,11 +350,11 @@ data-reactive-defer-pending="true" aria-busy="true">#{inner}</div>)
 
         # A forced :stream without the capability is a CONFIG mistake — warn
         # loudly but once per process (a deferred reply can fire per keystroke;
-        # per-reply spam would bury the signal), then degrade to :fetch.
+        # per-reply spam would bury the signal), then degrade to :fetch. The
+        # "warned" flag is per-Ractor state (Store), never a module ivar written
+        # on the request path.
         def warn_stream_degraded
-          return if @stream_degraded_warned
-
-          @stream_degraded_warned = true
+          return unless Phlex::Reactive::Store.first_warning?(:defer_stream_degraded)
           return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
 
           ::Rails.logger.warn(

data/lib/phlex/reactive/doctor/ractor_readiness.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    class Doctor
+      # Ractor mode (zoolutions/phlex-reactive#364): a non-main Ractor can read
+      # phlex-reactive's configuration once it is finalized and every setting
+      # is Ractor-shareable, and the request path writes no class only when
+      # every component class was loaded, instrumented and warmed at boot,
+      # which needs eager loading.
+      #
+      # Advisory only (never ✗): no app has to run Ractors, and Rails, the
+      # ActiveSupport::MessageVerifier behind Phlex::Reactive.verifier, and
+      # Phlex rendering still block it upstream. Never loads a server.
+      module RactorReadiness
+        UPSTREAM = "Ractor mode still waits on Rails, on ActiveSupport (the verifier is an " \
+                   "ActiveSupport::MessageVerifier) and on Phlex rendering (yippee-fun/phlex#1055)"
+
+        SHARE_FIX = "Make each value Ractor-shareable: a callable as a capture-free lambda in a module or " \
+                    "class body (Phlex::Reactive.finalize! shares it), any other object deep-frozen with " \
+                    "Ractor.make_shareable before you assign it. A value that cannot be shared (a logger, an " \
+                    "SDK client) keeps working on the main Ractor only; or leave Ractor mode off."
+
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          # Setting => the class of its value, for every configuration reader
+          # (Phlex::Reactive::CONFIG_READERS) whose value is not
+          # Ractor-shareable. The verifier is left out: it is never shareable.
+          def unshareable_settings
+            Phlex::Reactive::CONFIG_READERS.each_with_object({}) do |reader, out|
+              value = Phlex::Reactive.public_send(reader)
+              out[reader] = value.class unless Phlex::Reactive::Shareable.shareable?(value)
+            end
+          end
+
+          def eager_load? = defined?(::Rails) && ::Rails.application ? ::Rails.application.config.eager_load : false
+        end
+
+        def ractor_readiness_check(eager_load: Doctor.eager_load?, finalized: Phlex::Reactive.finalized?,
+                                   unshareable: Doctor.unshareable_settings)
+          if !eager_load
+            advise("eager loading is off: Ractor mode needs every component loaded and prepared at boot",
+              "config.eager_load = true (the production default)")
+          elsif !finalized
+            advise("the configuration is not finalized",
+              "Boot through the engine (it calls Phlex::Reactive.finalize! once the app's initializers have run), " \
+              "or call Phlex::Reactive.finalize! at the end of your own boot.")
+          elsif unshareable.any?
+            names = unshareable.map { |name, klass| "#{name} (#{klass})" }.join(", ")
+            advise("#{unshareable.size} settings hold a value a non-main Ractor cannot read: #{names}", SHARE_FIX)
+          else
+            Check.new(:ok, "the configuration is finalized and Ractor-shareable; #{UPSTREAM}", name: :ractor_readiness)
+          end
+        end
+
+        private
+
+        def advise(message, fix) = Check.new(:unknown, "Ractor mode: #{message}", name: :ractor_readiness, fix:)
+      end
+    end
+  end
+end

data/lib/phlex/reactive/doctor.rb

@@ -17,6 +17,7 @@ module Phlex
     # trip and (for the component checks) iterate the loaded Streamable registry.
     class Doctor
       include FiberIsolation
+      include RactorReadiness
 
       # The result of one check: a status (:ok/:fail/:unknown), a human message,
       # and (on anything but :ok) a fix line telling the adopter what to do. A
@@ -79,6 +80,7 @@ module Phlex
           verifier_check,
           base_controller_check,
           fiber_isolation_check,
+          ractor_readiness_check,
           action_check(components),
           id_check(components),
           authorization_check(components),