phlex-reactive 0.14.3 → 0.15.0

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

@@ -13,6 +13,8 @@ module Phlex
       module Helpers
         extend ActiveSupport::Concern
         include Selection
+        include Sortable
+        include Editable
 
         # The acting client's SSE connection id during the current action (nil
         # outside an action, or when the client isn't subscribed to a stream).
@@ -125,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
 
@@ -278,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
@@ -322,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
@@ -360,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:,
@@ -382,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
@@ -404,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":[…]}'
@@ -435,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\")), " \
@@ -452,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.
@@ -1730,6 +1760,49 @@ 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).
+        def trigger_descriptors(event, shortcut, window_bound, method, once)
+          return "#{event}#{"@window" if window_bound}->reactive##{method}#{":once" if once}" unless shortcut
+
+          shortcut.filters.map { "keydown.#{it}@window->reactive##{method}#{":once" if once}" }.join(" ")
+        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/sortable.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Phlex
+  module Reactive
+    module Component
+      # Sortable lists (issue #350): drag rows to reorder a list, or drag a row
+      # in from another list, and ONE declared action receives the row and its
+      # new position — through the normal action pipeline (the signed token,
+      # the request queue, busy:, the reply).
+      #
+      #   ul(**mix(reactive_root, reactive_sortable(:move, handle: "[data-drag-handle]"))) do
+      #     @list.tasks.each do |task|
+      #       li(id: dom_id(task), **reactive_sortable_item(task.id)) do
+      #         span(data: { drag_handle: true }) { "⠿" }
+      #         plain task.title
+      #       end
+      #     end
+      #   end
+      #
+      # On drop the client sends the action with these params (declare the
+      # ones you want; default-deny drops the rest):
+      #
+      #   item      the dragged row's key (reactive_sortable_item(key))
+      #   position  its 0-based index in the target list after the drop
+      #   after     the key of the row it now follows, nil when it is first
+      #   from      "self" for a reorder, else the name of the list it came from
+      #
+      # The row moves in the DOM at once and moves back when the action fails
+      # (or its reply does not render the list). Rows can be dragged with a
+      # mouse, a pen or a finger (a 200 ms press), and with the keyboard: a
+      # focused row picks up on Space/Enter, moves with the arrow keys, drops
+      # on Space/Enter and goes back on Escape, each step announced through a
+      # live region in the words of `messages:`.
+      #
+      # The drag itself is the client's sortable feature module
+      # (features/sortable.js); a page without a sortable loads none of it on
+      # the split client.
+      module Sortable
+        # The announcement words, {position} and {count} filled in by the
+        # client. Override any of them (a translation) with messages:.
+        SORTABLE_MESSAGES = {
+          picked: "Picked up item {position} of {count}",
+          moved: "Moved to position {position} of {count}",
+          dropped: "Dropped",
+          cancelled: "Cancelled"
+        }.freeze
+
+        # The params the client fills in on drop: a static params: may not set them.
+        SORTABLE_DROP_PARAMS = %i[item position after from].freeze
+
+        # A sortable list. `action` is called on drop.
+        #
+        #   group:     links lists (drag between them) and sources to targets
+        #   handle:    a CSS selector, resolved inside each row; only it starts a
+        #              pointer drag. Without it the whole row drags.
+        #   name:      what a row dragged OUT of this list into another reports
+        #              as `from` (and what that list's from: map keys on)
+        #   from:      a drag-in calls another action: from: { "templates" => :insert }
+        #   params:    static params sent with every drop (e.g. the lane a list is)
+        #   disabled:  refuse every drag from or into this list
+        #   busy:      on(busy:)'s vocabulary, applied to the list while pending
+        #   messages:  the live-region words, merged over SORTABLE_MESSAGES
+        def reactive_sortable(action, group: nil, handle: nil, name: nil, from: nil, params: nil,
+                              disabled: false, busy: nil, messages: nil)
+          sortable_requires_component!
+          action = sortable_action!(action)
+          data = { reactive_sortable: action }
+          data[:reactive_sortable_group] = sortable_name!(:group, group) unless group.nil?
+          data[:reactive_sortable_handle] = sortable_handle!(handle) unless handle.nil?
+          data[:reactive_sortable_name] = sortable_list_name!(name) unless name.nil?
+          data[:reactive_sortable_from] = sortable_from!(from) unless from.nil?
+          data[:reactive_sortable_params] = sortable_params!(params) unless params.nil?
+          data[:reactive_sortable_disabled] = "true" if disabled
+          data[:reactive_sortable_busy] = pending_hint_json(busy, action, :busy) if busy
+          data[:reactive_sortable_messages] = sortable_messages!(messages)
+          { data: }
+        end
+
+        # A list whose rows are COPIED into any sortable of the same group,
+        # never moved. The target's action (or its from: mapping for `name`)
+        # decides what lands, and its reply renders the new row. Needs no
+        # token: it works on a ClientBindings root.
+        def reactive_sortable_source(group:, name: "source")
+          { data: { reactive_sortable_source: sortable_list_name!(name),
+                    reactive_sortable_group: sortable_name!(:group, group) } }
+        end
+
+        # A row and its key — a String or an Integer, sent as-is (JSON-typed).
+        # The row is focusable, for the keyboard model (unless disabled).
+        def reactive_sortable_item(key, disabled: false)
+          unless (key.is_a?(String) && !key.strip.empty?) || key.is_a?(Integer)
+            raise ArgumentError,
+              "reactive_sortable_item key must be a String or an Integer (the row's id), got #{key.inspect}"
+          end
+
+          data = { reactive_sortable_item: key.to_json }
+          # A disabled row cannot be picked up, so it stays out of the tab order.
+          return { data: data.merge(reactive_sortable_disabled: "true") } if disabled
+
+          { tabindex: 0, data: }
+        end
+
+        private
+
+        def sortable_requires_component!
+          return if self.class.include?(Phlex::Reactive::Component::Identity)
+
+          raise ArgumentError,
+            "reactive_sortable needs the full Phlex::Reactive::Component — a drop calls a server action, " \
+            "which Phlex::Reactive::ClientBindings has no token for. A copy-only list on a client-only " \
+            "root is reactive_sortable_source(group:)."
+        end
+
+        # The on() courtesy (issue #105): an undeclared action fails at render
+        # under verbose_errors, not as a 403 at drop time.
+        def sortable_action!(action)
+          if action.nil? || action.to_s.strip.empty?
+            raise ArgumentError, "reactive_sortable needs an action to call on drop, e.g. reactive_sortable(:move)"
+          end
+
+          if Phlex::Reactive.verbose_errors &&
+             (actions = self.class.reactive_actions).any? && !actions.key?(action.to_sym)
+            raise Phlex::Reactive::Error,
+              "#{self.class} has no declared action #{action.to_sym.inspect} (declared: #{actions.keys.inspect})"
+          end
+
+          action.to_s
+        end
+
+        def sortable_name!(option, value)
+          unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
+            raise ArgumentError, "reactive_sortable #{option}: needs a name (a String or Symbol), got #{value.inspect}"
+          end
+
+          value.to_s
+        end
+
+        # "self" is what a reorder within one list reports as `from`.
+        def sortable_list_name!(value)
+          name = sortable_name!(:name, value)
+          if name == "self"
+            raise ArgumentError,
+              'reactive_sortable name: "self" is reserved — it is the `from` of a reorder within one list'
+          end
+
+          name
+        end
+
+        def sortable_handle!(handle)
+          selector = handle.to_s
+          if handle == true || handle == false || selector.strip.empty?
+            raise ArgumentError,
+              "reactive_sortable handle: needs a CSS selector resolved inside each row " \
+              "(e.g. \"[data-drag-handle]\"), got #{handle.inspect}"
+          end
+
+          selector
+        end
+
+        def sortable_from!(from)
+          valid = from.is_a?(Hash) && from.any? && from.keys.all? { !it.to_s.strip.empty? }
+          unless valid
+            raise ArgumentError,
+              "reactive_sortable from: maps a source list's name to the action a drag-in from it calls, " \
+              "e.g. from: { \"templates\" => :insert }, got #{from.inspect}"
+          end
+
+          from.to_h { |list, action| [sortable_list_name!(list), sortable_action!(action)] }.to_json
+        end
+
+        def sortable_params!(params)
+          raise ArgumentError, "reactive_sortable params: must be a Hash, got #{params.inspect}" unless params.is_a?(Hash)
+
+          taken = params.keys.map(&:to_sym) & SORTABLE_DROP_PARAMS
+          unless taken.empty?
+            raise ArgumentError,
+              "reactive_sortable params: cannot set #{taken.first.inspect} — the client fills in " \
+              "#{SORTABLE_DROP_PARAMS.map(&:inspect).join(", ")} on drop"
+          end
+
+          params.to_json
+        end
+
+        def sortable_messages!(messages)
+          return SORTABLE_MESSAGES_JSON if messages.nil?
+          unless messages.is_a?(Hash)
+            raise ArgumentError,
+              "reactive_sortable messages: must be a Hash, got #{messages.inspect}"
+          end
+
+          unknown = messages.keys.map { it.to_s.to_sym } - SORTABLE_MESSAGES.keys
+          unless unknown.empty?
+            raise ArgumentError,
+              "reactive_sortable got an unknown messages: key #{unknown.first.inspect} — " \
+              "supported: #{SORTABLE_MESSAGES.keys.map(&:inspect).join(", ")}"
+          end
+
+          messages.each do |name, words|
+            next if words.is_a?(String)
+
+            raise ArgumentError, "reactive_sortable messages: #{name} must be a String, got #{words.inspect}"
+          end
+
+          SORTABLE_MESSAGES.merge(messages.transform_keys { it.to_s.to_sym }).to_json
+        end
+
+        SORTABLE_MESSAGES_JSON = SORTABLE_MESSAGES.to_json
+        private_constant :SORTABLE_MESSAGES_JSON, :SORTABLE_DROP_PARAMS
+      end
+    end
+  end
+end

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 effects hints devtools].freeze
-      # (Gzipped, bun zlib level 9: the default file 26.1 KB; the core 12.4 KB;
-      # persist 3.2, defer 2.8, form 1.0, bindings 5.4, compute 2.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