chats 0.1.1

data/lib/chats/broadcasts.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+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:
+  #
+  #   1. The CONVERSATION stream (`turbo_stream_from @conversation` on the
+  #      thread page): surgical message append/replace/remove, the read-state
+  #      payload, and the typing custom action. One render per event, shared
+  #      by every subscriber — bubbles are rendered VIEWER-AGNOSTIC and the
+  #      `chats--thread` Stimulus controller aligns own-vs-other client-side
+  #      (comparing each bubble's sender key against its own `me` value),
+  #      which is what makes a single broadcast render possible at all.
+  #   2. The per-messager INBOX stream (`[messager, :chats_inbox]`, subscribed
+  #      only on the inbox page): we broadcast Turbo 8 page REFRESHES instead
+  #      of surgically patching rows. An inbox row is intensely per-viewer
+  #      (unread badge, bold state, ordering), so patching it from a shared
+  #      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
+  #
+  #   3. The per-messager BADGE stream (`[messager, :chats_badge]`,
+  #      subscribable from ANY page via the `chats_unread_badge` helper —
+  #      e.g. a bottom-nav dock): a tiny `update` of the badge element.
+  #      Deliberately separate from the inbox stream — if badges rode on it,
+  #      every page embedding a badge would full-refresh on every message.
+  #
+  # 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.
+  module Broadcasts
+    extend ActionView::RecordIdentifier # dom_id
+
+    MESSAGE_PARTIAL = "chats/messages/message"
+    BADGE_PARTIAL = "chats/shared/unread_badge"
+    READ_STATE_PARTIAL = "chats/conversations/read_state"
+
+    class << self
+      def message_created(message)
+        conversation = message.conversation
+
+        Turbo::StreamsChannel.broadcast_append_later_to(
+          conversation,
+          target: dom_id(conversation, :messages),
+          partial: MESSAGE_PARTIAL,
+          locals: { message: message }
+        )
+
+        fan_out_inboxes(conversation, skip_badge_for: message.sender)
+      end
+
+      def message_updated(message)
+        Turbo::StreamsChannel.broadcast_replace_later_to(
+          message.conversation,
+          target: dom_id(message),
+          partial: MESSAGE_PARTIAL,
+          locals: { message: message }
+        )
+
+        # Edits/deletes change the inbox preview when they touch the latest
+        # message; a refresh is debounced and cheap, so just fan out.
+        fan_out_inboxes(message.conversation, badges: false)
+      end
+
+      def message_destroyed(message)
+        # Hard delete: the row is gone — broadcast synchronously (nothing to
+        # serialize into a job) and let inboxes re-render.
+        Turbo::StreamsChannel.broadcast_remove_to(
+          message.conversation,
+          target: dom_id(message)
+        )
+
+        fan_out_inboxes(message.conversation, badges: false)
+      end
+
+      # The viewer-agnostic read-state payload (a hidden element carrying
+      # every participant's read horizon as JSON). The thread controller
+      # turns it into a per-viewer "Seen" indicator client-side.
+      def read_state(conversation)
+        Turbo::StreamsChannel.broadcast_replace_later_to(
+          conversation,
+          target: dom_id(conversation, :read_state),
+          partial: READ_STATE_PARTIAL,
+          locals: { conversation: conversation }
+        )
+      end
+
+      # Ephemeral "X is typing…" — a Turbo Stream CUSTOM ACTION (registered
+      # in chats/thread_controller.js as Turbo.StreamActions.chats_typing),
+      # carrying the typist in attributes. Nothing is persisted; if nobody's
+      # subscribed it evaporates, which is exactly right for presence-ish
+      # signals. No `_later`: typing is only meaningful NOW.
+      def typing(conversation, messager)
+        Turbo::StreamsChannel.broadcast_action_to(
+          conversation,
+          action: :chats_typing,
+          target: dom_id(conversation, :typing),
+          attributes: {
+            "data-name" => Chats.display_name_for(messager),
+            "data-key" => Chats.messager_key(messager)
+          }
+        )
+      end
+
+      def refresh_inbox_of(messager)
+        Turbo::StreamsChannel.broadcast_refresh_later_to(messager, :chats_inbox)
+      end
+
+      def update_badge_of(messager)
+        # 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.
+        Turbo::StreamsChannel.broadcast_replace_later_to(
+          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 }
+        )
+      end
+
+      private
+
+      # 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),
+      # and every participant except the sender gets a fresh unread badge.
+      def fan_out_inboxes(conversation, skip_badge_for: nil, badges: true)
+        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
+        end
+      end
+    end
+  end
+end

