pgbus 0.9.0 → 0.9.2

data/lib/pgbus/streams/renderer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Pgbus
+  module Streams
+    # Turns a renderable into a complete `<turbo-stream>` action tag,
+    # ready to hand to Stream#broadcast. This centralises the off-request
+    # render + tag-building that every consumer would otherwise stitch
+    # together by hand (the #1 footgun in server-driven UI: rendering a
+    # component outside a request without a usable view context).
+    #
+    # pgbus deliberately has no hard dependency on turbo-rails, ActionView,
+    # or Phlex, so this builder is self-contained and matches Turbo's wire
+    # format directly. The browser's Turbo runtime consumes the tag; the
+    # exact string is the contract, not any particular Ruby library.
+    #
+    # Renderable resolution (first match wins):
+    #   - String              → used verbatim (already-rendered markup)
+    #   - responds to :call   → Phlex::HTML#call (the issue's example shape)
+    #   - responds to :render_in → ViewComponent / phlex-rails
+    #     (`render_in(view_context)`; a nil context is passed because
+    #     off-request there is no controller — components that need URL
+    #     helpers should be rendered by the app and the string passed in)
+    #   - else                → to_s
+    #
+    # Tag format mirrors Turbo::Streams::TagBuilder:
+    #   - content actions wrap the markup in a <template>
+    #   - content-less actions (remove) emit no <template>
+    module Renderer
+      # Turbo stream actions that carry no content (no <template> wrapper).
+      CONTENTLESS_ACTIONS = %w[remove].freeze
+
+      module_function
+
+      # Builds a `<turbo-stream action target><template>...</template></turbo-stream>`
+      # string. `renderable` may be nil for content-less actions.
+      def turbo_stream_tag(action:, target:, renderable: nil)
+        raise ArgumentError, "target is required" if target.nil? || target.to_s.empty?
+
+        action = action.to_s
+        attrs = %(action="#{escape(action)}" target="#{escape(target)}")
+
+        return "<turbo-stream #{attrs}></turbo-stream>" if CONTENTLESS_ACTIONS.include?(action)
+
+        content = render(renderable)
+        "<turbo-stream #{attrs}><template>#{content}</template></turbo-stream>"
+      end
+
+      # Resolves a renderable to an HTML string. See module docs for the
+      # resolution order. Returns "" for nil (a content action with no
+      # renderable still emits an empty <template>).
+      def render(renderable)
+        return "" if renderable.nil?
+        return renderable if renderable.is_a?(String)
+        return renderable.call.to_s if renderable.respond_to?(:call)
+        return renderable.render_in(nil).to_s if renderable.respond_to?(:render_in)
+
+        renderable.to_s
+      end
+
+      def escape(value)
+        CGI.escape_html(value.to_s)
+      end
+    end
+  end
+end

data/lib/pgbus/streams.rb

@@ -15,6 +15,12 @@ module Pgbus
     # this specifically can rescue Pgbus::Streams::StreamNameTooLong.
     class StreamNameTooLong < ArgumentError; end
 
+    # The default SSE `event:` name for a broadcast frame. Turbo's
+    # StreamObserver consumes frames the client re-dispatches as the
+    # `message` DOM event; the client maps this SSE event name to
+    # `message`. Broadcasts may override it with a typed name (issue #170).
+    DEFAULT_SSE_EVENT = "turbo-stream"
+
     # Process-wide registry of server-side audience filter predicates.
     # Register filters at boot time via:
     #   Pgbus::Streams.filters.register(:admin_only) { |user| user.admin? }
@@ -28,6 +34,25 @@ module Pgbus
       @filters = nil
     end
 
+    # Process-wide publish-side coalescer for high-frequency broadcasts
+    # (issue #171). Lazily built; the flush re-enters the normal broadcast
+    # path so a coalesced frame is just a deferred ordinary broadcast.
+    def self.coalescer
+      # `target:` is part of the flush signature but unused here — it's only
+      # a coalescing key; the target is already encoded in the payload's
+      # turbo-stream tag. Absorbed via ** so it isn't a broadcast argument.
+      @coalescer ||= Coalescer.new(
+        flush: lambda do |stream_name:, payload:, opts:, **|
+          Pgbus.stream(stream_name).broadcast(payload, **opts)
+        end
+      )
+    end
+
+    # Clears the coalescer. Used by tests; not intended for runtime.
+    def self.reset_coalescer!
+      @coalescer = nil
+    end
+
     # A handle on a single logical stream. The name can be any string, an
     # object responding to `to_gid_param`, or an array of streamables (which
     # are joined with colons — turbo-rails-compatible).
