chats 0.6.2 → 0.7.2

data/app/views/chats/tray/_item.html.erb

@@ -0,0 +1,44 @@
+<%# One item of the tray (`chats_tray_item`): closed, a tab on the bottom
+    edge (a round button on a phone); open, a panel with the dock's skin and
+    the dock's bar on top (a full-screen sheet on a phone). A <details>: it
+    opens and closes with no JavaScript, like the dock's own panel.
+
+    data-chats-active / data-chats-minimized are the read gate chats' thread
+    controller obeys in a dock window: a thread inside a closed item never
+    marks anything read (chats--tray keeps the pair in step and dispatches
+    `chats:activated` when the item opens).
+
+    Locals: key, label (the closed tab's words), title (the open panel's,
+    HTML allowed), icon (HTML), badge (HTML: `chats_tray_badge` and the
+    stream that replaces it), badge_url (where a missed badge is asked
+    again), body (the panel's content). %>
+<%= tag.details id: "chats_tray_#{key}",
+      class: "chats-tray__item",
+      data: {
+        "chats--tray-target": "item",
+        chats_tray_key: key,
+        chats_tray_badge_url: badge_url,
+        chats_active: "true",
+        chats_minimized: true,
+        action: "toggle->chats--tray#toggled"
+      } do %>
+  <%# The summary reads "Need help?, 2 unread" from its own text closed,
+      and the panel's title open. %>
+  <summary class="chats-tray__launcher">
+    <% if icon %><span class="chats-tray__icon" aria-hidden="true"><%= icon %></span><% end %>
+    <span class="chats-tray__label"><%= label %></span>
+    <span class="chats-tray__title"><%= title %></span>
+    <%= badge %>
+    <span class="chats-tray__chevron" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+           stroke-linejoin="round" focusable="false"><path d="m6 15 6-6 6 6" /></svg>
+    </span>
+    <span class="chats-tray__close-glyph" aria-hidden="true">
+
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+           focusable="false"><path d="M6 6l12 12M18 6 6 18" /></svg>
+    </span>
+  </summary>
+
+  <%= tag.div body, class: "chats-tray__body", role: "region", "aria-label": strip_tags(title.to_s).squish %>
+<% end %>

data/app/views/chats/tray/_tray.html.erb

@@ -0,0 +1,27 @@
+<%# The tray: the items a host puts in the corner (`chats_dock { … }`, or
+    `chats_tray { … }` on its own), left to right in the block's order,
+    between the dock's windows and its panel. Each item is a
+    `chats_tray_item`; the chats--tray controller (tray_controller.js) runs
+    them all: one open at a time, the phone sheet, Escape, memory, badges.
+
+    Locals: tray (the items' HTML), owner (whose memory: the viewer's key,
+    or "guest"), standalone (true when there is no dock around it). %>
+<% standalone = local_assigns.fetch(:standalone, false) %>
+<%# The id names the owner, as the corner's and the dock's do: the tray rides
+    along with them from page to page (data-turbo-permanent), and on each
+    visit chats--tray reconciles its items with the ones the new page rendered
+    under the same id (by key: one still there keeps its state). %>
+<%= tag.div tray,
+      id: "chats_tray_items_#{owner}",
+      class: "chats-tray",
+      data: {
+        controller: "chats--tray",
+        "chats--dock-target": ("tray" unless standalone),
+        "chats--tray-owner-value": owner,
+        "chats--tray-standalone-value": standalone,
+        action: "keydown->chats--tray#keydown " \
+                "turbo:before-render@document->chats--tray#reconcile " \
+                "turbo:before-cache@document->chats--tray#releaseSheet " \
+                "turbo:load@document->chats--tray#pageChanged turbo:render@document->chats--tray#pageChanged " \
+                "turbo:frame-load@document->chats--tray#frameLoaded"
+      } %>

data/config/importmap.rb

@@ -18,8 +18,12 @@ pin "controllers/chats/refresh_inbox_controller", to: "chats/refresh_inbox_contr
 pin "controllers/chats/dock_controller", to: "chats/dock_controller.js"
 pin "controllers/chats/unread_badge_controller", to: "chats/unread_badge_controller.js"
 pin "controllers/chats/split_controller", to: "chats/split_controller.js"
+pin "controllers/chats/tray_controller", to: "chats/tray_controller.js"
 
 # Not a controller: what the inbox, thread, badge and dock controllers share
 # to catch up on broadcasts they missed. Outside controllers/ so the eager
 # loader never tries to register it.
 pin "chats/recovery", to: "chats/recovery.js"
+# What the dock's sheet and the tray's share: the page's inert and its scroll
+# lock, held by owner.
+pin "chats/sheet", to: "chats/sheet.js"

data/config/locales/en.yml

@@ -51,6 +51,7 @@ en:
       save: "Save"
       react: "React"
       toggle_reaction: "React with %{emoji}"
+      menu: "Message options"
     composer:
       editing: "Edit message"
       cancel_edit: "Cancel edit"

data/config/locales/es.yml

