chats 0.1.1 → 0.6.2

data/app/controllers/chats/application_controller.rb

@@ -55,11 +55,52 @@ module Chats
       Chats.config.layout
     end
 
-    # Conversations are ALWAYS resolved through the viewer's own inbox
-    # relation: not-a-participant, left, or blocked-counterpart threads all
-    # come back as a plain 404 — existence is never leaked to outsiders.
+    # Conversations are ALWAYS resolved through relations that only hold
+    # what this viewer may open (conversation_lookup_scopes): not a
+    # participant, left, or a blocked counterpart all come back as a plain
+    # 404, the same 404 as an id that doesn't exist — existence is never
+    # leaked to outsiders. Every engine endpoint (the thread, a dock window,
+    # sending, editing, reacting, reading) looks a conversation up here.
+    #
+    # The first scope that has it wins; later scopes are asked only on a
+    # miss. Errors a scope raises are not rescued: a broken product scope
+    # must fail loudly, never turn into a quiet 404.
     def find_conversation(id = params[:id])
-      chats_current_messager.chats.find(id)
+      conversation_lookup_scopes.each do |scope|
+        conversation = scope.find_by(id: id)
+        return conversation if conversation
+      end
+
+      raise ActiveRecord::RecordNotFound.new(
+        "Couldn't find Chats::Conversation with 'id'=#{id}", Chats::Conversation.name, "id", id
+      )
+    end
+
+    protected
+
+    # Where find_conversation looks, in order: by default the viewer's own
+    # inbox relation (`Messager#chats`: their active seats, blocks and
+    # `config.inbox_scope` applied).
+    #
+    # THE extension point for a conversation that must open although the
+    # inbox hides it. A product gem built on chats (support_desk: a
+    # requester's own ticket, which the host's inbox_scope keeps out of the
+    # inbox) prepends a module that appends its own relation:
+    #
+    #   module SupportDesk::ConversationLookup
+    #     protected
+    #
+    #     def conversation_lookup_scopes
+    #       super + [SupportDesk::Ticket.conversations_of(chats_current_messager)]
+    #     end
+    #   end
+    #   Chats::ApplicationController.prepend(SupportDesk::ConversationLookup)
+    #
+    # Each scope must hold only conversations this viewer may open: the
+    # union of the scopes IS the authorization. Nothing the scopes don't
+    # name becomes reachable.
+    def conversation_lookup_scopes
+      [chats_current_messager.chats]
     end
   end
 end

data/app/controllers/chats/conversations_controller.rb

@@ -2,37 +2,80 @@
 
 module Chats
   # The inbox (index), the thread (show), starting conversations from host
-  # pages (create), and the per-member actions (read/typing/leave/mute).
+  # pages (create), the messaging dock's recent list (dock), and the
+  # per-member actions (read/typing/leave/mute).
   class ConversationsController < ApplicationController
+    # The most rows the dock's recent list shows, whatever `recent:` asks.
+    DOCK_RECENT_LIMIT = 50
+    # How far before its list of what exists a catch-up stops naming
+    # deletions (see #present_messages).
+    PRESENT_MARGIN = 10.seconds
+    # The most ids a catch-up cursor may name, and the longest id (a UUID is
+    # 36): a client past either gets its history re-rendered instead.
+    CURSOR_IDS_LIMIT = 200
+    CURSOR_ID_LENGTH = 64
+    # The two-pane messaging page's conversation frame (index.html.erb): a
+    # request from it is answered with the pane alone (pane.html.erb).
+    PANE_FRAME = "chats_conversation"
+
     before_action :set_conversation, only: %i[show read typing leave mute unmute refresh]
+    helper_method :chats_counterpart, :chats_two_panes?, :chats_inbox_filter
 
     # The inbox. Everything is preloaded/batched so rendering N rows costs a
     # constant number of queries (conversations + last messages + participants
     # + one grouped unread-count query — see Conversation.unread_counts_for).
+    # Rows are Conversation | InboxGroup: stacking, search and the `?with=`
+    # filter all live in Chats::Inbox, so this action stays three lines.
     def index