@@ -76,9 +101,48 @@ module Pgbus
       # Per-broadcast `durable:` overrides the stream-level default for a
       # single broadcast. `nil` (the default) defers to the stream's own
       # `durable?` setting; `true`/`false` flip the mode for this call only.
-      def broadcast(payload, visible_to: nil, durable: nil)
+      #
+      # Actor-echo suppression: pass `exclude:` with the broadcaster's own
+      # SSE connection id (surfaced to the page as
+      # `<meta name="pgbus-connection-id">` / the element's `connection-id`
+      # attribute, sent back on the action request as the
+      # `X-Pgbus-Connection` header). The dispatcher skips delivery to that
+      # one connection, so the actor doesn't receive the echo of its own
+      # broadcast — it already applied the change via the action's HTTP
+      # response. Everyone else gets the broadcast. A nil/blank `exclude`
+      # is a no-op (the common path).
+      # Typed SSE event name: pass `event:` to set the SSE `event:` field
+      # on the delivered frame (e.g. `event: "presence"`, `event:
+      # "reactive"`) while keeping the payload a Turbo Stream. Clients that
+      # care can route on the typed event without sniffing the HTML;
+      # default consumers still receive the standard turbo-stream/`message`
+      # path. The default (`nil` or `"turbo-stream"`) is not carried on the
+      # wire — it's the implicit default the dispatcher applies.
+      # High-frequency coalescing: pass `coalesce:` (a window in milliseconds,
+      # or `true` for the default window) together with `target:` to batch
+      # rapid broadcasts to the same (stream, target) and publish only the
+      # latest within the window. Superseded frames never reach the bus.
+      # Last-write-wins, so this is only safe for idempotent replace/update
+      # of a stable target (the high-frequency case: cursors, typing,
+      # progress). Returns nil — the actual broadcast is deferred to the
+      # coalescer's flush. See issue #171 and Pgbus::Streams::Coalescer.
+      def broadcast(payload, visible_to: nil, durable: nil, exclude: nil, event: nil, coalesce: nil, target: nil)
+        if coalesce
+          return coalesce_broadcast(
+            payload,
+            coalesce: coalesce,
+            target: target,
+            visible_to: visible_to,
+            durable: durable,
+            exclude: exclude,
+            event: event
+          )
+        end
+
         wrapped = { "html" => payload.to_s }
         wrapped["visible_to"] = visible_to.to_s if visible_to
+        wrapped["exclude"] = exclude.to_s if exclude && !exclude.to_s.empty?
+        wrapped["event"] = event.to_s if event && event.to_s != DEFAULT_SSE_EVENT
 
         use_durable = durable.nil? ? @durable : durable
         return broadcast_ephemeral(wrapped) unless use_durable
@@ -101,6 +165,36 @@ module Pgbus
         end
       end
 
+      # Renders a renderable (a Phlex component, a ViewComponent, or a
+      # pre-rendered HTML string) into a complete `<turbo-stream>` action
+      # tag and broadcasts it atomically — the render and the broadcast in
+      # one call. This removes the #1 footgun in server-driven UI: building
+      # the off-request render context and the turbo-stream wrapper by hand
+      # at every call site.
+      #
+      #   Pgbus.stream("chat", room).broadcast_render(
+      #     renderable: Chat::Message.new(chat_message: msg),
+      #     action: :append, target: "chat-messages-#{room}",
+      #     exclude: connection_id   # composes with #165
+      #   )
+      #
+      # `action` defaults to :replace. `target` is required. `exclude:`,
+      # `visible_to:`, and `durable:` are forwarded to #broadcast unchanged,
+      # so actor-echo suppression and audience filtering compose. Returns
+      # whatever #broadcast returns (msg_id, or nil when deferred to
+      # after_commit inside a transaction).
+      #
+      # See Pgbus::Streams::Renderer for the renderable-resolution order.
+      # Components that need URL helpers or a full view context should be
+      # rendered by the app (which has the request context) and the
+      # resulting string passed as `renderable:`.
+      def broadcast_render(target:, action: :replace, renderable: nil, visible_to: nil, durable: nil, exclude: nil,
+                           event: nil, coalesce: nil)
+        html = Renderer.turbo_stream_tag(action: action, target: target, renderable: renderable)
+        broadcast(html, visible_to: visible_to, durable: durable, exclude: exclude, event: event,
+                        coalesce: coalesce, target: target)
+      end
+
       def current_msg_id
         @client.stream_current_msg_id(@name)
       end
