chats 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7e254b33cba3c656807db12e1ca491be50335584cd5824b32d7514ffcacc1bf
-  data.tar.gz: 227ad7e2280ad374bc9cb1bf48ff67d164a2ad0893e9be676dfc2a3af0bcfe67
+  metadata.gz: c51ebc5c0e2da96363bb5b2e85d9a9c2a91e41f7ddb9d351ff10001654a48325
+  data.tar.gz: a06cde14d3953972e7061b2950b7a52c696f4292e25a2a91c9c7bb6ce7d269cb
 SHA512:
-  metadata.gz: feb3c7419b117cd252b35c4c3202ec1ab5dfb85aa3c9da26488d490102cabc33c177ea03d2cbad1251d1af29405e023718552f1a210fb8f69207e2657d8b940b
-  data.tar.gz: f68dc5a7814bbe56f8bad71e3495c5c1d4258fcc364e284fb118b9faee455124e041612eed1f4f38ed43a255513501430e0b5d6aa13646cc8e8438979598b4c7
+  metadata.gz: 5d23c31395edb382ec05fc6b7478a4e219b1878dc29f67092451101ef720bf2df556ae92976384665c0e108ca4607557ed9d1badf0af9357143182f1fdb57e6d
+  data.tar.gz: 3f02985c90410059af142a03fc3a3298540f71fb05d9b46991f39ea22999bfab64738f86beb92db7355e98c68e7962c2b6e79925335cf409d67842c1b1a7a5eb

data/CHANGELOG.md

