chats 0.1.1 → 0.2.0

data/config/locales/es.yml

@@ -8,6 +8,11 @@ es:
       no_results_title: "Sin resultados"
       no_results_hint: "No hay nada que coincida con «%{query}»."
       no_messages: "Sin mensajes todavía"
+      filtered_by: "Conversaciones con %{name}"
+      clear_filter: "Ver todas las conversaciones"
+      group_count:
+        one: "1 conversación"
+        other: "%{count} conversaciones"
       you_prefix: "Tú:"
     thread:
       back: "Atrás"
@@ -22,6 +27,7 @@ es:
       yesterday: "Ayer"
       typing_suffix: "está escribiendo…"
       new_messages: "Mensajes nuevos"
+      see_all: "Ver todas"
     conversation:
       empty_title: "Conversación"
     message:
@@ -30,6 +36,7 @@ es:
       copy: "Copiar"
       copied: "¡Copiado!"
       attachment: "Foto"
+      signature: "— %{name}"
       close_attachment: "Cerrar foto"
       edit: "Editar"
       delete: "Eliminar"
@@ -44,6 +51,7 @@ es:
       placeholder: "Escribe un mensaje…"
       send: "Enviar"
       attach: "Adjuntar imágenes"
+      locked: "Esta conversación está cerrada."
     buttons:
       chat: "Mensaje"
     flashes:
@@ -67,7 +75,10 @@ es:
         chats/message:
           attributes:
             base:
+              locked: "Esta conversación está cerrada."
               blocked: "No puedes enviar mensajes a esta persona."
+            author:
+              not_a_messager: "debe ser un mensajero (acts_as_messager)"
             sender:
               blank: "es obligatorio"
               not_a_participant: "no participa en esta conversación"

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/chats",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

data/docs/PRD.md

@@ -18,7 +18,7 @@ Direct messages, group chats, reactions, attachments, read receipts — Hotwire-
 
 A gem you add to a Rails app to get **Instagram/X-DM-class** user-to-user messaging without building it again. The happy path is one generator + one `acts_as_messager` line + a mounted engine; the result is a working, real-time, polished inbox. Power users override views, policies, and adapters.
 
-It is **not** a chatbot/LLM framework, not a Slack-clone with workspaces, and not a support-ticketing tool. It is peer-to-peer (and group) human messaging.
+It is **not** a chatbot/LLM framework, not a Slack-clone with workspaces, and not a support-ticketing tool (that is `support_desk`, a separate product gem built on this one — see README). It is peer-to-peer (and group) human messaging.
 
 **Why it exists:** every consumer app eventually needs DMs, and everyone rebuilds the same Conversation/Message/Participant/Receipt model, the same Action Cable + Turbo plumbing, and the same "report this message / block this user / filter this text" surface. We already built the moderation half for CarHey; `chats` is the messaging half, and the two snap together.
 

data/docs/campfire_review.md

@@ -11,7 +11,7 @@ with the same facts.
 
 | Campfire pattern | Where it landed here | Notes |
 | --- | --- | --- |