@@ -172,6 +266,61 @@ module Pgbus
         nil
       end
 
+      # Submits a frame to the process-wide coalescer instead of
+      # broadcasting now. Requires a target (the dedupe key — there's no
+      # way to last-write-win without one). The window is `coalesce` in ms
+      # when numeric, else the coalescer's default. Returns nil; the
+      # coalescer flushes the latest frame as an ordinary broadcast.
+      def coalesce_broadcast(payload, coalesce:, target:, visible_to:, durable:, exclude:, event:)
+        if target.nil? || target.to_s.empty?
+          raise ArgumentError,
+                "broadcast(coalesce:) requires target: — coalescing keys on (stream, target), " \
+                "so the latest frame per target can win. Use broadcast_render(coalesce:) which " \
+                "already has a target, or pass target: explicitly."
+        end
+
+        window_ms = coalesce_window_ms(coalesce)
+        # Resolve durability against THIS stream instance now, not nil. The
+        # coalescer's flush re-enters Pgbus.stream(@name), whose durability
+        # could resolve differently (config patterns) than this instance —
+        # passing the resolved value keeps the coalesced frame's mode stable.
+        resolved_durable = durable.nil? ? @durable : durable
+
+        submit = lambda do
+          Streams.coalescer.submit(
+            stream_name: @name,
+            target: target.to_s,
+            payload: payload.to_s,
+            window_ms: window_ms,
+            opts: { visible_to: visible_to, durable: resolved_durable, exclude: exclude, event: event }
+          )
+        end
+
+        # Transaction gating: a coalesced DURABLE broadcast made inside an
+        # open transaction must not flush if the transaction rolls back, so
+        # defer the submission to after_commit (mirrors the non-coalesced
+        # path). Ephemeral coalescing is fire-and-forget, so it submits now.
+        transaction = resolved_durable ? current_open_transaction : nil
+        if transaction
+          transaction.after_commit { submit.call }
+        else
+          submit.call
+        end
+        nil
+      end
+
+      # Resolves the coalescing window in ms. `true` → the default window;
+      # a positive Numeric is used as-is. Anything else is a misuse and is
+      # rejected at the API boundary with an actionable error rather than a
+      # cryptic NoMethodError deep inside the coalescer's timer math.
+      def coalesce_window_ms(coalesce)
+        return Coalescer::DEFAULT_WINDOW_MS if coalesce == true
+        return coalesce if coalesce.is_a?(Numeric) && coalesce.positive?
+
+        raise ArgumentError,
+              "coalesce: must be true or a positive Numeric window in milliseconds, got #{coalesce.inspect}"
+      end
+
       def ensure_queue!
         return if @ensured
 

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.9.0"
+  VERSION = "0.9.2"
 end

data/lib/pgbus/web/stream_app.rb

@@ -117,10 +117,11 @@ module Pgbus
         hijack_result = env["rack.hijack"].call
         io = hijack_result || env["rack.hijack_io"]
 