data/lib/chats/configuration.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+module Chats
+  # All of the gem's knobs, with delightful defaults: a fresh `Configuration`
+  # is fully working out of the box for the classic Devise + `User` Rails app.
+  #
+  # Two design rules, shared across the gem ecosystem (moderate, api_keys, …):
+  #
+  #   1. Class names are stored as STRINGS and constantized lazily, so the
+  #      initializer can reference app classes before they're loaded and
+  #      everything survives Zeitwerk reloads.
+  #   2. Cross-gem seams are PROCS with no-op defaults, so `chats` runs
+  #      standalone and lights up when the host wires moderate / Noticed /
+  #      goodmail in.
+  class Configuration
+    ATTACHMENT_MODES = [false, :images, :any].freeze
+    DELETION_MODES = [false, :soft, :hard].freeze
+
+    # --- Host integration -----------------------------------------------------
+
+    # The primary conversing model. Participants stay polymorphic regardless
+    # (any `acts_as_messager` model can join a conversation); this is the
+    # class the engine's controllers resolve `current_messager` against and
+    # the default for docs/generators.
+    attr_reader :messager_class
+
+    # The controller the engine inherits from. Pointing this at the host's
+    # `ApplicationController` (the default) gives the engine the host's
+    # layout, helpers, `current_user`, locale switching, etc. — the same
+    # pattern api_keys uses for its dashboard.
+    attr_reader :parent_controller
+
+    # Method called on the controller to fetch the current messager
+    # (`:current_user` works with Devise out of the box).
+    attr_accessor :current_messager_method
+
+    # Method called as a `before_action` to require authentication
+    # (`:authenticate_user!` works with Devise out of the box).
+    attr_accessor :authenticate_method
+
+    # Optional explicit layout for the engine's screens. `nil` (default)
+    # inherits whatever layout the parent controller resolves — usually the
+    # host's `application` layout. Set to e.g. `"app"` if your host renders
+    # its logged-in surfaces with a different layout.
+    attr_accessor :layout
+
+    # --- Feature flags --------------------------------------------------------
+
+    # Group conversations (3+ participants, a title, join/leave). Direct 1:1
+    # conversations are always available.
+    attr_accessor :groups
+
+    # Emoji reactions on messages.
+    attr_accessor :reactions
+
+    # Read receipts ("Seen") + unread tracking. Read state is stored on the
+    # participant (`last_read_at`), not per-message — see Chats::Participant
+    # for the rationale.
+    attr_accessor :read_receipts
+
+    # Live "X is typing…" indicators (Turbo Stream custom action; no Action
+    # Cable channel of its own, see Chats::ConversationsController#typing).
+    attr_accessor :typing_indicators
+
+    # Whether senders can edit their own messages after sending.
+    attr_accessor :editing
+
+    # What "delete" means: `:soft` keeps a tombstone ("message deleted", body
+    # gone — the WhatsApp model, and the safest for Trust & Safety evidence),
+    # `:hard` destroys the row, `false` disables deletion entirely.
+    attr_reader :deletion
+
+    # Message attachments: `false` (none), `:images` (images only — the
+    # default), or `:any` (any content type). Backed by ActiveStorage's
+    # `has_many_attached`, so the host must have ActiveStorage installed to
+    # enable this.
+    attr_reader :attachments
+
+    # Inbox search box (partial matching across participant names, conversation
+    # titles, subject labels, and message bodies — no extra dependencies; swap
+    # in pg_search & friends by overriding the controller if you outgrow it).
+    attr_accessor :search
+
+    # --- Limits ---------------------------------------------------------------
+
+    attr_accessor :messages_per_page, :max_message_length, :max_group_size, :max_attachment_size,
+                  :max_attachments_per_message
+
+    # 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 }`.
+    # Set to `nil` to disable.
+    attr_reader :send_rate_limit
+
+    # Encrypt message bodies at rest with ActiveRecord Encryption
+    # (`encrypts :body`). Requires the host to have AR encryption keys
+    # configured (`bin/rails db:encryption:init`). Note: turning this on
+    # makes message-body search degrade to title/participant matching.
+    attr_accessor :encrypt_messages
+
+    # --- Policies (procs) -----------------------------------------------------
+
+    # Host authorization on top of block enforcement: may +sender+ open a
+    # conversation with / send to +recipient+? Blocking is ALWAYS enforced
+    # underneath this (see Chats.can_message?) so a permissive or buggy
+    # policy can never let a blocked pair talk.
+    attr_reader :can_message
+
+    # May +creator+ create a group conversation?
+    attr_reader :can_create_group
+
+    # --- Ecosystem seams (procs, no-op defaults) ------------------------------
+
+    # ->(messager) { ids } — every messager id that can't talk with the given
+    # one (bidirectional). Wire to the moderate gem with one line:
+    #   config.blocked_messager_ids = ->(user) { Moderate.blocked_ids_for(user) }
+    attr_reader :blocked_messager_ids
+
+    # ->(event, **payload) — domain-moment fan-out (see Chats.notify).
+    attr_reader :notifier
+
+    # --- Display procs (used by the bundled views) ----------------------------
+
+    # ->(messager) { String } — how a messager is named in inboxes, bubbles
+    # and typing indicators. The default tries the obvious candidates.
+    attr_reader :messager_display_name
+
+    # ->(messager) { url/attachment/nil } — an avatar for the messager.
+    # Return anything `image_tag` accepts (a URL, an ActiveStorage attachment
+    # or variant), or nil to render an initials placeholder.
+    attr_reader :messager_avatar
+
+    def initialize
+      @messager_class = "User"
+      @parent_controller = "::ApplicationController"
+      @current_messager_method = :current_user
+      @authenticate_method = :authenticate_user!
+      @layout = nil
+
+      @groups = true
+      @reactions = true
+      @read_receipts = true
+      @typing_indicators = true
+      @editing = true
+      @deletion = :soft
+      @attachments = :images
+      @search = true
+
+      @messages_per_page = 30
+      @max_message_length = 5_000
+      @max_group_size = 32
+      @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
+
+      @encrypt_messages = false
+
+      @can_message = ->(_sender, _recipient) { true }
+      @can_create_group = ->(_creator) { true }
+
+      @blocked_messager_ids = ->(_messager) { [] }
+      @notifier = ->(_event, **_payload) {}
+
+      @messager_display_name = lambda do |messager|
+        messager.try(:display_name) || messager.try(:name) ||
+          messager.try(:full_name) || messager.try(:username) ||
+          messager.try(:email) || "#{messager.class.model_name.human} #{messager.id}"
+      end
+      @messager_avatar = ->(messager) { messager.try(:avatar) }
+    end
+
+    # --- Validating setters ---------------------------------------------------
+    #
+    # Fail at boot with a plain-English message, not at 3am with a NoMethodError.
+
+    def messager_class=(value)
+      name = value.is_a?(Class) ? value.name : value.to_s
+      raise ConfigurationError, "messager_class can't be blank" if name.strip.empty?
+
+      @messager_class = name
+    end
+
+    def parent_controller=(value)
+      name = value.is_a?(Class) ? value.name : value.to_s
+      raise ConfigurationError, "parent_controller can't be blank" if name.strip.empty?
+
+      @parent_controller = name
+    end
+
+    def attachments=(value)
+      normalized = normalize_flag(value)
+      unless ATTACHMENT_MODES.include?(normalized)
+        raise ConfigurationError, "attachments must be one of #{ATTACHMENT_MODES.inspect}, got #{value.inspect}"
+      end
+
+      @attachments = normalized
+    end
+
+    def deletion=(value)
+      normalized = normalize_flag(value)
+      unless DELETION_MODES.include?(normalized)
+        raise ConfigurationError, "deletion must be one of #{DELETION_MODES.inspect}, got #{value.inspect}"
+      end
+
+      @deletion = normalized
+    end
+
+    def send_rate_limit=(value)
+      if value.nil?
+        @send_rate_limit = nil
+        return
+      end
+
+      hash = value.to_h.symbolize_keys
+      unless hash[:to].is_a?(Integer) && hash[:to].positive? && hash[:within].respond_to?(:to_i)
+        raise ConfigurationError,
+              "send_rate_limit must be nil or { to: Integer, within: duration }, got #{value.inspect}"
+      end
+
+      @send_rate_limit = hash
+    end
+
+    def can_message=(value)
+      @can_message = ensure_callable(value, "can_message")
+    end
+
+    def can_create_group=(value)
+      @can_create_group = ensure_callable(value, "can_create_group")
+    end
+
+    def blocked_messager_ids=(value)
+      @blocked_messager_ids = ensure_callable(value, "blocked_messager_ids")
+    end
+
+    def notifier=(value)
+      @notifier = ensure_callable(value, "notifier")
+    end
+
+    def messager_display_name=(value)
+      @messager_display_name = ensure_callable(value, "messager_display_name")
+    end
+
+    def messager_avatar=(value)
+      @messager_avatar = ensure_callable(value, "messager_avatar")
+    end
+
+    # Cross-field validation, run at the end of `Chats.configure`.
+    def validate!
+      if max_message_length && max_message_length < 1
+        raise ConfigurationError, "max_message_length must be positive (got #{max_message_length})"
+      end
+
+      if max_group_size && max_group_size < 3
+        # 2 participants is a direct conversation; a "group" of 2 is a smell.
+        raise ConfigurationError, "max_group_size must be at least 3 (got #{max_group_size})"
+      end
+
+      if messages_per_page.to_i < 1
+        raise ConfigurationError, "messages_per_page must be positive (got #{messages_per_page.inspect})"
+      end
+
+      true
+    end
+
+    # The constantized messager class (resolved lazily — see class comment).
+    def messager_model
+      messager_class.constantize
+    end
+
+    private
+
+    def normalize_flag(value)
+      return value if value == false || value.nil?
+
+      value.to_sym
+    end
+
+    def ensure_callable(value, name)
+      unless value.respond_to?(:call)
+        raise ConfigurationError, "#{name} must respond to #call (a proc/lambda), got #{value.inspect}"
+      end
+
+      value
+    end
+  end
+end

