chats 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7e254b33cba3c656807db12e1ca491be50335584cd5824b32d7514ffcacc1bf
+  data.tar.gz: 227ad7e2280ad374bc9cb1bf48ff67d164a2ad0893e9be676dfc2a3af0bcfe67
+SHA512:
+  metadata.gz: feb3c7419b117cd252b35c4c3202ec1ab5dfb85aa3c9da26488d490102cabc33c177ea03d2cbad1251d1af29405e023718552f1a210fb8f69207e2657d8b940b
+  data.tar.gz: f68dc5a7814bbe56f8bad71e3495c5c1d4258fcc364e284fb118b9faee455124e041612eed1f4f38ed43a255513501430e0b5d6aa13646cc8e8438979598b4c7

data/.rubocop.yml

@@ -0,0 +1,43 @@
+# MERGE our excludes with rubocop's defaults (vendor/, node_modules/, …) —
+# a bare Exclude key would REPLACE them.
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 3.2
+  Exclude:
+    # The dummy host app mirrors GENERATED code (its chats migration is a
+    # copy of the install template, which emits Rails-omakase array spacing
+    # so installs are rubocop-clean in stock Rails apps) — don't lint it
+    # against the gem's own style.
+    - test/dummy/db/**/*
+    # Appraisal-generated Gemfiles.
+    - gemfiles/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Hard size metrics fight readable, well-commented domain code and thorough
+# test classes; we optimize for the latter.
+Metrics:
+  Enabled: false
+
+# `a` / `b` are the natural names for a symmetric pair of messagers
+# (direct_between!(a, b), blocked_between?(a, b)).
+Naming/MethodParameterName:
+  AllowedNames: [a, b, at, id, to]
+
+# The moderate-gem duck-typed contract fixes keyword names (field:) even
+# where an implementation doesn't use them — renaming to _field would change
+# the keyword and break the contract.
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - chats.gemspec # the long-form rubygems description is one line by design

data/.simplecov

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file (auto-loaded before test suite)
+# This keeps test_helper.rb clean and follows best practices.
+# Coherent with the rest of the gem ecosystem (moderate, usage_credits, pricing_plans, …).
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+
+  # Don't count the test suite itself toward coverage
+  add_filter "/test/"
+
+  # Don't count code that ISN'T unit-testable by this suite and would only
+  # distort the numbers:
+  #   - Generators + their templates: these run via `rails generate
+  #     chats:install` / `chats:views` in a real host. The generator classes ARE
+  #     exercised by Rails::Generators::TestCase, but the migration .erb itself
+  #     is never loaded as Ruby here (the dummy migrates a copy of it instead).
+  #   - version.rb: a single constant; nothing to cover.
+  add_filter "/lib/generators/"
+  add_filter "/lib/chats/version.rb"
+
+  # Track Ruby files in the lib directory (gem source code)
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Minimum coverage thresholds to prevent coverage REGRESSION. The primitives
+  # (models, concerns, configuration, the facade) are thoroughly covered by the
+  # unit suite; controllers and the broadcast paths are driven by the
+  # integration tests. The thresholds sit just under the current floor so the
+  # gate catches a real regression without failing on the existing baseline;
+  # raise them as coverage grows.
+  minimum_coverage line: 80, branch: 60
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV["TEST_ENV_NUMBER"]}" if ENV["TEST_ENV_NUMBER"]
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  puts "\n#{"=" * 60}"
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
+end