-        write_headers(io, stream_name: stream_name, since_id: since_id)
+        connection_id = SecureRandom.hex(8)
+        write_headers(io, stream_name: stream_name, since_id: since_id, connection_id: connection_id)
 
         connection = Pgbus::Web::Streamer::Connection.new(
-          id: SecureRandom.hex(8),
+          id: connection_id,
           stream_name: stream_name,
           io: io,
           since_id: since_id,
@@ -138,14 +139,16 @@ module Pgbus
         require_relative "streamer/falcon_connection" unless defined?(Pgbus::Web::Streamer::FalconConnection)
 
         body = ::Protocol::HTTP::Body::Writable.new
+        connection_id = SecureRandom.hex(8)
 
         body.write(Pgbus::Streams::Envelope.retry_directive(2_000))
         body.write(Pgbus::Streams::Envelope.comment(
                      "pgbus stream open since_id=#{since_id} stream=#{stream_name}"
                    ))
+        body.write(Pgbus::Streams::Envelope.connected(id: connection_id))
 
         connection = Pgbus::Web::Streamer::FalconConnection.new(
-          id: SecureRandom.hex(8),
+          id: connection_id,
           stream_name: stream_name,
           body: body,
           since_id: since_id,
@@ -165,10 +168,11 @@ module Pgbus
         }
       end
 
-      def write_headers(io, stream_name:, since_id:)
+      def write_headers(io, stream_name:, since_id:, connection_id:)
         io.write(Pgbus::Streams::Envelope.http_response_headers)
         io.write(Pgbus::Streams::Envelope.retry_directive(2_000))
         io.write(Pgbus::Streams::Envelope.comment("pgbus stream open since_id=#{since_id} stream=#{stream_name}"))
+        io.write(Pgbus::Streams::Envelope.connected(id: connection_id))
       end
 
       def streamer

data/lib/pgbus/web/streamer/connection.rb

@@ -14,6 +14,10 @@ module Pgbus
       # the client-side leg of the replay-race fix (§6.5 of the design doc).
       class Connection
         attr_reader :id, :stream_name, :io, :mutex, :last_msg_id_sent, :context
+        # The presence member id this connection auto-joined as, or nil for
+        # non-presence streams / anonymous connections. Set by the
+        # Dispatcher on connect; read on disconnect and heartbeat touch.
+        attr_accessor :presence_member
 
         def initialize(id:, stream_name:, io:, since_id:, writer:, write_deadline_ms:, context: nil)
           @id = id
@@ -25,6 +29,7 @@ module Pgbus
           @mutex = Mutex.new
           @dead = false
           @closed = false
+          @presence_member = nil
           @created_at = monotonic
           @last_write_at = @created_at
           # Context is whatever the StreamApp's authorize hook returned
@@ -43,7 +48,7 @@ module Pgbus
 
             bytes = Pgbus::Streams::Envelope.message(
               id: envelope.msg_id,
-              event: "turbo-stream",
+              event: sse_event_for(envelope),
               data: envelope.payload
             )
 
@@ -115,6 +120,15 @@ module Pgbus
 
         private
 
+        # The SSE event name for a frame: the envelope's typed event when
+        # present, else the default turbo-stream. Plain ReadAfter::Envelopes
+        # (no event field) and StreamEnvelopes with a nil event both fall
+        # back to the default. (issue #170)
+        def sse_event_for(envelope)
+          event = envelope.respond_to?(:event) ? envelope.event : nil
+          event && !event.to_s.empty? ? event.to_s : Pgbus::Streams::DEFAULT_SSE_EVENT
+        end
+
         def monotonic
           # Qualify ::Process because Pgbus::Process already exists as a
           # namespace for worker/supervisor/consumer and would otherwise

data/lib/pgbus/web/streamer/falcon_connection.rb

@@ -13,6 +13,7 @@ module Pgbus
       # is fiber-safe under Falcon's scheduler.
       class FalconConnection
         attr_reader :id, :stream_name, :io, :mutex, :last_msg_id_sent, :context
+        attr_accessor :presence_member
 
         def initialize(id:, stream_name:, body:, since_id:, write_deadline_ms:, context: nil)
           @id = id
@@ -24,6 +25,7 @@ module Pgbus
           @mutex = Mutex.new
           @dead = false
           @closed = false
+          @presence_member = nil
           @created_at = monotonic
           @last_write_at = @created_at
           @context = context
@@ -36,7 +38,7 @@ module Pgbus
 
             bytes = Pgbus::Streams::Envelope.message(
               id: envelope.msg_id,
-              event: "turbo-stream",
+              event: sse_event_for(envelope),
               data: envelope.payload
             )
 
@@ -94,6 +96,12 @@ module Pgbus
 
         private
 
+        # See Connection#sse_event_for. (issue #170)
+        def sse_event_for(envelope)
+          event = envelope.respond_to?(:event) ? envelope.event : nil
+          event && !event.to_s.empty? ? event.to_s : Pgbus::Streams::DEFAULT_SSE_EVENT
+        end
+
         def write_to_body(bytes)
           @mutex.synchronize do
             return :closed if @dead || @body.closed?

data/lib/pgbus/web/streamer/heartbeat.rb

@@ -61,6 +61,7 @@ module Pgbus
         # code goes through the background thread.
         def tick
           now = @clock.call
+          presence_conns = []
           @registry.each_connection do |connection|
             if connection.dead?
               # Already dead (e.g. IoWriter returned :closed on a previous
@@ -76,8 +77,15 @@ module Pgbus
             end
 
             result = connection.write_comment("heartbeat #{now.to_i}")
-            enqueue_disconnect(connection) if connection.dead? || result != :ok
+            if connection.dead? || result != :ok
+              enqueue_disconnect(connection)
+              next
+            end
+
+            presence_conns << connection if presence_member?(connection)
           end
+
+          enqueue_presence_touch(presence_conns)
         end
 
         private
@@ -99,6 +107,20 @@ module Pgbus
         def enqueue_disconnect(connection)
           @queue << StreamEventDispatcher::DisconnectMessage.new(connection: connection)
         end
+
+        def presence_member?(connection)
+          connection.respond_to?(:presence_member) && !connection.presence_member.nil?
+        end
+
+        # Posts one batched touch per tick so the dispatcher (which owns AR
+        # connection release) refreshes last_seen_at for live presence
+        # members, keeping them out of the sweeper. No message when no
+        # connection has presence — avoids waking the dispatcher for nothing.
+        def enqueue_presence_touch(connections)
+          return if connections.empty?
+
+          @queue << StreamEventDispatcher::PresenceTouchMessage.new(connections: connections)
+        end
       end
     end
   end

data/lib/pgbus/web/streamer/stream_event_dispatcher.rb

@@ -32,18 +32,34 @@ module Pgbus
       # disambiguate from Pgbus::Process::Dispatcher, which is an
       # unrelated worker-side pool coordinator. See issue #98 item 8.
       class StreamEventDispatcher
-        WakeMessage       = Listener::WakeMessage
-        ConnectMessage    = Data.define(:connection)
-        DisconnectMessage = Data.define(:connection)
+        WakeMessage          = Listener::WakeMessage
+        ConnectMessage       = Data.define(:connection)
+        DisconnectMessage    = Data.define(:connection)
+        # Posted by the Heartbeat once per tick with the current presence
+        # connections, so the touch (a last_seen_at refresh) runs on the
+        # dispatcher thread where AR connections are released each pass.
+        PresenceTouchMessage = Data.define(:connections)
 
         # An unwrapped stream broadcast. Similar shape to
         # Pgbus::Client::ReadAfter::Envelope (msg_id + payload) so
         # Connection#enqueue can consume either type via duck typing,
-        # but adds the `visible_to` label carried through from
-        # Pgbus::Streams::Stream#broadcast. The Dispatcher uses
-        # visible_to to decide per-connection delivery; Connection
-        # never sees the field.
-        StreamEnvelope = Data.define(:msg_id, :enqueued_at, :payload, :source, :visible_to)
+        # but adds two delivery-control fields carried through from
+        # Pgbus::Streams::Stream#broadcast:
+        #   - `visible_to` — audience filter label (evaluated per-connection)
+        #   - `exclude`    — a connection id to skip (actor-echo suppression:
+        #                    the broadcaster's own SSE connection does not
+        #                    receive the echo of its own broadcast)
+        # The Dispatcher uses both to decide per-connection delivery;
+        # Connection never sees either field.
+        #   - `event`      — the SSE `event:` name for the delivered frame.
+        #                    nil means the default (turbo-stream); a typed
+        #                    name (e.g. "presence", "reactive") lets clients
+        #                    route without sniffing the HTML (issue #170).
+        StreamEnvelope = Data.define(:msg_id, :enqueued_at, :payload, :source, :visible_to, :exclude, :event) do
+          def initialize(msg_id:, enqueued_at:, payload:, source:, visible_to: nil, exclude: nil, event: nil)
+            super
+          end
+        end
 
         DEFAULT_READ_LIMIT = 500
 
@@ -51,13 +67,18 @@ module Pgbus
 
         def initialize(client:, registry:, listener:, dispatch_queue:,
                        logger: Pgbus.logger, read_limit: DEFAULT_READ_LIMIT,
-                       filters: nil, config: nil, stream_counter: nil)
+                       filters: nil, config: nil, stream_counter: nil,
+                       presence_provider: nil)
           @client = client
           @registry = registry
           @listener = listener
           @queue = dispatch_queue
           @logger = logger
           @read_limit = read_limit
