chats 0.1.1 → 0.6.2

data/config/routes.rb

@@ -5,6 +5,14 @@ Chats::Engine.routes.draw do
   # `mount Chats::Engine => "/messages"` the inbox is /messages, a thread is
   # /messages/:id, sending is POST /messages/:conversation_id/messages.
   resources :conversations, path: "", only: %i[index show create] do
+    # The messaging dock's recent list (`chats_dock`), served into its turbo
+    # frame. A collection route, so it is drawn before /:id and never read as
+    # a conversation id.
+    get :dock, on: :collection
+    # Every unread badge on the page, fresh (`chats_unread_badge` and the
+    # dock's), for a page that may have missed the badge streams.
+    get :badge, on: :collection
+
     member do
       post :read    # advance the viewer's read horizon (mark as read)
       post :typing  # ephemeral "X is typing…" ping (see Chats::Broadcasts.typing)

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"
@@ -25,6 +26,8 @@ group :test do
   gem "mysql2"
   gem "pg"
   gem "sqlite3"
+  gem "capybara", require: false
+  gem "selenium-webdriver", require: false
   gem "bootsnap", require: false
   gem "importmap-rails"
   gem "propshaft"

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"
@@ -25,6 +26,8 @@ group :test do
   gem "mysql2"
   gem "pg"
   gem "sqlite3"
+  gem "capybara", require: false
+  gem "selenium-webdriver", require: false
   gem "bootsnap", require: false
   gem "importmap-rails"
   gem "propshaft"

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"
@@ -25,6 +26,8 @@ group :test do
   gem "mysql2"
   gem "pg"
   gem "sqlite3"
+  gem "capybara", require: false
+  gem "selenium-webdriver", require: false
   gem "bootsnap", require: false
   gem "importmap-rails"
   gem "propshaft"

data/lib/chats/action.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Chats
+  # The one featured button a message can carry: a label and the place it
+  # takes you.
+  #
+  #   alice.message!(bob, "Let's play!", action: { label: "Join my room", url: "/play/friend/abcd" })
+  #
+  #   message.action        # => #<data Chats::Action label="Join my room", url="/play/friend/abcd">
+  #   message.action.label  # => "Join my room"
+  #   message.action.to_h   # => { label: "Join my room", url: "/play/friend/abcd" }
+  #
+  # An immutable value, compared by value: two actions with the same label
+  # and url are the same action. It knows nothing about what makes one safe
+  # to render — Chats::Message validates that at the write, where a bad one
+  # can fail loudly instead of rendering a dead or dangerous link.
+  Action = Data.define(:label, :url) do
+    # Whatever a host hands `action:` — nil, a Hash (string or symbol keys),
+    # or an Action — as an Action, or nil.
+    #
+    # Unknown keys raise rather than vanish: `{ label:, url:, method: :post }`
+    # silently becoming a GET link is exactly the surprise this refuses.
+    def self.wrap(value)
+      case value
+      when nil, self then value
+      when Hash
+        attributes = value.to_h { |key, attribute| [key.to_s, attribute] }
+        unknown = attributes.keys - members.map(&:to_s)
+        if unknown.any?
+          raise ArgumentError, "unknown action keys: #{unknown.join(", ")} (an action is a label and a url)"
+        end
+
+        new(label: attributes["label"], url: attributes["url"])
+      else
+        raise ArgumentError, "an action is a Hash with a label and a url, or a Chats::Action — got #{value.inspect}"
+      end
+    end
+
+    # Both are text by the time they're stored: a path helper's String, a
+    # URI, a symbol label — all read back as the String the column holds.
+    # nil stays nil so a missing one is a validation error, not a "" that
+    # looks present.
+    #
+    # Each is a frozen, PLAIN String copy. `Data` freezes the action, not the
+    # strings it was handed, so without the copy `action.url.replace(
+    # "javascript:…")` would rewrite a validated action in place — and so
+    # would the caller mutating the string they passed in. Plain, because
+    # `String.new` drops an html_safe mark: a label that arrived as a
+    # SafeBuffer (a host's `t("…_html")`) would otherwise render unescaped
+    # in the button. An action is a value: what the validator saw is what
+    # the bubble renders, and the bubble escapes it like any other content.
+    def initialize(label:, url:)
+      super(label: plain(label), url: plain(url))
+    end
+
+    private
+
+    def plain(value)
+      String.new(value.to_s).freeze unless value.nil?
+    end
+  end
+
+  class Action
+    # How `chats_messages.action` (json/jsonb) reads and writes: an Action
+    # or nil on the Ruby side, `{"label":…,"url":…}` in the column. Every
+    # assignment goes through Action.wrap, so a Hash, an Action and nil all
+    # work, and anything else raises right where it was assigned.
+    class Type < ActiveRecord::Type::Json
+      def cast(value)
+        Action.wrap(value)
+      end
+
+      # Reads only the two keys an action has, so a row written by a later
+      # version with more of them still loads instead of raising.
+      def deserialize(value)
+        stored = super
+        Action.wrap(stored.slice("label", "url")) if stored.is_a?(Hash)
+      end
+
+      def serialize(value)
+        super(Action.wrap(value)&.to_h)
+      end
+    end
+  end
+end