@@ -51,6 +51,7 @@ es:
       save: "Guardar"
       react: "Reaccionar"
       toggle_reaction: "Reaccionar con %{emoji}"
+      menu: "Opciones del mensaje"
     composer:
       editing: "Editar mensaje"
       cancel_edit: "Cancelar edición"

data/lib/chats/after_commit.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Chats
+  # Work that must not happen before the change it announces is durable,
+  # owned by the TRANSACTION, the way a record's after_commit callbacks are.
+  #
+  #   Chats::AfterCommit.run(connection, key: [:unread_consumed, seat.id]) { … }
+  #
+  # The block is wrapped in an Envelope and enrolled in the connection's
+  # current transaction (`connection.add_transaction_record`, the call Active
+  # Record makes for a saved record, on every supported Rails), which
+  # finalizes it: runs it on commit, drops it on rollback or when an exception
+  # ends the transaction. Nothing lives on a Ruby instance or on the thread,
+  # so it doesn't matter which instance of a row was saved, whether the row
+  # survives the transaction (a seat destroyed after its read), or which
+  # thread runs next. The rules are after_commit's:
+  #
+  #   - with no transaction open, it runs at once;
+  #   - in a transaction that joins its parent, and in a savepoint
+  #     (`requires_new: true`) under a joinable parent, it moves up and runs
+  #     at the outermost commit; a savepoint that rolls back drops only its
+  #     own envelopes;
+  #   - under a parent that is not joinable (and the wrapper Rails'
+  #     transactional tests run each test in), it runs when the savepoint is
+  #     released, when after_commit runs too.
+  #
+  # +key+: at most one envelope per key per transaction (the first one wins).
+  #
+  # The same shape as moderate's Moderate::DeferredNotices.
+  module AfterCommit
+    # What a transaction finalizes: Active Record calls `before_committed!`,
+    # then `committed!` or `rolledback!` on every record enrolled in it, and
+    # reads `trigger_transactional_callbacks?`, `destroyed?` and
+    # `_new_record_before_last_commit` when it chooses which instance of a
+    # row runs callbacks.
+    class Envelope
+      attr_accessor :_new_record_before_last_commit
+
+      def initialize(work)
+        @work = work
+        @finalized = false
+      end
+
+      def trigger_transactional_callbacks? = true
+      def has_transactional_callbacks? = true # rubocop:disable Naming/PredicatePrefix -- Active Record's name
+      def destroyed? = false
+      def before_committed!; end
+
+      # Once, when the transaction that owns it runs commit callbacks. (Active
+      # Record also calls it with should_run_callbacks: false when it is only
+      # cleaning up after an exception: nothing runs then.)
+      def committed!(should_run_callbacks: true)
+        return if @finalized
+
+        @finalized = true
+        @work.call if should_run_callbacks
+      end
+
+      def rolledback!(force_restore_state: false, should_run_callbacks: true)
+        @finalized = true
+      end
+    end
+
+    # The keys already enrolled, per transaction object (gone with it).
+    KEYS = ObjectSpace::WeakMap.new
+    private_constant :KEYS
+
+    class << self
+      def run(connection, key: nil, &work)
+        transaction = connection&.current_transaction
+        return work.call unless transaction&.open?
+
+        if key
+          keys = (KEYS[transaction] ||= Set.new)
+          return unless keys.add?(key)
+        end
+        connection.add_transaction_record(Envelope.new(work))
+        nil
+      end
+
+      # A model's connection, as of now (Rails 7.2 renamed it lease_connection).
+      def connection_for(model)
+        model.respond_to?(:lease_connection) ? model.lease_connection : model.connection
+      end
+    end
+  end
+end

data/lib/chats/broadcasts.rb

@@ -270,6 +270,12 @@ module Chats
       # and every participant except the sender gets a fresh unread badge.
       # Everyone else — the sender, and every seat on an edit or a delete —
       # gets the dock's list refresh alone.
+      #
+      # The badge moving is also a domain moment, `:unread_changed`, for
+      # every badge chats doesn't draw itself (a product gem's own count, a
+      # native app's). Emitted here because this is where it happens for
+      # every message, system ones included, which `:message_created`
+      # deliberately skips.
       def fan_out_inboxes(conversation, skip_badge_for: nil, badges: true, message: nil)
         conversation.participants.active.includes(:messager).each do |participant|
           messager = participant.messager
@@ -278,7 +284,9 @@ module Chats
           refresh_inbox_of(messager)
           if badges && messager != skip_badge_for
             update_badge_of(messager, conversation: conversation, message: message, participant: participant)
+            Chats.notify(:unread_changed, messager: messager, conversation: conversation)
           else
+
             update_dock_of(messager, conversation: conversation)
           end
         end

data/lib/chats/models/participant.rb

@@ -90,11 +90,24 @@ module Chats
     #     read in a notification center the moment the thread is read, so a
     #     bell badge doesn't keep advertising messages the user has already
     #     seen). Same notify hook as :message_created; error-isolated.
+    #   - `:unread_changed`, in the same case, once the read has COMMITTED
+    #     (inside a host's transaction that rolls back, never): it promises
+    #     subscribers the count they read is the one that stands.
     def read!(at: Time.current)
       return self if last_read_at && last_read_at >= at
 
       had_unread = unread?
