phlex-reactive 0.15.5 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb2e7841a38e3400b1777833cde2f16a73794b54c29f9e0ceb1a2b02c358263d
-  data.tar.gz: 8023c8ab7f9bb88833282c33c99a7797f565fb491795cf9b0c7566d0040653ef
+  metadata.gz: b96289b4a91d050b1631c5c31663714e3aba33370f1a4e8d87d04c662fa3ed81
+  data.tar.gz: 55c7126c343c696e66f4baf5d4c62d09a2e8fa8861c1bbe04b9b5f67c265c42c
 SHA512:
-  metadata.gz: 5257d059749e070f6b7e369e89c06fbca8b5c6b0cb9d6663b7983081a9af5a7831ba7f4d46b01da97d04a49f5fe727b6d760351f449d140e4ccffb2881cfd7c3
-  data.tar.gz: 0e29f1ca596e632855b89c9dacf2b1e0e4b6fc0db3f836f662d61c8349c0fbda0f11ebb706fe165acfcfb4ed9fbcd4d630154db8f25c023b8d7ce547dbaf9cab
+  metadata.gz: c4298ac14bf00c485324d9b61ae72fb812e0c87f1afd66cc09a24c2f0dd0917b7bf40458dd37223ba79650b4cf8a3bd44745cb7bf66d74f27f19021a3969b1a5
+  data.tar.gz: a652652cfd5a2c7439c846afb421c8d99ff3cf902276da910e05228c7313cf9c3662c8c5391cfaab1316ec4399115d96cd5441fa9d4a8dbee74e032831d419d5

data/CHANGELOG.md