-| **Stale-room refresh** (`Rooms::RefreshesController` + `refresh_room_controller.js`): on tab-visible-after-sleep or cable reconnect, fetch `?since=` and append new / replace updated | `ConversationsController#refresh`, `Message.created_since/.updated_since`, thread controller `refreshThread()` | The single biggest reliability pattern in their codebase — mobile WebViews reap WebSockets constantly. We improved the trigger: instead of their dedicated `HeartbeatChannel`, we observe the `connected` attribute turbo-rails already toggles on `<turbo-cable-stream-source>`. Zero new channels. We also added a deep-backlog escape hatch: > 1 page missed answers with a Turbo 8 `refresh` stream action (full morph) instead of splicing arbitrary history. |
+| **Stale-room refresh** (`Rooms::RefreshesController` + `refresh_room_controller.js`): on tab-visible-after-sleep or cable reconnect, fetch `?since=` and append new / replace updated | `ConversationsController#refresh`, `Message.created_since/.updated_since`, thread controller `refreshThread()`; **and the inbox** via `refresh_inbox_controller.js` (same reconnect/visibility triggers, but the recovery action is a Turbo 8 page `refresh` since inbox broadcasts already are page refreshes) | The single biggest reliability pattern in their codebase — mobile WebViews reap WebSockets constantly. We improved the trigger: instead of their dedicated `HeartbeatChannel`, we observe the `connected` attribute turbo-rails already toggles on `<turbo-cable-stream-source>`. Zero new channels. We also added a deep-backlog escape hatch: > 1 page missed answers with a Turbo 8 `refresh` stream action (full morph) instead of splicing arbitrary history. The inbox got the same doctrine (missed inbox refreshes had no recovery before). |
 | **DOM cap** (`message_paginator.js` `maxMessages: 300`) | Thread controller `trimExcessMessages()` (300 + 20 leeway) | Only trims while the viewer is parked at the bottom. Our pagination is a server-rendered lazy-frame chain (theirs is JS-driven), so trimming also re-plants the keyset anchor frame (`rebuildPaginationAnchor()`) — trimmed history stays reachable on scroll-up with no gaps. |
 | **Out-of-order arrival handling** (their `messages_controller.js` re-sorts on insert) | Thread controller `ensureChronological()` | Broadcast appends from concurrent host job workers can land out of order. ISO8601 lexicographic compare; equal timestamps keep arrival order. |
 | **First-unread anchoring** (they page around the first unread; membership unread marker) | The «new messages» divider: `@first_unread_id` computed in `#show` *before* `read!` advances the horizon | We render a divider rather than re-anchoring the page — the thread still opens at the bottom (coordination chats are short; jumping deep into history on open would feel broken at our scale). Backlogs deeper than a page pin the divider to the top of the page. |

data/gemfiles/rails_7.1.gemfile

@@ -14,6 +14,7 @@ group :development do
 end
 
 group :test do
+  gem "json", "~> 2.7"
   gem "minitest", "~> 6.0"
   gem "minitest-mock"
   gem "mocha", "~> 2.0"

data/gemfiles/rails_7.2.gemfile

@@ -14,6 +14,7 @@ group :development do
 end
 
 group :test do
+  gem "json", "~> 2.7"
   gem "minitest", "~> 6.0"
   gem "minitest-mock"
   gem "mocha", "~> 2.0"

data/gemfiles/rails_8.1.gemfile

@@ -14,6 +14,7 @@ group :development do
 end
 
 group :test do
+  gem "json", "~> 2.7"
   gem "minitest", "~> 6.0"
   gem "minitest-mock"
   gem "mocha", "~> 2.0"

data/lib/chats/configuration.rb

@@ -86,6 +86,12 @@ module Chats
     attr_accessor :messages_per_page, :max_message_length, :max_group_size, :max_attachment_size,
                   :max_attachments_per_message
 
+    # How many conversations the inbox loads (and therefore how deep search
+    # and grouping see). The inbox is a "recent activity" surface, not an
+    # archive — raise it only if your users really keep hundreds of live
+    # threads.
+    attr_accessor :inbox_limit
+
     # Per-sender send throttle, enforced with Rails 8's built-in controller
     # `rate_limit` when available (feature-detected; on Rails 7.1 it's a
     # no-op). Shape: `{ to: Integer, within: ActiveSupport::Duration }`.
@@ -109,6 +115,12 @@ module Chats
     # May +creator+ create a group conversation?
     attr_reader :can_create_group
 
+    # ->(relation, viewer) { relation } — composed into the inbox query
+    # before the limit, so a host can hide or re-scope rows without
+    # overriding the controller:
+    #   config.inbox_scope = ->(relation, viewer) { relation.where.not(kind: "group") }
+    attr_reader :inbox_scope
+
     # --- Ecosystem seams (procs, no-op defaults) ------------------------------
 
     # ->(messager) { ids } — every messager id that can't talk with the given