-      @conversations = chats_current_messager.chats
-                                             .includes(:last_message, :subject, participants: :messager)
-                                             .limit(200)
-      @conversations = apply_search(@conversations)
-      @unread_counts = Chats::Conversation.unread_counts_for(chats_current_messager, @conversations)
+      # The dock's search form posts here, so that without JavaScript it
+      # lands on the full inbox's results; from the dock's frame, the answer
+      # is the dock's own list.
+      return dock if turbo_frame_request_id == "chats_dock_list"
+
+      load_inbox
+    end
+
+    # The messaging dock's recent list (`chats_dock`): the first rows of the
+    # viewer's inbox — the same rows, stacks and search, through the same
+    # Chats::Inbox — rendered into the dock's `chats_dock_list` frame. The
+    # frame asks for `?recent=` rows (the helper's `recent:` option).
+    def dock
+      @inbox = Chats::Inbox.for(chats_current_messager, query: params[:q], limit: dock_recent)
+      @rows = @inbox.rows
+      @unread_counts = @inbox.unread_counts
+
+      render :dock, layout: false
+    end
+
+    # The viewer's unread badges as a Turbo Stream: the nav badge
+    # (`chats_unread_badge`) and every badge in the dock, replaced with the
+    # same count the badge streams send. What a page asks for when it may
+    # have missed them (chats/recovery: a reconnect, a return to a hidden
+    # page, a restored page). Reads nothing, writes nothing.
+    def badge
+      render :badge, formats: :turbo_stream, locals: { count: chats_current_messager.unread_chats_count }
     end
 
     # The thread. Renders the LATEST page of messages; older pages stream in
     # through a lazy Turbo Frame chain (keyset-paginated — see
     # Message.before_message and _messages_page.html.erb).
+    #
+    # `?window=1` from a Turbo frame is the same thread as a floating dock
+    # window: the window template (its compact header around the same
+    # thread body), no layout.
+    #
+    # With two panes (`config.inbox_layout = :split`, the default) the
+    # thread is the conversation pane of the messaging page: the whole page
+    # (the inbox's template, with the pane open), or, asked from that page's
+    # own conversation frame (a row clicked on a wide screen), the pane
+    # alone. `:stacked` renders the thread page.
     def show
       @participant = @conversation.participant_for(chats_current_messager)
 
       anchor = params[:before].present? ? @conversation.messages.find_by(id: params[:before]) : nil
-      scope = @conversation.messages.includes(:sender, :reactions)
-      scope = scope.with_attached_files if scope.respond_to?(:with_attached_files)
+      scope = rendered_messages
       scope = scope.before_message(anchor) if anchor
-
-      # Fetch newest-first + reverse so "the last N messages" render in
-      # chronological order. One extra record peeks whether older pages exist.
-      page = scope.recent_first.limit(Chats.config.messages_per_page + 1).to_a
-      @more_messages = page.size > Chats.config.messages_per_page
-      @messages = page.first(Chats.config.messages_per_page).reverse
+      @messages, @more_messages = latest_page_of(scope)
 
       if anchor
         # Older-page request from the pagination frame: render just the page.
@@ -40,51 +83,73 @@ module Chats
                locals: { conversation: @conversation, messages: @messages, more: @more_messages }
       else
         # The «new messages» divider: computed BEFORE read! advances the
-        # horizon (after it, nothing is unread anymore). Anchored to the
-        # oldest unread bubble on the rendered page; when the backlog runs
-        # deeper than one page it pins to the top of the page instead —
-        # the scroll-up frame chain holds the rest.
-        if @participant&.unread?
-          @first_unread_id = @participant.unread_messages.where(id: @messages.map(&:id)).oldest_first.pick(:id) ||
-                             @messages.first&.id
-        end
+        # horizon (after it, nothing is unread anymore).
+        @first_unread_id = first_unread_id(@participant, @messages)
 