data/lib/chats/engine.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "turbo-rails"
+
+module Chats
+  # The mountable engine: wires autoloading, migrations, locales, the
+  # ActiveRecord macros, importmap pins, asset paths, and boot-time model
+  # configuration into the host app.
+  class Engine < ::Rails::Engine
+    isolate_namespace Chats
+
+    # -------------------------------------------------------------------------
+    # Zeitwerk: the gem keeps its ActiveRecord models under lib/chats/models
+    # (same layout as the moderate gem) so the whole domain ships in lib/ and
+    # the engine's app/ tree only holds the web layer (controllers, helpers,
+    # views). For that to autoload correctly we manage the loader by hand:
+    #
+    #   - `push_dir(lib/chats, namespace: Chats)` makes lib/chats/models/...
+    #     autoloadable *under the Chats namespace*.
+    #   - `collapse(models)` + `collapse(models/concerns)` mean the files in
+    #     those folders define Chats::Conversation / Chats::Messager — not
+    #     Chats::Models::Conversation.
+    #   - The SPINE files (version/errors/configuration/macros/engine) are
+    #     required explicitly by lib/chats.rb at boot, so they must be
+    #     *ignored* by the loader or Zeitwerk would complain about double
+    #     definitions / unmanaged constants.
+    # -------------------------------------------------------------------------
+    LIB_ROOT = File.expand_path("..", __dir__)
+    CHATS_LIB = File.expand_path("chats", LIB_ROOT)
+
+    ZEITWERK_IGNORED = %w[
+      version.rb errors.rb configuration.rb engine.rb macros.rb
+    ].freeze
+
+    initializer "chats.autoload", before: :set_autoload_paths do
+      loader = Rails.autoloaders.main
+
+      ZEITWERK_IGNORED.each do |file|
+        path = File.join(CHATS_LIB, file)
+        loader.ignore(path) if File.exist?(path)
+      end
+
+      %w[models models/concerns].each do |dir|
+        path = File.join(CHATS_LIB, dir)
+        loader.collapse(path) if File.directory?(path)
+      end
+
+      loader.push_dir(CHATS_LIB, namespace: Chats)
+    end
+
+    config.eager_load_paths << CHATS_LIB
+
+    # Make the gem's migrations runnable from the host without copying
+    # (`rails db:migrate` picks them up) — the install generator still copies
+    # a host-owned migration, which is the recommended path; this initializer
+    # mainly serves the dummy app and hosts that prefer engine-owned
+    # migrations.
+    initializer "chats.migrations" do |app|
+      unless app.root.to_s == root.to_s
+        config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+
+    # Expose `acts_as_messager` / `acts_as_chat_subject` on every AR model.
+    initializer "chats.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend Chats::Macros
+      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
+
+    # NOTE: the host-facing helpers (`chat_button_to`, `chats_unread_badge`, …)
+    # are exposed to ActionView from the BOTTOM of engine_helper.rb itself
+    # (moderate's proven pattern), NOT from an initializer here: an
+    # `on_load(:action_view)` registered during initializers fires
+    # IMMEDIATELY in hosts where something (web-console, a mailer preview…)
+    # already loaded ActionView — and at that point the autoloader can't
+    # resolve Chats::EngineHelper yet (NameError at boot). Keeping the hook
+    # in the same file as the constant makes it self-resolving; the
+    # `to_prepare` touch below guarantees the file loads on every boot and
+    # code reload even before anything references it.
+
+    # -------------------------------------------------------------------------
+    # JavaScript: the engine ships tiny Stimulus controllers (thread, composer,
+    # debounced-submit) 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
+    # `eagerLoadControllersFrom("controllers", application)`, which scans the
+    # rendered importmap for keys matching ^controllers/.*_controller$ and
+    # registers each one, deriving the identifier from the path
+    # ("controllers/chats/thread_controller" → "chats--thread"; see
+    # stimulus-rails' stimulus-loading.js, registerControllerFromPath).
+    # Result: a host with the default Stimulus setup gets the chats--*
+    # controllers REGISTERED AUTOMATICALLY, zero JS changes.
+    #
+    # We `unshift` (not `<<`) our importmap so the HOST's pins are drawn after
+    # ours — importmap-rails resolves duplicate pins last-wins, so a host can
+    # override any chats controller by pinning the same key (or just dropping
+    # a file at app/javascript/controllers/chats/thread_controller.js, which
+    # `pin_all_from "app/javascript/controllers"` then pins over ours).
+    # importmap-rails appends the app's own config/importmap.rb inside its
+    # "importmap" initializer and draws everything in path order:
+    # https://github.com/rails/importmap-rails (lib/importmap/engine.rb)
+    # -------------------------------------------------------------------------
+    initializer "chats.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap)
+        app.config.importmap.paths.unshift(root.join("config/importmap.rb"))
+        # Sweep the importmap cache when our JS changes (dev nicety).
+        app.config.importmap.cache_sweepers << root.join("app/javascript")
+      end
+    end
+
+    # Serve the engine's JS + CSS through the host's asset pipeline
+    # (propshaft or sprockets — both honor config.assets.paths).
+    initializer "chats.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/javascript")
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+      end
+    end
+
+    # Apply boot-time configuration that has to touch autoloaded classes —
+    # runs on every reload in development so it stays applied to fresh ones.
+    config.to_prepare do
+      # Touch the helper so its bottom-of-file on_load(:action_view) hook
+      # registers even if no engine code was referenced yet (see NOTE above).
+      # (Assigned to appease Lint/Void — the constant REFERENCE is the point.)
+      _loaded = Chats::EngineHelper
+
+      if Chats.config.encrypt_messages && Chats::Message.respond_to?(:encrypts)
+        # Opt-in encryption at rest (config.encrypt_messages = true).
+        # `deterministic: false` (the default) is correct for free text.
+        Chats::Message.encrypts :body
+      end
+    end
+  end
+end