data/lib/chats/broadcasts.rb

@@ -4,7 +4,7 @@ require "action_view/record_identifier"
 
 module Chats
   # ALL of the gem's real-time fan-out, in one file — read this and you know
-  # the entire live behavior. Three streams exist:
+  # the entire live behavior. Four streams exist:
   #
   #   1. The CONVERSATION stream (`turbo_stream_from @conversation` on the
   #      thread page): surgical message append/replace/remove, the read-state
@@ -20,9 +20,8 @@ module Chats
   #      broadcast would force per-viewer renders of per-viewer partials;
   #      a refresh makes each client re-request the page and get a correct,
   #      personalized render with morphing + scroll preservation for free.
-  #      Turbo debounces refreshes per stream and tags them with the
-  #      originating request id so the tab that caused the change skips its
-  #      own refresh. https://turbo.hotwired.dev/handbook/streams
+  #      At most one is queued per messager at a time (see
+  #      refresh_inbox_of). https://turbo.hotwired.dev/handbook/streams
   #
   #   3. The per-messager BADGE stream (`[messager, :chats_badge]`,
   #      subscribable from ANY page via the `chats_unread_badge` helper —
@@ -30,15 +29,46 @@ module Chats
   #      Deliberately separate from the inbox stream — if badges rode on it,
   #      every page embedding a badge would full-refresh on every message.
   #
+  #   4. The per-messager DOCK stream (`[messager, :chats_dock]`, subscribed
+  #      by the messaging dock — `chats_dock`). One render per participant
+  #      per event (chats/dock/_update), carrying up to two things:
+  #        * the dock's BADGES, with the same count as stream 3, whenever the
+  #          badge moves (a message for them, a read of theirs);
+  #        * the SIGNAL (chats/dock/_signal), replaced so the dock's
+  #          controller sees it connect: reload the recent list, and — for a
+  #          new message the participant should hear about — which
+  #          conversation it was, from whom, how much is unread there, and
+  #          that its window may pop open. Senders and edits/deletes get the
+  #          signal too (their lists reorder), never the pop-up.
+  #      The hint names a conversation only to a participant who can SEE it
+  #      (`messager.chats`: blocks and `inbox_scope` applied) — the dock's
+  #      own list and window endpoints refuse anything else, and the stream
+  #      must not tell them what those hide. No polling, no Action Cable
+  #      channel of our own.
+  #
   # Everything uses the `_later` variants (rendering happens in background
   # jobs, never inline in the request) except `message_destroyed`, where the
-  # record is gone and can't be serialized for a job.
+  # record is gone and can't be serialized for a job. Every job is enqueued
+  # from an after_commit callback, so a broadcast never announces a write
+  # that could still roll back, and never waits in memory: once the write
+  # has committed, its broadcast is in the job queue.
+  #
+  # A broadcast can still be missed — Action Cable has no replay, and a
+  # client whose socket is down when it is sent never gets it. The client
+  # side catches up (chats/recovery.js: on reconnect, on return to a hidden
+  # page, on network-online, on a back/forward-cache restore), so every
+  # surface fed by these streams heals without polling.
   module Broadcasts
     extend ActionView::RecordIdentifier # dom_id
 
     MESSAGE_PARTIAL = "chats/messages/message"
     BADGE_PARTIAL = "chats/shared/unread_badge"