-      update!(last_read_at: at)
+      connection = Chats::AfterCommit.connection_for(self.class) # the one this read writes on
+      # The transaction owns the announcement (Chats::AfterCommit), the one the
+      # write is in: it runs at the real commit, never for a rollback, once per
+      # seat per transaction, whatever else happens to the seat meanwhile.
+      self.class.transaction do
+        update!(last_read_at: at)
+        if had_unread
+          seat = { messager: messager, conversation: conversation } # whatever becomes of the row
+          Chats::AfterCommit.run(connection, key: [:unread_consumed, id]) { Chats.notify(:unread_changed, **seat) }
+        end
+      end
       broadcast_read_state if Chats.config.read_receipts
       Chats::Broadcasts.refresh_inbox_of(messager)
       Chats::Broadcasts.update_badge_of(messager)

data/lib/chats/subscribers.rb

@@ -25,11 +25,24 @@ module Chats
     #   :conversation_created  conversation:              a conversation just came into being
     #   :participant_left      participant:               someone left a group
     #   :conversation_read     conversation:, participant: a read consumed unread content
+    #   :unread_changed        messager:, conversation:    a messager's unread count there may
+    #                                                      have moved (any message, system ones
+    #                                                      included, or a read that consumed some).
+    #                                                      Always after the write commits (a
+    #                                                      message's fan-out; a read's, by its
+    #                                                      transaction: Chats::AfterCommit),
+    #                                                      never for one that rolls back. ONCE PER ELIGIBLE SEAT: a
+    #                                                      message in a 100-seat group calls it
+    #                                                      99 times, synchronously, in that
+    #                                                      after_commit. Subscribers stay cheap
+    #                                                      (filter on the conversation first, no
+    #                                                      query) and enqueue, or coalesce.
     EVENTS = {
       message_created: :message,
       conversation_created: :conversation,
       participant_left: :participant,
-      conversation_read: nil
+      conversation_read: nil,
+      unread_changed: nil
     }.freeze
 
     # The events the deprecated `config.notifier=` hook is subscribed to:

data/lib/chats/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chats
-  VERSION = "0.6.2"
+  VERSION = "0.7.2"
 end

data/lib/generators/chats/templates/initializer.rb

@@ -243,6 +243,7 @@ Chats.configure do |config|
   #   app/views/chats/slots/_composer_actions.html.erb          your own buttons above the composer
   #   app/views/chats/slots/_locked_composer.html.erb           the locked composer's body
   #   app/views/chats/slots/_message_meta.html.erb              after each bubble's timestamp
+  #   app/views/chats/slots/_message_menu.html.erb              your items in a message's menu (Report…)
   #   app/views/chats/slots/_dock_panel_footer.html.erb         beside "See all messages" in the dock
   #
   # `rails generate chats:views` is still there for wholesale restyling.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chats
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.2
 platform: ruby
 authors:
 - rameerez
@@ -138,8 +138,10 @@ files:
 - app/javascript/chats/dock_controller.js
 - app/javascript/chats/recovery.js
 - app/javascript/chats/refresh_inbox_controller.js
+- app/javascript/chats/sheet.js
 - app/javascript/chats/split_controller.js
 - app/javascript/chats/thread_controller.js
+- app/javascript/chats/tray_controller.js
 - app/javascript/chats/unread_badge_controller.js
 - app/views/chats/conversations/_conversation_pane.html.erb
 - app/views/chats/conversations/_conversation_row.html.erb
@@ -173,31 +175,21 @@ files:
 - app/views/chats/messages/locked.turbo_stream.erb
 - app/views/chats/shared/_unread_badge.html.erb
 - app/views/chats/shared/_verified_badge.html.erb
+- app/views/chats/tray/_badge.html.erb
+- app/views/chats/tray/_corner.html.erb
+- app/views/chats/tray/_item.html.erb
+- app/views/chats/tray/_tray.html.erb
 - config/importmap.rb
 - config/locales/en.yml
 - config/locales/es.yml
 - config/routes.rb
 - context7.json
-- docs/PRD.md
-- docs/campfire_review.md
-- docs/screenshots/composer-actions.png
-- docs/screenshots/dock-bar.png
-- docs/screenshots/dock-desktop.png
-- docs/screenshots/dock-phone-button.png
-- docs/screenshots/dock-phone-panel.png
-- docs/screenshots/dock-phone-window.png
-- docs/screenshots/inbox.png
-- docs/screenshots/split-inbox-empty.png
-- docs/screenshots/split-inbox-phone-list.png
-- docs/screenshots/split-inbox-phone-thread.png
-- docs/screenshots/split-inbox.png
-- docs/screenshots/system-note-action.png
-- docs/screenshots/thread-actions-phone.png
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.1.gemfile
 - lib/chats.rb
 - lib/chats/action.rb
+- lib/chats/after_commit.rb
 - lib/chats/broadcasts.rb
 - lib/chats/configuration.rb
 - lib/chats/engine.rb