data/lib/chats/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Chats
+  # Base class for every error this gem raises, so hosts can
+  # `rescue Chats::Error` to catch anything chats-specific.
+  class Error < StandardError; end
+
+  # Raised by `Chats.configure` / setters when the configuration is invalid
+  # (unknown filter mode, blank class name, non-callable hook, …).
+  class ConfigurationError < Error; end
+
+  # Raised when trying to open a conversation with (or send a message to)
+  # someone the sender is blocked with — in either direction. Controllers
+  # translate this into a friendly flash; model-level callers get the raise.
+  class BlockedError < Error; end
+
+  # Raised when the host `can_message` policy (or a feature flag like
+  # `config.groups = false`) forbids the attempted action.
+  class NotAllowedError < Error; end
+end

data/lib/chats/macros.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Chats
+  # The two host-facing macros. The engine extends `ActiveRecord::Base` with
+  # this module (via `ActiveSupport.on_load(:active_record)`), so any model
+  # can declare:
+  #
+  #   class User < ApplicationRecord
+  #     acts_as_messager            # can converse: inbox, DMs, groups
+  #   end
+  #
+  #   class Ride < ApplicationRecord
+  #     acts_as_chat_subject        # conversations can be *about* a ride
+  #   end
+  #
+  # Each macro just includes the corresponding concern — all the behavior
+  # lives in Chats::Messager / Chats::ChatSubject so it's discoverable,
+  # testable, and `include`-able directly when a host prefers that style.
+  module Macros
+    def acts_as_messager
+      include Chats::Messager
+    end
+
+    def acts_as_chat_subject
+      include Chats::ChatSubject
+    end
+  end
+end