@@ -6,6 +6,106 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.16.0]
+
+### Upgrading from 0.15.x
+
+- **The configuration is finalized automatically at boot (#364).** Nothing to
+  call: the engine runs `Phlex::Reactive.finalize!` once the app has booted,
+  after every initializer and every `after_initialize` block the app
+  registered. From then on every setting reads back as a frozen copy, and the
+  param-type and named-schema registries are closed (registering into either
+  after boot already raised). Booting the gem without the engine, call
+  `Phlex::Reactive.finalize!` at the end of your own boot.
+
+- **The configuration's lists are frozen once the app has booted (#364).**
+  Append to `authorization_errors` in an initializer or an `after_initialize`
+  block, as before; after boot, assign a new list (`<<` raises `FrozenError`).
+  `around_action`, `on_action_error` and `register_token_upgrader` now replace
+  a frozen list instead of appending to it; `around_actions`,
+  `on_action_error_hooks` and `token_upgraders` are frozen, and
+  `authorization_methods`' default is a frozen list. A setting reads back
+  frozen too: change it by assigning, never in place.
+
+- **Nothing an app configures makes boot raise (#364).** A value no Ractor can
+  share is kept as it is and works on the main Ractor only: a block written in
+  an initializer (`around_action`, `on_action_error`, `param_type`), a lambda
+  that closes over app state, a logger, an APM object, the verifier. An app
+  booting without a `secret_key_base` (a production rake task or build step)
+  keeps the verifier lazy, as before: the first token raises, not boot.
+
+### Added
+
+- **`Phlex::Reactive.finalize!`, `finalized?` and a test-only
+  `reset_finalization!` (#364).** `finalize!` freezes the param-type and
+  named-schema registries and stores every setting as a deep-frozen,
+  Ractor-shareable copy (the objects an app handed in are never frozen), so a
+  non-main Ractor can read the configuration. The engine calls it at boot (see
+  Upgrading). Writers keep working afterwards, and what they write is shared
+  too.
+
+- **`Phlex::Reactive.renderer` takes a name (#364).** `renderer =
+  "ApplicationController"`, like `base_controller_name`, resolves on every read,
+  so a class Zeitwerk reloaded in development is picked up (and the per-thread
+  view contexts rebuild for it). A class keeps working, and keeps rendering the
+  class object it was given. The README and the install template show the name.
+
+- **`phlex_reactive:doctor` reports Ractor readiness (#364).** An advisory line
+  (never a failure): eager loading on, the configuration finalized, and each
+  setting `finalize!` shares that still holds a value a non-main Ractor cannot
+  read, with its class (the verifier, never shareable, is left out).
+
+- **RBS signatures (#364).** `sig/` covers the configuration and token surface
+  of `Phlex::Reactive`, a component's class-level DSL, Streamable (its instance
+  methods and its class methods), `Response`, `ParamSchema`, `Store` and
+  `Shareable`, and ships with the gem. Lint runs `rbs -I sig validate`; a spec
+  fails when a public method has no signature.
+
+- **Concurrency conformance (#364).** conformance-kit 0.4's gates run in CI:
+  every `rubocop-thread_safety` cop, with no directory excludes (`NewThread`
+  is excluded only from the five spec files that start threads on purpose),
+  thread and Async contention examples over rendering, tokens, params and
+  broadcasts, a
+  Ruby 4.0 Ractor canary (param coercion, Stream wrapping, `Streamable#dom_id`,
+  configuration reads and token upgrades run in a non-main Ractor; rendering and
+  signing are pending on Phlex and ActiveSupport), and `conformance-audit
+  --strict`. A report-only kino smoke serves the dummy app in Ractor mode and
+  records the first blocker. Docs: a new "Concurrency & Ractors" guide page.
+
+### Changed
+
+- **No reader writes on first use (#364).** Every setting starts at its default
+  when the gem loads (the param-type registry is seeded then too; the verifier,
+  which needs `Rails.application`, is built by `finalize!` at boot when it can
+  be). With eager loading the engine also prepends `verify_authorized`'s
+  interceptor to every component and resolves every component's registries and
+  render memos at boot (a `ClientBindings`-only view's too), so a request
+  writes no class.
+
+- **Per-Ractor state instead of `Concurrent::Map` and lock constants (#364).**
+  The fragment viewer warnings, the CSRF-name patterns, the once-per-process
+  config warnings, the APM adapter memo, the Streamable class registry, the
+  pending-markup variants and the registry's write lock live in
+  `Phlex::Reactive::Store` (`Ractor.store_if_absent`, with a Mutex-guarded
+  table on an engine without Ractors). `lib/` and `app/` no longer reference
+  `concurrent-ruby`, which was never a declared dependency.
+
+### Fixed
+
+- **Eager loading the gem raised `NoMethodError: undefined method 'to_json'`
+  in a process that had not loaded json yet (#364).** `Component::Sortable`
+  calls `Hash#to_json` while it loads; it now requires json itself.
+
+- **`verify_authorized` could prepend two interceptors to one class (#364).**
+  The lazy, request-path `Authorization.instrument!` checked and prepended
+  without a lock; two threads first-calling it for one class both prepended.
+  It now holds a lock across the check and the prepend.
+
+## [0.15.5] - 2026-10-15
+
+Consolidates everything since 0.14.1; tags 0.14.2–0.15.4 shipped without
+changelog sections, so this section spans the whole run to 0.15.5.
+
 ### Added
 
 - **A server deadline counted down on the client — `reactive_countdown(until:, format: :ms, waiting:, done:)` (#400).**

data/README.md

@@ -3936,8 +3936,10 @@ Phlex::Reactive.authorization_errors = [Pundit::NotAuthorizedError]
 Phlex::Reactive.authorization_methods = %i[authorize! authorize allowed_to?]
 # Phlex::Reactive.verify_authorized = false   # turn the guard off (not recommended)
 
-# Use your ApplicationController to render components (app helpers / Current):
-Phlex::Reactive.renderer = ApplicationController
+# Use your ApplicationController to render components (app helpers / Current).
+# By name, like base_controller_name, it follows a code reload in development;
+# a Class keeps rendering the class object it was given:
+Phlex::Reactive.renderer = "ApplicationController"
 
 # Sign tokens with a dedicated key instead of secret_key_base:
 Phlex::Reactive.verifier = ActiveSupport::MessageVerifier.new(ENV["REACTIVE_KEY"])
@@ -3989,6 +3991,17 @@ Phlex::Reactive.around_action do |ctx, &action|
 end
 ```
 
+**The configuration is finalized at boot.** Once the app has booted (after your
+initializers and every `after_initialize` block), the engine calls
+`Phlex::Reactive.finalize!` for you: the param-type and named-schema registries
+freeze, and every setting is stored as a frozen, Ractor-shareable copy (the
+objects you handed in are not frozen). Append to `authorization_errors` in an
+initializer; after boot, assign a new list (`<<` raises `FrozenError`). A value
+no Ractor can share (a block written in an initializer, a lambda that closes
+over app state, a logger, an APM object, the verifier) is kept as it is and
+works on the main Ractor only: finalizing never raises for it. Booting without
+the engine? Call `Phlex::Reactive.finalize!` at the end of your own boot.
+
 #### Two seams: HTTP-layer (`base_controller_name`) vs component-layer (`around_action`)
 
 There are two places to wrap a reactive action, and they see different things:

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

@@ -45,8 +45,9 @@ module Phlex
       # 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
+      # class-level setting, so in practice one entry), not one per request:
+      # memoized in the per-Ractor table (Phlex::Reactive::Store) under this key.
+      CSRF_TOKEN_PATTERNS_KEY = :phlex_reactive_csrf_token_patterns
 
       # Stands in for the response when asking the cookie jar what it WOULD
       # write (CookieJar#write calls set_cookie / delete_cookie per pending
@@ -261,7 +262,7 @@ module Phlex
         # 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
+        Phlex::Reactive::Store.table(CSRF_TOKEN_PATTERNS_KEY).fetch(token_name) do
           names = (CSRF_TOKEN_NAMES | [token_name]).reject(&:empty?).map { Regexp.escape(it) }
           /\bname\s*=\s*["']?(?:#{names.join("|")})(?![\w-])/i
         end

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