phlex-reactive 0.9.3 → 0.9.5

data/lib/phlex/reactive/mcp/tools/config_tool.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      module Tools
+        # phlex_reactive_config — a REDACTED config summary. It reports the
+        # page-stable, non-secret configuration a developer needs to understand
+        # the install, and NEVER the verifier, secret_key_base, or any token. The
+        # allowlist below is explicit: a field is reported only if it appears here.
+        class ConfigTool < BaseTool
+          tool_name "phlex_reactive_config"
+          title "phlex-reactive config"
+          description <<~DESC
+            A redacted summary of the phlex-reactive configuration: gem version,
+            action_path, base_controller_name, renderer, verify_authorized +
+            authorization_methods, verbose_errors/debug/log_events, flash_target,
+            and whether pgbus is present/streams-capable. NEVER reports the
+            verifier, secret_key_base, or any signed token. Read-only.
+          DESC
+
+          input_schema(properties: {}, required: [])
+
+          def self.call(server_context: nil) # rubocop:disable Lint/UnusedMethodArgument
+            json_response(
+              version: Phlex::Reactive::VERSION,
+              action_path: Phlex::Reactive.action_path,
+              base_controller_name: Phlex::Reactive.base_controller_name,
+              renderer: renderer_name,
+              verify_authorized: Phlex::Reactive.verify_authorized,
+              authorization_methods: Phlex::Reactive.authorization_methods,
+              authorization_errors: Phlex::Reactive.authorization_errors.map(&:to_s),
+              verbose_errors: Phlex::Reactive.verbose_errors,
+              debug: Phlex::Reactive.debug,
+              log_events: Phlex::Reactive.log_events,
+              flash_target: Phlex::Reactive.flash_target,
+              pgbus: pgbus?,
+              pgbus_streams: pgbus_streams?
+            )
+          end
+
+          # The renderer is a controller CLASS (or nil) — report its name, never
+          # the object (which could inspect to something with state).
+          def self.renderer_name
+            renderer = Phlex::Reactive.renderer
+            renderer.respond_to?(:name) ? renderer.name : renderer.class.name
+          rescue StandardError
+            nil
+          end
+
+          # Is pgbus present and stream-capable? Delegates to the config readers
+          # when they exist; otherwise probes directly (defined? + respond_to?),
+          # so the report is correct regardless of pgbus version.
+          # Delegate to the gem's own capability gates (issue #165) — the
+          # canonical runtime probes (`pgbus_streams?` inspects
+          # Pgbus::Streams::Stream#broadcast's parameters directly, never a live
+          # stream call). Reported as plain booleans; degrade to false if the
+          # readers ever raise.
+          def self.pgbus?
+            !!Phlex::Reactive.pgbus?
+          rescue StandardError
+            false
+          end
+
+          def self.pgbus_streams?
+            !!Phlex::Reactive.pgbus_streams?
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp/tools/doctor_tool.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      module Tools
+        # phlex_reactive_doctor — the install validator's checks as structured
+        # JSON (name/status/message/fix), the same data `bin/rails
+        # phlex_reactive:doctor` prints as text.
+        class DoctorTool < BaseTool
+          tool_name "phlex_reactive_doctor"
+          title "phlex-reactive doctor"
+          description <<~DESC
+            Validate the phlex-reactive install and return each check as structured
+            JSON: name, status (ok/fail/unknown), message, and a fix line for any
+            non-passing check. The same checks `bin/rails phlex_reactive:doctor`
+            prints — route, Stimulus registration, csrf, verifier round-trip, base
+            controller, every action has a method, stable #id, and the advisory
+            authorization heuristic. Read-only.
+          DESC
+
+          input_schema(properties: {}, required: [])
+
+          def self.call(server_context: nil) # rubocop:disable Lint/UnusedMethodArgument
+            eager_load_app!
+            doctor = Phlex::Reactive::Doctor.new
+            checks = doctor.checks.map do
+              { name: it.name, status: it.status, message: it.message, fix: it.fix }
+            end
+            json_response(checks: checks, ok: !doctor.failures?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp/tools/find_tool.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module MCP
+      module Tools
+        # phlex_reactive_find — fuzzy-search components by name and return the
+        # ranked matches, each with full per-action detail INCLUDING the Prism-
+        # extracted method definition source. The tool for "where is X defined and
+        # what does its action do?".
+        class FindTool < BaseTool
+          tool_name "phlex_reactive_find"
+          title "phlex-reactive find"
+          description <<~DESC
+            Fuzzy-find reactive components by name (exact > prefix > substring >
+            subsequence, on both the demodulized and full name). Returns the ranked
+            matches, each with its actions' param schema, source location,
+            authorization heuristic, and the full method-definition SOURCE
+            (extracted with Prism). Read-only.
+
+            NOTE: unlike the other tools (which report names/paths/schemas only),
+            this one returns the action's source code verbatim — so anything
+            hardcoded in an action body is surfaced too. Don't embed secrets or
+            credentials in action definitions (read them from ENV/credentials).
+          DESC
+
+          input_schema(
+            properties: {
+              query: { type: "string", description: "The search string (component name fragment)." }
+            },
+            required: ["query"]
+          )
+
+          def self.call(query:, server_context: nil) # rubocop:disable Lint/UnusedMethodArgument
+            eager_load_app!
+            matches = Phlex::Reactive::Inspector.find(query).map { match_hash(it) }
+            json_response(query: query, matches: matches)
+          end
+
+          def self.match_hash(info)
+            {
+              name: info.name,
+              path: Phlex::Reactive::Inspector::Report.location_str(info.path),
+              record_key: info.record_key,
+              state_keys: info.state_keys,
+              actions: info.actions.map { action_detail(it) }
+            }
+          end
+
+          def self.action_detail(action)
+            {
+              name: action.name,
+              params: action.params,
+              source_location: Phlex::Reactive::Inspector::Report.location_str(action.source_location),
+              authorization_call_detected: action.authorization_call_detected?,
+              # The full method SOURCE — this is the one field that exposes an
+              # action body verbatim (see the tool description). A secret hardcoded
+              # in an action would surface here; keep secrets out of action bodies.
+              definition: action.definition
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/mcp.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # The read-only diagnostic MCP server (issue #168): a stdio server exposing
+    # five read-only tools (doctor, components, actions, find, config) so Claude
+    # Code inside a HOST app can introspect the live reactive registry when
+    # debugging. It mirrors pgbus's MCP subtree.
+    #
+    # The `mcp` gem is OPTIONAL and NEVER a gemspec runtime dependency — this
+    # whole subtree references the optional gem's constants (MCP::Tool,
+    # MCP::Server), so it is kept OUT of the Zeitwerk loader (loader.ignore in
+    # lib/phlex/reactive.rb) and loaded explicitly via MCP.load!.
+    #
+    #   Phlex::Reactive::MCP.load!         # lazy-require the gem + the tool tree
+    #   Phlex::Reactive::MCP::Runner.run   # drive the stdio transport
+    #
+    # Entry point for a host app: `bin/rails phlex_reactive:mcp` (a rake task, not
+    # an exe — introspection needs the booted Rails app). Consumer .mcp.json:
+    #
+    #   { "mcpServers": { "phlex-reactive": {
+    #       "command": "bin/rails", "args": ["phlex_reactive:mcp"] } } }
+    module MCP
+      # Every file under lib/phlex/reactive/mcp/, in DEPENDENCY ORDER (base_tool
+      # before the tools that subclass it; the tools before the server that lists
+      # them; the server before the runner that builds it). Loaded by load! after
+      # the optional gem itself.
+      REQUIRES = %w[
+        phlex/reactive/mcp/base_tool
+        phlex/reactive/mcp/tools/doctor_tool
+        phlex/reactive/mcp/tools/components_tool
+        phlex/reactive/mcp/tools/actions_tool
+        phlex/reactive/mcp/tools/find_tool
+        phlex/reactive/mcp/tools/config_tool
+        phlex/reactive/mcp/server
+        phlex/reactive/mcp/runner
+      ].freeze
+
+      module_function
+
+      # Lazy-require the optional `mcp` gem, then the tool tree in dependency
+      # order. Idempotent (plain require). ONLY `require "mcp"` is rescued — a
+      # LoadError from an internal path propagates verbatim so a typo isn't
+      # masked as "add the mcp gem".
+      def load!
+        begin
+          require "mcp"
+        rescue LoadError
+          raise Phlex::Reactive::Error,
+            "The phlex-reactive MCP diagnostic server needs the `mcp` gem. " \
+            "Add `gem \"mcp\"` to your Gemfile (a dev/test group is fine) and run `bundle install`."
+        end
+
+        REQUIRES.each { require it }
+      end
+    end
+  end
+end

data/lib/phlex/reactive/reply.rb

@@ -99,6 +99,24 @@ module Phlex
       def streams(*strings)
         Response.streams(@component, *strings)
       end
+
+      # Defer an expensive segment (issue #165): `reply.defer(Totals.new(...))`.
+      #
+      # With NO prior verb, the bound component's token is refreshed via a tiny
+      # token-only stream (Response.streams), NOT a full self-replace: a full
+      # replace would re-render the acting component SYNCHRONOUSLY on the request
+      # thread — and if you defer your OWN subject (`reply.defer(self)`), that is
+      # the very render you meant to move OFF the critical path, so the defer
+      # would be silently defeated (a double render). The token-only refresh
+      # rolls the signed identity forward without any synchronous render; the
+      # deferred segment's directive rides alongside. Chain off a verb when you
+      # DO want a synchronous piece too:
+      #
+      #   reply.streams(volume_cell).defer(SessionTotals.new(workout: @workout))
+      #   reply.replace.defer(Totals.new(order: @order))   # explicit self re-render
+      def defer(component, placeholder: nil, morph: false)
+        Response.streams(@component).defer(component, placeholder:, morph:)
+      end
     end
   end
 end

data/lib/phlex/reactive/response.rb

@@ -312,16 +312,29 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
       # NOT trip refresh_token? — it exists only to default #js's target to the
       # bound component's id, so reply.morph.js(js.focus("@root")) scopes to the
       # morphed root without the caller repeating the id.
+      # No deferred segments — the shared default so the common (non-defer)
+      # reply never allocates an empty array per Response.
+      NO_SEGMENTS = [].freeze
+
       def initialize(streams: [], redirect_url: nil, render_self: true, token_component: nil,
-                     subject_component: nil)
+                     subject_component: nil, deferred_segments: NO_SEGMENTS)
         @streams = streams.freeze
         @redirect_url = redirect_url
         @render_self = render_self
         @token_component = token_component
         @subject_component = subject_component
+        @deferred_segments = deferred_segments.freeze
         freeze
       end
 
+      # The recorded reply.defer segments (issue #165), in call order. The
+      # Response only RECORDS them; the endpoint (via the Defer module) builds
+      # the placeholder + directive streams AFTER the action's transaction
+      # committed and picks the delivery lane.
+      attr_reader :deferred_segments
+
+      def deferred? = !@deferred_segments.empty?
+
       # Append extra turbo-stream strings (a sibling component, a flash).
       # Returns a NEW Response (immutable).
       def stream(*more)
@@ -330,7 +343,39 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
           redirect_url: @redirect_url,
           render_self: @render_self,
           token_component: @token_component,
-          subject_component: @subject_component
+          subject_component: @subject_component,
+          deferred_segments: @deferred_segments
+        )
+      end
+
+      # Record a DEFERRED segment (issue #165): `component`'s render is taken
+      # off the actor's critical path — the reply carries a pending marker (or
+      # `placeholder:`) plus a delivery directive, and the real HTML reaches
+      # the SAME actor when the render completes (pull fetch or pgbus push,
+      # picked at the endpoint). `morph: true` makes the arrival morph in place.
+      # Returns a NEW Response (immutable). Chain it like any other verb:
+      #
+      #   reply.streams(volume_cell_stream).defer(SessionTotals.new(workout:))
+      #
+      # Dead constructs fail HERE, loudly: defer on a redirect (the client is
+      # navigating away), a non-reactive component (its identity could never be
+      # rebuilt at render time), a bogus placeholder type.
+      def defer(component, placeholder: nil, morph: false)
+        if redirect?
+          raise Phlex::Reactive::Error,
+            "reply.defer on a redirect reply is dead — the client is navigating away, " \
+            "so the deferred render could never land"
+        end
+        Phlex::Reactive::Defer.validate_segment!(component, placeholder)
+
+        self.class.new(
+          streams: @streams,
+          redirect_url: @redirect_url,
+          render_self: @render_self,
+          token_component: @token_component,
+          subject_component: @subject_component,
+          deferred_segments: @deferred_segments +
+            [Phlex::Reactive::Defer::Segment.new(component:, placeholder:, morph:)]
         )
       end
 

