chats 0.1.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7e254b33cba3c656807db12e1ca491be50335584cd5824b32d7514ffcacc1bf
-  data.tar.gz: 227ad7e2280ad374bc9cb1bf48ff67d164a2ad0893e9be676dfc2a3af0bcfe67
+  metadata.gz: a0e116038dc60b864f51b65edb4f5b879305da0cabef4c8aa2db73e23464c674
+  data.tar.gz: '0179846f4e07b60cb1d07a9d50909a836456794636da584a6178843f0d39f8ff'
 SHA512:
-  metadata.gz: feb3c7419b117cd252b35c4c3202ec1ab5dfb85aa3c9da26488d490102cabc33c177ea03d2cbad1251d1af29405e023718552f1a210fb8f69207e2657d8b940b
-  data.tar.gz: f68dc5a7814bbe56f8bad71e3495c5c1d4258fcc364e284fb118b9faee455124e041612eed1f4f38ed43a255513501430e0b5d6aa13646cc8e8438979598b4c7
+  metadata.gz: 1c3dc69a2bdba881bc7fc6543bc768885797e121f8d23b619e72a578cb3e7c6555c9b19c6dde52bec3085efe52d98e40dc277af932015bb08f65a7aaf67ca5c1
+  data.tar.gz: 4ab1a0ae08133bbe02240e12b1efa8efccb6dfe5bfbf53a1662acce5542a74ec4bb3adfc1eeaf10e6db94a961b17dc81523e8b2ac5044fa02ff22bba6904e303

data/CHANGELOG.md