+          # Vends a presence handle for a logical stream name. Injected so
+          # tests can record join/leave/touch without a DB. Production
+          # defaults to the real per-stream Presence via Pgbus.stream.
+          @presence_provider = presence_provider || ->(name) { Pgbus.stream(name).presence }
           # Filters default to the process-wide registry so production
           # code picks up whatever was registered at boot. Tests inject
           # a fresh Filters instance to avoid cross-test pollution.
@@ -175,9 +196,10 @@ module Pgbus
 
         def handle(msg)
           case msg
-          when WakeMessage       then handle_wake(msg)
-          when ConnectMessage    then handle_connect(msg)
-          when DisconnectMessage then handle_disconnect(msg)
+          when WakeMessage          then handle_wake(msg)
+          when ConnectMessage       then handle_connect(msg)
+          when DisconnectMessage    then handle_disconnect(msg)
+          when PresenceTouchMessage then handle_presence_touch(msg)
           else
             @logger.warn { "[Pgbus::Streamer::StreamEventDispatcher] unknown message: #{msg.class}" }
           end
@@ -239,6 +261,7 @@ module Pgbus
 
           visible_to = parsed["visible_to"]
           visible_to = visible_to.to_sym if visible_to.is_a?(String)
+          exclude = parsed["exclude"]
 
           @ephemeral_seq += 1
           envelope = StreamEnvelope.new(
@@ -246,7 +269,9 @@ module Pgbus
             enqueued_at: Time.now.utc.iso8601(6),
             payload: html,
             source: "ephemeral",
-            visible_to: visible_to
+            visible_to: visible_to,
+            exclude: exclude,
+            event: normalize_sse_event(parsed["event"])
           )
 
           registered.each do |conn|