data/lib/phlex/reactive/streamable.rb

@@ -157,7 +157,11 @@ module Phlex
           # known only after rendering, so we mutate the payload inside the block.
           event = { component: name, bytesize: 0 }
           Phlex::Reactive.instrument("render", event) do
-            html = component.render_in(turbo_view_context)
+            # Machinery renders are REAL (issue #165): a reactive_lazy component
+            # emits its actual template here — the lazy shell is for the
+            # page-embedded initial mount only. Two fiber-local writes; the
+            # render bench holds flat.
+            html = Phlex::Reactive::Defer.with_real_render { component.render_in(turbo_view_context) }
             event[:bytesize] = html.bytesize
             html
           end

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.9.3"
+    VERSION = "0.9.5"
   end
 end

data/lib/phlex/reactive.rb

@@ -56,10 +56,34 @@ module Phlex
     # the stdlib one an app catches.
     class UnknownParamType < ::ArgumentError; end
 
+    # Raised when the default-ON verify_authorized guard (issue #168) finds an
+    # action completed WITHOUT any authorization call — the fail-closed
+    # presence-side complement to authorization_errors. It fires INSIDE the
+    # action's transaction, so the mutation rolls back, and it is NOT rescued
+    # into a 4xx: it bubbles as a developer error (a 500 your error tracker
+    # must see) because a missing authorize! is a bug, not a client fault. The
+    # message names the component#action and all three remedies (call an
+    # authorization method / mark_authorized! / declare skip_verify_authorized).
+    class AuthorizationNotVerified < Error; end
+
     # Purpose string bound into every identity token's signature so a token
     # minted for phlex-reactive can't be replayed against another verifier use.
     IDENTITY_PURPOSE = "phlex-reactive/identity"
 