@@ -130,6 +142,17 @@ module Chats
     # or variant), or nil to render an initials placeholder.
     attr_reader :messager_avatar
 
+    # ->(messager) { path_or_url_or_nil } — where a messager's profile lives.
+    # The bundled views link names and avatars to it; nil (the default) means
+    # no anchor at all, so the gem never assumes a `user_path` exists.
+    attr_reader :messager_url
+
+    # ->(message) { String } — the signature line under a SIGNED message
+    # (one written by an author on the sender's behalf — see
+    # Chats::Message#signed?). nil (the default) renders the localized
+    # "— Author Name".
+    attr_reader :message_signature
+
     def initialize
       @messager_class = "User"
       @parent_controller = "::ApplicationController"
@@ -152,14 +175,18 @@ module Chats
       @max_attachment_size = 10 * 1024 * 1024 # 10 MB
       @max_attachments_per_message = 4
       @send_rate_limit = { to: 60, within: 60 } # 60 messages per minute per sender
+      @inbox_limit = 200
 
       @encrypt_messages = false
 
       @can_message = ->(_sender, _recipient) { true }
       @can_create_group = ->(_creator) { true }
+      @inbox_scope = ->(relation, _viewer) { relation }
 
       @blocked_messager_ids = ->(_messager) { [] }
       @notifier = ->(_event, **_payload) {}
+      @messager_url = ->(_messager) { nil }
+      @message_signature = nil
 
       @messager_display_name = lambda do |messager|
         messager.try(:display_name) || messager.try(:name) ||
@@ -232,8 +259,41 @@ module Chats
       @blocked_messager_ids = ensure_callable(value, "blocked_messager_ids")
     end
 
+    # DEPRECATED (removed in 1.0): sugar that subscribes one `(event,
+    # **payload)` proc to the two events that existed in 0.1.1
+    # (:message_created, :conversation_read) — and ONLY those, so an old
+    # keyword-specific hook can't start raising on events it was never
+    # written for. `Chats.on` supersedes it: many subscribers, per-event
+    # payloads, reload-safe keys, and every event.
     def notifier=(value)
-      @notifier = ensure_callable(value, "notifier")
+      hook = ensure_callable(value, "notifier")
+      Chats.deprecator.warn(
+        "config.notifier is deprecated and will be removed in chats 1.0. " \
+        "It receives #{Chats::Subscribers::LEGACY_NOTIFIER_EVENTS.map(&:inspect).join(" and ")} only; " \
+        "the events added in 0.2.0 are Chats.on-only. " \
+        "Subscribe with Chats.on(:message_created) { |message| … } instead " \
+        "(see the README's \"Events\" section)."
+      )
+
+      Chats::Subscribers::LEGACY_NOTIFIER_EVENTS.each do |event|
+        Chats::Subscribers.on(event, key: Chats::Subscribers::NOTIFIER_KEY, style: :event) do |fired, **payload|
+          hook.call(fired, **payload)
+        end
+      end
+
+      @notifier = hook
+    end
+
+    def inbox_scope=(value)
+      @inbox_scope = ensure_callable(value, "inbox_scope")
+    end
+
+    def messager_url=(value)
+      @messager_url = ensure_callable(value, "messager_url")
+    end
+
+    def message_signature=(value)
+      @message_signature = value.nil? ? nil : ensure_callable(value, "message_signature")
     end
 
     def messager_display_name=(value)
@@ -259,6 +319,8 @@ module Chats
         raise ConfigurationError, "messages_per_page must be positive (got #{messages_per_page.inspect})"
       end
 
+      raise ConfigurationError, "inbox_limit must be positive (got #{inbox_limit.inspect})" if inbox_limit.to_i < 1
+
       true
     end
 