-        # Opening the thread reads it. (Live appends while the thread stays
-        # open are read via the thread controller's POST to #read.)
-        @participant&.read!
+        if dock_window?
+          # A window does NOT read on render: it may be restored minimized
+          # after a reload, and a header nobody has looked at must not
+          # swallow the unread badge. The thread controller posts #read once
+          # the window is actually on screen (`read-pending`).
+          render :window, layout: false
+        else
+          # Opening the thread reads it. (Live appends while the thread
+          # stays open are read via the thread controller's POST to #read.)
+          # A render the server doesn't read is marked `read-pending`: the
+          # thread controller reads it once it is on screen.
+          @read_pending = !reads_on_render?
+          @participant&.read! unless @read_pending
+          render_split_page if chats_two_panes?
+        end
       end
     end
 
-    # Stale-thread catch-up: appends messages created — and replaces ones
-    # edited/tombstoned — since the newest `updated_at` the client has
-    # rendered (`?since=` in ms). The thread controller calls this when the
-    # tab wakes from a long sleep or its Turbo Stream subscription
-    # reconnects, i.e. whenever broadcasts may have been missed. Mobile
-    # WebViews suspend WebSockets aggressively, so without this a
-    # backgrounded chat silently loses messages until a manual reload.
-    # Pattern from Basecamp's Campfire (Rooms::RefreshesController):
-    # https://github.com/basecamp/once-campfire
+    # Stale-thread catch-up, on the client's cursors (see Message's catch-up
+    # scopes): `after=` µs and `after_ids=`, its newest creation and the ids
+    # it has at that moment (0 and none for an empty thread); `changed=` µs
+    # and `changed_ids=`, its newest change; `from=` µs, its oldest bubble's
+    # creation. Bubbles ejected before they carried these send `since=` ms
+    # alone, and are answered as they always were. The thread
+    # controller calls this whenever chats/recovery says the stream may have
+    # missed something: a reconnect, a return after 10 seconds hidden, the
+    # network back, a restored page. Mobile WebViews suspend WebSockets
+    # aggressively, so without this a backgrounded chat silently loses
+    # messages until a manual reload. Pattern from Basecamp's Campfire
+    # (Rooms::RefreshesController): https://github.com/basecamp/once-campfire
+    #
+    # The answer touches the history only, never the composer or its draft:
+    # messages created since are appended, ones changed since (edits,
+    # tombstones, reactions) replaced, the read state replaced, and — under
+    # `deletion: :hard` — the bubbles that no longer exist removed. Reads
+    # nothing: catching up is not reading (the controller posts #read once
+    # the viewer can see the new messages).
+    #
+    # `render turbo_stream:`, NOT `render html: … content_type:` — the
+    # latter forces text/html and silently ignores the content type, so the
+    # body says <turbo-stream> while the response says it isn't one.
     def refresh
-      head :no_content and return if params[:since].blank?
+      head :no_content and return if params[:changed].blank? && params[:since].blank?
 
-      since = Time.zone.at(0, params[:since].to_i, :millisecond)
-      scope = @conversation.messages.includes(:sender, :reactions)
-      scope = scope.with_attached_files if scope.respond_to?(:with_attached_files)
-
-      @new_messages = scope.created_since(since).oldest_first.limit(Chats.config.messages_per_page + 1).to_a
-
-      # A backlog deeper than one page would mean splicing an arbitrary
-      # amount of history through surgical appends; a Turbo 8 page refresh
-      # (morph + scroll preservation) re-renders the latest page + frame
-      # chain correctly instead. Raw tag rather than `turbo_stream.refresh`
-      # so we don't depend on turbo-rails ≥ 2.0 helpers.
-      if @new_messages.size > Chats.config.messages_per_page
-        render html: '<turbo-stream action="refresh"></turbo-stream>'.html_safe,
-               content_type: "text/vnd.turbo-stream.html"
-        return
-      end
+      # A client whose cursors name more than the limit (a busy thread whose
+      # live bubbles piled up since it last caught up, or a forged request)
+      # is answered with what is cheap at any size: the latest page.
+      return render_from_scratch if cursors_over_limit?
 