+    # Purpose string for DEFER tokens (issue #165) — the short-TTL identity a
+    # reply.defer directive carries so the client can fetch the expensive
+    # render off the actor's critical path. A distinct purpose makes the two
+    # token families non-interchangeable BY SIGNATURE: an action token is
+    # rejected at the defer endpoint (it must not become a render oracle) and a
+    # defer token can never invoke an action (it carries no action grant).
+    DEFER_PURPOSE = "phlex-reactive/defer"
+
+    # The defer_transport values (issue #165): :auto picks push (pgbus durable
+    # one-shot stream + ActiveJob) when capable, else pull (parallel fetch);
+    # :fetch forces pull; :stream requests push but still degrades to pull with
+    # a warning when the capability is absent (degrade, never break).
+    DEFER_TRANSPORTS = %i[auto fetch stream].freeze
+
     # The current identity-token payload version (issue #111), stamped into every
     # signed token under the "v" key. It exists so the NEXT breaking shape change
     # (a rename, per-token expiry, a nonce) can upgrade tokens already in flight
@@ -167,6 +191,37 @@ module Phlex
         false
       end
 
+      # verify_authorized (issue #168): the default-ON runtime guard. When true,
+      # an action that completes without any authorization call raises
+      # AuthorizationNotVerified inside its transaction (fail-closed — the
+      # mutation rolls back). Default ON is a deliberate, pre-1.0 breaking change:
+      # a forgotten authorize! becomes a loud 500, not a silent hole. Opt out per
+      # component with `skip_verify_authorized`, mark a bespoke check with
+      # `mark_authorized!`, or turn it off globally here. The `defined?` guard
+      # (not `||=`) makes an explicit `= false` stick.
+      attr_writer :verify_authorized
+
+      def verify_authorized
+        return @verify_authorized if defined?(@verify_authorized)
+
+        true
+      end
+
+      # The method names verify_authorized's interceptor wraps to detect an
+      # authorization call (issue #168). Defaults to the common set across
+      # authorization libraries — Pundit (`authorize`), CanCanCan (`authorize!`),
+      # ActionPolicy (`authorize!`/`allowed_to?`). Set in an initializer to match
+      # your app's helper. `mark_authorized!` always counts, regardless of this
+      # list. The `defined?` guard makes an explicit override (including a
+      # narrower list) stick.
+      attr_writer :authorization_methods
+
+      def authorization_methods
+        return @authorization_methods if defined?(@authorization_methods)
+
+        %i[authorize! authorize allowed_to?]
+      end
+
       # Register an app-defined param type (issue #109). The block receives the
       # raw client value and returns the coerced value — or Phlex::Reactive::
       # ParamSchema::DROP to reject it (the keyword default then applies, keeping
