chats 0.5.0 → 0.6.0

data/app/assets/stylesheets/chats.css

@@ -32,6 +32,13 @@
   --chats-bubble-text: #111827;
   --chats-radius: 1.1rem;
   --chats-max-width: 42rem;
+  /* The conversation list beside an open conversation (two panes). */
+  --chats-list-width: 320px;
+  /* --chats-split-height, how tall the two-pane page is, is NOT declared
+     here: the rules read it with the whole screen (100dvh) as the fallback,
+     so a host's own declaration wins wherever it is, even on a :root rule
+     loaded before this file (the bundled views link it in the body).
+     Under a host header: calc(100dvh - <the header's height>). */
 
   /* Safe areas, re-pointable by a host with its own source of truth. */
   --chats-safe-top: env(safe-area-inset-top, 0px);
@@ -133,6 +140,9 @@
   flex-shrink: 0;
 }
 .chats-badge--floating[hidden] { display: none; }
+/* chats_unread_badge's wrapper (its catch-up controller): no box of its own,
+   so the badge sits in the host's layout exactly as if it weren't there. */
+.chats-unread-badge-live { display: contents; }
 
 /* --- Empty states ------------------------------------------------------------ */
 
@@ -1004,6 +1014,110 @@ turbo-frame[id^="chats_page_"] {
 }
 
 