-      @updated_messages = scope.updated_since(since)
+      scope = rendered_messages
+      new_messages, @updated_messages = catch_up_on(scope)
+      @new_messages = new_messages.oldest_first.limit(Chats.config.messages_per_page + 1).to_a
+
+      # More than a page behind: splicing an arbitrary backlog through
+      # surgical appends would leave a hole in the scroll-up chain. Re-render
+      # the history at the latest page instead, exactly as opening the thread
+      # does, frame chain included. A thread view ejected before the history
+      # had its id (no `history=1`) gets the page refresh it always got;
+      # `request_id: nil`, because Turbo skips a refresh tagged with a request
+      # of its own, and this one answers the client's own catch-up.
+      return render_from_scratch if @new_messages.size > Chats.config.messages_per_page
+
+      @caught_up = caught_up_cursors if params[:changed].present?
+      @present = present_messages if Chats.config.deletion == :hard && params[:from].present?
       render "chats/conversations/refresh", formats: :turbo_stream
     end
 
@@ -93,6 +158,12 @@ module Chats
     # `chat_button_to` helper — unforgeable and purpose-scoped, so raw
     # polymorphic params never reach `GlobalID::Locator`. Policy and block
     # checks still run inside `chat_with` (defense in depth).
+    #
+    # `dock=1` (`chat_button_to …, dock: true`) answers a Turbo Stream that
+    # appends the conversation's floating window to the dock instead of
+    # navigating. Same id, so a window already open is replaced, not
+    # doubled; on a page without the dock the stream has no target and does
+    # nothing. Without Turbo it is the plain redirect.
     def create
       recipient = locate_signed!(params.require(:recipient_sgid), purpose: :chats_recipient)
       raise ActiveRecord::RecordNotFound unless Chats.messager_class?(recipient.class)
@@ -101,7 +172,16 @@ module Chats
                 locate_signed!(params[:subject_sgid], purpose: :chats_subject)
 
       conversation = chats_current_messager.chat_with(recipient, about: subject)
-      redirect_to conversation_path(conversation)
+
+      if params[:dock].present? && request.format.turbo_stream?
+        render turbo_stream: turbo_stream.append(
+          "chats_dock_windows",
+          partial: "chats/dock/window",
+          locals: { conversation: conversation, focus: true }
+        )
+      else
+        redirect_to conversation_path(conversation)
+      end
     rescue Chats::BlockedError
       # Fallback is the INBOX (engine root) — inside the engine, `root_path`
       # already resolves there, never to the host root.
@@ -152,47 +232,277 @@ module Chats
       @conversation = find_conversation
     end
 
-    def locate_signed!(sgid, purpose:)
-      GlobalID::Locator.locate_signed(sgid, for: purpose) || raise(ActiveRecord::RecordNotFound)
+    # The inbox's rows, for the inbox page and for the two-pane page.
+    def load_inbox
+      @inbox = Chats::Inbox.for(chats_current_messager, query: params[:q], with: inbox_filter)
+      @rows = @inbox.rows
+      @unread_counts = @inbox.unread_counts
+      # Back-compat for inboxes ejected under 0.1.x, which loop over
+      # @conversations: they keep rendering the flat list (no stacking, i.e.
+      # exactly what they rendered before). Re-eject or delete your copy to
+      # get the stacked rows.
+      @conversations = @inbox.conversations
     end
 