@@ -307,6 +362,186 @@ module Phlex
         instance.view_context
       end
 
+      # --- Deferred reply segments (issue #165) --------------------------
+
+      # Lifetime (seconds) of a defer token. It only needs to cover the
+      # reply→fetch gap (or reply→job→SSE on the push lane), so it stays short:
+      # a leaked defer token is a render oracle for exactly one component
+      # identity until this expires. nil resets to the default.
+      attr_writer :defer_token_ttl
+
+      def defer_token_ttl
+        @defer_token_ttl ||= 120
+      end
+
+      # The path the defer endpoint is mounted at (the pull lane's target).
+      # Default "/reactive/defer"; set before boot if it collides.
+      attr_writer :defer_path
+
+      def defer_path
+        @defer_path ||= "/reactive/defer"
+      end
+
+      # How deferred segments reach the actor: :auto (push iff capable, else
+      # pull), :fetch (always pull), :stream (push; degrades to pull with a
+      # warning when the capability is absent). Validated at assignment — a
+      # typo'd transport must fail at the initializer, not silently at reply
+      # time. nil resets to the default.
+      def defer_transport
+        @defer_transport ||= :auto
+      end
+
+      def defer_transport=(value)
+        value = value&.to_sym
+        unless value.nil? || DEFER_TRANSPORTS.include?(value)
+          raise ::ArgumentError,
+            "Phlex::Reactive.defer_transport must be one of #{DEFER_TRANSPORTS.map(&:inspect).join(", ")} " \
+            "(got #{value.inspect})"
+        end
+
+        @defer_transport = value
+      end
+
+      # The ActiveJob queue the push lane's DeferredRenderJob runs on. Default
+      # "default"; point it at a fast queue in production — a deferred segment
+      # is a UX-latency render, and letting it starve behind heavy jobs defeats
+      # the point. nil resets to the default.
+      attr_writer :defer_job_queue
+
+      def defer_job_queue
+        @defer_job_queue ||= "default"
+      end
+
+      # Signs a defer payload (issue #165): same shape + version stamp as the
+      # identity token, but purpose-scoped to DEFER_PURPOSE and expiring after
+      # defer_token_ttl. verify/verify_defer are therefore mutually exclusive
+      # by construction — see the DEFER_PURPOSE comment.
+      # SECURITY (the leaked-token exchange): the defer endpoint re-renders the
+      # real component, whose root carries a fresh NON-expiring identity (action)
+      # token — so a leaked defer token replayed by ANOTHER actor within its TTL
+      # would hand that actor a permanent action token for the same identity.
+      # The purpose is therefore ALSO scoped to the minting actor's binding (the
+      # session id, via with_defer_binding), so a defer token minted under
+      # binding A fails verification under binding B — the exchange can't cross
+      # actors. Unbound (no session — the ActionController::Base default) is the
+      # documented today-behavior; `authorize!` in the action stays the real
+      # authority in every case.
+      # Sign a defer token. `unbound: true` (the reactive_lazy channel) mints
+      # under the PLAIN DEFER_PURPOSE, never the /binding suffix — because a
+      # lazy shell renders during the PAGE render, on a fresh visit where the
+      # session doesn't exist yet (Rails establishes it DURING that response),
+      # so it can't be bound; and it lives in the actor's own page, a small leak
+      # surface. reply.defer tokens (the default) mint under the current actor's
+      # binding — they live in an action HTTP response that can transit proxies/
+      # logs, the real cross-infrastructure leak vector. See docs/security +
+      # the README defer security note. `authorize!` in the action is the real
+      # authority for the harvested-action-token step in both cases.
+      def sign_defer(payload, unbound: false)
+        purpose = unbound ? DEFER_PURPOSE : defer_purpose
+        verifier.generate(payload.merge("v" => TOKEN_VERSION), purpose:, expires_in: defer_token_ttl)
+      end
+
+      # Returns the verified, version-upgraded defer payload, or nil when the
+      # token is tampered, expired, carries the wrong purpose (an action token
+      # OR a BOUND token minted under a DIFFERENT actor binding), or a version
+      # this code doesn't understand — all fail closed through the endpoint's
+      # InvalidToken → 400 path. Tries the current-binding purpose first (the
+      # reply.defer, actor-bound case), then falls back to the plain
+      # DEFER_PURPOSE (the unbound lazy case) — so an unbound lazy token
+      # resolves under ANY binding, while a bound token minted under session-A
+      # still fails under session-B (it was signed with /session-A, which
+      # matches NEITHER /session-B nor the plain purpose).
+      def verify_defer(token)
+        payload = verifier.verified(token, purpose: defer_purpose)
+        payload ||= verifier.verified(token, purpose: DEFER_PURPOSE) if current_defer_binding
+        payload && upgrade_token(payload)
+      end
+
+      # The purpose string for the CURRENT actor's defer tokens: the base
+      # DEFER_PURPOSE, plus the binding when one is present. Binding is folded
+      # into the PURPOSE (not the payload) so it's part of the signature's
+      # domain separation — a mismatched binding is a verification failure, not
+      # a value the endpoint must remember to compare.
+      def defer_purpose
+        binding = current_defer_binding
+        binding ? "#{DEFER_PURPOSE}/#{binding}" : DEFER_PURPOSE
+      end
+
+      # The acting client's defer binding during a request, or nil. Set by the
+      # ActionsController from defer_binding_for(request) — threaded exactly
+      # like current_connection_id.
+      def current_defer_binding
+        Thread.current[:phlex_reactive_defer_binding]
+      end
+
+      def with_defer_binding(binding)
+        previous = Thread.current[:phlex_reactive_defer_binding]
+        Thread.current[:phlex_reactive_defer_binding] = binding.presence
+        yield
+      ensure
+        Thread.current[:phlex_reactive_defer_binding] = previous
+      end
+
+      # Resolve a request to its defer binding: the id of an ALREADY-PERSISTED
+      # session, else nil. The `exists?` gate is load-bearing — a bare
+      # `session.id` LAZILY generates an id even for an empty, never-written
+      # session, and that id is NOT persisted (no Set-Cookie), so two requests
+      # for the same read-only page get DIFFERENT lazy ids and a bound token
+      # minted on one is rejected on the other. Only a persisted session (an
+      # authenticated app wrote one at login) has a stable id across the mint
+      # (page render / action) and the verify (defer endpoint) — exactly the
+      # case where cross-actor exchange is the real threat. A read-only page
+      # with no session mints + verifies UNBOUND consistently (the TTL +
+      # `authorize!` remain the bound). Tolerant of a store that lazily raises:
+      # degrade to nil (unbound), never a 500. Override to bind to your own
+      # actor identity (a stable user id, an API-token digest) — recommended for
+      # a token-authenticated API with no cookie session.
+      def defer_binding_for(request)
+        session = request.session
+        return nil unless session.respond_to?(:exists?) && session.exists?
+
+        session.id&.to_s
+      rescue StandardError
+        nil
+      end
+
+      # --- pgbus capability gates (issue #165) ---------------------------
+      # Runtime capability detection, never `defined?(Pgbus)` alone or a
+      # version string (the core optionality invariant): pgbus < 0.9.2 also
+      # defines ::Pgbus, so the Streams gate probes the ACTUAL keyword.
+
+      # Necessary but NOT sufficient — the Streams entrypoint exists.
+      def pgbus?
+        return false unless defined?(::Pgbus)
+
+        ::Pgbus.respond_to?(:stream)
+      end
+
+      # The reactive-Streams capability: Stream#broadcast accepts :exclude
+      # (the pgbus >= 0.9.2 shape). This is the gate that prevents
+      # `ArgumentError: unknown keyword :exclude` on an old pgbus.
+      def pgbus_streams?
+        return false unless pgbus?
+        return false unless defined?(::Pgbus::Streams::Stream)
+
+        ::Pgbus::Streams::Stream.instance_method(:broadcast)
+          .parameters.any? { |_type, name| name == :exclude }
+      rescue ::NameError
+        false
+      end
+
+      # Everything the defer PUSH lane needs at runtime: streams-capable pgbus,
+      # server-side signed-src minting (SignedName.sign — the element's src is
+      # built off-request), and ActiveJob to run the render off the request
+      # thread. Anything missing → the pull lane (which is always available).
+      def defer_push_capable?
+        return false unless pgbus_streams?
+        return false unless defined?(::Pgbus::Streams::SignedName) &&
+                            ::Pgbus::Streams::SignedName.respond_to?(:sign)
+
+        defined?(::ActiveJob::Base) ? true : false
+      end
+
       # DOM id of the host-app container a Response#flash appends into.
       # Default "flash"; override to match your layout's flash region.
       def flash_target