@@ -4,6 +4,172 @@ 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.2.0] - 2026-09-16
+
+The release that makes `chats` a foundation other products can be built on:
+a messager that isn't a person, a conversation whose openness belongs to its
+subject, a message someone wrote on someone else's behalf, and extension
+points that don't require ejecting a screen. **Nothing here changes existing
+behaviour until you set an option** — 0.1.1 installs upgrade by running
+`rails generate chats:upgrade && rails db:migrate`.
+
+### Added
+- **Headless messagers.** `acts_as_messager notifications: false, blockable:
+  false, inbox: :grouped` — a support desk, a bot, an org mailbox. Class
+  predicates (`chat_notifications?`, `chat_blockable?`, `chat_inbox_mode`,
+  `chat_group_path`) are read duck-typed everywhere, `Participant#
+  notifiable_for?` honours them, and the bundled views hide block/report
+  affordances against a non-blockable counterpart. Hosts stop writing
+  `is_a?(User)` in every notifier and view.
+- **Subject-owned locks.** `Chats::ChatSubject#chat_locked?` /
+  `#chat_locked_notice` (both inert by default) decide whether a conversation
+  still accepts messages; `Conversation#locked?` / `#locked_notice` read
+  them, and `Chats::Message` refuses non-system writes with an `:locked`
+  error, and every OTHER write refuses too — `Message#edit!`,
+  `#soft_delete!` and `Reaction.toggle!` raise `Chats::LockedError` (a
+  `NotAllowedError` subclass), and the edit/delete/react endpoints answer 422
+  with the notice. The bundled bubble stops offering what would only fail:
+  no Edit, no Delete, no reaction toggles, while existing reactions still
+  render as plain counts and Copy still works. Moderation is the one
+  exception — `remove_reported_field!` removes reported content from a locked
+  conversation, because a product lock must never shield it. The thread stays
+  readable: the composer is replaced by the notice
+  (`chats/conversations/_locked_composer`, overridable through the
+  `locked_composer` slot), and a send that lands on a freshly locked
+  conversation gets a **422 that swaps the composer** instead of an
+  exception. System messages are exempt, so your app can always explain the
+  lock in the thread it just closed.
+- **Message authorship.** `chats_messages.author_type/author_id` (nullable,
+  polymorphic, indexed) plus `Message#author`, `#signed?`, `#authored_by?`
+  and `Messager#message!(…, author:)`. `sender` stays the seat; `author` is
+  who wrote it. Signed bubbles render a signature line ("— Lucía G."),
+  rewritable with `config.message_signature`. New generator: **`rails
+  generate chats:upgrade`** writes the migration (guarded, so it is a no-op
+  on a fresh 0.2.0 install, which already has the columns).
+- **Grouped inbox rows.** `Chats::Inbox.for(viewer)` returns
+  `Chats::Conversation | Chats::InboxGroup` rows sorted by activity; every
+  direct thread with an `inbox: :grouped` counterpart folds into one stack
+  (`#messager`, `#conversations`, `#unread_count`, `#last_message`,
+  `#last_message_at`, `#open_count`). A stack of one links straight to its
+  thread, which gains a "see all" link back; a deeper stack opens
+  `GET /conversations?with=<signed gid>` (purpose `:chats_inbox_with`, minted
+  by `Chats.inbox_with_sgid`) or wherever `group_path:` points. Grouping
+  happens in ONE place. `config.inbox_limit` bounds ROWS, not
+  conversations: stacked threads are queried separately from ordinary ones,
+  so a desk with hundreds of open threads can never evict the rest of the
+  inbox, and a stack's `open_count`/`unread_count` are GLOBAL — two indexed
+  aggregates per stack, never per conversation and never by loading the
+  stack to count it. `Chats::Inbox#unread_count` is the stack-aware badge number;
+  `unread_chats_count` is unchanged.
+- **`config.inbox_limit`** (200, replacing a literal in the controller) and
+  **`config.inbox_scope`** `->(relation, viewer) { relation }`, composed into
+  the inbox query before the limit.
+- **View slots.** The bundled views render `chats/slots/_inbox_top`,
+  `_inbox_empty`, `_conversation_header_actions`, `_locked_composer` and
+  `_message_meta` when such a partial exists — one memoized lookup when it
+  doesn't. Hosts (and engines mounted on top of chats) add a row or a button
+  without ejecting a screen.
+- **Subscribers.** `Chats.on(:message_created | :conversation_created |
+  :participant_left | :conversation_read)` replaces the single notifier
+  proc: many subscribers per event, each isolated through
+  `Rails.error.report(e, handled: true, context: { event: })` so a failing
+  one is *visible* and never stops the others or the write that emitted
+  them. Registration is reload-safe (`key:` replaces in place;
+  `Chats.reset_subscribers!` clears). Two NEW events:
+  `:conversation_created` (once per conversation, never on resume) and
+  `:participant_left`.
+- **`config.messager_url`** `->(messager) { nil }` — the bundled views link
+  names and titles to it, and render plain text when it returns nil. The gem
+  no longer assumes a host has `user_path`.
+- **`Participant#reseat!(new_messager)`** — hand a seat to another messager
+  inside a transaction, keeping the read horizon, the role and the history,
+  and re-indexing a direct thread's `direct_key` so `chat_with` keeps
+  resolving to it instead of stranding a duplicate. Refuses with
+  `Chats::NotAllowedError` when the resulting pair already has a direct
+  conversation, checked BEFORE the write so a unique-index violation can
+  never poison a host's transaction.
+- **Inbox missed-broadcast recovery** (`chats--refresh-inbox` controller): the
+  inbox already receives Turbo 8 page *refreshes*, but Action Cable has no
+  replay — a refresh broadcast sent while the client's socket was down
+  (backgrounded tab/app, network blip) was lost and the inbox sat stale until
+  the user navigated. The new controller re-runs the same page refresh on
+  cable reconnect and on return-to-visible, extending the thread's
+  stale-catch-up doctrine (`docs/campfire_review.md`) to the inbox. It reuses
+  the thread's channel-free reconnect detection (observing the
+  `<turbo-cable-stream-source>` `connected` attribute), so no new Action Cable
+  channel is introduced. Auto-registered via the engine importmap pin; hosts
+  need zero changes.
+
+### Changed
+- `config.notifier` is **deprecated** (removed in 1.0). It still works and
+  receives `:message_created` and `:conversation_read` — the two events 0.1.1
+  had — and ONLY those: the events added in 0.2.0 are `Chats.on`-only, so a
+  0.1.x hook written `->(event, message:, **)` can never be handed an event
+  it has no keyword for. It registers as a subscriber under a reserved key,
+  so re-assigning it replaces rather than stacks, and warns through
+  `Chats.deprecator`, which the engine registers with
+  `Rails.application.deprecators`.
+  **If your test environment sets `config.active_support.deprecation =
+  :raise`** (a common default) and you still assign `config.notifier`, that
+  warning now raises at boot, because the engine registers the gem's
+  deprecator with the app. Either move the hook to `Chats.on` — the migration
+  is one line — or silence just this one:
+
+  ```ruby
+  # config/initializers/chats.rb
+  Chats.deprecator.silence do
+    Chats.configure { |config| config.notifier = ->(event, **payload) { … } }
+  end
+  ```
+- The install migration now creates the `author` columns, so a fresh install
+  needs no upgrade step.
+- **If you ejected the inbox or the composer under 0.1.x**, nothing breaks:
+  `ConversationsController#index` still assigns `@conversations` (the flat,
+  unstacked list an ejected inbox loops over), and an ejected composer simply
+  misses the DOM id the locked-composer swap targets — the 422 is then a
+  no-op instead of a replace. Re-eject (or delete) those two files to pick up
+  stacked rows and locked composers.
+
+### Fixed
+- **A host's own locale file no longer loses to the gem's.** The engine
+  appended its `config/locales` onto the application's `i18n.load_path` on
+  top of Rails' own `:add_locales`. Railtie paths are unshifted ahead of
+  everything, so that second copy landed *after* the host's files and
+  silently overrode them — a host rewording `chats.flashes.blocked` in its
+  own `es.yml` kept reading ours, with no error to see. Gem first, host last,
+  pinned by a test that ships a host override in the dummy app.
+- **Migrations name every adapter they actually run on.** `json_column_type`
+  matched `"postgresql"`, which activerecord-postgis-adapter never reports
+  (it answers `"PostGIS"`), so PostGIS hosts silently got `json` where the
+  gem meant `jsonb`. `json_column_default` matched `/mysql/`, which misses
+  Trilogy (Rails reports `"Trilogy"`), handing those hosts a default MySQL
+  rejects. Both now match by prefix and by both spellings.
+- **The thread's missed-broadcast recovery never took effect for a deep
+  backlog.** `ConversationsController#refresh` answered with `render html:
+  … content_type: "text/vnd.turbo-stream.html"`, and `render html:` forces
+  `text/html` and ignores the content type — so the response said
+  `<turbo-stream action="refresh">` in a body nothing would treat as a
+  stream. It now renders `turbo_stream.refresh(request_id: nil)`; the nil
+  request id matters, because Turbo skips a refresh tagged with a request id
+  it recognizes as its own, and this response answers the client's own
+  catch-up fetch. The failure was invisible by construction: a recovery path
+  that does nothing looks exactly like the staleness it exists to fix.
+- `:participant_added` was documented as a notifier event but never emitted.
+  The event catalogue is now exactly what the gem fires, and registering for
+  anything else raises at boot with the valid list.
+- **A signed message is its author's to answer for.** `Message#reported_owner`
+  now returns `author || sender`. With authorship, an answer sent from a
+  headless seat (a support desk) carries a human author, and a host's
+  moderation `owner` is typed to its user class — a desk there raised an
+  association type mismatch from inside the agent's own reply the first time
+  a text filter tripped, and the moderation screens then asked the desk for
+  an avatar it does not have.
+- **`jsonb` on PostGIS.** The install migration decided jsonb-or-json with
+  `adapter_name.downcase.include?("postgresql")`, and activerecord-postgis-
+  adapter answers `"PostGIS"`, so PostGIS hosts silently got plain `json`
+  columns. The template now matches the prefix (`/\Apostg/i`). Existing
+  installs are unaffected; a host that wants jsonb can `change_column` it.
+
 ## [0.1.1] - 2026-06-10
 
 Reliability + UX patterns adopted after a deep review of Basecamp's

