phlex-reactive 0.14.4 → 0.15.0

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

@@ -66,7 +66,9 @@ module Phlex
           # verify_authorized opt-out (issue #168): a scalar bare flag (skip the
           # WHOLE component) plus a list of named actions.
           skip_all: :@reactive_own_skip_all,
-          skip_actions: :@reactive_own_skip_actions
+          skip_actions: :@reactive_own_skip_actions,
+          # Presence roster — reactive_presence (issue #358).
+          presence: :@reactive_own_presence
         }.freeze
 
         # The identity-side hot-path memos swept by bump! (see the contract

data/lib/phlex/reactive/component.rb

@@ -146,6 +146,7 @@ module Phlex
       include ClientBindings
       include Identity
       include Lazy
+      include PresenceDeclaration
     end
   end
 end

data/lib/phlex/reactive/defer.rb

@@ -112,6 +112,11 @@ module Phlex
             "got #{placeholder.class}"
         end
 
+        # The signed SSE URL a <pgbus-stream-source> subscribes to `key` with —
+        # minted off-view, as pgbus_stream_from would. Shared with presence
+        # (issue #358), whose roster subscribes to its stream the same way.
+        def stream_src(key) = signed_stream_src(key)
+
         private
 
         # The delivery directive: `<turbo-stream action="reactive:defer">`

data/lib/phlex/reactive/engine.rb

@@ -20,10 +20,10 @@ module Phlex
       # build script (scripts/build_client.js), the core's own table and the
       # default entry name the same features —
       # spec/phlex/engine_client_pin_spec.rb fails when they disagree.
-      CLIENT_FEATURES = %w[persist defer form bindings compute sortable effects hints devtools].freeze
-      # (Gzipped, bun zlib level 9: the default file 28.9 KB; the core 13.5 KB;
-      # persist 3.1, defer 3.0, form 1.0, bindings 6.2, compute 2.1, sortable
-      # 3.1, effects 1.7, hints 1.0, devtools 1.6 KB. spec/javascript/bundle_budget.test.js
+      CLIENT_FEATURES = %w[persist defer form bindings compute sortable presence effects hints devtools].freeze
+      # (Gzipped, bun zlib level 9, KB = 1,024 B: the default file 30.9 KB; the core 14.3 KB;
+      # persist 3.1, defer 2.9, form 1.1, bindings 6.5, compute 2.0, sortable
+      # 3.1, presence 1.3, effects 1.7, hints 0.9, devtools 1.5 KB. spec/javascript/bundle_budget.test.js
       # is the source of truth and holds a ratchet on each.)
 
       # Mount POST /reactive/actions -> Phlex::Reactive::ActionsController#create
@@ -202,6 +202,11 @@ module Phlex
         Phlex::Reactive.freeze_param_types!
         # Freeze the named-schema registry the same way (issue #184).
         Phlex::Reactive.freeze_param_schemas!
+
+        # Presence (issue #358): register the presence stream pattern and the
+        # change hook with the transport. A no-op without a capable pgbus — an
+        # app on Action Cable boots exactly as before.
+        Phlex::Reactive::Presence.install!
       end
     end
   end

data/lib/phlex/reactive/js.rb

@@ -304,6 +304,30 @@ module Phlex
         append("dispatch", args.freeze)
       end
 
+      # --- Presence (issue #358) ---
+      #
+      # presence(**state) — write this tab's presence state through the root's
+      # generated presence_set action (reactive_presence): only the declared
+      # keys reach the server, typed like action params. Always targets the
+      # ROOT, which must declare reactive_presence (the client warns and does
+      # nothing otherwise). ACTOR-ONLY like focus/submit: a broadcast that set
+      # every subscriber's selection would be hostile (BROADCAST_REFUSED_OPS).
+      #   li(**on_client(:click, js.presence(selected: item.id))) { item.title }
+      def presence(**state)
+        raise ArgumentError, "#{self.class}: presence needs at least one state key (e.g. selected: 7)" if state.empty?
+
+        state.each do |name, value|
+          next if value.nil? || [String, Integer, TrueClass, FalseClass].any? { value.is_a?(it) }
+          next if value.is_a?(Float) && value.finite? # NaN and Infinity have no JSON form
+
+          raise ArgumentError,
+            "#{self.class}: presence state values must be scalar (String/Integer/finite Float/true/false/nil) — " \
+            "#{name.inspect} is #{value.class}"
+        end
+
+        append("presence", { "to" => ROOT_SENTINEL, "state" => state.transform_keys(&:to_s).freeze }.freeze)
+      end
+
       # The wire format: a JSON array of [op, args] pairs, applied in order.
       def to_json(*)
         @ops.to_json