+    DOCK_UPDATE_PARTIAL = "chats/dock/update"
     READ_STATE_PARTIAL = "chats/conversations/read_state"
+    # The inbox stream's whole payload. Built once, with no request id.
+    INBOX_REFRESH = %(<turbo-stream action="refresh" method="morph" scroll="preserve"></turbo-stream>)
+    # How long a queued inbox refresh stands for the writes after it.
+    INBOX_REFRESH_PENDING = 2.seconds
 
     class << self
       def message_created(message)
@@ -51,7 +81,7 @@ module Chats
           locals: { message: message }
         )
 
-        fan_out_inboxes(conversation, skip_badge_for: message.sender)
+        fan_out_inboxes(conversation, skip_badge_for: message.sender, message: message)
       end
 
       def message_updated(message)
@@ -107,11 +137,73 @@ module Chats
         )
       end
 
+      # Straight into the job queue, NOT `broadcast_refresh_later_to`: that
+      # one first parks the refresh for half a second in an in-process
+      # timer (Turbo::Debouncer, a Concurrent::ScheduledTask) and only then
+      # enqueues the job, so a deploy or a crash inside that half second
+      # drops the refresh with nothing left to retry it.
+      #
+      # One job per messager at a time. A refresh carries no data — the
+      # client re-requests its inbox — so while one is queued and hasn't
+      # started, it covers every write that commits before it runs: a burst
+      # (five messages in a 100-person group) is one job per participant,
+      # not five. A marker in Rails.cache says one is queued; the job removes
+      # it as it STARTS, before it broadcasts, so a write that still finds
+      # the marker has committed before that broadcast, and a write after
+      # it queues the next job. Every way the marker can go wrong costs an
+      # extra job, never a missed refresh: a cache without it (null store,
+      # a per-process memory store, an eviction) just doesn't coalesce, and
+      # the marker expires after INBOX_REFRESH_PENDING, so a job lost from
+      # the queue holds nothing back for longer than that.
+      # Refreshes that still arrive close together merge on the client:
+      # Turbo runs one page refresh for refreshes within 150 ms of each
+      # other (Session#pageRefreshDebouncePeriod), and chats--refresh-inbox
+      # reruns one that landed mid-visit, which Turbo would ignore.
+      #
+      # The marker goes up BEFORE the enqueue, so another write can find it
+      # while the enqueue is still in flight and count on that refresh. An
+      # enqueue that fails is therefore tried once more, and if the queue
+      # refuses again the refresh is broadcast right here: the writes that
+      # counted on it are never left without one. The failure is reported to
+      # Rails.error, not raised: the write has committed, and the refresh is
+      # out.
+      #
+      # Only a marker that is really there means a refresh is queued. A store
+      # that can't hold it (RedisCacheStore answers nil when the write
+      # fails, any store may raise) means nothing about the queue, so this
+      # write queues its own refresh.
       def refresh_inbox_of(messager)
-        Turbo::StreamsChannel.broadcast_refresh_later_to(messager, :chats_inbox)
+        return if inbox_refresh_queued?(inbox_refresh_marker(messager))
+        return if 2.times.any? { enqueue_inbox_refresh(messager) } # once more if the first fails
+
+        refresh_inbox_now(messager)
+      end
+
+      # The job's half (Chats::InboxRefreshJob): take the marker down, then
+      # broadcast. `method: morph, scroll: preserve` ride on the tag, so the
+      # inbox morphs in place whatever the host layout's refresh meta says.
+      # No request id: one refresh may answer writes from several requests,
+      # and a tab that skipped it as "its own" would miss the others'.
+      def refresh_inbox_now(messager)
+        begin
+          Rails.cache.delete(inbox_refresh_marker(messager))
+        rescue StandardError => e
+          Rails.error.report(e, handled: true) # the marker expires on its own; the refresh goes out regardless
+        end
+        Turbo::StreamsChannel.broadcast_stream_to(messager, :chats_inbox, content: INBOX_REFRESH)
       end
 