data/README.md

@@ -7,7 +7,7 @@
 
 `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.
+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 a few 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. Both the thread and the inbox self-heal after a missed broadcast (cable reconnect / return-to-visible), so a client that slept through a WebSocket drop still catches up.
 
 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.
 
@@ -66,7 +66,7 @@ end
 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.
+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 bundled 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:
 
@@ -86,6 +86,9 @@ And a live unread badge in your nav:
 
 **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.
 
+> [!NOTE]
+> **Want customer support?** Ticketing stays out of `chats` on purpose — queues, assignment and SLAs are not messaging. [`support_desk`](https://github.com/rameerez/support_desk) is the product gem that adds them ON TOP of this one: tickets that are real conversations, a support desk that sends while your staff sign, and a BYOUI agent console. It uses the seams below (headless messagers, subject locks, message authorship, grouped inbox rows), so you get the same threads, attachments and read state you already have.
+
 ## 🧱 The data model
 
 Five concepts, namespaced and polymorphic from day one (no hard `User` coupling anywhere):
@@ -94,7 +97,7 @@ Five concepts, namespaced and polymorphic from day one (no hard `User` coupling
 - **`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.
+- **Any model with `acts_as_messager`** — users, organizations, support desks, bots: participants and senders are polymorphic. A messager that is not a person declares it (`notifications: false, blockable: false, inbox: :grouped`) and the gem stops treating it like one. See [`support_desk`](https://github.com/rameerez/support_desk) for the worked example.
 
 Two deliberate design decisions worth knowing:
 
@@ -201,30 +204,32 @@ Moderate::Flag.flag!(
 - [ ] 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
+## 🔔 Events: subscribe to the domain moments
 
-`chats` fires domain moments through a single no-op-default notifier — it does **not** build its own notification bus:
+`chats` fires domain moments at subscribers — 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
-}
+# config/initializers/chats.rb (or anywhere that runs at boot)
+Chats.on(:message_created)      { |message| NewMessageNotifier.with(record: message).deliver }
+Chats.on(:conversation_created) { |conversation| Analytics.track("chat_started", conversation) }
+Chats.on(:participant_left)     { |participant| AuditLog.log("chat_left", participant) }
+Chats.on(:conversation_read)    { |conversation:, participant:| Bell.mark_read(participant.messager, conversation) }
 ```
 
-> 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.
+Four properties, all of which matter the first time something goes wrong at 3am:
+
+- **Many subscribers per event.** Your mailer, your analytics and your audit log don't have to share one `case` statement.
+- **Each one is isolated.** A raising subscriber is reported through `Rails.error.report(e, handled: true, context: { event: })` — *visible*, not swallowed — and the next subscriber still runs. The message is already committed; notifications are best-effort fan-out.
+- **Reload-safe.** Registering from reloadable code? Pass a key and a reload replaces the subscriber instead of stacking a second one:
+
+  ```ruby
+  Rails.application.config.to_prepare do
+    Chats.on(:message_created, key: :unread_email) { |message| … }
+  end
+  ```
+- **Unknown events fail loudly**, at boot, naming the ones that exist.
+
+> **Deprecated:** `config.notifier = ->(event, **payload) {}` still works and will be removed in 1.0. It receives `:message_created` and `:conversation_read` — the two events that existed in 0.1.1 — and *only* those, so an old `->(event, message:, **)` hook can never start raising on an event it was never written for. The events added in 0.2.0 are `Chats.on`-only. Move it to `Chats.on` — that's the whole migration.
 
 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:
 
@@ -232,7 +237,7 @@ The etiquette helpers every messaging product needs ship on the participant, so
 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.notifiable_for?(message) # not the sender, not muted, not departed, not headless
       next unless participant.should_notify?           # unread + not already notified this burst
 
       ChatsMailer.with(participant: participant).unread_messages.deliver_now
@@ -241,9 +246,7 @@ class ChatsUnreadEmailJob < ApplicationJob
   end
 end
 
-config.notifier = ->(event, message:, **) {
-  ChatsUnreadEmailJob.set(wait: 10.minutes).perform_later(message) if event == :message_created
-}
+Chats.on(:message_created) { |message| ChatsUnreadEmailJob.set(wait: 10.minutes).perform_later(message) }
 ```
 
 And it works in the other direction too — your app can post **into** conversations:
@@ -252,6 +255,111 @@ And it works in the other direction too — your app can post **into** conversat
 ride.chat_conversations.find_each { |c| c.post_system_message!("Your ride was cancelled") }
 ```
 
+## 🤖 Headless messagers: desks, bots, storefronts
+
+Not every messager is a person. A support desk, an order bot or an organization mailbox converses like anyone else but must never be notified, can't meaningfully be blocked, and shouldn't fill the inbox with one row per thread. Say so once, on the model:
+
+```ruby
+class SupportDesk < ApplicationRecord
+  acts_as_messager notifications: false,   # Participant#notifiable_for? says no, always
+                   blockable:     false,   # the views hide block/report affordances
+                   inbox:         :grouped # every thread with it is ONE inbox row
+end
+```
+
+That's the whole point of the option: **your notifiers and views stop asking `is_a?(User)`**. The predicates are on the class (`SupportDesk.chat_notifications?`, `.chat_blockable?`, `.chat_inbox_mode`) and duck-typed everywhere the gem reads them, so an ordinary `acts_as_messager` model behaves exactly as it always did.
+
+## 🗂️ Grouped inbox rows
+
+With `inbox: :grouped`, every direct conversation a viewer has with that messager folds into a single inbox row — a stack:
+
+```ruby
+inbox = Chats::Inbox.for(current_user)   # [Chats::Conversation | Chats::InboxGroup], newest activity first
+inbox.unread_count                       # the stack-aware badge number
+
+group = inbox.rows.first
+group.messager       # the desk
+group.conversations  # the stacked threads, freshest first
+group.unread_count   # aggregated across the stack
+group.open_count     # how many are in it
+```
+
+- `config.inbox_limit` bounds **rows**, not conversations: stacked threads are queried separately from ordinary ones, so a desk with 500 open tickets can never evict your friends from the inbox. A stack's `open_count` and `unread_count` are **global** — two indexed aggregates per stack, however deep it runs — so stacking neither goes N+1 nor loads a stack to count it.
+- A stack of one links **straight to the thread**, which then carries a small "see all" link back to the stack.
+- The stack list is chats' own filtered inbox — `GET /conversations?with=<signed gid>` — unless you point it somewhere else with `group_path: ->(viewer) { support_path }`.
+- Two knobs shape the whole query: `config.inbox_limit` (200) and `config.inbox_scope = ->(relation, viewer) { relation }`.
+
+`user.unread_chats_count` is unchanged (it counts conversations); `Chats::Inbox#unread_count` is the stack-aware number for badges.
+
+## 🔒 Locked conversations
+
+Whether a conversation still takes messages belongs to the thing it's **about** — a closed ticket, a delivered order, an archived listing. The subject already owns the conversation's meaning; it owns its openness too:
+
+```ruby
+class Ticket < ApplicationRecord
+  acts_as_chat_subject
+
+  def chat_locked?       = closed?
+  def chat_locked_notice = "This ticket is closed. Reply to reopen it."
+end
+```
+
+- `Chats::Message` refuses new messages with an `:locked` error; `Conversation#locked?` and `#locked_notice` read the subject.
+- **System messages are exempt**: your app can always post "This ticket was closed" into the thread it just closed.
+- The thread **stays readable**. Only the composer changes: it's replaced by the notice (the `locked_composer` slot overrides the body). Gate the action, never hide the explanation.
+- A send that lands on a conversation locked since the page loaded gets a **422 that swaps the composer for the notice** — no raise, no lying screen.
+
+## ✍️ Signed messages
+
+`sender` is the seat a message came from; `author` is who **wrote** it on that seat's behalf. That's how a shared desk answers as itself while the human stays visible:
+
+```ruby
+desk.message!(alice, "On it!", author: lucia)   # sender: the desk, author: Lucía
+message.signed?          # true — author present and not the sender
+message.authored_by?(lucia)
+```
+
+The bundled bubble renders a signature line ("— Lucía G.") via `Chats.display_name_for`; `config.message_signature = ->(message) { … }` rewrites it. Ordinary messages have no author and render exactly as before.
+
+Existing installs get the columns with one command:
+
+```bash
+rails generate chats:upgrade && rails db:migrate
+```
+
+## 🔌 View slots
+
+Ejecting a whole screen to add one row or one button is too coarse. The bundled views render a partial named `chats/slots/_<slot>` **when it exists** — no configuration, no registration, and an absent slot costs one memoized lookup:
+
+| slot | where it renders |
+|---|---|
+| `inbox_top` | above the first inbox row |
+| `inbox_empty` | inside the empty state |
+| `conversation_header_actions` | the thread's menu (gets `blockable:`) |
+| `locked_composer` | the locked composer's body |
+| `message_meta` | after each bubble's timestamp |
+
+```erb
+<%# app/views/chats/slots/_inbox_top.html.erb %>
+<%= link_to "Need help? Write to us", support_path, class: "support-door" %>
+```
+
+An engine mounted on top of chats ships its own `app/views/chats/slots/…`; the host's file wins by view-path order. `rails generate chats:views` is still there for wholesale restyling.
+
+## 🔗 Profile links
+
+`chats` never assumes your app has a `user_path`. Tell it where a messager lives and names become links; leave it alone and they render as plain text:
+
+```ruby
+config.messager_url = lambda do |messager|
+  routes = Rails.application.routes.url_helpers
+
+  case messager
+  when User then routes.user_path(messager)   # a desk or a bot has no profile: nil
+  end
+end
+```
+
 ## 🎨 Make it yours
 
 The bundled UI is intentionally framework-free (semantic `chats-*` classes + one self-contained stylesheet, themed with CSS variables):
@@ -269,7 +377,7 @@ Want full control? Eject the views Devise-style and restyle with your own stack
 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.
+Override any bundled Stimulus controller by pinning the same importmap key — host pins win. The current keys are `controllers/chats/thread_controller`, `controllers/chats/composer_controller`, `controllers/chats/debounced_submit_controller`, and `controllers/chats/refresh_inbox_controller`.
 
 ## Configuration reference
 
@@ -308,13 +416,19 @@ Chats.configure do |config|
   config.can_message = ->(sender, recipient) { true }
   config.can_create_group = ->(creator) { true }
 
+  # Inbox shaping
+  config.inbox_limit = 200
+  config.inbox_scope = ->(relation, viewer) { relation }
+
   # Ecosystem seams (no-op defaults; chats runs standalone)
   config.blocked_messager_ids = ->(messager) { [] }
-  config.notifier = ->(event, **payload) {}
+  config.notifier = ->(event, **payload) {}   # DEPRECATED — use Chats.on
 
   # 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
+  config.messager_url = ->(messager) { nil }                 # nil ⇒ names render as plain text
+  config.message_signature = nil                             # ->(message) { } for signed bubbles
 end
 ```
 
@@ -329,6 +443,8 @@ 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
+alice.message!(bob, "hi", author: lucia)      # written by lucia, sent from alice's seat
+Chats::Inbox.for(alice)                       # [Conversation | InboxGroup] + #unread_count
 
 # Conversations
 conversation.participant?(user)               # active membership
@@ -339,11 +455,14 @@ conversation.unread_count_for(user)
 conversation.mark_read_by!(user)
 conversation.post_system_message!("Ride cancelled")
 conversation.add_participant!(user)           # idempotent, race-safe
+conversation.locked?                          # the SUBJECT decides (chat_locked?)
+conversation.locked_notice                    # why, in words
 
 # Messages
 message.edit!("fixed")                        # stamps edited_at
 message.soft_delete!                          # tombstone (or destroy, per config)
 message.read_by?(user)
+message.signed? / message.authored_by?(lucia) # authorship
 Chats::Reaction.toggle!(message:, reactor:, emoji: "👍")
 
 # Participants (the per-member state)
@@ -352,10 +471,26 @@ participant.mute! / participant.unmute!
 participant.leave!                            # groups
 participant.notifiable_for?(message)          # notification etiquette
 participant.should_notify? / participant.mark_notified!
+participant.reseat!(new_messager)             # hand the seat over, read horizon intact
+
+# Events
+Chats.on(:message_created) { |message| }      # also :conversation_created,
+                                              # :participant_left, :conversation_read
 ```
 
 Errors are namespaced and meaningful: `Chats::BlockedError`, `Chats::NotAllowedError`, `Chats::ConfigurationError` — all under `Chats::Error`.
 
+## Upgrading
+
+`chats` ships the migrations a version bump needs; your initializer and views stay yours:
+
+```bash
+rails generate chats:upgrade   # 0.2.0: message authorship columns
+rails db:migrate
+```
+
+Nothing in 0.2.0 changes behaviour until you set an option — see the [CHANGELOG](CHANGELOG.md).
+
 ## 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.

data/app/assets/stylesheets/chats.css

@@ -816,3 +816,47 @@ turbo-frame[id^="chats_page_"] {
   border-radius: 0.5rem;
 }
 .chats-emoji:hover { background: var(--chats-surface); }
+
+/* ---------------------------------------------------------------------------
+   0.2.0 — stacked inbox rows, locked composers, signed messages
+   --------------------------------------------------------------------------- */
+
+/* A stack (Chats::InboxGroup) reads as one row; the count line sits where a
+   single conversation shows its subject. */
+.chats-row--group .chats-row__subject { font-weight: 600; }
+
+/* The inbox filtered to one counterpart (?with=). */
+.chats-inbox__filter {
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
+  margin: 0 0 0.5rem;
+  font-size: 0.85rem;
+  color: var(--chats-text-muted);
+}
+.chats-inbox__filter-clear { color: inherit; text-decoration: underline; }
+
+/* "See all" back to the stack, under the thread title. */
+.chats-thread__see-all { margin: 0; font-size: 0.72rem; }
+.chats-thread__see-all-link { color: var(--chats-text-muted); text-decoration: underline; }
+
+/* Who wrote it, when that isn't the seat it came from. */
+.chats-message__signature {
+  margin-top: 0.25rem;
+  font-size: 0.7rem;
+  font-style: italic;
+  opacity: 0.75;
+}
+
+/* The composer, replaced by the reason the conversation is closed. Same box,
+   so the thread doesn't jump when a subject locks under an open composer. */
+.chats-composer--locked {
+  display: block;
+  padding: 0.85rem 1rem;
+  text-align: center;
+}
+.chats-composer__locked-notice {
+  margin: 0;
+  font-size: 0.85rem;
+  color: var(--chats-text-muted);
+}

data/app/controllers/chats/conversations_controller.rb

@@ -5,16 +5,22 @@ module Chats
   # pages (create), and the per-member actions (read/typing/leave/mute).
   class ConversationsController < ApplicationController
     before_action :set_conversation, only: %i[show read typing leave mute unmute refresh]
+    helper_method :chats_counterpart
 
     # The inbox. Everything is preloaded/batched so rendering N rows costs a
     # constant number of queries (conversations + last messages + participants
     # + one grouped unread-count query — see Conversation.unread_counts_for).
+    # Rows are Conversation | InboxGroup: stacking, search and the `?with=`
+    # filter all live in Chats::Inbox, so this action stays three lines.
     def index
-      @conversations = chats_current_messager.chats
-                                             .includes(:last_message, :subject, participants: :messager)
-                                             .limit(200)
-      @conversations = apply_search(@conversations)
-      @unread_counts = Chats::Conversation.unread_counts_for(chats_current_messager, @conversations)
+      @inbox = Chats::Inbox.for(chats_current_messager, query: params[:q], with: inbox_filter)
+      @rows = @inbox.rows
+      @unread_counts = @inbox.unread_counts
+      # Back-compat for inboxes ejected under 0.1.x, which loop over
+      # @conversations: they keep rendering the flat list (no stacking, i.e.
+      # exactly what they rendered before). Re-eject or delete your copy to
+      # get the stacked rows.
+      @conversations = @inbox.conversations
     end
 
     # The thread. Renders the LATEST page of messages; older pages stream in
@@ -76,11 +82,18 @@ module Chats
       # A backlog deeper than one page would mean splicing an arbitrary
       # amount of history through surgical appends; a Turbo 8 page refresh
       # (morph + scroll preservation) re-renders the latest page + frame
-      # chain correctly instead. Raw tag rather than `turbo_stream.refresh`
-      # so we don't depend on turbo-rails ≥ 2.0 helpers.
+      # chain correctly instead.
+      #
+      # `render turbo_stream:`, NOT `render html: … content_type:` — the
+      # latter forces text/html and silently ignores the content type, so the
+      # body says <turbo-stream> while the response says it isn't one.
+      #
+      # `request_id: nil` on purpose: Turbo skips a refresh tagged with a
+      # request id it recognizes as its own, and this response is the answer
+      # to the client's OWN catch-up fetch — the one client that must not
+      # skip it.
       if @new_messages.size > Chats.config.messages_per_page
-        render html: '<turbo-stream action="refresh"></turbo-stream>'.html_safe,
-               content_type: "text/vnd.turbo-stream.html"
+        render turbo_stream: turbo_stream.refresh(request_id: nil)
         return
       end
 
@@ -156,43 +169,30 @@ module Chats
       GlobalID::Locator.locate_signed(sgid, for: purpose) || raise(ActiveRecord::RecordNotFound)
     end
 
-    # Partial, case-insensitive matching across the inbox metadata users can
-    # actually see: participant names, conversation titles, subject labels,
-    # and message bodies. The inbox is capped at 200 rows, so metadata is
-    # filtered portably in Ruby from the already-preloaded objects while the
-    # potentially larger message-body set stays in SQL. No PostgreSQL-only
-    # full-text dependency is needed for this scale.
-    def apply_search(conversations)
-      return conversations unless Chats.config.search
-
-      query = params[:q].to_s.strip
-      return conversations if query.empty?
-
-      loaded = conversations.to_a
-      normalized_query = query.downcase
-      pattern = "%#{Chats::Conversation.sanitize_sql_like(query.downcase)}%"
-      message_match_ids =
-        if Chats.config.encrypt_messages
-          []
-        else
-          Chats::Message.where(conversation_id: loaded.map(&:id), deleted_at: nil)
-                        .where("LOWER(chats_messages.body) LIKE ?", pattern)
-                        .distinct
-                        .pluck(:conversation_id)
-        end
+    # `?with=<signed gid>` — the inbox filtered to one counterpart (a stack's
+    # contents). Signed and purpose-scoped like every other polymorphic
+    # param the engine accepts; a tampered one is a plain 404.
+    def inbox_filter
+      return nil if params[:with].blank?
 
-      loaded.select do |conversation|
-        message_match_ids.include?(conversation.id) ||
-          searchable_metadata(conversation).downcase.include?(normalized_query)
-      end
-    end
+      messager = locate_signed!(params[:with], purpose: :chats_inbox_with)
+      raise ActiveRecord::RecordNotFound unless Chats.messager_class?(messager.class)
 
-    def searchable_metadata(conversation)
-      participant_names = conversation.participants.filter_map do |participant|
-        Chats.display_name_for(participant.messager) if participant.active?
-      end
+      messager
+    end
 
-      [conversation.title, conversation.subject_label, *participant_names].compact.join(" ")
+    # The other party of a direct thread (nil for groups) — the thread header
+    # names them, links to their profile, and decides whether to offer the
+    # "see all" link back to their stack. LAZY and memoized: a group thread
+    # never pays for it, and a direct one pays once no matter how many of
+    # those three things the rendered view asks for.
+    def chats_counterpart
+      return @chats_counterpart if defined?(@chats_counterpart)
+
+      @chats_counterpart =
+        if @conversation&.direct?
+          @conversation.other_participants(chats_current_messager).includes(:messager).first&.messager
+        end
     end
   end
 end