data/lib/phlex/reactive/presence/component_methods.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Presence
+      # What reactive_presence adds to a component (issue #358). Included only
+      # by a class that declares presence, so every other component keeps
+      # ActiveSupport's Object#presence.
+      module ComponentMethods
+        # The roster, read once per render (and again after #presence.set). The
+        # memo is namespaced: a component's own @presence must not be clobbered.
+        def presence
+          @reactive_presence_roster ||= Roster.new( # rubocop:disable Naming/MemoizedInstanceVariableName
+            Transport.members(reactive_presence_stream_name),
+            keys: self.class.reactive_presence_declaration.state.keys,
+            connection_id: Presence.connection_id,
+            writer: -> { reactive_presence_write(it) }
+          )
+        end
+
+        # The generated action js.presence sends. Runs authorize_presence_state!
+        # first when the component defines it (raise to refuse), writes the
+        # actor's tab state, and morphs the actor's own view.
+        #
+        # The client also sends it EMPTY on every connect (the announce). That
+        # writes no value — only the reverse note (this class and the record of
+        # the token the actor already holds) on the actor's own row — so there
+        # is nothing to authorize, and the hook is skipped: its keywords may be
+        # required, and calling it with none would raise.
+        def presence_set(**state)
+          authorize_presence_state!(**state) if state.any? && respond_to?(:authorize_presence_state!, true)
+          presence.set(**state)
+          reply.morph
+        end
+
+        # data-reactive-presence-peer / -member on a tab's element: the client
+        # marks the one that is this tab ("me") and this person's other tabs.
+        def reactive_presence_peer(peer)
+          { data: { reactive_presence_peer: peer.seat.to_s, reactive_presence_member: peer.member_id.to_s } }
+        end
+
+        # data-reactive-presence-member / -seats on a person's element.
+        def reactive_presence_member(member)
+          { data: { reactive_presence_member: member.id.to_s, reactive_presence_seats: member.seats.size.to_s } }
+        end
+
+        # [record, :presence, name] — or [*key, :presence, name] record-less.
+        def reactive_presence_stream_parts
+          declaration = self.class.reactive_presence_declaration
+          [*reactive_presence_subject, :presence, declaration.name]
+        end
+
+        def reactive_presence_stream_name
+          @reactive_presence_stream_name ||= reactive_presence_key(reactive_presence_stream_parts)
+        end
+
+        # The root's subscription marker (reactive_attrs): the signed SSE src of
+        # the presence stream. The client mints the <pgbus-stream-source> from it.
+        # And the seats this render saw: a template need not render an element
+        # per tab, so the client diffs these for reactive:presence and checks
+        # them to know its own tab is on the roster. Seats only (pgbus limits
+        # them to [A-Za-z0-9_-]), never a member or connection id.
+        def reactive_presence_data
+          Presence.require_capable!(self.class)
+          { reactive_presence: Transport.source_src(reactive_presence_stream_name),
+            reactive_presence_roster: presence.peers.filter_map(&:seat).join(" ") }
+        end
+
+        private
+
+        # The stream key for the parts. Only pgbus's budget error becomes a
+        # ConfigurationError (the backstop for a name the declaration could not
+        # check); a missing key keeps its own error.
+        def reactive_presence_key(parts)
+          Transport.stream_name(parts)
+        rescue ::ArgumentError => e # pgbus raises the core one; Phlex defines its own
+          raise ConfigurationError, Transport.over_budget_message(self.class, parts.last, e.message)
+        end
+
+        def reactive_presence_subject
+          declaration = self.class.reactive_presence_declaration
+          return declaration.key if declaration.key
+
+          record_key = self.class.reactive_record_key
+          unless record_key
+            raise ArgumentError,
+              "#{self.class.name}: reactive_presence needs reactive_record (the stream is the record's) " \
+              "or key: (the raw stream key parts of a record-less roster)"
+          end
+
+          [instance_variable_get(:"@#{record_key}")]
+        end
+
+        def reactive_presence_write(state)
+          declared = self.class.reactive_presence_declaration.state.keys
+          unknown = state.keys.map(&:to_sym) - declared
+          unless unknown.empty?
+            raise ArgumentError,
+              "#{self.class.name}: presence.set got undeclared state #{unknown.join(", ")} " \
+              "(declared: #{declared.join(", ")})"
+          end
+
+          connection_id = Presence.connection_id
+          return if connection_id.nil?
+
+          merged = (presence.me&.state || {}).merge(state.transform_keys(&:to_sym)).transform_keys(&:to_s)
+          written = Transport.set_state(reactive_presence_stream_name, connection_id:,
+            state: merged.merge(NOTE_KEY => reactive_presence_note))
+          @reactive_presence_roster = nil
+          # No row for this connection (it expired, or pgbus never joined it:
+          # no identity): nothing changed for the peers.
+          return if written.nil?
+
+          # A seatless actor (no ?seat=) is on no roster: nothing any viewer
+          # sees changed, so there is nothing to broadcast.
+          me = presence.me
+          return if me.nil?
+
+          Presence.broadcast(self.class.from_identity(reactive_identity_payload), exclude: connection_id)
+          me
+        end
+
+        # Which component wrote the row: its identity payload (class, record gid,
+        # declared reactive_state), which is how the render job rebuilds it from
+        # the stream (see Presence::NOTE_KEY) — the same shape a token carries.
+        def reactive_presence_note = reactive_identity_payload
+      end
+    end
+  end
+end