-      def update_badge_of(messager)
+      # The unread badges of +messager+: the nav badge (stream 3) and the
+      # dock's (stream 4), with the signal that tells the dock what changed.
+      # +conversation+ and +message+ say what happened (both nil for a
+      # read); +participant+ is the messager's seat there.
+      def update_badge_of(messager, conversation: nil, message: nil, participant: nil)
+        # Counted at broadcast-enqueue time: the badge is advisory UI; a
+        # count that's seconds stale self-heals on the next event. The SAME
+        # count the page renders (`chats_unread_badge`), so what the inbox
+        # scope hides never lights the badge. Counted once for both.
+        count = messager.unread_chats_count
+
         # REPLACE, not update: the partial renders the whole badge element
         # (its id included) — an `update` would nest it inside the existing
         # element and duplicate the id. Replace keeps it idempotent.
@@ -119,29 +211,98 @@ module Chats
           messager, :chats_badge,
           target: "chats_unread_badge",
           partial: BADGE_PARTIAL,
-          # Counted at broadcast-enqueue time: the badge is advisory UI; a
-          # count that's seconds stale self-heals on the next event.
-          # reorder(nil): COUNT(DISTINCT) + the inbox's COALESCE order would
-          # error on PostgreSQL.
-          locals: { count: Chats::Conversation.inbox_for(messager).unread_by(messager).reorder(nil).distinct.count }
+          locals: { count: count }
+        )
+
+        update_dock_of(messager, count: count, conversation: conversation, message: message, participant: participant)
+      end
+
+      # The dock's update (stream 4): the badges when +count+ is given, and
+      # the signal. A conversation the messager cannot see is never named:
+      # its badge count is still truthful, the signal is simply not sent.
+      def update_dock_of(messager, count: nil, conversation: nil, message: nil, participant: nil)
+        signal = dock_signal(messager, conversation, message, participant)
+        return if count.nil? && signal.nil?
+
+        Turbo::StreamsChannel.broadcast_render_later_to(
+          messager, :chats_dock,
+          partial: DOCK_UPDATE_PARTIAL,
+          locals: { count: count, signal: signal }
         )
       end
 
       private
 
+      # Whether the queue took the job. A refusal is reported to Rails.error
+      # however the adapter says it: perform_later raises, or returns false
+      # (a callback aborted it), or a job that wasn't enqueued.
+      def enqueue_inbox_refresh(messager)
+        job = Chats::InboxRefreshJob.perform_later(messager)
+        job = nil unless job.is_a?(ActiveJob::Base) # false: a callback aborted it
+        return true if job&.successfully_enqueued?
+
+        Rails.error.report(job&.enqueue_error || ActiveJob::EnqueueError.new("Chats::InboxRefreshJob was not enqueued"),
+                           handled: true)
+        false
+      rescue StandardError => e
+        Rails.error.report(e, handled: true)
+        false
+      end
+
+      # Whether a refresh is already queued for this marker's messager: the
+      # write was refused (false) AND the marker can be read back. Anything
+      # else — this write put it up, the store answered nil or raised, the
+      # marker vanished in between — is "not that we know of".
+      def inbox_refresh_queued?(marker)
+        written = Rails.cache.write(marker, true, unless_exist: true, expires_in: INBOX_REFRESH_PENDING)
+        written == false && Rails.cache.read(marker).present?
+      rescue StandardError => e
+        Rails.error.report(e, handled: true)
+        false
+      end
+
+      def inbox_refresh_marker(messager)
+        "chats:inbox-refresh:#{Chats.messager_key(messager)}"
+      end
+
       # New activity: every active participant's inbox refreshes (including
-      # the sender's — their OTHER tabs/devices need the new ordering; the
-      # originating tab skips its own refresh via Turbo's request-id dedup),
+      # the sender's — their other tabs and devices need the new ordering),
       # and every participant except the sender gets a fresh unread badge.
-      def fan_out_inboxes(conversation, skip_badge_for: nil, badges: true)
+      # Everyone else — the sender, and every seat on an edit or a delete —
+      # gets the dock's list refresh alone.
+      def fan_out_inboxes(conversation, skip_badge_for: nil, badges: true, message: nil)
         conversation.participants.active.includes(:messager).each do |participant|
           messager = participant.messager
           next if messager.nil?
 
           refresh_inbox_of(messager)
-          update_badge_of(messager) if badges && messager != skip_badge_for
+          if badges && messager != skip_badge_for
+            update_badge_of(messager, conversation: conversation, message: message, participant: participant)
+          else
+            update_dock_of(messager, conversation: conversation)
+          end
         end
       end
