phlex-reactive 0.14.4 → 0.15.1

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

@@ -127,6 +127,10 @@ module Phlex
              (on_complete = self.class.reactive_on_complete_attr)
             data[:reactive_on_complete] = on_complete
           end
+          # Presence (issue #358): the signed src of the roster's presence
+          # stream, from which the client mints its subscription. Only a class
+          # that declares reactive_presence has the method.
+          data.merge!(reactive_presence_data) if respond_to?(:reactive_presence_data)
           { data: }
         end
 
@@ -280,6 +284,17 @@ module Phlex
         # (trailing-edge) — passing both raises ArgumentError.
         #   div(**mix(reactive_root, on(:track, event: "scroll", window: true, throttle: 250)))
         #
+        # `shortcut:` (issue #357, also RESERVED) binds a page-level keyboard
+        # chord: a window keydown whose `mod` is meta on Apple platforms and
+        # ctrl elsewhere (rendered as a meta twin and a ctrl twin; the client
+        # runs the one for its platform). Unlike a plain window binding, the
+        # client prevents the chord's native default, and it skips the chord
+        # while focus is in an input, textarea, select or contenteditable
+        # (native text undo keeps working) unless the Hash form opts in. It
+        # decides event:, window: and outside:, so passing one raises.
+        #   span(**on(:undo, shortcut: "mod+z"))
+        #   span(**on(:close, shortcut: { keys: "esc", in_editable: true }))
+        #
         # `optimistic:` (issue #98) — a small, ALWAYS-REVERSIBLE vocabulary of
         # COSMETIC hints the client applies the instant the trigger fires and
         # REVERTS if the round trip fails, so a click/toggle gives instant feedback
@@ -324,9 +339,9 @@ module Phlex
         # busy_on for scoped indicators.
         #   button(**on(:save, busy: "Saving…")) { "Save" }
         #   button(**on(:destroy, confirm: "Sure?", busy: { add_class: "opacity-50" })) { "Delete" }
-        def on(action_name, event: "click", debounce: nil, throttle: nil, confirm: nil,
+        def on(action_name, event: nil, debounce: nil, throttle: nil, confirm: nil,
                window: false, once: false, outside: false, optimistic: nil, busy: nil,
-               **params)
+               shortcut: nil, **params)
           reject_removed_on_kwargs!(action_name, params)
           # A typo'd or forgotten action renders fine and only surfaces as an
           # opaque 403 at CLICK time (the endpoint's default-deny). Under
@@ -362,8 +377,11 @@ module Phlex
               "exclusive (debounce is trailing-edge, throttle is leading-edge); pick one"
           end
 