@@ -320,6 +345,7 @@ module Pgbus
           else
             @stream_counter.increment_connections(stream)
             @registry.register(connection)
+            presence_join(connection, stream)
           end
 
           record_stat(
@@ -346,6 +372,7 @@ module Pgbus
           removed = @registry.unregister(connection)
           @scanned_cursor.delete(connection)
           @stream_counter.decrement_connections(stream) if removed
+          presence_leave(connection, stream)
           cleanup_stream_if_unused(stream)
 
           record_stat(
@@ -355,6 +382,21 @@ module Pgbus
           )
         end
 
+        # Touches (refreshes last_seen_at for) the presence members on the
+        # given connections. Posted by the Heartbeat each tick so idle but
+        # still-connected members don't get swept. Connections without a
+        # presence member (non-presence streams, anonymous) are skipped.
+        def handle_presence_touch(msg)
+          msg.connections.each do |connection|
+            member_id = presence_member_of(connection)
+            next unless member_id
+
+            @presence_provider.call(connection.stream_name).touch(member_id: member_id)
+          rescue StandardError => e
+            @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] presence touch failed: #{e.class}: #{e.message}" }
+          end
+        end
+
         # If this stream has no remaining subscribers (registered or
         # in-flight), release all per-stream state so long-running
         # processes don't leak memory proportional to unique stream
@@ -426,6 +468,22 @@ module Pgbus
           @client.config.queue_name(stream_name)
         end
 