@@ -340,7 +575,10 @@ module Phlex
       # access (dom_id/url_for/t/csrf). Used for a Phlex component embedded as
       # Response#with content.
       def render(component)
-        component.render_in(off_request_view_context)
+        # A machinery render (issue #165): a reactive_lazy component embedded
+        # in a Response/flash renders its REAL template — the lazy shell is
+        # for the page-embedded initial mount only.
+        Phlex::Reactive::Defer.with_real_render { component.render_in(off_request_view_context) }
       end
 
       # A Turbo::Streams::TagBuilder bound to an off-request view context, used
@@ -597,8 +835,8 @@ loader.tag = "phlex-reactive"
 lib = File.expand_path("..", __dir__)
 loader.push_dir(lib)
 # js.rb defines JS and component/dsl.rb defines Component::DSL (acronyms), not
-# the default-inflected `Js`/`Dsl`.
-loader.inflector.inflect("js" => "JS", "dsl" => "DSL")
+# the default-inflected `Js`/`Dsl`. mcp.rb defines MCP (issue #168).
+loader.inflector.inflect("js" => "JS", "dsl" => "DSL", "mcp" => "MCP")
 # The gem-name shim (`require "phlex-reactive"`) is a plain require, not a
 # managed file.
 loader.ignore("#{lib}/phlex-reactive.rb")