data/lib/chats/engine.rb

@@ -30,7 +30,7 @@ module Chats
     CHATS_LIB = File.expand_path("chats", LIB_ROOT)
 
     ZEITWERK_IGNORED = %w[
-      version.rb errors.rb configuration.rb engine.rb macros.rb
+      version.rb errors.rb configuration.rb engine.rb macros.rb subscribers.rb
     ].freeze
 
     initializer "chats.autoload", before: :set_autoload_paths do
@@ -64,6 +64,13 @@ module Chats
       end
     end
 
+    # Hand the gem's deprecator to the app, so `config.active_support.
+    # deprecation` (and `deprecators.silence`) govern chats' own deprecation
+    # warnings like any other framework's.
+    initializer "chats.deprecator" do |app|
+      app.deprecators[:chats] = Chats.deprecator if app.respond_to?(:deprecators)
+    end
+
     # Expose `acts_as_messager` / `acts_as_chat_subject` on every AR model.
     initializer "chats.active_record" do
       ActiveSupport.on_load(:active_record) do
@@ -71,11 +78,20 @@ module Chats
       end
     end
 
-    # Ship the gem's locale files (en, es). Host locale files with the same
-    # keys override these automatically (I18n's load order puts the app last).
-    initializer "chats.locales" do |app|
-      app.config.i18n.load_path += Dir[root.join("config", "locales", "**", "*.{rb,yml}").to_s]
-    end
+    # The gem's locale files (en, es) ship through Rails::Engine's own
+    # :add_locales initializer, which picks up every engine's config/locales
+    # automatically — and deliberately NOT through a manual
+    # `app.config.i18n.load_path +=` on top of it.
+    #
+    # That append is not merely redundant, it inverts the contract: railtie
+    # paths are unshifted ahead of everything in load_path, so an appended
+    # copy lands AFTER the host's own locales and silently overrides them. A
+    # host rewording `chats.flashes.blocked` in its own es.yml would keep
+    # reading ours, with no error and nothing to see.
+    #
+    # Gem first, host last. `clickwrap` carries the same note; `support_desk`
+    # shipped the bug and measured it (its file sat in load_path 14 times and
+    # the host's override lost).
 
     # NOTE: the host-facing helpers (`chat_button_to`, `chats_unread_badge`, …)
     # are exposed to ActionView from the BOTTOM of engine_helper.rb itself
@@ -90,7 +106,8 @@ module Chats
 
     # -------------------------------------------------------------------------
     # JavaScript: the engine ships tiny Stimulus controllers (thread, composer,
-    # debounced-submit) with NO build step, pinned for importmap-rails hosts.
+    # debounced-submit, refresh-inbox) with NO build step, pinned for
+    # importmap-rails hosts.
     #
     # The pin keys live under "controllers/chats/..." ON PURPOSE: the stock
     # Rails `app/javascript/controllers/index.js` calls
@@ -125,6 +142,11 @@ module Chats
       if app.config.respond_to?(:assets)
         app.config.assets.paths << root.join("app/javascript")
         app.config.assets.paths << root.join("app/assets/stylesheets")
+
+        # Propshaft serves anything on the load path; Sprockets serves only
+        # what is on the precompile list, so a Sprockets host 404s the
+        # stylesheet without this line.
+        app.config.assets.precompile << "chats.css" if app.config.assets.respond_to?(:precompile)
       end
     end
 

data/lib/chats/errors.rb

@@ -17,4 +17,20 @@ module Chats
   # Raised when the host `can_message` policy (or a feature flag like
   # `config.groups = false`) forbids the attempted action.
   class NotAllowedError < Error; end