+        # Sanitizes a typed SSE event name from an untrusted broadcast
+        # payload before it reaches the SSE `event:` line. Returns nil
+        # (→ the default turbo-stream event) for non-strings, blanks, or
+        # any value containing CR/LF — a crafted event with a newline could
+        # otherwise inject extra SSE fields (a forged id:/data:) into the
+        # frame and corrupt cursor/event routing. Defense in depth with
+        # Envelope.message, which also strips newlines.
+        def normalize_sse_event(value)
+          return nil unless value.is_a?(String)
+
+          event = value.strip
+          return nil if event.empty? || event.match?(/[\r\n]/)
+
+          event
+        end
+
         # Pgbus::Streams::Stream#broadcast wraps HTML payloads as
         # {"html": "..."} so PGMQ's JSONB column accepts them. Here we
         # unwrap the html field and return a new envelope whose payload
@@ -442,13 +500,16 @@ module Pgbus
 
           visible_to = parsed["visible_to"]
           visible_to = visible_to.to_sym if visible_to.is_a?(String)
+          exclude = parsed["exclude"]
 
           StreamEnvelope.new(
             msg_id: envelope.msg_id,
             enqueued_at: envelope.enqueued_at,
             payload: html,
             source: envelope.source,
-            visible_to: visible_to
+            visible_to: visible_to,
+            exclude: exclude,
+            event: normalize_sse_event(parsed["event"])
           )
         rescue JSON::ParserError
           envelope
@@ -460,13 +521,67 @@ module Pgbus
         # Filters registry. Envelopes that predate the StreamEnvelope
         # refactor (plain ReadAfter::Envelope with no visible_to) also
         # pass through.
+        #
+        # Actor-echo suppression: an envelope carrying `exclude:` (a
+        # connection id) is dropped for the connection whose id matches.
+        # This lets the broadcaster's own SSE connection skip the echo of
+        # its own broadcast — the actor already applied the change via its
+        # action's HTTP response, so re-applying the SSE echo would
+        # double-apply (re-run animations, clobber optimistic edits). The
+        # exclude check runs *before* the audience filter so an excluded
+        # actor is skipped even when it would otherwise match visible_to.
         def visible_envelopes_for(envelopes, connection)
           envelopes.select do |envelope|
+            next false if excluded?(envelope, connection)
+
             label = envelope.respond_to?(:visible_to) ? envelope.visible_to : nil
             @filters.visible?(label, connection.context)
           end
         end
 
+        # True when the envelope names this connection in its `exclude`
+        # field. Guarded by respond_to? so plain ReadAfter::Envelopes
+        # (no exclude field) and connections without an id never match.
+        def excluded?(envelope, connection)
+          return false unless envelope.respond_to?(:exclude)
+
+          exclude = envelope.exclude
+          return false if exclude.nil? || exclude.to_s.empty?
+
+          connection.respond_to?(:id) && connection.id.to_s == exclude.to_s
+        end
+
+        # Connection-driven presence (issue #169). Auto-joins a member when
+        # the stream is configured for presence and the connection's
+        # authorize-context yields a member id. Stores the member id on the
+        # connection so handle_disconnect/handle_presence_touch can act on
+        # it. Failures are logged and swallowed: a presence DB hiccup must
+        # not knock a live SSE connection out of the registry.
+        def presence_join(connection, stream)
+          return unless @config&.stream_presence?(stream)
+
+          member = @config.presence_member_for(connection.context)
+          return unless member
+
+          @presence_provider.call(stream).join(member_id: member[:id], metadata: member[:metadata] || {})
+          connection.presence_member = member[:id] if connection.respond_to?(:presence_member=)
+        rescue StandardError => e
+          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] presence join failed: #{e.class}: #{e.message}" }
+        end
+
+        def presence_leave(connection, stream)
+          member_id = presence_member_of(connection)
+          return unless member_id
+
+          @presence_provider.call(stream).leave(member_id: member_id)
+        rescue StandardError => e
+          @logger.error { "[Pgbus::Streamer::StreamEventDispatcher] presence leave failed: #{e.class}: #{e.message}" }
+        end
+
+        def presence_member_of(connection)
+          connection.respond_to?(:presence_member) ? connection.presence_member : nil
+        end
+
         def monotonic_ms
           ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) * 1000.0
         end