-    # Partial, case-insensitive matching across the inbox metadata users can
-    # actually see: participant names, conversation titles, subject labels,
-    # and message bodies. The inbox is capped at 200 rows, so metadata is
-    # filtered portably in Ruby from the already-preloaded objects while the
-    # potentially larger message-body set stays in SQL. No PostgreSQL-only
-    # full-text dependency is needed for this scale.
-    def apply_search(conversations)
-      return conversations unless Chats.config.search
-
-      query = params[:q].to_s.strip
-      return conversations if query.empty?
-
-      loaded = conversations.to_a
-      normalized_query = query.downcase
-      pattern = "%#{Chats::Conversation.sanitize_sql_like(query.downcase)}%"
-      message_match_ids =
-        if Chats.config.encrypt_messages
-          []
-        else
-          Chats::Message.where(conversation_id: loaded.map(&:id), deleted_at: nil)
-                        .where("LOWER(chats_messages.body) LIKE ?", pattern)
-                        .distinct
-                        .pluck(:conversation_id)
-        end
+    # The open conversation on the two-pane page: the pane alone for the
+    # page's own conversation frame, else the whole page around it (any
+    # other frame of the page, the search's results among them, finds its
+    # own part in it).
+    #
+    # The pane alone comes in turbo-rails' minimal frame layout, always (even
+    # under a `config.layout`): nothing of the host's page is rendered for
+    # Turbo to throw away. Its title travels on the pane (`data-title`,
+    # chats_page_title), since Turbo leaves <head> alone on a frame visit.
+    def render_split_page
+      return render :pane, layout: "turbo_rails/frame" if pane_request?
+
+      load_inbox
+      render :index
+    end
+
+    def pane_request?
+      turbo_frame_request_id == PANE_FRAME
+    end
+
+    # Whether the messaging page is two panes: `config.inbox_layout = :split`
+    # (the default), unless this app ejected its views before there were
+    # two panes. `rails g chats:views` under 0.5 copied an inbox and a
+    # thread page and no conversation pane: that app keeps its own separate
+    # pages, rendered and read exactly as before, until it ejects again (or
+    # deletes its copies). Views ejected since 0.6 carry the pane, and are
+    # two panes like the gem's own.
+    def chats_two_panes?
+      return @chats_two_panes if defined?(@chats_two_panes)
+
+      @chats_two_panes = Chats.config.split_inbox? && !views_ejected_before_two_panes?
+    end
+
+    # The list's filter on the two-pane page: its search (`q`) or the stack
+    # it shows (`with`). A row opened in the pane carries it into its URL,
+    # /messages/:id?with=…, because that URL is what the list's live
+    # refreshes re-request: without it, the next refresh would bring back
+    # the whole inbox under a list that was filtered. The back link to the
+    # list keeps it too.
+    def chats_inbox_filter
+      { q: params[:q], with: params[:with] }.select { |_, value| value.is_a?(String) && value.present? }
+    end
+
+    def views_ejected_before_two_panes?
+      (own_view?("index") || own_view?("show")) && !own_view?("conversation_pane", partial: true)
+    end
+
+    # Whether the app renders its own copy of one of these views, not the gem's.
+    def own_view?(name, partial: false)
+      template = lookup_context.find_all(name, ["chats/conversations"], partial).first
+      template.present? && !template.identifier.to_s.start_with?(Chats::Engine.root.join("app/views").to_s)
+    end
+
+    # Whether showing the conversation reads it, there and then.
+    #
+    # Never a prefetch (Turbo 8 fetches a link the pointer rests on, which
+    # is nobody reading). On the thread page, everything else: opening it
+    # reads it.
+    #
+    # On the two-pane page, the viewer opening it: a row clicked (the
+    # pane's frame) or the page loaded by the browser itself (a link from
+    # elsewhere, a reload, no JavaScript). NOT a Turbo visit of the page,
+    # because one of those is the inbox's own refresh: every live update of
+    # the list re-requests this page, maybe in a hidden tab, and a read
+    # there would say "Seen" to the sender while nobody looks — and, since
+    # a read refreshes the reader's inbox, refresh the page again, forever.
+    # Turbo marks each of its requests (X-Turbo-Request-Id) and a refresh
+    # looks like any other visit, so a Turbo visit renders the pane unread
+    # and its thread reads it once it's on screen. A refresh's pane never
+    # gets that far: the page keeps its permanent one, and drops the new.
+    def reads_on_render?
+      return false if prefetch?
+      return true unless chats_two_panes?
+
+      pane_request? || request.headers["X-Turbo-Request-Id"].blank?
+    end
 