data/docs/PRD.md

@@ -1,254 +0,0 @@
-# `chats` — PRD (draft v0.2)
-
-**A drop-in, real-time messaging engine for any Rails 8+ app.**
-Direct messages, group chats, reactions, attachments, read receipts — Hotwire-native, polymorphic, and wired into the rest of our gem ecosystem (`moderation`/`banbanban`, `goodmail`, future `notifications`/push) so a developer gets messaging **and** its Trust & Safety + notifications story by configuring once.
-
-> **Status: SHIPPED as v0.1.0 (2026-06-09).** This PRD is kept as the original design document; the README and the code are the source of truth now. What shipped vs. this draft:
->
-> - **Built gem-first** (not CarHey-first): by build time the moderation system had already been extracted as the `moderate` gem, so the proven-shape argument for incubating in-app no longer applied. The gem was built standalone with its own dummy-app suite and integrated into CarHey in the same change (Gemfile `github: "rameerez/chats"`).
-> - **Namespace drift**: everywhere this doc says `Moderation::*` / `moderates_content` / `filter_policy`, the real extracted API is `Moderate::*`, `has_reportable_content`, `moderates`, `config.filter`, `Moderate.blocked_ids_for`. The interop shipped duck-typed (no hard dependency, §7's resolution), via `config.blocked_messager_ids` + plain contract methods on `Chats::Message`/`Chats::Conversation`.
-> - **No `Chats::MessageReceipt` table**: read state shipped as a per-participant horizon (`last_read_at`), which delivers unread counts + "Seen" with zero per-message writes (the Campfire model). Receipts can be added later without breaking API — see `Chats::Participant`'s doc.
-> - **Typing indicators** shipped as a Turbo Stream custom action over the existing `Turbo::StreamsChannel` (a debounced POST + broadcast), not a bespoke `Chats::ConversationChannel` — no Action Cable identification requirements on the host.
-> - **Noticed** remains uninstalled in CarHey; the interim notifier proc schedules a debounced goodmail job exactly as §8's caveat anticipated. The `c.notifier` seam is Noticed-ready.
-> - Open question §12 (cardinality) resolved: per-pair-**per-subject** when `about:` is passed, plain per-pair otherwise — the host picks. CarHey threads per listing.
-
----
-
-## 1. Vision & positioning
-
-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 (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.
-
----
-
-## 2. Design principles
-
-1. **Hotwire-native, zero custom JS by default.** Turbo Streams for live message append/update/delete, Turbo Frames for lazy panes, Stimulus only for the few genuinely-interactive bits (composer autosize, typing throttle, scroll-to-bottom). No SPA, no build step (importmap-friendly).
-2. **Mountable engine, `isolate_namespace Chats`.** All models/controllers/tables namespaced (`Chats::Conversation`, `chats_messages`). Host route names stay the host's choice.
-3. **Polymorphic from day one.** A participant is not hard-typed to `User`. Any model that `acts_as_messager` can converse — `User`, `Organization`, a support `Agent`, a bot. This is the same inversion discipline the moderation gem uses (configurable class names + polymorphic targets).
-4. **Good defaults, easy override.** Ships working controllers + views; every view is overridable by copying into the host; every policy is a config hook.
-5. **Decoupled, adapter-driven ecosystem interop.** `chats` does not depend on CarHey. It depends on small, documented adapter interfaces for moderation, notifications, and auth — defaulting to no-ops so it runs standalone, and snapping onto `moderation`/`goodmail` when present.
-6. **Compliance by composition.** Messages are UGC. Rather than re-implement report/block/filter, `chats` content plugs into the `moderation` gem, so adding `chats` to a compliant app keeps it compliant (DSA + Apple 1.2 + Google Play) instead of reopening those gaps.
-7. **Delightful DX.** Consistent with the ecosystem: a `Chats.configure do |c| … end` block, `acts_as_*` macros, adapter objects, and an install generator — so `railsfast` + `goodmail` + `moderation` + `chats` feel like one coherent toolkit.
-
----
-
-## 3. Architecture & data model
-
-### Engine
-`Chats::Engine < ::Rails::Engine` with `isolate_namespace Chats`. Ships migrations, models, controllers, views, Stimulus controllers, Action Cable channels, and generators.
-
-### Core models (namespaced, UUID PKs to match the ecosystem)
-- **`Chats::Conversation`** — `kind` (`direct` | `group`), `title` (groups), `last_message_at` (denormalized for inbox ordering), optional polymorphic `subject` (so a conversation can be *about* a host record — a ride, an order, a listing — which is how CarHey attaches a chat to a trip).
-- **`Chats::Participant`** — polymorphic `messager` (`messager_type`/`messager_id`), `conversation_id`, `role` (`member` | `admin` | `owner` for groups), `last_read_at`, `muted_at`, `left_at`. Unique on `[conversation_id, messager_type, messager_id]`.
-- **`Chats::Message`** — `conversation_id`, polymorphic `sender` (the messager), `body` (text), `reply_to_id` (self-ref for threads/quotes), `edited_at`, `deleted_at` (soft delete / "deleted for everyone"), `metadata` jsonb. Has many attachments (ActiveStorage) and reactions.
-- **`Chats::MessageReceipt`** — per-recipient delivery/read state (`message_id`, `participant_id`, `delivered_at`, `read_at`). Powers read receipts + unread counts. (For large groups, receipts are opt-in / aggregated — see §6.)
-- **`Chats::Reaction`** — `message_id`, polymorphic `reactor`, `emoji`. Unique on `[message_id, reactor, emoji]`.
-- Attachments via **ActiveStorage** `has_many_attached :files` on `Message` (configurable: disabled, images-only, any).
-
-### Host integration: `acts_as_messager`
-```ruby
-class User < ApplicationRecord
-  acts_as_messager   # injects has_many :chat_participations, :chat_messages, helpers
-end
-```
-The macro is the single host contract on the actor side. A model can also `acts_as_chat_subject` if conversations attach to it (e.g. `Ride`).
-
-### Tables (sketch)
-`chats_conversations`, `chats_participants`, `chats_messages`, `chats_message_receipts`, `chats_reactions`. All UUID, all polymorphic where noted, indexed for the two hot queries: **a messager's inbox** (`participants` by messager + `conversations.last_message_at`) and **a conversation's message page** (`messages` by `conversation_id, created_at`).
-
----
-
-## 4. Real-time (Hotwire)
-
-- **Turbo Streams over Action Cable.** `Chats::Conversation` broadcasts `append`/`replace`/`remove` to a per-conversation stream; participants subscribe via `turbo_stream_from conversation`. New message → append to the thread + update each inbox row's preview/unread badge.
-- **`Chats::ConversationChannel`** (Action Cable) for presence + typing indicators (ephemeral, not persisted) and for authorizing the stream subscription (a non-participant must not subscribe).
-- **Stimulus** controllers (namespaced `chats--*`): `composer` (autosize, Enter-to-send, typing-throttle ping), `scroll` (stick-to-bottom, infinite-scroll older pages via Turbo Frame pagination), `receipts` (mark-read on viewport intersection).
-- **Read state**: when a participant views a conversation, mark messages read (debounced) → broadcast a lightweight receipt update so the sender sees "Seen".
-- Degrades gracefully: with cable down, it's still a working request/response inbox (Turbo Drive navigation); realtime is an enhancement, not a requirement.
-
----
-
-## 5. Generators & onboarding
-
-- `rails g chats:install` → writes `config/initializers/chats.rb`, copies migrations, mounts the engine (`mount Chats::Engine => "/chats"`), adds `acts_as_messager` guidance.
-- `rails chats:install:migrations` → idempotent migration copy.
-- `rails g chats:views [scope]` → eject overridable views into the host.
-- `rails g chats:stimulus` / component generator → eject the Stimulus controllers / view components for deep customization.
-
-One-command setup; explicit initializer; no magic.
-
----
-
-## 6. Configurable features
-
-`Chats.configure do |c| … end`:
-- `c.messager_class = "User"` (default) — the primary actor; polymorphic participants still allow others.
-- Feature flags (all default sensible): `c.groups = true`, `c.attachments = :images` (`false`/`:images`/`:any`), `c.reactions = true`, `c.read_receipts = true`, `c.typing_indicators = true`, `c.editing = true`, `c.deletion = :soft`, `c.search = true`, `c.threads = false`.
-- `c.messages_per_page = 30`, `c.max_message_length`, `c.max_group_size`.
-- `c.read_receipts_max_group_size` — disable per-recipient receipts above N (perf).
-- **Policies** (the authorization seam): `c.can_message = ->(from:, to:) { … }` (default: true unless blocked — see moderation), `c.can_create_group`, `c.can_join`. Defaults are permissive but trivially overridable; CarHey will scope DMs to a confirmed ride relationship initially.
-- **Adapters** (the ecosystem seam — §7/§8): `c.moderation`, `c.notifiers`, `c.authorizer`, `c.current_messager`.
-
----
-
-## 7. Moderation interop (the critical seam)
-
-`chats` content is UGC; it must be reportable, blockable, and filterable. Instead of re-implementing T&S, `chats` plugs into the **`moderation`** gem (the system CarHey is extracting from PR #28). The interop is via small, documented contracts so `chats` works standalone (no-op adapter) and lights up when `moderation` is present.
-
-### 7.1 Reportable messages & conversations
-`Chats::Message` (and `Chats::Conversation`) `include Moderation::Reportable` and implement the concern contract already proven in CarHey:
-```ruby
-class Chats::Message < ApplicationRecord
-  include Moderation::Reportable
-  reportable_fields :body
-  def reported_owner = sender
-  def moderation_label = "Message #{id}"
-  def moderation_snapshot_text(field) = body if field.to_s == "body"
-  def remove_reported_field!(field) = (update!(body: nil, deleted_at: Time.current); true) if field.to_s == "body"
-  def report_visible_to?(viewer, field:) = participant?(viewer)   # only people in the convo can report it
-  # moderation_subject_url / return_path / admin_path take a routes object (already the concern's shape)
-end
-```
-The host registers these in `Moderation.config.reportable_class_names`. **No CarHey coupling** — this is exactly the polymorphic adapter the moderation concern was designed for. A "Denunciar mensaje" affordance reuses moderation's `report_link` helper.
-
-### 7.2 Block enforcement (blocked users can't DM)
-`chats`' default `can_message` policy and inbox/visibility queries consult a **block adapter** that defaults to `Moderation::Block.user_ids_related_to(user)` (the bidirectional SSOT query). A blocked pair: cannot start a new conversation, cannot send into an existing one, and don't surface to each other. Wire-once: `c.moderation.blocked_ids_for = ->(user) { Moderation::Block.user_ids_related_to(user) }`. When `moderation` isn't installed, the default is "nobody blocked".
-
-### 7.3 Content filtering with configurable modes
-Filtering is configurable **per class/field** via a registry on the moderation gem (keyed by `"Class#field"`, ancestor-aware), with three modes:
-- **`:off`** — no check.
-- **`:block`** — reject at write time. Stays an ActiveModel **validator** (it legitimately stops the save).
-- **`:flag`** — the write **succeeds**, and a pending review item is created **out-of-band**.
-
-Wired once in `config/initializers/moderation.rb`:
-```ruby
-Moderation.configure do |c|
-  c.filter_policy "Chats::Message", :body, mode: :flag
-  c.filter_policy "Chats::Message", :files, mode: :flag, adapter: Chats::AttachmentReviewAdapter
-end
-```
-
-Two design rules are now proven in CarHey:
-1. **`:flag` does not live in a validator.** Validators remain side-effect-free. `:flag` runs from `Moderation::ContentFilterable` after commit, so system-generated review rows survive only after the host row exists and can be safely consumed by human/admin or ML workers.
-2. **The flag is a separate `Moderation::Flag` table, not `Moderation::Report`.** `Report` models a human notice/report with contact fields, message, good-faith confirmation, DSA taxonomy, decision, and appeal window. A system flag has no notifier. Current CarHey shape: polymorphic `flaggable`, optional `owner`, `field`, `source` (`text_filter`, `image_filter`, `external_classifier`, `manual`), `mode` (`flag`, `block`), `status` (`pending`, `actioned`, `dismissed`), `excerpt`, `categories`, `scores`, and `context`. A shared `pending` scope is the SSOT both a Madmin queue and future ML consumers read.
-
-**Adapter interface** (one method, score-carrying so a wordlist and an AI classifier are interchangeable):
-```ruby
-adapter.classify(value) # => { allowed:, categories:, scores:, source:, metadata: }
-```
-The moderation core wraps adapter hashes in `Moderation::FilterResult`. Built-in wordlist behavior is CarHey's `TextFilter` (NFKD normalization, leetspeak folding, spacing/accent resistance, Spanish/English YAML blocklist), score `1.0` per hit. Optional `:openai`/`:ruby_llm` adapters can return real `0..1` scores, and should run from a background job in `:flag` mode for expensive media/ML checks. Report intake only re-runs a block-mode adapter synchronously when the adapter explicitly exposes `synchronous? == true`; external/network adapters should leave that false and rely on `Moderation::Flag` evidence instead. The existing `moderate` gem remains a possible upstream home for this adapter interface, but not a hard dependency: today it is English-oriented and too narrow for CarHey/Spanish compliance needs.
-
-`chats` consumes all of this with the real **two-part** shape: on the model, `include Moderation::ContentFilterable` **+ `moderates_content :body`** (declares the scanned fields — drives the `validate` for `:block` and the `after_commit` for `:flag`); in the initializer, one `c.filter_policy "Chats::Message", :body, mode: :flag` line (sets the mode). A `filter_policy` line **without** `moderates_content` silently does nothing. Flagging is `Moderation::Flag.flag!` called from `ContentFilterable` (there is **no** `Moderation.flag` facade, and the standalone `ObjectionableContentValidator` is dead code — the concern owns `:block` too). For `:files` (attachments), override `moderation_field_value` / `moderation_field_changed_for_commit?` since the default `public_send(:files)` returns an ActiveStorage proxy, not classifiable content (mirror CarHey's host-supplied `ImageReviewAdapter`). The filter-mode + `Flag` machinery is a **moderation-gem change to land first** (independently useful for CarHey avatars today).
-
-### 7.4 Compliance inheritance
-Because messages flow through moderation, adding `chats` to a DSA/Apple/Google-compliant app **keeps it compliant only if the host enables the required policies**:
-- `Chats::Message` and `Chats::Conversation` are registered reportable classes.
-- Message body and attachment policies are configured (`:block`, `:flag`, or explicit `:off`).
-- Blocking is enforced before conversation creation and before every send.
-- Every message/conversation UI exposes report and block affordances.
-- Admins can see `Moderation::Report`, `Moderation::Flag`, and `Moderation::Appeal` queues.
-- Report decisions are delivered via moderation: the **DSA legal email** (receipt / decision / statement-of-reasons) goes through moderate's direct, synchronous goodmail seam (its boolean return gates the `*_notified_at` DSA timestamps — Noticed's fire-and-forget can't honor that), while **affected-user surfaces** (in-app feed + push) are layered via a host Noticed notifier. This is moderation's responsibility, not "the chats bus."
-
-This is a launch gate for the CarHey chats PR, not optional polish. A chat surface is high-velocity UGC; shipping it without these hooks would regress App Store Guideline 1.2, Google Play UGC, and DSA notice-and-action.
-
----
-
-## 8. Notifications: integrate with Noticed (the host's adopted orchestrator)
-
-**The host has chosen [Noticed](https://github.com/excid3/noticed) v3 as the notification orchestrator + in-app feed, and `action_push_native` for push** (see CarHey's `docs/notifications_architecture_prd.md`). `chats` does **not** build its own fan-out bus — Noticed already owns multi-subscriber fan-out, the per-recipient in-app feed (`Noticed::Notification` records), per-user preferences (`if/unless`), and the channel adapters (email/action_cable/action_push_native/custom). A second bus inside `chats` would double-wire goodmail and strand chats events away from push/feed/telegram. (Do **not** route chats through the `moderate` gem's `Moderation.notify` PORO either — that bus exists only to gate moderate's synchronous DSA legal email; it is not the cross-channel orchestrator.)
-
-The shape:
-- **`chats` is a Noticed event *source*.** On notification-worthy domain moments, `chats` fires a host **Noticed Notifier** through a single no-op-default `c.notifier` adapter proc. In CarHey that proc is `->(event, **p) { NewMessageNotifier.with(message: p[:message]).deliver }`. The gem takes **no hard dependency on Noticed** (the default proc is a no-op, so `chats` runs standalone).
-- **Recipients live in the host Notifier**, not in `chats`. `chats` passes the domain object (the message/conversation); the Notifier's `recipients -> { params[:message].conversation.participants.excluding(params[:message].sender) }` computes who gets it.
-- **The 5 channels are host-owned Noticed delivery methods**, wired once: in-app feed (Noticed core + a `TurboStream` delivery method for the live bell), the **chats DM surface** (a custom `DeliveryMethods::Chats`), **email via goodmail** (Noticed's built-in `:email` pointing at a normal `ApplicationMailer` that uses `goodmail_mail` — **goodmail needs zero changes**, and it is **not** `Goodmail::Base`), **push via `action_push_native`**, and **admin Telegram via `telegrama`** as a `bulk_deliver_by`.
-- **The in-app feed is Noticed's, not chats'.** `chats` owns only the chat/DM surface (channel 2). The bell/feed is `current_user.notifications` (`Noticed::Notification`).
-- **Debounced email is a Noticed config**, not a chats-owned digest job: `config.wait = 10.minutes` + `config.unless = -> { read? }` gives the classic "email only if still unread."
-
-> **Status caveat:** Noticed + `action_push_native` are **not yet installed** in CarHey. Until they are, the interim CarHey wiring may call goodmail directly. The *target* is the Noticed integration above; `chats`'s hooks are designed so that milestone wires Noticed **once** with no gem changes. Two push gotchas to honor when it lands (from the action_push_native source): the `:action_push_native` delivery method calls `with_apple`/`with_google`/`with_data` unconditionally — **all three must be set** (at least `-> { {} }`); and `before_enqueue` is a real Noticed v3 callback that may `throw(:abort)`, while `config.if`/`config.unless` remain the clearer preference gates.
-
-### 8.1 Chats domain moments → Noticed notifiers (not a private bus)
-
-These are the moments at which `chats` fires a host Notifier — they are **not** events on a chats-owned bus:
-
-| Domain moment | Host Notifier | Channels |
-|---|---|---|
-| message created | `NewMessageNotifier` | feed + chats DM + push + debounced email |
-| @mention | `MentionNotifier` (optional) | feed + push + email |
-| added to conversation | `ParticipantAddedNotifier` (optional) | feed + push |
-
-Non-notification domain changes (edited / deleted / reacted) need **no** notification framework — handle locally, or emit `ActiveSupport::Notifications` if instrumentation is wanted. **Do not emit a `message_flagged` event** — flagging is owned by `Moderation::Flag` / `ContentFilterable`; re-emitting it would double-count. Each Notifier's payload carries the domain object + actor + a stable idempotency key (Noticed `params` + dedup).
-
-### 8.2 `chats` is both a Noticed *source* and a Noticed *target*
-
-These are different directions and both are true (this resolves the ambiguity flagged in the host PRD §11):
-- **Source:** a user message fires `NewMessageNotifier` (above) → participants get bell + push + email.
-- **Target:** other notifiers post a *system* message **into** a conversation via the custom `DeliveryMethods::Chats`, calling a stable chats API — `Chats::Conversation#post_system_message!(body:)` (a `Chats::SystemSender` participant), e.g. "Your ride was cancelled" dropped into the ride's chat. The host delivery method must match chats' real signature — messages have a **conversation + participants**, not a per-message `recipient:`, so the illustrative `Chats::Message.create!(recipient:)` in the host PRD §5.5 is wrong; chats exposes `post_system_message!` instead.
-
----
-
-## 9. Security, privacy, performance
-
-- **Authorization everywhere**: channel subscriptions, message reads, and mutations all gate on participation + the `authorizer` adapter. A non-participant can't read or stream a conversation.
-- **Privacy**: soft-delete semantics ("delete for me" vs "delete for everyone"); optional message encryption-at-rest (ActiveRecord Encryption) behind a flag; PII-aware (don't leak presence to blocked users).
-- **Abuse/rate limits**: per-sender send rate limit (Rails 8 `rate_limit`); attachment type/size limits; optional attachment scanning hook.
-- **Compliance rate limits**: reporting/appeal forms use anti-abuse checks owned by moderation; message sends have separate high-throughput per-sender limits so attackers cannot create unlimited UGC before moderation catches up.
-- **Scale**: denormalized `last_message_at`, receipt opt-out for large groups, cursor pagination, `find_each`-friendly broadcasts, counter-cached unread.
-
----
-
-## 10. Cross-gem DX conventions (the ecosystem)
-
-To make this "the best Ruby gem ecosystem," `chats` follows and reinforces shared conventions with `railsfast`, `goodmail`, `moderation`, `organizations`, `pricing_plans`:
-- **One `X.configure do |c| … end` block per gem**, required keys validated at boot.
-- **`acts_as_*` host macros** for model integration (`acts_as_messager`, `acts_as_reportable`/`Moderation::Reportable`, etc.).
-- **Adapter objects + procs** for cross-gem seams (notifier, moderation, audit), defaulting to no-ops so each gem runs standalone.
-- **Configurable class-name strings + polymorphic targets** (never hard constants) so no gem depends on a host's `User`.
-- **Install generators** writing a templated initializer + idempotent migrations + engine mount.
-- **Goodmail for all transactional mail**; **moderation for all UGC T&S**; **a shared event/notifier contract** so notifications fan out uniformly.
-
-Target experience: `bundle add chats moderation goodmail`, run three installers, add `acts_as_messager` + `include Moderation::Reportable`, set a couple of adapter procs in initializers — and you have real-time DMs with reporting, blocking, filtering, email + push notifications, and DSA/store compliance, with every view overridable.
-
----
-
-## 11. Build plan
-
-**Phase 0 — in CarHey (validate the shape against a real app):**
-1. Replace the interim coordination model (the `Ride::JoinRequest#message` free-text + the `/messages` "Próximamente" placeholder) with real `Chats` conversations attached to a ride (`acts_as_chat_subject` on `Ride`).
-2. `Chats::Message include Moderation::Reportable`; register it in `Moderation.config.reportable_class_names`; reuse `report_link` + the block enforcement.
-3. Wire `Chats.config.notifier` → goodmail (`ChatsGoodmailer`) and `Chats.config.moderation` → the moderation adapters.
-4. Scope `can_message` to confirmed ride relationships (CarHey policy); prove the polymorphic/adapter seams under a real workload + tests.
-5. Launch gate: no chat PR merges unless report/block/filter/flag/appeal paths are green for `Chats::Message`, attachments, and conversations.
-
-**Phase 1 — extract to the gem:** `bundle gem chats` (engine), move the namespaced models/controllers/views/channels/generators, add `messager_class` string + `constantize`, ship default `en` locale + overridable views, write the install generator, and replace CarHey's direct usage with the gem.
-
-**Phase 2 — ecosystem polish:** extract the shared event dispatcher if moderation + chats both prove the same API; ship optional `goodmail`, `moderation`, `noticed`, and push adapters; document one canonical RailsFast setup.
-
----
-
-## 11.1 Acceptance criteria for CarHey v1
-
-- A driver/passenger with an accepted ride relationship can open a conversation from the ride screen.
-- New messages appear in real time through Turbo Streams and still work without WebSockets.
-- A participant can report a message, block the sender, and stop receiving future messages from that sender.
-- `Chats::Message#body` goes through moderation filter policy; attachments create `Moderation::Flag` rows in `:flag` mode.
-- Madmin shows reports, flags, and appeals for chat content without CarHey-specific case statements.
-- Goodmail sends a debounced unread-message digest through the shared notifier array.
-- Full CarHey test suite covers send/read/receipt/report/block/filter/appeal happy paths and authz negatives.
-
----
-
-## 12. Open questions
-- Conversation ↔ subject cardinality (one chat per ride? per pair-per-ride?).
-- Group membership model for very large groups (receipts, fan-out) — start capped.
-- E2E encryption: out of scope v1 (at-rest only); revisit.
-- Search backend: start with Postgres `ILIKE`/trigram; pluggable adapter for later.
-- Exact dependency direction: does `chats` depend on `moderation` directly, or only on a `moderation`-shaped adapter interface? → **adapter interface** (keeps `chats` usable without `moderation`), with a first-class `moderation` adapter shipped.
-
----
-
-## 13. Non-goals (v1)
-Bots/LLM agents, workspaces/tenancy, voice/video, message scheduling, public channels/communities, federation. Deferred, not designed against.