+/* ---------------------------------------------------------------------------
+   0.6.0 — two panes (config.inbox_layout = :split)
+   ---------------------------------------------------------------------------
+
+   The messaging page as LinkedIn has it: from 700px wide (the dock's phone
+   rule, and chats--split's), the list on the left and the open conversation
+   on the right, both as tall as the screen, each scrolling on its own. Below
+   that, one column, exactly as the separate pages: /messages is the list,
+   /messages/:id the thread. Every request renders both panes; this media
+   query alone picks, so it holds before JavaScript runs and without it.
+
+     .chats-split                 the page (.chats.chats-inbox too)
+     .chats-split__list           the list's <nav>
+     .chats-split__conversation   the `chats_conversation` frame
+     .chats-split__pane           a conversation in it (section)
+     .chats-split__thread         its permanent wrapper, around .chats-thread--pane
+     .chats-split__empty          no conversation open (--inbox: no conversations at all)
+
+   The page is as wide as the list plus a thread page (--chats-max-width),
+   so the conversation reads at the width it always had, and as tall as
+   --chats-split-height (the screen; a host with its own header above the
+   page sets what is left: calc(100dvh - 4rem)). */
+.chats-split {
+  max-width: calc(var(--chats-list-width) + var(--chats-max-width));
+  /* The list alone (a phone): at least what is left of the screen, never
+     the shell's whole 100dvh, which would run past it under a host header. */
+  min-height: var(--chats-split-height, 100dvh);
+}
+.chats-split__list { display: flex; flex-direction: column; min-width: 0; }
+.chats-split__conversation {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+.chats-split__pane,
+.chats-split__thread {
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+/* The thread page's body, inside the pane: no shell of its own (the page is
+   the .chats shell), and the pane's height, not the screen's. */
+.chats-thread--pane {
+  flex: 1;
+  min-height: 0;
+  height: auto;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.chats-split__empty { margin: auto; }
+.chats-row--current .chats-row__link {
+  background: var(--chats-surface);
+  box-shadow: inset 3px 0 0 var(--chats-accent);
+}
+
+@media (min-width: 700px) {
+  .chats-split {
+    box-sizing: border-box;
+    flex-direction: row;
+    height: var(--chats-split-height, 100dvh);
+    min-height: 0;
+    overflow: hidden;
+    /* Its edges, where a page wider than it shows the host's background. */
+    border-inline: 1px solid var(--chats-border);
+  }
+  .chats-split__list {
+    box-sizing: border-box;
+    flex: 0 0 var(--chats-list-width);
+    width: var(--chats-list-width);
+    border-right: 1px solid var(--chats-border);
+  }
+  /* The rows scroll; the title and the search stay. */
+  .chats-split__list > turbo-frame {
+    display: block;
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    overscroll-behavior-y: contain;
+  }
+  .chats-split__conversation { flex: 1 1 0; }
+  /* The list is right there: no way back to it. */
+  .chats-split .chats-thread__back { display: none; }
+}
+
+@media (max-width: 699.98px) {
+  /* A conversation open: the page is the thread, as tall as the screen. */
+  .chats-split:has(.chats-split__pane) {
+    height: var(--chats-split-height, 100dvh);
+    min-height: 0;
+    overflow: hidden;
+  }
+  .chats-split:has(.chats-split__pane) > .chats-split__list { display: none; }
+  .chats-split:has(.chats-split__pane) > .chats-split__conversation { flex: 1; }
+  /* None: the page is the list. The empty pane shows under it only to say
+     there are no conversations at all (the inbox's empty state lives there). */
+  .chats-split:not(:has(.chats-split__pane, .chats-split__empty--inbox)) > .chats-split__conversation {
+    display: none;
+  }
+}
+
 /* ---------------------------------------------------------------------------
    0.5.0 — the messaging dock (chats_dock)
    ---------------------------------------------------------------------------

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

@@ -7,9 +7,19 @@ module Chats
   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
+    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
@@ -22,14 +32,7 @@ module Chats
       # is the dock's own list.
       return dock if turbo_frame_request_id == "chats_dock_list"
 
-      @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
+      load_inbox
     end
 
     # The messaging dock's recent list (`chats_dock`): the first rows of the
@@ -44,6 +47,15 @@ module Chats
       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).
@@ -51,19 +63,19 @@ module Chats
     # `?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.
@@ -71,14 +83,8 @@ 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)
 
         if dock_window?
           # A window does NOT read on render: it may be restored minimized
@@ -86,51 +92,64 @@ module Chats
           # swallow the unread badge. The thread controller posts #read once
           # the window is actually on screen (`read-pending`).
           render :window, layout: false
-        elsif !prefetch?
+        else
           # Opening the thread reads it. (Live appends while the thread
           # stays open are read via the thread controller's POST to #read.)
-          @participant&.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?
-
-      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.
-      #
-      # `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.
-      #
-      # `request_id: nil` on purpose: Turbo skips a refresh tagged with a
-      # request id it recognizes as its own, and this response is the answer
-      # to the client's OWN catch-up fetch — the one client that must not
-      # skip it.
-      if @new_messages.size > Chats.config.messages_per_page
-        render turbo_stream: turbo_stream.refresh(request_id: nil)
-        return
-      end
-
-      @updated_messages = scope.updated_since(since)
+      head :no_content and return if params[:changed].blank? && params[:since].blank?
+
+      # 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?
+
+      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
 
@@ -213,6 +232,229 @@ module Chats
       @conversation = find_conversation
     end
 
+    # 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
+
+    # 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).
+    def render_split_page
+      return render :pane, layout: false 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
+
+    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
+
+    # 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?

data/app/helpers/chats/engine_helper.rb

@@ -57,13 +57,23 @@ module Chats
     # tab docks). Subscribes to the messager's badge stream so it updates in
     # real time without refreshing the page it sits on (see
     # Chats::Broadcasts for why badges get their own stream).
+    #
+    # The viewer's own badge also catches up on updates its stream missed
+    # (the chats--unread-badge controller asks GET /badge on a reconnect, on
+    # a return to a hidden page, on a restored page). Its wrapper is
+    # `display: contents` in chats.css, so it changes no layout.
     def chats_unread_badge(messager = chats_viewer)
       return if messager.nil?
 
-      safe_join([
-                  turbo_stream_from(messager, :chats_badge),
-                  render(partial: "chats/shared/unread_badge", locals: { count: messager.unread_chats_count })
-                ])
+      badge = safe_join([
+                          turbo_stream_from(messager, :chats_badge),
+                          render(partial: "chats/shared/unread_badge", locals: { count: messager.unread_chats_count })
+                        ])
+      return badge unless messager == chats_viewer
+
+      tag.span(badge, class: "chats-unread-badge-live",
+                      data: { controller: "chats--unread-badge",
+                              "chats--unread-badge-url-value": chats_routes.badge_conversations_path })
     end
 
     # The messaging dock, LinkedIn / Steam style: a bar in the bottom-right
@@ -117,6 +127,19 @@ module Chats
       { chats_dock_toggle: true }
     end
 
+    # The CLDR plural categories JavaScript's Intl.PluralRules answers with.
+    PLURAL_CATEGORIES = %i[zero one two few many other].freeze
+
+    # Every plural form of +key+ the current locale provides, for client-side
+    # pluralization ({ one: "…", few: "…", other: "…" }). The gem ships
+    # one/other; a host adds the forms its languages need (Polish few/many,
+    # Arabic zero/two…) in its own locale files. Empty when the key is
+    # missing, never a "translation missing" string.
+    def chats_plural_forms(key)
+      forms = I18n.t(key, default: {})
+      forms.is_a?(Hash) ? forms.slice(*PLURAL_CATEGORIES) : {}
+    end
+
     # Whether +viewer+ muted +conversation+, read from the preloaded seats
     # (the inbox loads them), so a row costs no query for it.
     def chats_muted?(conversation, viewer)