@@ -615,9 +853,21 @@ loader.ignore("#{lib}/generators")
 # Zeitwerk's naming — test_helpers.rb requires it explicitly (only when RSpec is
 # present), and the loader must ignore it.
 loader.ignore("#{lib}/phlex/reactive/test_helpers/matchers.rb")
+# The MCP diagnostic tool tree (issue #168) subclasses the OPTIONAL `mcp` gem's
+# constants (MCP::Tool) at class-definition time, so the whole mcp/ subdirectory
+# must stay out of the autoloader — Phlex::Reactive::MCP.load! requires it in
+# dependency order only when the gem is present. mcp.rb itself (the load! entry
+# point) references no gem constant at load time, so Zeitwerk autoloads it
+# normally (inflected MCP above); only the gem-dependent subtree is ignored.
+loader.ignore("#{lib}/phlex/reactive/mcp")
 # The engine is required explicitly below (only when Rails is present) and must
 # not be eager-loaded before that.
 loader.do_not_eager_load("#{__dir__}/reactive/engine.rb")
+# The defer push-lane job subclasses ActiveJob::Base, which is NOT a gem
+# dependency — eager-loading it in an app without ActiveJob would raise at
+# boot. The constant autoloads on first reference, which only happens behind
+# Phlex::Reactive.defer_push_capable? (that gate requires ActiveJob::Base).
+loader.do_not_eager_load("#{__dir__}/reactive/deferred_render_job.rb")
 loader.setup
 
 require "phlex/reactive/engine" if defined?(Rails::Engine)