@@ -4,6 +4,239 @@ 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.3.1] - 2026-09-16
+
+### Fixed
+- **The verified badge was a star, not a check.** 0.3.0 shipped a
+  five-pointed star as the "official account" mark, copied from a host icon
+  that was named `verified_badge` but drawn as a star. A star reads as
+  "favourite" or "rated", not "this account is really us", and at 14px a
+  solid star and a solid rosette are the same blob. It is now heroicons
+  `check-badge`: a scalloped rosette with a tick knocked out of it, which
+  is the mark people already read as verified. `fill-rule="evenodd"` is
+  what knocks the tick out — without it the rosette fills solid.
+
+## [0.3.0] - 2026-09-16
+
+Official accounts. Some counterparts are not people you met — they are a
+support desk, an organization, a shop, a brand — and a person should be able
+to tell at a glance. **Nothing changes until a model says so**: 0.2.x
+installs upgrade by bumping the gem, with no migration and no new
+configuration.
+
+### Added
+- **`acts_as_messager verified: true`.** A messager declares itself an
+  OFFICIAL account, and every bundled view that shows its name marks it: the
+  inbox row, the stacked inbox row, and the thread header. `Klass.
+  chat_verified?` is the class predicate and `Chats.verified?(messager)`
+  reads it duck-typed — false for a plain model, a nil, a non-messager — so
+  hosts can badge their own screens without a class check. The option is
+  independent of the headless ones: a desk is usually headless *and*
+  official, a shop is usually official and nothing else. Unlike its boolean
+  neighbours it refuses to coerce — `verified: "false"` raises
+  `Chats::ConfigurationError` at boot rather than quietly verifying an
+  account, because a badge is a trust claim and not a display preference.
+- **The badge itself**, `chats/shared/_verified_badge` — an inline rosette
+  that sizes itself from the text it sits beside. It is an image with a
+  name, not decoration: `role="img"` plus a localized label
+  (`chats.verified.label`, "Official account" / "Cuenta oficial"), and the
+  glyph is `aria-hidden` so a screen reader never announces it twice.
+- **`config.verified_badge`** `->(messager) { markup }` — swap the glyph for
+  your design system's own, vary it per messager, or return nil for no badge.
+  The default (nil) renders the gem's rosette.
+- **`--chats-verified`** (`#0284c7`) — the badge colour, a CSS custom
+  property like the rest of the gem's theming, inherited through
+  `currentColor`. Not the familiar `#1d9bf0`: the badge is a meaningful
+  graphic, so WCAG 1.4.11 asks 3:1 of it, and `#1d9bf0` is 3.00:1 on
+  `--chats-bg` but 2.73:1 on `--chats-surface` — the inbox row's HOVER
+  background, so it failed exactly while somebody was pointing at it.
+  `#0284c7` clears the bar on both grounds and on a dark one, so a host
+  inverting the palette inherits a badge that still passes.
+  `test/verified_badge_contrast_test.rb` computes it rather than trusting a
+  swatch.
+- **`chats_verified_badge(messager)`** — the view helper behind all three
+  surfaces, available in host views too. Nil for everyone who hasn't
+  declared `verified: true`, so it is safe to drop next to any name
+  unconditionally.
+- **`Chats::Conversation#counterpart_for(viewer)`** — the other messager in a
+  direct thread (nil for a group, and for a thread whose other seat left).
+  The title, the avatar and the badge on an inbox row now resolve the
+  counterpart through this one method, memoized per viewer, so a row that
+  cost one query in 0.2.0 still costs one.
+
+### Changed
+- The bundled inbox row wraps its title in `.chats-row__name`, and the thread
+  header wraps its name in `.chats-thread__name`, so a long name still
+  ellipsizes while the badge beside it stays visible. If you ejected these
+  views with `rails generate chats:views`, your copies are untouched and keep
+  working; re-run the generator only if you want the badge.
+
+## [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; an official one (`verified: true`) gets the badge everywhere its name appears. 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,158 @@ 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.
+
+## ✅ Official accounts: the verified badge
+
+A support desk, an organization, a shop or a brand is an **official** counterpart, and the person talking to it should see that at a glance — the blue tick everyone already reads. Say it once, on the model, next to the other `acts_as_messager` options:
+
+```ruby
+class SupportDesk < ApplicationRecord
+  acts_as_messager verified: true
+end
+```
+
+Every bundled view that shows a messager's name now marks it: the inbox row, the stacked inbox row, and the thread header. The mark is an image with a name, not decoration — `role="img"` plus a localized label (`chats.verified.label`: "Official account" / "Cuenta oficial"), with the glyph itself `aria-hidden` so nothing is announced twice.
+
+`verified:` is **independent of everything else**. A desk is usually headless *and* official; a shop is usually official and completely ordinary otherwise. Combine what you need:
+
+```ruby
+acts_as_messager verified: true                                   # official, notifiable, blockable
+acts_as_messager notifications: false, inbox: :grouped, verified: true  # an official desk
+```
+
+It is the one boolean option that **refuses to coerce**, and that is deliberate — please don't "fix" it into a `!!` to match its neighbours. `notifications:` and `blockable:` coerce, so `notifications: "false"` quietly means `true`; on those two the damage is a stray notification. Here the same slip would hand an account the mark that tells people it is really us, and the strings that reach a model declaration come from exactly the places that produce `"false"`: an ENV var, a YAML round-trip, a settings row. So `verified: "false"` raises `Chats::ConfigurationError` at boot, where somebody is looking, rather than shipping a verified impostor nobody notices.
+
+Read it anywhere you render your own screens — duck-typed, never a class check:
+
+```ruby
+SupportDesk.chat_verified?       # the class predicate
+Chats.verified?(messager)        # false for a plain model, a nil, a non-messager
+chats_verified_badge(messager)   # the view helper: markup, or nil for everyone else
+```
+
+**Change the colour** with one CSS variable (the badge inherits it through `currentColor`):
+
+```css
+:root { --chats-verified: #0284c7; }
+```
+
+The default is `#0284c7` rather than the more familiar `#1d9bf0`. The badge is a meaningful graphic, so it owes 3:1 against what it sits on (WCAG 1.4.11), and `#1d9bf0` is 3.00:1 on the page but **2.73:1 on `--chats-surface`** — the inbox row's hover background, so it failed exactly while someone was pointing at it. `#0284c7` clears the bar on both (4.10 and 3.72) and on a dark ground too (4.33 on `#111827`), so inverting the palette doesn't leave you with a badge you have to remember to fix. If you override it, `test/verified_badge_contrast_test.rb` shows the arithmetic worth repeating.
+
+**Change the glyph** — to your design system's icon, a per-messager mark, or nothing — with a callable that gets the messager and returns html_safe markup (or `nil` for no badge):
+
+```ruby
+config.verified_badge = lambda do |messager|
+  ApplicationController.helpers.image_tag("official.svg", class: "badge", alt: "Official account")
+end
+```
+
+Or eject `app/views/chats/shared/_verified_badge.html.erb` with `rails generate chats:views` and rewrite it.
+
+## 🗂️ 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):
@@ -260,6 +415,7 @@ The bundled UI is intentionally framework-free (semantic `chats-*` classes + one
 :root {
   --chats-accent: #facc15;           /* own bubbles, send button, badges */
   --chats-accent-contrast: #111827;
+  --chats-verified: #0284c7;         /* the "official account" badge */
 }
 ```
 
@@ -269,7 +425,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 +464,20 @@ 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
+  config.verified_badge = nil                                # ->(messager) { markup } for verified: true
 end
 ```
 
@@ -329,21 +492,28 @@ 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
+Chats.verified?(desk)                         # official account? (acts_as_messager verified: true)
 
 # Conversations
 conversation.participant?(user)               # active membership
 conversation.other_participants(user)
+conversation.counterpart_for(viewer)          # the other messager (nil for groups)
 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
+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 +522,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.