+
+      # What the dock is told, or nil for nothing at all. A read (no
+      # conversation) only reloads the list. A conversation the messager
+      # can't see (blocked, scoped out) is never named. A new message the
+      # participant would be notified about (Participant#notifiable_for?:
+      # not theirs, not muted, not a headless seat) may pop its window and
+      # be announced, with who it is from and how much is unread there.
+      def dock_signal(messager, conversation, message, participant)
+        return {} if conversation.nil?
+        return nil unless messager.chats.exists?(conversation.id)
+
+        signal = { conversation_id: conversation.id }
+        return signal unless message && participant&.notifiable_for?(message)
+
+        signal.merge(
+          notify: true,
+          sender_name: message.sender ? Chats.display_name_for(message.sender) : conversation.title_for(messager),
+          unread_count: participant.unread_count
+        )
+      end
     end
   end
 end

data/lib/chats/configuration.rb

@@ -15,6 +15,7 @@ module Chats
   class Configuration
     ATTACHMENT_MODES = [false, :images, :any].freeze
     DELETION_MODES = [false, :soft, :hard].freeze
+    INBOX_LAYOUTS = %i[split stacked].freeze
 
     # --- Host integration -----------------------------------------------------
 
@@ -86,6 +87,21 @@ 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
+
+    # How the inbox and a conversation share the screen. `:split` (the
+    # default): on screens at least 700px wide, /messages is two panes, the
+    # conversation list on the left and the open conversation on the right,
+    # and /messages/:id is that same page with the conversation open
+    # (LinkedIn's messaging page); narrower, the list and the thread are
+    # separate pages. `:stacked`: separate pages at every width, as before
+    # 0.6.
+    attr_reader :inbox_layout
+
     # 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 +125,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 +152,36 @@ 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
+
+    # ->(messager) { markup } — the badge shown next to an OFFICIAL
+    # account's name (`acts_as_messager verified: true`). nil (the default)
+    # renders the gem's own rosette, `chats/shared/_verified_badge`, coloured
+    # by the `--chats-verified` CSS variable.
+    #
+    # Return an html_safe value (anything `render`, `tag` or `image_tag`
+    # gives you) — a bare String is escaped, exactly as it would be anywhere
+    # else in a Rails view. Returning nil renders nothing, so a host can
+    # suppress the badge on some messagers without touching the models.
+    attr_reader :verified_badge
+
+    # ->(conversation, viewer) { String } — the title of the messaging page:
+    # the inbox (conversation nil) or a conversation. The bundled views
+    # give it to `content_for :title` (a layout doing `yield(:title)` shows
+    # it), and the two-pane page gives the tab the conversation's when a
+    # row opens it in the pane. nil (the default) is the localized
+    # `chats.page_title.inbox` / `chats.page_title.conversation`.
+    attr_reader :page_title
+
     def initialize
       @messager_class = "User"
       @parent_controller = "::ApplicationController"
@@ -152,14 +204,21 @@ 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
+      @inbox_layout = :split
 
       @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
+      @verified_badge = nil
+      @page_title = nil
 
       @messager_display_name = lambda do |messager|
         messager.try(:display_name) || messager.try(:name) ||
@@ -205,6 +264,18 @@ module Chats
       @deletion = normalized
     end
 
+    def inbox_layout=(value)
+      normalized = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless INBOX_LAYOUTS.include?(normalized)
+        raise ConfigurationError, "inbox_layout must be one of #{INBOX_LAYOUTS.inspect}, got #{value.inspect}"
+      end
+
+      @inbox_layout = normalized
+    end
+
+    # Whether the inbox and the open conversation are one two-pane page.
+    def split_inbox? = inbox_layout == :split
+
     def send_rate_limit=(value)
       if value.nil?
         @send_rate_limit = nil
@@ -232,8 +303,49 @@ 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 verified_badge=(value)
+      @verified_badge = value.nil? ? nil : ensure_callable(value, "verified_badge")
+    end
+
+    def page_title=(value)
+      @page_title = value.nil? ? nil : ensure_callable(value, "page_title")
     end
 
     def messager_display_name=(value)
@@ -259,6 +371,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