-      loaded.select do |conversation|
-        message_match_ids.include?(conversation.id) ||
-          searchable_metadata(conversation).downcase.include?(normalized_query)
+    def time_from_ms(value)
+      Time.zone.at(0, value.to_i, :millisecond)
+    end
+
+    def time_from_us(value)
+      Time.zone.at(0, value.to_i, :microsecond)
+    end
+
+    # What to append and what to replace: on the two microsecond cursors,
+    # or on the one millisecond cursor of bubbles ejected before them.
+    def catch_up_on(scope)
+      if params[:changed].present?
+        created_at, created_seen = cursor(:after)
+        updated_at, updated_seen = cursor(:changed)
+        [scope.created_after(created_at, seen: created_seen),
+         scope.created_through(created_at, seen: created_seen).updated_after(updated_at, seen: updated_seen)]
+      else
+        since = time_from_ms(params[:since])
+        [scope.created_since(since), scope.updated_since(since)]
       end
     end
 
-    def searchable_metadata(conversation)
-      participant_names = conversation.participants.filter_map do |participant|
-        Chats.display_name_for(participant.messager) if participant.active?
+    # The moment and the ids seen with it, from `<name>=µs` and `<name>_ids=1,2`.
+    def cursor(name)
+      [time_from_us(params[name]), params[:"#{name}_ids"].to_s.split(",")]
+    end
+
+    def cursors_over_limit?
+      return true if params[:full].present?
+
+      %i[after_ids changed_ids].any? do |name|
+        ids = params[name].to_s.split(",")
+        ids.size > CURSOR_IDS_LIMIT || ids.any? { |id| id.size > CURSOR_ID_LENGTH }
       end