-          window_bound = window || outside
-          action = "#{event}#{"@window" if window_bound}->reactive#dispatch#{":once" if once}"
+          # Guarded here, not inside: building the caller label allocates (on() is a hot path).
+          shortcut = shortcut_for!("on(#{action_name.inspect})", shortcut, event:, window:, outside:) unless shortcut.nil?
+          event ||= "click"
+          window_bound = window || outside || !shortcut.nil?
+          action = trigger_descriptors(event, shortcut, window_bound, "dispatch", once)
           attrs = {
             data: {
               action:,
@@ -384,6 +402,9 @@ module Phlex
           # The client decides preventDefault behavior from event.params (never by
           # sniffing the descriptor), so EVERY window binding flags the param.
           attrs[:data][:reactive_window_param] = "true" if window_bound
+          # Issue #357: the client reads the shortcut to pick the twin for its
+          # platform, skip editable targets and prevent the chord.
+          attrs[:data][:reactive_shortcut_param] = shortcut_param_attr(shortcut) if shortcut
           # Force type="button" for click triggers so a bare button inside a <form>
           # can't submit it — EXCEPT when checked: :keep is declared: that hint's
           # whole point is to let a click-bound checkbox/radio flip natively, and a
@@ -406,7 +427,9 @@ module Phlex
         # modifiers (#80): outside-click-to-close a dropdown is
         #   div(**mix(reactive_root, on_client(:click, js.hide("#menu"), outside: true)))
         # Window-bound triggers are never preventDefault-ed by the client and skip
-        # the forced type="button".
+        # the forced type="button". `shortcut:` (issue #357) works as on()'s, on
+        # a bare :keydown only:
+        #   div(**mix(reactive_root, on_client(:keydown, js.toggle("#palette"), shortcut: "mod+k")))
         #
         # Issue #271: each call emits ONE self-describing binding record —
         #   data-reactive-ops-param='{"on":"click","window":true,"outside":true,"ops":[…]}'
@@ -437,7 +460,8 @@ module Phlex
         # Validation is loud: only a non-empty Phlex::Reactive::JS chain is
         # accepted — a dead trigger should fail at render, not no-op in the
         # browser.
-        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil)
+        def on_client(event, ops, window: false, once: false, outside: false, confirm: nil, detail: nil,
+                      shortcut: nil)
           unless ops.is_a?(Phlex::Reactive::JS)
             raise ArgumentError,
               "on_client expects a Phlex::Reactive::JS chain (e.g. js.toggle(\"#menu\")), " \
@@ -454,11 +478,15 @@ module Phlex
               "submit event this trigger is bound to. Bind the submit op to another event " \
               "(change/input), or gate it behind a reducer's $ops / reactive_on_complete."
           end
-          window_bound = window || outside
+          shortcut = client_shortcut!(event, shortcut, window:, outside:)
+          window_bound = window || outside || !shortcut.nil?
           record = client_binding_record(event, ops, window_bound:, outside:, once:, confirm:, detail:)
+          # The record's `on` stays the bare keydown: the client reads a key
+          # filter from `on`, and `mod` is not a key.
+          record["shortcut"] = shortcut.param if shortcut
           attrs = {
             data: {
-              action: "#{event}#{"@window" if window_bound}->reactive#runOps#{":once" if once}",
+              action: trigger_descriptors(event, shortcut, window_bound, "runOps", once),
               # Space-free (issue #271): compact JSON has no structural
               # whitespace, so every space is inside a string, where \u0020
               # parses to the same string — and mix's space-join stays splittable.
@@ -1732,6 +1760,64 @@ module Phlex
             "on(#{action_name.inspect}) #{key}: was removed in issue #181 — use #{REMOVED_ON_KWARGS[key]}"
         end
 
+        # Issue #357: parse on()'s shortcut: (nil when absent). A shortcut
+        # decides the event, the window binding and the containment rule, so
+        # an explicit event:/window:/outside: next to it is a mistake.
+        def shortcut_for!(caller, shortcut, event:, window:, outside:)
+          { "event:" => event, "window:" => window, "outside:" => outside }.each do |name, value|
+            next unless value
+
+            raise ArgumentError,
+              "#{caller} got shortcut: with #{name} — a shortcut is always a window keydown " \
+              "binding; drop #{name}"
+          end
+          Phlex::Reactive::Shortcut.parse(shortcut)
+        end
+
+        # on_client's event is positional: with shortcut: it must be the bare
+        # keydown (the key filter comes from the shortcut).
+        def client_shortcut!(event, shortcut, window:, outside:)
+          return if shortcut.nil?
+
+          unless event == "keydown"
+            raise ArgumentError,
+              "on_client(#{event.inspect}) got shortcut: — bind it to :keydown " \
+              "(on_client(:keydown, ops, shortcut: \"mod+k\")); the key comes from the shortcut"
+          end
+          shortcut_for!("on_client(:keydown)", shortcut, event: nil, window:, outside:)
+        end
+
+        # The data-action descriptors of an on()/on_client trigger: one, or a
+        # shortcut's meta and ctrl twins (space-joined, as mix joins them).
+        # The common, shortcut-less path is ONE interpolation (on() is a hot path).
+        # A chord whose key Stimulus lacks (issue #366: delete, backspace) binds a
+        # bare window keydown: the client's shortcut check matches it alone.
+        def trigger_descriptors(event, shortcut, window_bound, method, once)
+          return "#{event}#{"@window" if window_bound}->reactive##{method}#{":once" if once}" unless shortcut
+          return bare_shortcut_descriptor(shortcut, method, once) unless shortcut.stimulus_filterable?
+
+          shortcut.filters.map { "keydown.#{it}@window->reactive##{method}#{":once" if once}" }.join(" ")
+        end
+
+        # Stimulus removes a `:once` listener after its FIRST event, and a bare
+        # keydown hears every key, so the first keypress of any kind would spend it.
+        def bare_shortcut_descriptor(shortcut, method, once)
+          if once
+            raise ArgumentError,
+              "shortcut: #{shortcut.keys.inspect} cannot take once: — its key is matched by the " \
+              "library, not Stimulus, so the first key pressed of any kind would spend the binding"
+          end
+
+          "keydown@window->reactive##{method}"
+        end
+
+        # A Hash param is JSON (Stimulus's param reader parses it back into an
+        # object); the String form stays a plain string.
+        def shortcut_param_attr(shortcut)
+          param = shortcut.param
+          param.is_a?(Hash) ? param.to_json : param
+        end
+
         # Normalize + validate a pending-state hint (issue #181), returning its
         # JSON wire form. ONE vocabulary + ONE normalizer for both optimistic: (kind
         # :optimistic, reverts on FAILURE) and busy: (kind :busy, reverts on

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # The reactive_presence macro (issue #358). Not named `Presence`: this
+      # module is in every reactive component's constant lookup, where a bare
+      # noun would shadow a host app's kit component of that name (the #233
+      # rule). The behaviour it adds lives in Phlex::Reactive::Presence.
+      module PresenceDeclaration
+        extend ActiveSupport::Concern
+
+        # A presence name is the last part of the stream name, so it is one
+        # identifier: no colon (the stream-name separator), no spaces.
+        PRESENCE_NAME = /\A[a-z][a-z0-9_]*\z/
+
+        class_methods do
+          # Declare this component the roster of a presence stream:
+          # [record, :presence, name], or [*key, :presence, name] for a
+          # record-less component.
+          #
+          #   reactive_record :board
+          #   reactive_presence :viewers, state: { selected: :integer }, ttl: 45
+          #
+          # `state:` is each tab's ephemeral state, typed with the same table as
+          # action params; undeclared keys are dropped. `ttl:` is how many
+          # seconds a silent tab survives. Adds the presence_set action (what
+          # js.presence sends) and `presence` (the roster) to the component.
+          def reactive_presence(name, state: {}, ttl: Phlex::Reactive::Presence::DEFAULT_TTL, key: nil)
+            require_server_actions!(:reactive_presence)
+            declaration = build_presence_declaration(name, state, ttl, key)
+            refuse_dormant_presence! if reactive_dormant?
+            # The name's fit in pgbus's stream-name budget is configuration (the
+            # queue prefix), so it is refused here; the render re-checks it.
+            transport = Phlex::Reactive::Presence::Transport
+            if transport.wired? && !transport.fits?(declaration.name)
+              raise Phlex::Reactive::ConfigurationError, transport.over_budget_message(self, declaration.name)
+            end
+
+            # The generated action. Exempt from verify_authorized: the signed
+            # token already proves the actor rendered this root, and the write
+            # is typed, default-deny, ephemeral and lands only on the actor's own
+            # row (keyed by its secret SSE connection id). A component that needs
+            # a check defines authorize_presence_state!(**state); the action runs
+            # it first.
+            action :presence_set, params: declaration.state
+            skip_verify_authorized :presence_set
+            Registry.write_scalar(self, :presence, declaration)
+            include Phlex::Reactive::Presence::ComponentMethods
+
+            # Class load runs before a database exists: the signatures alone gate it.
+            transport.register_ttl(declaration.name, ttl) if transport.wired?
+            declaration
+          end
+
+          # The Phlex::Reactive::Presence::Declaration, or nil.
+          def reactive_presence_declaration
+            Registry.resolve_scalar(self, :presence, :reactive_presence_declaration)
+          end
+
+          # The presence stream name a roster of `record` subscribes to — what
+          # streams_authorize sees. For a strict per-record check at connect
+          # time: compare it with the key of each record the user may view.
+          # A record-less roster (key:) ignores `record`.
+          def reactive_presence_stream_name_for(record = nil)
+            declaration = reactive_presence_declaration
+            subject = declaration.key || [record]
+            Phlex::Reactive::Presence::Transport.stream_name([*subject, :presence, declaration.name])
+          end
+
+          private
+
+          def build_presence_declaration(name, state, ttl, key)
+            name = name.to_s
+            unless PRESENCE_NAME.match?(name)
+              raise ArgumentError,
+                "#{self.name}: reactive_presence name must be a lowercase identifier (it ends the stream " \
+                "name), got #{name.inspect}"
+            end
+            unless ttl.is_a?(Integer) && ttl.positive?
+              raise ArgumentError, "#{self.name}: reactive_presence ttl: must be a positive Integer (seconds), " \
+                                   "got #{ttl.inspect}"
+            end
+            refuse_ttl_within_heartbeat!(ttl)
+
+            state = state.transform_keys(&:to_sym)
+            if state.key?(Phlex::Reactive::Presence::NOTE_KEY.to_sym)
+              raise ArgumentError,
+                "#{self.name}: reactive_presence state key #{Phlex::Reactive::Presence::NOTE_KEY} is reserved"
+            end
+
+            Phlex::Reactive::Presence::Declaration.new(
+              name: name.to_sym, state: state.freeze, ttl:, key: key && Array(key).dup.freeze
+            )
+          end
+
+          # A ttl at or below the heartbeat would expire a live tab between two
+          # beats: its row would vanish and come back on the next one.
+          def refuse_ttl_within_heartbeat!(ttl)
+            heartbeat = Phlex::Reactive::Presence::Transport.heartbeat_interval
+            return if ttl > heartbeat
+
+            raise ArgumentError,
+              "#{name}: reactive_presence ttl: #{ttl} is at or below the transport's heartbeat interval " \
+              "(#{heartbeat} s), so a live tab would expire between two beats. Use more than #{heartbeat} " \
+              "(two missed beats is a good floor)."
+          end
+
+          def refuse_dormant_presence!
+            raise ArgumentError,
+              "#{name}: reactive_presence cannot be dormant — a dormant root never connects, so its tab " \
+              "would never join the stream. Drop reactive_dormant on this component."
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -186,6 +186,26 @@ module Phlex
         append("focus_first", target_args(to, global:))
       end
 
+      # --- Modal dialogs (issue #365) ---
+      #
+      # show_modal(to)   — HTMLDialogElement#showModal(): the top layer, a
+      #                    focus trap, ::backdrop, Escape to close and focus
+      #                    restored to the opener, all the browser's own. A
+      #                    dialog already open NON-modally is closed and
+      #                    reopened as a modal; one already modal is left as is.
+      # close_dialog(to) — HTMLDialogElement#close() (a closed one is left as is).
+      # A target that is not a <dialog> is skipped. Both ACTOR-ONLY like focus:
+      # opening a modal steals focus, so a broadcast refuses them — a
+      # broadcaster renders the dialog open with data: { reactive_modal: true }.
+
+      def show_modal(to, global: false)
+        append("show_modal", target_args(to, global:))
+      end
+
+      def close_dialog(to, global: false)
+        append("close_dialog", target_args(to, global:))
+      end
+
       # --- Submit (issue #226) ---
       #
       # submit(to = :root) — requestSubmit() the TARGET'S OWN form: the target
@@ -304,6 +324,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