data/lib/chats/models/application_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Chats
+  # Abstract base for every chats model. Kept separate from the host's
+  # ApplicationRecord on purpose: the gem's models must not inherit host
+  # callbacks/scopes, and the host must be able to swap its own base class
+  # without touching ours.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/chats/models/concerns/chat_subject.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Chats
+  # Included by `acts_as_chat_subject`. Lets conversations be *about* a host
+  # record — `user.chat_with(driver, about: ride)` — which both threads the
+  # right people into the right context and shows up as a context line in
+  # the inbox/thread UI.
+  #
+  # Override +chat_subject_label+ to control that context line:
+  #
+  #   class Ride::Listing < ApplicationRecord
+  #     acts_as_chat_subject
+  #     def chat_subject_label = "#{origin_locality} → #{destination_locality}"
+  #   end
+  module ChatSubject
+    extend ActiveSupport::Concern
+
+    included do
+      # `nullify`, not `destroy`: deleting the subject (a ride, an order)
+      # must never delete people's conversation history — the thread just
+      # loses its context line.
+      has_many :chat_conversations,
+               class_name: "Chats::Conversation",
+               as: :subject,
+               dependent: :nullify
+
+      Chats.register_chat_subject(self)
+    end
+
+    # Short human label shown as the conversation's context line.
+    def chat_subject_label
+      "#{self.class.model_name.human} #{id}"
+    end
+  end
+end