+
+  # Raised when a conversation's SUBJECT has locked it (see
+  # Chats::ChatSubject#chat_locked?) and something tries to write to it
+  # anyway — send, edit, delete, react. A subclass of NotAllowedError on
+  # purpose: a host that already rescues NotAllowedError keeps working, and
+  # one that wants to show the lock notice specifically can rescue this.
+  # System messages are never refused: the app must always be able to say
+  # "this was closed" in the thread it just closed.
+  class LockedError < NotAllowedError
+    attr_reader :conversation
+
+    def initialize(message = nil, conversation: nil)
+      @conversation = conversation
+      super(message || conversation&.locked_notice || "this conversation is closed")
+    end
+  end
 end

data/lib/chats/inbox.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Chats
+  # THE inbox query, in one object: load a viewer's recent conversations,
+  # optionally filter them, and fold the ones that belong to a stacked
+  # counterpart into Chats::InboxGroup rows.
+  #
+  #   Chats::Inbox.for(alice)                       # rows, newest activity first
+  #   Chats::Inbox.for(alice, query: "madrid")      # the search box
+  #   Chats::Inbox.for(alice, with: support_desk)   # one stack's contents
+  #
+  # Rows are `Chats::Conversation | Chats::InboxGroup`, sorted by last
+  # activity descending. Grouping happens HERE and nowhere else.
+  #
+  # == Why `inbox_limit` bounds ROWS, not conversations
+  #
+  # A stacked counterpart can hold hundreds of threads. Limiting the raw
+  # conversation query first would let a busy support desk EVICT everything
+  # else from the inbox — 200 desk threads and not one message from a friend.
+  # So the two populations are queried separately: ordinary conversations get
+  # the limit, stacked ones get their own bounded window, and the limit is
+  # applied again to the ROWS that come out. A stack's numbers
+  # (`open_count`, `unread_count`) are then GLOBAL, read with two indexed
+  # aggregates per stack — never per conversation, and never by loading the
+  # stack to count it.
+  class Inbox
+    include Enumerable
+
+    attr_reader :viewer, :query, :with
+
+    class << self
+      # The inbox for +viewer+. Returns a Chats::Inbox, which enumerates its
+      # rows (`to_a` for a plain Array).
+      def for(viewer, query: nil, with: nil)
+        new(viewer, query: query, with: with)
+      end
+    end
+
+    def initialize(viewer, query: nil, with: nil)
+      @viewer = viewer
+      @query = query.to_s.strip.presence
+      @with = with
+    end
+
+    # Conversation | InboxGroup rows, newest activity first, at most
+    # `config.inbox_limit` of them.
+    def rows
+      @rows ||= build_rows
+    end
+
+    # Yield each row (Enumerable gives `map`, `select`, `find`, … from here).
+    def each(&)
+      rows.each(&)
+    end
+
+    # The rows as a plain Array.
+    def to_a
+      rows
+    end
+
+    # How many rows the inbox has.
+    def size
+      rows.size
+    end
+
+    # Whether the inbox has any rows at all.
+    def any?
+      rows.any?
+    end
+
+    # Whether the inbox has no rows.
+    def empty?
+      rows.empty?
+    end
+
+    # The conversations behind the rows, stacked threads included. Stays an
+    # ActiveRecord::Relation (already loaded) in the simple case — no search,
+    # nothing stacked — so an inbox ejected under 0.1.x can still chain
+    # `.where` or hand it to a paginator. Becomes an Array once rows had to
+    # be assembled in Ruby.
+    def conversations
+      rows
+      @flat
+    end
+
+    # { conversation_id => unread message count } — one grouped query for
+    # every loaded conversation, which is what the row badges read.
+    def unread_counts
+      @unread_counts ||= Chats::Conversation.unread_counts_for(viewer, conversations)
+    end
+
+    # Unread messages in one conversation, from the grouped query above.
+    def unread_count_for(conversation)
+      unread_counts.fetch(conversation.id, 0)
+    end
+
+    # The stack-aware badge number: how many inbox ROWS carry unread content
+    # (a stack of five unread threads is still one thing to deal with).
+    # `Messager#unread_chats_count` is the unstacked count and is unchanged.
+    def unread_count
+      rows.count do |row|
+        row.is_a?(Chats::InboxGroup) ? row.unread? : unread_count_for(row).positive?
+      end
+    end
+
+    # True when scoped to one counterpart (`?with=`): a stack's contents,
+    # which are listed individually rather than re-stacked.
+    def filtered?
+      with.present?
+    end
+
+    private
+
+    def limit
+      Chats.config.inbox_limit
+    end
+
+    # Memoized so `config.inbox_scope` is consulted ONCE per inbox for the
+    # row query, however many legs it is split into (the stack aggregates
+    # apply it separately, to their own relation).
+    def base_relation
+      @base_relation ||= begin
+        relation = Chats::Conversation.inbox_for(viewer)
+                                      .includes(:last_message, :subject, participants: :messager)
+        Chats.config.inbox_scope.call(relation, viewer) || relation
+      end
+    end
+
+    # The polymorphic types worth splitting out. Empty when nothing stacks
+    # (an ordinary app pays nothing) and when the inbox is already filtered
+    # to one counterpart.
+    def grouped_types
+      @grouped_types ||= filtered? ? [] : Chats.grouped_messager_types
+    end
+
+    # Seats held by a stacked messager — never the viewer's own seat, so a
+    # stacked messager's OWN inbox stays flat.
+    def stacked_seats
+      Chats::Participant.select(:conversation_id)
+                        .where(messager_type: grouped_types)
+                        .where.not(messager_type: viewer.class.polymorphic_name, messager_id: viewer.id)
+    end
+
+    def load_conversations
+      if filtered?
+        @ungrouped_relation = filter_to_counterpart(base_relation).limit(limit)
+        @stacked = []
+      elsif grouped_types.empty?
+        @ungrouped_relation = base_relation.limit(limit)
+        @stacked = []
+      else
+        stacked = Chats::Conversation.direct.where(id: stacked_seats)
+        @ungrouped_relation = base_relation.where.not(id: stacked).limit(limit)
+        # Ordered by recency and limited like the other leg, which also makes
+        # the FIRST conversation of each counterpart that counterpart's
+        # freshest — that's the one the stacked row previews.
+        @stacked = apply_search(base_relation.direct.where(id: stacked_seats).limit(limit))
+      end
+
+      @ungrouped = apply_search(@ungrouped_relation)
+      # The relation itself when nothing had to be assembled in Ruby (it is
+      # loaded, so iterating it costs nothing extra); the flat Array otherwise.
+      @flat = @stacked.empty? && query.nil? ? @ungrouped_relation : @ungrouped + @stacked
+    end
+
+    # Only the direct threads shared with one counterpart. Direct only, by
+    # design: a group that happens to include the desk is not part of the
+    # desk's stack.
+    def filter_to_counterpart(relation)
+      seats = Chats::Participant.select(:conversation_id).where(
+        messager_type: with.class.polymorphic_name, messager_id: with.id
+      )
+      relation.direct.where(id: seats)
+    end
+
+    def build_rows
+      load_conversations
+      rows = @ungrouped.dup
+      stacks = {}
+
+      @stacked.each do |conversation|
+        counterpart = stacked_counterpart(conversation)
+        # The SQL prefilter matches by polymorphic type; an STI sibling that
+        # isn't actually grouped lands here and goes back to being a row.
+        next rows << conversation if counterpart.nil?
+
+        (stacks[Chats.messager_key(counterpart)] ||= [counterpart, []]).last << conversation
+      end
+
+      rows.concat(stacks.each_value.map { |messager, members| build_group(messager, members) })
+      sort_rows(rows).first(limit)
+    end
+
+    # Newest activity first, exactly like the SQL the relation would have
+    # used (COALESCE(last_message_at, created_at) DESC), at full timestamp
+    # precision — `to_r`, not `to_f`, because two messages a microsecond
+    # apart must not collapse into a tie. Ties break on id, so the order is
+    # total and a row never shuffles between renders.
+    def sort_rows(rows)
+      rows.sort do |a, b|
+        by_activity = sort_key(b).to_r <=> sort_key(a).to_r
+        by_activity.zero? ? compare_ids(b, a) : by_activity
+      end
+    end
+
+    def build_group(messager, members)
+      totals = stack_totals(messager)
+
+      Chats::InboxGroup.new(
+        messager: messager,
+        conversations: sort_rows(members),
+        unread_count: totals[:unread],
+        open_count: totals[:open]
+      )
+    end
+
+    # What a stacked row says about the WHOLE stack, in two indexed
+    # aggregates — independent of how deep the stack is, and of how much of
+    # it we loaded.
+    def stack_totals(messager)
+      scope = Chats::Conversation.inbox_for(viewer).reorder(nil).direct.where(
+        id: Chats::Participant.select(:conversation_id).where(
+          messager_type: messager.class.polymorphic_name, messager_id: messager.id
+        )
+      )
+      scope = Chats.config.inbox_scope.call(scope, viewer) || scope
+
+      {
+        open: scope.distinct.count,
+        unread: scope.unread_by(viewer).reorder(nil).count("chats_messages.id")
+      }
+    end
+
+    # The other party of a DIRECT conversation, when their class asked to be
+    # stacked (`acts_as_messager inbox: :grouped`). Read from the preloaded
+    # participants — no extra query per row.
+    def stacked_counterpart(conversation)
+      return nil unless conversation.direct?
+
+      other = conversation.participants.find do |participant|
+        participant.messager.present? && participant.messager != viewer
+      end&.messager
+
+      other if Chats.grouped_inbox?(other)
+    end
+
+    def sort_key(row)
+      row.last_message_at || (row.respond_to?(:created_at) ? row.created_at : nil) || Chats::Conversation::EPOCH
+    end
+
+    # The total-order tiebreak: a conversation's own id, a stack's freshest
+    # conversation's id. Works for bigint and uuid keys alike, and never
+    # raises on a pair it can't compare — it just calls them equal.
+    def compare_ids(a, b)
+      left = tiebreak(a)
+      right = tiebreak(b)
+      return 0 if left.nil? || right.nil? || left.class != right.class
+
+      left <=> right
+    end
+
+    def tiebreak(row)
+      row.is_a?(Chats::InboxGroup) ? row.conversation&.id : row.id
+    end
+
+    # Partial, case-insensitive matching across the inbox metadata users can
+    # actually see: participant names, conversation titles, subject labels,
+    # and message bodies. Each leg is capped (config.inbox_limit), 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 at this scale.
+    def apply_search(relation)
+      return relation.to_a unless Chats.config.search && query
+
+      loaded = relation.to_a
+      normalized_query = query.downcase
+      message_match_ids = conversations_matching_body(loaded)
+
+      loaded.select do |conversation|
+        message_match_ids.include?(conversation.id) ||
+          searchable_metadata(conversation).downcase.include?(normalized_query)
+      end
+    end
+
+    def conversations_matching_body(conversations)
+      return [] if Chats.config.encrypt_messages || conversations.empty?
+
+      pattern = "%#{Chats::Conversation.sanitize_sql_like(query.downcase)}%"
+      Chats::Message.where(conversation_id: conversations.map(&:id), deleted_at: nil)
+                    .where("LOWER(chats_messages.body) LIKE ?", pattern)
+                    .distinct
+                    .pluck(:conversation_id)
+    end
+
+    def searchable_metadata(conversation)
+      participant_names = conversation.participants.filter_map do |participant|
+        Chats.display_name_for(participant.messager) if participant.active?
+      end
+
+      [conversation.title, conversation.subject_label, *participant_names].compact.join(" ")
+    end
+  end
+end