+    end
+
+    # Where the client stands once it has rendered this answer: what it was
+    # sent is now known to be on screen, so the cursors move to it. Sent
+    # back with the answer (the chats_caught_up action), because only an
+    # answer that arrived may move them.
+    def caught_up_cursors
+      after = cursor(:after).first
+      changed_at, changed_seen = cursor(:changed)
+      sent = @new_messages + @updated_messages.to_a
+      after = [after, *@new_messages.map(&:created_at)].max
+
+      newest = sent.map(&:updated_at).max
+      changed_seen = [] if newest && newest > changed_at
+      changed_at = [changed_at, newest].compact.max
+      changed_seen |= sent.select { |message| message.updated_at == changed_at }.map { |message| message.id.to_s }
+
+      cursors_tag(after, changed_at, changed_seen)
+    end
+
+    def cursors_tag(after, changed_at, changed_seen)
+      helpers.turbo_stream_action_tag(
+        :chats_caught_up,
+        target: helpers.dom_id(@conversation, :messages),
+        "data-after": microseconds(after), "data-changed": microseconds(changed_at),
+        "data-changed-ids": changed_seen.join(","),
+        # Which render of the thread asked: an answer for an earlier one is
+        # ignored (see the thread controller's caughtUp).
+        "data-render": params[:render].to_s.first(CURSOR_ID_LENGTH).presence
+      )
+    end
+
+    def microseconds(time)
+      (time.to_i * 1_000_000) + time.usec
+    end
+
+    # The history at its latest page, or, for a thread view ejected before
+    # the history had its id (no `history=1`), the page refresh it always
+    # got. `request_id: nil`: Turbo skips a refresh tagged with a request of
+    # its own, and this one answers the client's own catch-up.
+    def render_from_scratch
+      return render_latest_history if params[:history].present?
+
+      render turbo_stream: turbo_stream.refresh(request_id: nil)
+    end
+
+    # The conversation's messages with everything a bubble renders.
+    def rendered_messages
+      scope = @conversation.messages.includes(:sender, :reactions)
+      scope.respond_to?(:with_attached_files) ? scope.with_attached_files : scope
+    end
+
+    # The newest page of +scope+, oldest first, and whether older pages
+    # exist. Fetched newest-first and reversed; one extra record peeks.
+    def latest_page_of(scope)
+      page = scope.recent_first.limit(Chats.config.messages_per_page + 1).to_a
+      [page.first(Chats.config.messages_per_page).reverse, page.size > Chats.config.messages_per_page]
+    end
+
+    # Where the «new messages» line goes: the oldest unread bubble on the
+    # page; when the backlog runs deeper than one page, the top of the page
+    # (the scroll-up frame chain holds the rest). Nil when nothing is unread.
+    def first_unread_id(participant, messages)
+      return unless participant&.unread?
+
+      participant.unread_messages.where(id: messages.map(&:id)).oldest_first.pick(:id) || messages.first&.id
+    end
+
+    # The thread's history at its latest page, for a catch-up more than a
+    # page behind: the same messages, frame chain and «new messages» line
+    # the thread opens with (chats/conversations/_history).
+    #
+    # A complete render, so it carries its own cursors: the newest creation
+    # and the newest change on the page.
+    def render_latest_history
+      messages, more = latest_page_of(rendered_messages)
+      participant = @conversation.participant_for(chats_current_messager)
+      newest_change = messages.map(&:updated_at).max || Time.zone.at(0)
+      history = turbo_stream.update(
+        helpers.dom_id(@conversation, :history),
+        partial: "chats/conversations/history",
+        locals: { conversation: @conversation, messages: messages, more: more,
+                  first_unread_id: first_unread_id(participant, messages),
+                  counterpart: chats_counterpart, window: false }
+      )
+      cursors = cursors_tag(messages.map(&:created_at).max || Time.zone.at(0), newest_change,
+                            messages.select { |message| message.updated_at == newest_change }.map { |m| m.id.to_s })
+
+      render turbo_stream: helpers.safe_join([history, cursors])
+    end
+
+    # Under `deletion: :hard` a deleted message leaves nothing to replace:
+    # the catch-up names every message from the client's oldest bubble on
+    # that still exists, and the client removes the bubbles not named.
+    # `until` sits PRESENT_MARGIN before the list is read: a message whose
+    # insert had not committed yet is missing from the list but may already
+    # have reached the client live — it must not be taken for a deleted one.
+    def present_messages
+      margin = Time.current - PRESENT_MARGIN
+      ids = @conversation.messages.where(created_at: time_from_us(params[:from])..).pluck(:id)
+
+      { ids: ids.map { |id| helpers.dom_id(Chats::Message.new(id: id)) },
+        until: (margin.to_i * 1_000_000) + margin.usec }
+    end
+
+    # A dock window asks for its thread from inside its own turbo frame. A
+    # plain visit to the same URL (no frame) still gets the page.
+    def dock_window?
+      params[:window].present? && turbo_frame_request?
+    end
+
+    # Turbo 8 prefetches a link when the pointer rests on it, and a pointer
+    # resting on an inbox row is not somebody reading the thread. The visit
+    # itself, if it happens, reads.
+    # https://turbo.hotwired.dev/handbook/drive#prefetching-links-on-hover
+    def prefetch?
+      request.headers["X-Sec-Purpose"] == "prefetch" || request.headers["Sec-Purpose"]&.include?("prefetch")
+    end
+
+    def dock_recent
+      Integer(params[:recent], exception: false)&.clamp(1, DOCK_RECENT_LIMIT) || 10
+    end
+
+    def locate_signed!(sgid, purpose:)
+      GlobalID::Locator.locate_signed(sgid, for: purpose) || raise(ActiveRecord::RecordNotFound)
+    end
+
+    # `?with=<signed gid>` — the inbox filtered to one counterpart (a stack's
+    # contents). Signed and purpose-scoped like every other polymorphic
+    # param the engine accepts; a tampered one is a plain 404.
+    def inbox_filter
+      return nil if params[:with].blank?
+
+      messager = locate_signed!(params[:with], purpose: :chats_inbox_with)
+      raise ActiveRecord::RecordNotFound unless Chats.messager_class?(messager.class)
+
+      messager
+    end
+
+    # The other party of a direct thread (nil for groups) — the thread header
+    # names them, links to their profile, and decides whether to offer the
+    # "see all" link back to their stack. LAZY and memoized: a group thread
+    # never pays for it, and a direct one pays once no matter how many of
+    # those three things the rendered view asks for.
+    def chats_counterpart
+      return @chats_counterpart if defined?(@chats_counterpart)
 
-      [conversation.title, conversation.subject_label, *participant_names].compact.join(" ")
+      @chats_counterpart = @conversation&.counterpart_for(chats_current_messager)
     end
   end
 end