data/lib/phlex/reactive/presence/roster.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Presence
+      # The presence of one stream as one render reads it (issue #358): what
+      # `presence` returns in a roster component's view_template and actions.
+      # Built from the transport's rows once per render.
+      #
+      # A row is one SSE connection. Two presence roots in one tab are two
+      # connections of one seat, so peers are grouped by seat: one entry per tab.
+      class Roster
+        include Enumerable
+
+        def initialize(rows, keys:, connection_id: nil, writer: nil)
+          # seat => its connection ids. Private: a connection id is the bearer
+          # key for writing that row, so only `me` reads it.
+          @connections = {}
+          @peers = build_peers(rows, keys)
+          @connection_id = connection_id
+          @writer = writer
+        end
+
+        # Every tab, in join order.
+        attr_reader :peers
+
+        def each(&) = @peers.each(&)
+
+        # The tabs grouped by person, in order of their first tab.
+        def members
+          @members ||= @peers.group_by(&:member_id).map do |id, seats|
+            Member.new(id:, metadata: seats.last.metadata, seats:)
+          end
+        end
+
+        # The tabs whose state matches, e.g. where(selected: item.id).
+        def where(**state) = @peers.select { matches?(it, state) }
+
+        def count = @peers.size
+
+        alias size count
+
+        def empty? = @peers.empty?
+
+        # The actor's own tab during an action (found by its presence
+        # connection), nil in a plain render or before the tab has connected.
+        def me
+          return if @connection_id.nil?
+
+          @peers.find { @connections[it.seat].include?(@connection_id) }
+        end
+
+        # In an action: write the actor's tab state (merged into what it had),
+        # morph the roster into the other viewers' tabs, return the actor's
+        # peer. nil when the actor's tab has no presence connection yet.
+        def set(**state) = @writer.call(state)
+
+        private
+
+        def matches?(peer, state) = state.all? { |key, value| peer.state[key] == value }
+
+        # A row without a seat (a connection that sent no ?seat=: an app's own
+        # turbo_stream_from of the stream, a source without `presence`, a stale
+        # client) is no peer: no client can mark it "me", and keying it by its
+        # connection id would render that id — the bearer key for its row.
+        def build_peers(rows, keys)
+          rows.select { it["seat"].present? }.group_by { it["seat"] }.map do |seat, seat_rows|
+            first = seat_rows.first
+            @connections[seat] = seat_rows.map { it["connection_id"] }
+            Peer.new(
+              seat:, member_id: first["id"].to_s, metadata: seat_rows.last["metadata"] || {},
+              state: declared_state(seat_rows, keys), joined_at: first["joined_at"]
+            )
+          end
+        end
+
+        # The seat's state, declared keys only (never the reverse note), merged
+        # across its connections in join order.
+        def declared_state(seat_rows, keys)
+          seat_rows.each_with_object({}) do |row, state|
+            (row["state"] || {}).each do |key, value|
+              key = key.to_sym
+              state[key] = value if keys.include?(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/presence/transport.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phlex
+  module Reactive
+    module Presence
+      # Every pgbus touchpoint of presence (issue #358), in one place. The
+      # transport half lives in pgbus (zoolutions/pgbus#515): presence rows keyed
+      # by SSE connection, each with the tab's seat and a state jsonb, a change
+      # hook, and a heartbeat that expires silent rows. Nothing else in the gem
+      # names a pgbus presence constant or configuration key.
+      #
+      # pgbus stays optional: the capability is a probe of the real method
+      # signatures, never a version string, and without it nothing here runs —
+      # reactive_presence raises a ConfigurationError at render instead.
+      module Transport
+        # Every presence stream's name ends in ":presence:<name>" — the parts
+        # [record, :presence, name] joined by pgbus/Turbo. Registered with the
+        # transport at boot so a subscription to one joins on connect and leaves
+        # on disconnect, with no controller code.
+        PATTERN = /:presence:[^:]+\z/
+        # Hex characters of the subject's digest that start a presence key.
+        DIGEST_LENGTH = 16
+        # What joins the digest and the presence name.
+        SEPARATOR = ":presence:"
+
+        # pgbus's default streams_heartbeat_interval (seconds), used when pgbus
+        # is absent or does not expose the setting.
+        DEFAULT_HEARTBEAT = 15
+
+        # The change hook install! sets: the app's own hook (if any) first, then
+        # presence's. Its class is how a second install! knows it is in place.
+        ChainedHook = Data.define(:previous, :on_change) do
+          def call(stream_name, change)
+            previous&.call(stream_name, change)
+            on_change.call(stream_name, change)
+          end
+        end
+
+        class << self
+          # The code is there: pgbus with reactive Streams AND presence keyed by
+          # connection (a join that takes connection_id:, a set_state,
+          # seats_supported?), a change hook and a ttl setting, and ActiveJob
+          # (the roster re-renders off the hook's thread). Signatures only, no
+          # query: boot and class load gate on this, and both run before a
+          # database exists (`rails db:create`, `assets:precompile`). What it
+          # gates is configuration, harmless on an unmigrated table.
+          def wired?
+            return false unless Phlex::Reactive.pgbus_streams?
+            return false unless defined?(::Pgbus::Streams::Presence) && defined?(::ActiveJob::Base)
+
+            presence = ::Pgbus::Streams::Presence
+            join_keys = presence.instance_method(:join).parameters.map(&:last)
+            return false unless join_keys.include?(:connection_id) && presence.method_defined?(:set_state)
+            return false unless presence.respond_to?(:seats_supported?)
+
+            # streams_authorize= marks pgbus 0.18 (#524), which also fires
+            # pgbus:connected only after the seat joined (#523) and drops a
+            # closed tab at once (#520); neither of those has a signature.
+            config = ::Pgbus.configuration
+            %i[streams_presence_on_change= streams_presence_ttl streams_presence_patterns streams_authorize=].all? do
+              config.respond_to?(it)
+            end
+          rescue ::NameError
+            false
+          end
+
+          # Wired AND the seat table is migrated. seats_supported? is a query
+          # (pgbus memoizes a success), so only a render and the render job ask.
+          # A database error propagates: answering false would hide it.
+          def capable?
+            wired? && ::Pgbus::Streams::Presence.seats_supported?
+          end
+
+          # How often the transport's heartbeat touches a live tab (seconds):
+          # configuration only, no query, so a declaration can read it at
+          # class load.
+          def heartbeat_interval
+            config = ::Pgbus.configuration if Phlex::Reactive.pgbus? && ::Pgbus.respond_to?(:configuration)
+            interval = config.streams_heartbeat_interval if config.respond_to?(:streams_heartbeat_interval)
+            interval.is_a?(Numeric) ? interval : DEFAULT_HEARTBEAT
+          end
+
+          # The stream name the transport (and every Turbo broadcast) uses for
+          # these parts.
+          # "<16 hex of the subject>:presence:<name>": the subject (the record,
+          # or a record-less roster's key) becomes a fixed-length digest of its
+          # stream name, so the key fits pgbus's queue-name budget (41 chars by
+          # default) whatever the model is called — the raw gid form, or pgbus's
+          # own "<param_key>_<digest>" fragment, overflows it for Document,
+          # Conversation, ProjectBoard, …. Leaves 15 chars for the presence
+          # name; ":presence:<name>" stays the suffix the patterns match. Not
+          # reversible: the render job finds the record through the row's note.
+          # pgbus raises ArgumentError when it still does not fit.
+          def stream_name(parts)
+            *subject, presence, name = parts
+            digest = Digest::SHA256.hexdigest(::Pgbus::Streams::Stream.name_from(subject))[0, DIGEST_LENGTH]
+            ::Pgbus.stream_key!("#{digest}:#{presence}:#{name}")
+          end
+
+          def stream_name_budget = ::Pgbus.stream_name_budget
+
+          # Whether a presence name fits the key: pure configuration (the queue
+          # prefix), no database, so the declaration can check it.
+          def fits?(name) = DIGEST_LENGTH + SEPARATOR.length + name.to_s.length <= stream_name_budget
+
+          def over_budget_message(klass, name, detail = nil)
+            "#{klass.name}: the presence stream for reactive_presence :#{name} does not fit pgbus's " \
+              "stream-name budget of #{stream_name_budget} chars (a #{DIGEST_LENGTH}-char digest of the record, " \
+              "\":presence:\" and the name). Use a shorter presence name.#{" (#{detail})" if detail}"
+          end
+
+          # The signed SSE URL a <pgbus-stream-source> subscribes with.
+          def source_src(stream_name) = Phlex::Reactive::Defer.stream_src(stream_name)
+
+          # The rows of a stream: Hashes with "id" (the member), "connection_id",
+          # "seat", "state", "metadata" and "joined_at".
+          def members(stream_name) = ::Pgbus.stream(stream_name).presence.members
+
+          # Writes the state of ONE connection's row on the stream (pgbus
+          # shallow-merges it into what the row had).
+          def set_state(stream_name, connection_id:, state:)
+            ::Pgbus.stream(stream_name).presence.set_state(connection_id:, state:)
+          end
+
+          # At boot: auto-join presence streams, and hear their changes. An
+          # app's own change hook keeps running (chained, first).
+          def install!(on_change)
+            config = ::Pgbus.configuration
+            patterns = config.streams_presence_patterns
+            patterns << PATTERN unless patterns.include?(PATTERN)
+            previous = config.streams_presence_on_change
+            return if previous.is_a?(ChainedHook)
+
+            config.streams_presence_on_change = ChainedHook.new(previous:, on_change:)
+          end
+
+          # A component's ttl: — seconds a silent seat survives — keyed by its
+          # presence name, which every stream of that component ends with.
+          # pgbus takes an Integer (every stream) or a Hash of stream name /
+          # pattern => seconds with a :default; an Integer becomes the Hash's
+          # default so the app's own setting still covers every other stream.
+          def register_ttl(name, seconds)
+            config = ::Pgbus.configuration
+            ttl = config.streams_presence_ttl
+            config.streams_presence_ttl = ttl = { default: ttl } unless ttl.is_a?(Hash)
+            ttl.store(/:presence:#{Regexp.escape(name.to_s)}\z/, seconds)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/presence.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # Presence (issue #358): who is viewing a stream, one SEAT per browser tab,
+    # each with an ephemeral, declared state (the item it has selected), and a
+    # roster component that re-renders itself in every viewer's tab on join,
+    # leave, expiry and state change.
+    #
+    #   class Boards::Viewers < Phlex::HTML
+    #     include Phlex::Reactive::Component
+    #
+    #     reactive_record :board
+    #     reactive_presence :viewers, state: { selected: :integer }, ttl: 45
+    #
+    #     def view_template
+    #       div(**reactive_root) do
+    #         presence.members.each do |member|
+    #           span(**reactive_presence_member(member)) { member.metadata["name"] }
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # The transport does the membership (pgbus, zoolutions/pgbus#515): an SSE
+    # connection to a presence stream joins on connect and leaves on
+    # disconnect, a silent one expires after the stream's ttl, and each change
+    # calls the hook this module installs. The hook enqueues
+    # PresenceRenderJob, which re-renders the roster for everyone.
+    #
+    # Every pgbus call is in Presence::Transport. Without a capable transport
+    # (no pgbus, an older one, Action Cable) a presence root raises
+    # Phlex::Reactive::ConfigurationError at render: there is no degraded mode.
+    module Presence
+      # The reverse note a presence write leaves in the seat's state: the class
+      # that wrote it and the record it renders. A stream name cannot be turned
+      # back into a record (pgbus digests long names), so the render job reads
+      # this from any seat still on the stream. Never shown to the app: Peer#state
+      # holds only the declared keys.
+      NOTE_KEY = "_rp"
+
+      # A silent seat survives this many seconds (the transport's heartbeat,
+      # 15 s by default, keeps a live one fresh: two missed beats).
+      DEFAULT_TTL = 45
+
+      # Roster broadcasts coalesce: a page reload is a leave and a join within
+      # milliseconds, and a burst of selections is one morph per window.
+      COALESCE_MS = 150
+
+      # The client sends its presence source's connection id in this header, so
+      # a write lands on the row of THIS tab's presence connection — not on the
+      # first <pgbus-stream-source> on the page (X-Pgbus-Connection).
+      HEADER = "X-Reactive-Presence"
+
+      # What reactive_presence declared: the presence name, the state schema,
+      # the ttl, and the raw stream key parts of a record-less component.
+      Declaration = Data.define(:name, :state, :ttl, :key)
+
+      # One tab on the stream. `seat` is the tab's id (opaque; rendered by
+      # reactive_presence_peer so the client can find "me"), `state` the
+      # declared keys only. No connection id: it is the bearer key for writing
+      # the tab's row, so it stays inside the Roster.
+      Peer = Data.define(:seat, :member_id, :metadata, :state, :joined_at)
+
+      # One person: their seats, the newest one's metadata and state.
+      Member = Data.define(:id, :metadata, :seats) do
+        def state = seats.last&.state || {}
+      end
+
+      class << self
+        # Wired and migrated (a query: render time only). See Transport.
+        def capable? = Transport.capable?
+
+        # The actor's presence connection during an action (the HEADER), or nil.
+        def connection_id
+          Thread.current[:phlex_reactive_presence_connection]
+        end
+
+        def with_connection_id(connection_id)
+          previous = Thread.current[:phlex_reactive_presence_connection]
+          Thread.current[:phlex_reactive_presence_connection] = connection_id.presence
+          yield
+        ensure
+          Thread.current[:phlex_reactive_presence_connection] = previous
+        end
+
+        # Raise unless the transport can carry presence — at first render of a
+        # presence root, naming what is missing.
+        def require_capable!(klass)
+          return if capable?
+
+          raise Phlex::Reactive::ConfigurationError,
+            "#{klass.name} declares reactive_presence, which needs pgbus >= 0.18.1 (presence keyed by " \
+            "SSE connection, config.streams_authorize) with its presence table created or migrated " \
+            "(`rails g pgbus:add_presence`, `rails g pgbus:add_presence_seats`, or `rails pgbus:update`), " \
+            "and ActiveJob. Action Cable has no connection identity, so there is no fallback."
+        end
+
+        # Boot (the engine's after_initialize): register the presence stream
+        # pattern and the change hook. Gated on the signatures alone, never a
+        # query — boot runs before a database exists. Nothing is touched
+        # without them: an app on Action Cable boots exactly as before.
+        def install!
+          Transport.install!(method(:changed)) if Transport.wired?
+        end
+
+        # The transport's change hook (it runs on the SSE dispatcher thread):
+        # enqueue a roster render for a presence stream, nothing else.
+        def changed(stream_name, _change)
+          return unless Transport::PATTERN.match?(stream_name.to_s)
+
+          Phlex::Reactive::PresenceRenderJob.perform_later(stream_name.to_s)
+        end
+
+        # The job's body: rebuild every roster component a seat on the stream
+        # names, render it as the table is NOW, and morph it into every viewer's
+        # tab (the joiner included: its first paint ran before its connection
+        # existed). Nobody left, or a gone record, renders nothing.
+        def render_roster(stream_name)
+          return unless capable?
+
+          # One render per class and record. A roster's reactive_state is shared
+          # markup under one id, the same for every viewer, so the state any
+          # note carries will do; per-viewer state belongs in presence state.
+          notes = Transport.members(stream_name).filter_map { it["state"]&.[](NOTE_KEY) }
+          notes.uniq { [it["c"], it["gid"]] }.each do
+            component = build(it, stream_name)
+            broadcast(component, exclude: nil) if component
+          end
+        end
+
+        # Morph `component`'s roster into its stream's viewers.
+        def broadcast(component, exclude:)
+          Phlex::Reactive::Streamable.broadcast_component(
+            component.class, :replace, component, component, [component.reactive_presence_stream_name],
+            morph: true, target: nil, exclude:, visible_to: nil, coalesce: COALESCE_MS
+          )
+        end
+
+        # A roster component rebuilt from a note: the named class, only when it
+        # declares presence, with its record re-found (nil when it is gone).
+        def build(note, stream_name)
+          klass = note["c"].to_s.safe_constantize
+          return unless klass.respond_to?(:reactive_presence_declaration) && klass.reactive_presence_declaration
+
+          klass.from_identity(note.slice("gid", "s"))
+        rescue ::ActiveRecord::RecordNotFound
+          # The record is gone: there is nothing left to render.
+          nil
+        rescue Phlex::Reactive::Error => e
+          # The note cannot rebuild the component (no gid for one that needs
+          # its record): render nothing rather than fail the job on every retry.
+          Phlex::Reactive.send(:default_logger)&.warn(
+            "[phlex-reactive] presence stream #{stream_name}: cannot rebuild #{note["c"]} from its note " \
+            "(#{e.message}); its roster is not re-rendered"
+          )
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/presence_render_job.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    # A presence stream changed (issue #358): a tab joined, left, or expired.
+    # Re-render the roster as the table is when the job runs — not the change
+    # it was enqueued for — and morph it into every viewer's tab. A page
+    # reload (a leave, then a join within milliseconds) therefore renders the
+    # seat present, and coalescing folds the pair into one morph.
+    #
+    # Enqueued by Phlex::Reactive::Presence.changed, the transport's change
+    # hook, which runs on the SSE dispatcher thread: rendering there would hold
+    # it up. On defer_job_queue, like the push lane's render job.
+    #
+    # NOT eager-loaded (see the loader config in phlex/reactive.rb): the class
+    # body needs ActiveJob::Base, which isn't a gem dependency — the constant
+    # is only referenced behind Phlex::Reactive::Presence.capable?.
+    class PresenceRenderJob < ::ActiveJob::Base
+      queue_as { Phlex::Reactive.defer_job_queue }
+
+      def perform(stream_name)
+        Phlex::Reactive::Presence.render_roster(stream_name)
+      end
+    end
+  end
+end