data/AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This file provides guidance to AI Agents (like OpenAI's Codex, Cursor Agent, Claude Code, etc) when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project, and `docs/PRD.md` for the original product requirements (note: the PRD predates the extraction of the `moderate` gem — where it says `Moderation::`, the real, current API is `Moderate::`; the README and the code are the source of truth).

data/Appraisals

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Test the minimum supported Rails version (matches the gemspec floor). The
+# adaptive migration template and the `rate_limit` guard (a Rails 8.0+ API,
+# feature-detected in Chats::MessagesController) must both work here.
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.0"
+end
+
+appraise "rails-7.2" do
+  gem "rails", "~> 7.2.0"
+end
+
+# Test the latest Rails version — this is the default/main Gemfile anyway.
+appraise "rails-8.1" do
+  gem "rails", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-06-10
+
+Reliability + UX patterns adopted after a deep review of Basecamp's
+open-source Campfire (https://github.com/basecamp/once-campfire) — see
+`docs/campfire_review.md` for the full adopt/skip ledger:
+
+### Added
+- **Telegram-style long-press message actions**: nothing actionable
+  renders inline on bubbles anymore. Long-press (or right-click) lifts a
+  clone of the bubble to the center over a blurred glass backdrop, with
+  the reactions pill above and the contextual menu below (Copy · Edit ·
+  Delete in red — plus whatever the host's ejected views inject, e.g. a
+  report link). Menu content ships per-bubble as an inert
+  `<template data-chats-message-menu>`; `data-chats-own-only` items are
+  stripped for foreign messages (cosmetic — the server still authorizes).
+- **Composer edit mode**: the long-press Edit closes the popup (the bubble
+  morphs back home) and loads the body into the composer under a
+  quote-style "Edit message" cue (left accent border, one-line trimmed
+  original, ✕ to cancel); the SAME form re-targets to the message's
+  update URL with `_method=patch`. The old in-bubble edit form (GET
+  `/messages/:id/edit`, `_edit_form`) is REMOVED — update failures now
+  render into the composer's error slot. New locale keys:
+  `chats.message.copy/.copied`, `chats.composer.editing/.cancel_edit`.
+- **Stale-thread catch-up**: `GET /:id/refresh?since=ms` appends messages
+  created — and replaces ones edited/tombstoned — while the client was
+  asleep; answers deep backlogs with a Turbo 8 page refresh instead of
+  splicing. The thread controller calls it when the tab wakes after 60s+
+  hidden and whenever the Turbo Stream subscription reconnects (observed
+  via turbo-rails' `connected` attribute on the stream source — no extra
+  Action Cable channel). Mobile WebViews suspend sockets aggressively;
+  without this a backgrounded chat silently loses messages.
+- **«New messages» divider**: thread open renders a separator before the
+  first unread bubble (computed before `read!` advances the horizon).
+  New locale key: `chats.thread.new_messages`.
+- **`:conversation_read` notifier event**: fired from `Participant#read!`
+  when the horizon actually consumes unread content (`conversation:`,
+  `participant:` payload) — lets hosts keep external notification
+  surfaces (bells, badges) truthful the moment a thread is read.
+- **DOM budget**: the thread caps rendered bubbles (~300) in long live
+  sessions, trimming oldest only while parked at the bottom and
+  re-planting the keyset pagination anchor so trimmed history stays
+  reachable on scroll-up.
+- **Chronology guard**: out-of-order broadcast appends (concurrent host
+  job workers) are re-slotted into timestamp order client-side.
+
+### Changed
+- The recommended `config.notifier` signature is `->(event, **payload)`;
+  events now carry different payloads (`:message_created` → `message:`,
+  `:conversation_read` → `conversation:, participant:`). Keyword-specific
+  lambdas keep working for `:message_created` but log a harmless,
+  error-isolated complaint on other events.
+
+## [0.1.0] - 2026-06-09
+
+Initial release. A drop-in, real-time messaging engine for Rails 7.1+ (built for the Rails 8 omakase):
+
+- Direct (1:1) and group conversations, polymorphic participants via `acts_as_messager`
+- Conversations attachable to any domain record via `acts_as_chat_subject` (`about:`)
+- Real-time everything over Turbo Streams + Action Cable: message append/edit/delete, Turbo 8 inbox refreshes, live unread badges, typing indicators (custom stream action), read receipts ("Seen")
+- Read state as a per-participant horizon (no per-message receipts table)
+- Race-safe direct-conversation identity (`direct_key` + `create_or_find_by!`)
+- Image/any attachments (ActiveStorage), emoji reactions, message editing, soft-delete tombstones, system messages (`post_system_message!`)
+- Inbox with search, previews, unread counts; keyset-paginated infinite scroll-up
+- Block enforcement seam (`blocked_messager_ids`) hardcoded beneath the `can_message` policy; full duck-typed reportable contract for the `moderate` gem
+- Notifier hook (`config.notifier`) + notification-etiquette helpers (`notifiable_for?`, `should_notify?`, `mark_notified!`)
+- Per-sender rate limiting (Rails 8 `rate_limit`, feature-detected), optional encryption at rest
+- Adaptive install generator (uuid/bigint primary keys; postgres/mysql/sqlite JSON handling), Devise-style views ejector
+- Two self-registering Stimulus controllers (importmap pins under `controllers/chats/*`), bundled CSS-variable-themed stylesheet, `en`/`es` locales

data/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+Please go ahead and read the full context for this project at `.cursor/rules/0-overview.mdc` and `.cursor/rules/1-quality.mdc` now. Also read the README for a good overview of the project, and `docs/PRD.md` for the original product requirements (note: the PRD predates the extraction of the `moderate` gem — where it says `Moderation::`, the real, current API is `Moderate::`; the README and the code are the source of truth).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Javi R
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,384 @@
+# 💬 `chats` - Add user-to-user DMs & group chats to your Rails app
+
+[![Gem Version](https://badge.fury.io/rb/chats.svg)](https://badge.fury.io/rb/chats) [![Build Status](https://github.com/rameerez/chats/workflows/Tests/badge.svg)](https://github.com/rameerez/chats/actions)
+
+> [!TIP]
+> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=chats)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=chats)!
+
+`chats` gives your Rails app **Instagram-class user-to-user messaging**: direct messages, group chats, image attachments, emoji reactions, read receipts, unread badges, and typing indicators — all real-time, all server-rendered.
+
+It's **Hotwire-native**: messages stream live over Turbo Streams + Action Cable, the inbox refreshes itself with Turbo 8 morphing, and the only JavaScript is two tiny Stimulus controllers the gem ships and registers for you. No SPA, no build step, no custom WebSocket code — and everything degrades gracefully to plain request/response when WebSockets are down.
+
+Every consumer app eventually needs DMs, and everyone rebuilds the same conversation/participant/message schema, the same Action Cable plumbing, and the same "report this message, block this user" story. `chats` is that whole rebuild, done once, done right.
+
+## 👨‍💻 Example
+
+`chats` reads like plain English:
+
+```ruby
+class User < ApplicationRecord
+  acts_as_messager
+end
+
+alice.message!(bob, "hola!")              # DM in one line
+alice.chat_with(bob)                       # ...or just open the conversation
+alice.chat_with(bob, carol, title: "Trip") # groups
+alice.unread_chats_count                   # for your nav badge
+```
+
+Conversations can be *about* things in your domain:
+
+```ruby
+class Ride < ApplicationRecord
+  acts_as_chat_subject
+end
+
+passenger.message!(driver, "Can I bring a suitcase?", about: ride)
+```
+
+That `about:` gives you marketplace-style threading for free: one conversation per pair *per ride* — and the ride shows up as a context line in the inbox and the thread header.
+
+## Quickstart
+
+Add the gem:
+
+```ruby
+gem "chats"
+```
+
+Install it (creates the migration + an initializer):
+
+```bash
+bundle install
+rails generate chats:install
+rails db:migrate
+```
+
+Make your users conversational and mount the inbox:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  acts_as_messager
+end
+
+# config/routes.rb
+mount Chats::Engine => "/messages"
+```
+
+That's it. `/messages` is now a working, real-time inbox: threads, bubbles, reactions, read receipts, typing indicators. The engine inherits your `ApplicationController` (so your auth, layout, and locale apply automatically — Devise works out of the box), and its two Stimulus controllers register themselves through your existing importmap setup. Zero JavaScript changes.
+
+Drop a "Message" button anywhere — it renders only when the viewer is allowed to message that person:
+
+```erb
+<%= chat_button_to @driver, about: @ride %>
+```
+
+And a live unread badge in your nav:
+
+```erb
+<%= chats_unread_badge %>
+```
+
+## What `chats` does (and doesn't) do
+
+**Does:** direct 1:1 threads, group conversations, image (or any) attachments via ActiveStorage, emoji reactions, read receipts ("Seen"), unread counts and live badges, typing indicators, message editing, soft deletion (WhatsApp-style tombstones), system messages your app posts into threads, per-sender rate limiting, inbox search, infinite scroll-up pagination, optional encryption at rest, and small adapter seams for moderation + notifications.
+
+**Doesn't:** chatbots/LLM agents, workspaces/tenancy, voice/video, public channels, federation. It's peer-to-peer (and group) human messaging — not a Slack clone, not a support-ticketing tool.
+
+## 🧱 The data model
+
+Five concepts, namespaced and polymorphic from day one (no hard `User` coupling anywhere):
+
+- **`Chats::Conversation`** — `direct` or `group`, optionally *about* a polymorphic `subject` (a ride, an order, a listing). Denormalized `last_message_at` / `last_message_id` / `messages_count` so the inbox is one indexed query.
+- **`Chats::Participant`** — a messager's seat in a conversation. Holds role, read horizon, mute, soft-leave, and notification bookkeeping.
+- **`Chats::Message`** — `text` (human) or `system` (posted by your app). Soft-deletes to a tombstone. Attachments via ActiveStorage.
+- **`Chats::Reaction`** — one row per (message, reactor, emoji); tap-to-toggle, race-safe.
+- **Any model with `acts_as_messager`** — users, organizations, support agents: participants and senders are polymorphic.
+
+Two deliberate design decisions worth knowing:
+
+1. **Read state is a horizon, not per-message receipts.** A participant has ONE `last_read_at`; a message is unread iff it's newer. That's unread counts, badges, and "Seen" indicators with zero extra writes per message (a receipts table writes N rows per message — the classic chat-schema scaling trap), and it's exactly how Basecamp's Campfire models it.
+2. **Direct conversations have a deterministic identity** (`direct_key`, unique-indexed): two people DMing each other in the same instant race into the SAME conversation, guaranteed by the database, not by hope.
+
+## ⚡ Real-time, the Hotwire way
+
+- **The thread** subscribes to one conversation stream. New messages append surgically; edits/deletes replace bubbles in place; the sender's own bubble comes straight back in the form response (no cable round-trip), and Turbo's same-id dedup makes the echo broadcast a no-op.
+- **Bubbles are broadcast viewer-agnostic** — one render shared by every subscriber. A tiny Stimulus controller aligns own-vs-other client-side by comparing sender keys. This is what makes single-render broadcasts possible at all.
+- **The inbox** receives Turbo 8 page *refreshes* (morphing, scroll-preserving) instead of surgically patched rows: inbox rows are intensely per-viewer (unread badges, bold states, ordering), so each client re-requests and gets a correct, personalized render. Refreshes are debounced and tagged so the tab that caused the change skips its own.
+- **Unread badges** get their own stream (`chats_unread_badge` helper) so any page can host a live badge without inheriting inbox refreshes.
+- **Typing indicators** are a Turbo Stream *custom action* — ephemeral, nothing persisted, no Action Cable channel class, no connection identification requirements.
+- **Cable down?** Everything still works request/response. Real-time is an enhancement, not a requirement.
+
+## 🛡️ Trust & Safety: snaps onto the [`moderate`](https://github.com/rameerez/moderate) gem
+
+Messages are user-generated content — App Store Guideline 1.2, Google Play's UGC policy, and the EU DSA all expect **report**, **block**, and **filter** capabilities before you ship a chat. Instead of re-implementing any of that, `chats` exposes the exact seams the `moderate` gem expects, with **no hard dependency in either direction**: each gem runs standalone, and together they behave like one system. This section is the complete recipe.
+
+### 1. One line of blocking
+
+```ruby
+# config/initializers/chats.rb
+Chats.configure do |config|
+  config.blocked_messager_ids = ->(user) { Moderate.blocked_ids_for(user) }
+end
+```
+
+That single hook makes moderate's bidirectional block table the law everywhere chats makes a decision:
+
+- a blocked pair **can't open** a conversation (`Chats::BlockedError`),
+- **can't send** into an existing one (a block placed mid-conversation stops the very next message),
+- and **stop seeing** each other's direct threads in the inbox and unread counts — *hidden, never deleted*: lift the block and the history reappears.
+
+Two semantics worth knowing: blocking is enforced **beneath** your `can_message` policy (a permissive or buggy policy can never let a blocked pair talk), and **group conversations are exempt from pair blocks** — the industry standard: blocking someone removes your private line, not your seat in shared spaces. If your domain should eject blocked members from groups, do it in moderate's `on_block` hook by tearing down whatever domain relationship feeds the group membership.
+
+### 2. Reportable + filtered messages
+
+```ruby
+# An after-boot hook (config.to_prepare) so the macros re-apply on every reload:
+Rails.application.config.to_prepare do
+  Chats::Message.has_reportable_content :body, :files
+  Chats::Message.moderates :body, mode: :flag    # text → built-in wordlist
+  Chats::Message.moderates :files, mode: :flag, with: :your_image_adapter
+end
+
+# config/initializers/moderate.rb — the central policy registry:
+config.filter "Chats::Message", :body, mode: :flag
+config.filter "Chats::Message", :files, mode: :flag, with: :your_image_adapter
+```
+
+Use **`:flag`, never `:block`** for chat: you don't gag someone mid-conversation on a wordlist false positive. The message sends; a pending `Moderate::Flag` lands in the moderation queue for human (or ML) review.
+
+`Chats::Message` and `Chats::Conversation` already implement moderate's full duck-typed reportable contract, so everything downstream just works:
+
+| moderate calls… | chats answers… |
+|---|---|
+| `reported_owner` | the sender (who a decision notifies, who a ban targets) |
+| `moderation_snapshot(:body)` | the body — frozen as evidence at report time, surviving later edits/deletes |
+| `remove_reported_field!(:body)` | the **soft-delete tombstone** — a moderator's removal looks exactly like a user deletion ("Message deleted"), no special admin rendering path |
+| `report_visible_to?(viewer)` | participants only (a DM isn't public content), and never the author |
+| `moderation_field_value(:files)` / change detection | attachment-aware seams so image filters classify what actually changed |
+
+### 3. The report affordance — mind the broadcast
+
+Put a report link on every bubble **someone else** sent. One nuance matters: `chats` renders each bubble **once per broadcast, viewer-agnostically** (that's what makes real-time fan-out cheap), so anything depending on `current_user` at render time — like moderate's `report_link` helper, which checks `report_visible_to?(viewer)` — would silently vanish from live-appended bubbles. Use the **signed-target URL** instead (viewer-independent), and hide it on own bubbles with the same client-side mechanism the gem uses for edit/delete:
+
+```erb
+<%# in your ejected chats/messages/_message.html.erb, inside the actions row %>
+<% if message.sender %>
+  <%= link_to "Report",
+        main_app.new_abuse_report_path(
+          target: message.to_sgid_param(for: Moderate::Report::SIGNED_GLOBAL_ID_PURPOSE),
+          field: "body"
+        ),
+        class: "chats-message__action in-own-hidden" %>
+        <%# hide on .chats-message--own via your CSS; moderate's controller
+            re-checks report_visible_to? server-side, so hiding is cosmetic %>
+<% end %>
+```
+
+And give direct threads a **block** action in the thread menu (your ejected `show.html.erb`) pointing at your moderate-backed blocks endpoint. One UX trap: blocking hides the very thread the user is standing in — redirect to the inbox, not back.
+
+### 4. The admin side
+
+Reported and auto-flagged chat messages flow into moderate's standard queues (`Moderate::Report` / `Moderate::Flag` are polymorphic) with **zero chat-specific case statements**: resolving a report with content removal calls `remove_reported_field!` → the tombstone; banning goes through your configured `ban_handler`. For browsing context, point your admin tool at `Chats::Conversation` / `Chats::Message` read-only — and if you want a "flag this while browsing" affordance, file a manual flag and jump to its queue page rather than growing enforcement buttons on the browse surface:
+
+```ruby
+Moderate::Flag.flag!(
+  flaggable: message, field: "body", owner: message.reported_owner,
+  source: "manual", mode: "flag",
+  excerpt: message.body.to_s.truncate(500),
+  categories: ["manual_review"], scores: {}, context: { flagged_by_admin_id: admin.id }
+)
+```
+
+### 5. Did you wire it all? The launch checklist
+
+- [ ] `blocked_messager_ids` → `Moderate.blocked_ids_for`
+- [ ] `Chats::Message` reportable (`:body`, and `:files` if attachments are on)
+- [ ] body + files filter policies in `:flag` mode
+- [ ] report link on foreign bubbles (signed target, broadcast-safe)
+- [ ] block action on direct threads (redirecting away from the hidden thread)
+- [ ] admin queue handles chat flags/reports (it does, automatically — verify with one test)
+- [ ] a test that a block placed mid-conversation stops the next send
+
+## 🔔 Notifications: one hook, fan out anywhere
+
+`chats` fires domain moments through a single no-op-default notifier — it does **not** build its own notification bus:
+
+```ruby
+config.notifier = ->(event, **payload) {
+  case event
+  when :message_created
+    # payload: message:
+    NewMessageNotifier.with(record: payload[:message]).deliver  # Noticed, email, push…
+  when :conversation_read
+    # payload: conversation:, participant: — fired when a read actually
+    # consumed unread content. Use it to keep EXTERNAL notification
+    # surfaces truthful: e.g. mark this chat's rows read in your
+    # notification center the moment the thread is read, so a bell badge
+    # doesn't keep advertising messages the user has already seen.
+  end
+}
+```
+
+> Write the lambda as `->(event, **payload)` (not `->(event, message:, **)`):
+> events carry different payloads, and a keyword the event doesn't include
+> would raise — harmlessly (the hook is error-isolated and logged), but
+> noisily.
+
+The etiquette helpers every messaging product needs ship on the participant, so a debounced "email me only once until I come back" digest is a tiny host job:
+
+```ruby
+class ChatsUnreadEmailJob < ApplicationJob
+  def perform(message)
+    message.conversation.participants.active.each do |participant|
+      next unless participant.notifiable_for?(message) # not the sender, not muted, not departed
+      next unless participant.should_notify?           # unread + not already notified this burst
+
+      ChatsMailer.with(participant: participant).unread_messages.deliver_now
+      participant.mark_notified!
+    end
+  end
+end
+
+config.notifier = ->(event, message:, **) {
+  ChatsUnreadEmailJob.set(wait: 10.minutes).perform_later(message) if event == :message_created
+}
+```
+
+And it works in the other direction too — your app can post **into** conversations:
+
+```ruby
+ride.chat_conversations.find_each { |c| c.post_system_message!("Your ride was cancelled") }
+```
+
+## 🎨 Make it yours
+
+The bundled UI is intentionally framework-free (semantic `chats-*` classes + one self-contained stylesheet, themed with CSS variables):
+
+```css
+:root {
+  --chats-accent: #facc15;           /* own bubbles, send button, badges */
+  --chats-accent-contrast: #111827;
+}
+```
+
+Want full control? Eject the views Devise-style and restyle with your own stack (Tailwind classes added there get picked up by your build, since the files live in your `app/views`):
+
+```bash
+rails generate chats:views
+```
+
+Override the two Stimulus controllers by pinning the same importmap keys (`controllers/chats/thread_controller`, `controllers/chats/composer_controller`) — host pins win.
+
+## Configuration reference
+
+Everything lives in `config/initializers/chats.rb` (the install generator writes a fully-annotated version):
+
+```ruby
+Chats.configure do |config|
+  config.messager_class = "User"
+
+  # Controller integration (Devise-compatible defaults)
+  config.parent_controller = "::ApplicationController"
+  config.current_messager_method = :current_user
+  config.authenticate_method = :authenticate_user!
+  config.layout = nil                       # nil inherits the parent controller's
+
+  # Features — all on by default
+  config.groups = true
+  config.reactions = true
+  config.read_receipts = true
+  config.typing_indicators = true
+  config.editing = true
+  config.deletion = :soft                   # :soft (tombstone) | :hard | false
+  config.attachments = :images              # false | :images | :any
+  config.search = true
+
+  # Limits
+  config.messages_per_page = 30
+  config.max_message_length = 5_000
+  config.max_group_size = 32
+  config.max_attachment_size = 10.megabytes
+  config.max_attachments_per_message = 4
+  config.send_rate_limit = { to: 60, within: 1.minute }  # Rails 8 rate_limit; nil disables
+  config.encrypt_messages = false           # ActiveRecord Encryption on bodies
+
+  # Policies (on top of — never instead of — block enforcement)
+  config.can_message = ->(sender, recipient) { true }
+  config.can_create_group = ->(creator) { true }
+
+  # Ecosystem seams (no-op defaults; chats runs standalone)
+  config.blocked_messager_ids = ->(messager) { [] }
+  config.notifier = ->(event, **payload) {}
+
+  # Display (used by the bundled views)
+  config.messager_display_name = ->(messager) { messager.display_name }
+  config.messager_avatar = ->(messager) { messager.avatar }  # URL/attachment/variant or nil
+end
+```
+
+## 🤓 The full Ruby API
+
+```ruby
+# Messagers
+alice.chat_with(bob)                          # find-or-create the DM
+alice.chat_with(bob, about: ride)             # the DM about that ride
+alice.chat_with(bob, carol, title: "Trip")    # a group (alice is owner)
+alice.message!(bob, "hi", about: ride)        # send (resolves the thread)
+alice.message!(conversation, "hi", files: []) # send into a conversation
+alice.chats                                   # inbox relation, newest first
+alice.unread_chats_count                      # conversations with unread messages
+
+# Conversations
+conversation.participant?(user)               # active membership
+conversation.other_participants(user)
+conversation.title_for(viewer)                # counterpart name / group title
+conversation.subject_label                    # "Madrid → Barcelona"
+conversation.unread_count_for(user)
+conversation.mark_read_by!(user)
+conversation.post_system_message!("Ride cancelled")
+conversation.add_participant!(user)           # idempotent, race-safe
+
+# Messages
+message.edit!("fixed")                        # stamps edited_at
+message.soft_delete!                          # tombstone (or destroy, per config)
+message.read_by?(user)
+Chats::Reaction.toggle!(message:, reactor:, emoji: "👍")
+
+# Participants (the per-member state)
+participant.read!                             # advance the read horizon
+participant.mute! / participant.unmute!
+participant.leave!                            # groups
+participant.notifiable_for?(message)          # notification etiquette
+participant.should_notify? / participant.mark_notified!
+```
+
+Errors are namespaced and meaningful: `Chats::BlockedError`, `Chats::NotAllowedError`, `Chats::ConfigurationError` — all under `Chats::Error`.
+
+## Database support
+
+PostgreSQL, MySQL, and SQLite. The migration adapts automatically: it honors your app's configured primary key type (**uuid or bigint** — same detection `rails g model` uses), picks `jsonb` on Postgres / `json` elsewhere, and handles MySQL's no-defaults-on-JSON rule. Works on Rails 7.1+ and shines on the Rails 8 omakase.
+
+## Testing
+
+The gem is tested with Minitest against a real dummy host app — models, broadcasts (over the Action Cable test adapter), full request cycles, generators, and every authorization negative (outsiders, leavers, and blocked pairs all get plain 404s; existence never leaks).
+
+```bash
+bundle exec rake test            # full suite
+bundle exec appraisal install    # then test across Rails versions:
+bundle exec appraisal rails-7.1 rake test
+bundle exec appraisal rails-8.1 rake test
+```
+
+## Development
+
+After checking out the repo, run `bundle install`, then `bundle exec rake test`. The dummy app lives in `test/dummy` and mounts the engine at `/messages` exactly like a real host.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/chats. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "bundler/gem_tasks"
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "Chats"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test