chats 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80fff570dabbff3e99a5a5f37c43b43acd334a94aae30c23b8c76bfbab5441e8
-  data.tar.gz: 72efe83f785fe99876d6b5922a5d834897f1771f3880bead3b43ae6f342ba96d
+  metadata.gz: baea21fb7f7a5ce0c50ec662b84fbef24adaa4ceb0c12a876de29891f88a2419
+  data.tar.gz: c199fc0c645bd667b7672e1ca0ea7257eb0e9cf05179c576f606fcf784b9feb0
 SHA512:
-  metadata.gz: 362eda363af938a99823b38d7fd4e0a5594d62d305f6a47f88a1dc9978c6556ab37561259007f1649567472a98deecff6cc96050afbbedc3d36637ee99207a84
-  data.tar.gz: aa7b170ba97de94d58b08516dbd4674905f1ab78e2bcd4a2e9af997e0aab6d71a3fc35b1aea2f6f0ab97fd02d1d6fa46494a1826f784b35184105c0c1c3c89b6
+  metadata.gz: 7739f616cf9e555ea1ed2e6321937bc6698d9e08733ee6c496d95ed41e2331694b5340ab5be641ac2e73875a17c4a4859bfa09e01cb0b3984a5b4fa340dcceb1
+  data.tar.gz: 712ac6d49724af1505807c3aaadd4f10fd52c8fec9653efbb9d4a89843be6fa0b2ec680873e240cc4c2bc139048cb5796b1165fced263992dc13d1499d2da0fc

data/CHANGELOG.md

@@ -4,6 +4,94 @@ 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.4.0] - 2026-10-17
+
+Action buttons. A support desk writes "Your invoice is ready" and wants a
+*Pay now* button under it; a game writes "Let's play!" and wants *Join my
+room*. Until now a host pasted a URL into the body. **0.4.0 needs one
+migration** (`rails generate chats:upgrade && rails db:migrate`, one
+nullable JSON column) and otherwise changes nothing until you pass
+`action:`.
+
+### Added
+- **One action per message.** `alice.message!(bob, "Let's play!", action:
+  { label: "Join my room", url: "/play/abcd" })`, and the same `action:` on
+  `Conversation#post_system_message!`. `message.action` is a
+  `Chats::Action` (an immutable `Data` value: `#label`, `#url`, `#to_h`) or
+  nil, and `message.action?` says which. `Chats::Action.wrap` accepts a
+  Hash with string or symbol keys, an Action, or nil, and raises
+  `ArgumentError` for anything else, including a key an action doesn't have
+  (`method: :post` would otherwise have turned into a GET link silently).
+  Assigning goes through `wrap` immediately, so a mistake raises on the line
+  that made it.
+- **Validated at the write.** The label is present and at most 80
+  characters. The url is at most 2048 characters and is either an absolute
+  http(s) URL with a host (and a port from 1 to 65535, if it names one) or
+  a path on this site starting with a single `/`. `javascript:`, `data:`,
+  other schemes and relative paths are refused, and so is everything a
+  browser would send off-site: `//host`, `///host` (which URI.parse reads
+  as a hostless path), `/\host` and `/<tab>/host`. Anything starting with
+  `//` or `/\` is refused before the url is even parsed. The error is
+  `:action, :invalid`, in `en` and `es`. It is checked only when the action
+  changes, so editing an old message never fails because of an action
+  nobody touched.
+- **The bubble renders it** as `a.chats-message__action` under the text and
+  attachments, and inside the note for system messages
+  (`.chats-message__system--with-action`). The link has
+  `data-turbo-frame="_top"`: older pages of a thread load inside lazy
+  turbo-frames, and without it a link there would navigate only the frame.
+  It is a link and never a form because the bubble is rendered once for
+  every viewer and cloned into the long-press popup, so it cannot hold a
+  per-viewer CSRF token. An action is a destination; a host that needs a
+  POST points it at a page that asks first. The markup lives in its own
+  partial, `chats/messages/_action`. The button uses the accent pair: filled
+  with the accent on foreign bubbles and system notes, reversed on your own
+  accent bubble.
+- **Tombstones drop it.** Soft deletion clears the action along with the
+  body, and so does moderation's `remove_reported_field!`, which goes
+  through the same path. `edit!` keeps it.
+- **The composer can never set one.** `Chats::MessagesController` still
+  permits only `body` and `files`, the same as with `author:`, and a test
+  checks that a posted `message[action]` is ignored.
+- **`chats_messages.action`** (jsonb on PostgreSQL, json elsewhere, nullable,
+  no default), created by the install migration and added to existing
+  installs by `rails generate chats:upgrade`. The generator doesn't write
+  that migration where the column already exists (it asks the database; a
+  fresh 0.4.0 install has it), its `up` is guarded, and rolling it back
+  KEEPS the column: nothing a migration can see records whether it or the
+  create migration added it, and it must never drop a column, with every
+  message's button in it, that it did not add.
+- **The `composer_actions` slot.** `app/views/chats/slots/_composer_actions.
+  html.erb` (receives `conversation:`) renders a row of your own buttons
+  above the composer's input ("Create a game", "Send my location") without
+  ejecting it. The row is outside the composer's `<form>`, so `button_to`
+  works there. It goes away with the composer when the thread locks, whether
+  on page load or through the live 422 swap. Unstyled links and buttons get
+  a chip look applied with zero specificity, so any class you add wins.
+
+### Changed
+- **The composer partial's DOM.** `chats/messages/_composer` is now a dock
+  wrapping the form:
+  `div#<dom_id(conversation, :composer)>.chats-composer` contains the
+  `.chats-composer__actions` row (only when the slot exists) and then
+  `form.chats-composer__form`, which keeps the `chats--composer` controller,
+  its data-actions and everything inside it. In 0.3.x the form itself was
+  `form#…composer.chats-composer`. The swap id moved to the dock so the live
+  lock replaces the host's buttons along with the form. **If you ejected the
+  composer** (CarHey did), your copy keeps working unchanged:
+  `.chats-composer` still styles whatever element carries it, and the
+  locked-composer swap still targets your form's id. You only need to
+  re-eject to use `composer_actions`. If your own CSS or JS selects
+  `form.chats-composer`, change it to `form.chats-composer__form` (or
+  `.chats-composer form`) once you're on the bundled partial.
+- The Trust & Safety report-link recipe in the README referred to the
+  inline actions row that 0.1.1 removed, and to its `chats-message__action`
+  class, which now names the action button. It now puts the link in the
+  long-press menu as a `chats-popup__item` with `data-chats-other-only`. The
+  bundled CSS styles `.chats-message__action` only as a direct child of a
+  bubble, so links in views ejected from 0.1.0 that still use the class are
+  left alone.
+
 ## [0.3.2] - 2026-09-17
 
 ### Fixed

data/README.md

@@ -11,6 +11,8 @@ It's **Hotwire-native**: messages stream live over Turbo Streams + Action Cable,
 
 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.
 
+**Contents:** [Example](#-example) · [Quickstart](#quickstart) · [Data model](#-the-data-model) · [The macros](#-the-macros) · [Real-time](#-real-time-the-hotwire-way) · [Trust & Safety](#%EF%B8%8F-trust--safety-snaps-onto-the-moderate-gem) · [Events](#-events-subscribe-to-the-domain-moments) · [Headless messagers](#-headless-messagers-desks-bots-storefronts) · [Official accounts](#-official-accounts-the-verified-badge) · [Grouped inbox](#%EF%B8%8F-grouped-inbox-rows) · [Locked conversations](#-locked-conversations) · [Signed messages](#%EF%B8%8F-signed-messages) · [Action buttons](#-action-buttons) · [View slots](#-view-slots) · [Profile links](#-profile-links) · [Theming](#-make-it-yours) · [Configuration reference](#configuration-reference) · [The full Ruby API](#-the-full-ruby-api) · [View helpers](#-view-helpers) · [Errors](#errors) · [Locales](#locales) · [Upgrading](#upgrading) · [Testing](#testing)
+
 ## 👨‍💻 Example
 
 `chats` reads like plain English:
@@ -82,7 +84,7 @@ And a live unread badge in your nav:
 
 ## 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.
+**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, action buttons under messages ("Pay now", "Join my room"), 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.
 
@@ -104,6 +106,43 @@ 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.
 
+## 🧩 The macros
+
+### `acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil, verified: false)`
+
+Anyone (or anything) that can hold a seat in a conversation. Every option is a
+class-level fact the gem reads duck-typed, so an ordinary model behaves exactly
+as before and nothing asks `is_a?(User)`:
+
+| option | default | what it means |
+|---|---|---|
+| `notifications:` | `true` | `false` for a headless seat: `Participant#notifiable_for?` is never true for it, and `Chats.notifications_for?(messager)` says so |
+| `blockable:` | `true` | `false` hides block/report affordances against it and makes `Chats.blockable?(messager)` false |
+| `inbox:` | `:default` | `:grouped` folds every direct thread with this messager into ONE inbox row (`Chats::InboxGroup`) |
+| `group_path:` | `nil` | `->(viewer) { path }` — where a deep stack opens; default is chats' own filtered inbox |
+| `verified:` | `false` | the official-account badge wherever the name renders; refuses to coerce (`"false"` raises at boot) |
+
+Class predicates: `Klass.chat_notifications?`, `.chat_blockable?`, `.chat_inbox_mode`,
+`.chat_group_path`, `.chat_verified?`. Instance API below.
+
+### `acts_as_chat_subject`
+
+A domain record conversations can be *about*. Adds `chat_conversations` (`has_many`)
+and three overridable readers — the contract a product built on chats (a ticket, an
+order) implements:
+
+```ruby
+class Ticket < ApplicationRecord
+  acts_as_chat_subject
+
+  def chat_subject_label = "Ticket #{reference}"        # the context line in inbox rows and the thread header
+  def chat_locked?       = closed?                       # whether the conversation still takes messages
+  def chat_locked_notice = "This ticket is closed."      # what replaces the composer when it doesn't
+end
+```
+
+All three are inert by default (the label falls back to the record's `to_s`, nothing is locked).
+
 ## ⚡ 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.
@@ -166,16 +205,19 @@ Use **`:flag`, never `:block`** for chat: you don't gag someone mid-conversation
 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 %>
+<%# in your ejected chats/messages/_message.html.erb, inside .chats-popup__menu
+    in the <template data-chats-message-menu> (the long-press menu) %>
 <% 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 %>
+        class: "chats-popup__item", role: "menuitem",
+        data: { chats_other_only: true } %>
+        <%# data-chats-other-only: the popup drops it from your own bubbles;
+            moderate's controller re-checks report_visible_to? server-side,
+            so hiding is cosmetic %>
 <% end %>
 ```
 
@@ -216,6 +258,14 @@ Chats.on(:participant_left)     { |participant| AuditLog.log("chat_left", partic
 Chats.on(:conversation_read)    { |conversation:, participant:| Bell.mark_read(participant.messager, conversation) }
 ```
 
+| event | block arguments | when |
+|---|---|---|
+| `:message_created` | `message` | after a **text** message commits (system messages never notify) |
+| `:conversation_created` | `conversation` | once per conversation, never when an existing one is resumed |
+| `:participant_left` | `participant` | someone left a group |
+| `:conversation_read` | `conversation:, participant:` | a read advanced the horizon past unread content |
+
+
 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.
@@ -356,6 +406,13 @@ end
 - 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.
 
+Every other write refuses too: `Message#edit!`, `#soft_delete!` and
+`Chats::Reaction.toggle!` raise `Chats::LockedError` (a `NotAllowedError`
+subclass), the edit/delete/react endpoints answer 422 with the notice, and the
+bundled bubble stops offering them. Moderation is the one exception —
+`remove_reported_field!` removes reported content from a locked conversation,
+because a product lock must never shield it.
+
 ## ✍️ 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:
@@ -378,6 +435,77 @@ Existing installs get the columns with one command:
 rails generate chats:upgrade && rails db:migrate
 ```
 
+
+## 🎯 Action buttons
+
+A support desk writes "Your invoice is ready" and wants a **Pay now** button under it. A game writes "Let's play!" and wants **Join my room**. A marketplace posts "Your ride was cancelled" with **Book another**. Pasting a URL into the body is the wrong answer: one message can carry **one action**, a label and a url, and the bundled bubble renders it as a button.
+
+```ruby
+alice.message!(bob, "Let's play!", action: { label: "Join my room", url: play_room_path(room) })
+desk.message!(user, "Your invoice is ready", author: lucia, action: { label: "Pay now", url: invoice.payment_url })
+conversation.post_system_message!("Your ride was cancelled", action: { label: "Book another", url: new_ride_path })
+```
+
+<img src="docs/screenshots/thread-actions-phone.png" alt="A thread on a phone: a received message with a dark Join my room button, and your own dark bubble with a white Open my lobby button" width="320">
+
+*One action per message: accent-filled under someone else's message, reversed in your own bubble.*
+
+```ruby
+message.action          # => #<data Chats::Action label="Join my room", url="/play/abcd">, or nil
+message.action?         # => true
+message.action.label    # => "Join my room"
+message.action.to_h     # => { label: "Join my room", url: "/play/abcd" }
+
+Chats::Action.new(label: "Pay now", url: "/pay")   # accepted anywhere a Hash is
+```
+
+`Chats::Action` is an immutable value (`Data`), compared by value. Assign a Hash (string or symbol keys), an Action, or `nil`; anything else raises `ArgumentError` where you assigned it. A key an action doesn't have raises too: `{ label:, url:, method: :post }` would otherwise turn into a plain link without telling you.
+
+**An action is a place to go, not something that happens.** It renders as a link (`data-turbo-frame="_top"`, so it opens the page even from an older page of the thread, which loads inside a frame). It is never a form, and that is on purpose: every bubble is rendered **once** and broadcast to everyone in the thread, and the long-press popup clones it, so nothing that belongs to one viewer can live inside it. A form would need that viewer's CSRF token. If the button should *do* something (accept an offer, pay), point it at a page that asks first and does the work there.
+
+**It is validated when it is written**, so a bad one fails loudly in your code and never renders as a broken or dangerous link:
+
+- `label`: present, at most 80 characters.
+- `url`: at most 2048 characters, and EITHER an absolute `http://` / `https://` URL with a host (and, if it names one, a port from 1 to 65535), OR a path on your site that starts with a single `/`. Everything else is refused: `javascript:`, `data:`, `mailto:`, relative paths, and anything a browser would send to another site: `//elsewhere.example`, `///elsewhere.example`, `/\elsewhere.example`, `/<tab>/…`. URLs must be escaped, as Rails' url helpers already produce them.
+- The error is `errors.of_kind?(:action, :invalid)`, with a readable message in `en` and `es`.
+
+Body rules don't change: an action goes with a message, it is never a message by itself. Both text and system messages can carry one. `edit!` keeps the action. **A tombstone shows neither the body nor the button**: soft deletion clears the action, and so does a moderator's `remove_reported_field!`, because it goes through the same tombstone. The inbox preview still shows the body.
+
+**Only your Ruby code sets an action.** The composer can't: `Chats::MessagesController` permits `body` and `files` only, the same as with `author:`. Restyle the button with `.chats-message__action` (eject `chats/messages/_action.html.erb` to change its markup). It uses your `--chats-accent` / `--chats-accent-contrast` colours: accent-filled under someone else's message or a system note, reversed inside your own accent-coloured bubble.
+
+### Buttons next to the composer: the `composer_actions` slot
+
+Actions are the buttons your app puts under a message. The `composer_actions` [slot](#-view-slots) is for buttons *you* put next to the composer, such as "Create a game" or "Send my location", without ejecting it:
+
+```erb
+<%# app/views/chats/slots/_composer_actions.html.erb %>
+<%= button_to "🎮 Create a game", games_path, params: { conversation_id: conversation.id } %>
+<%= link_to "📍 Send my location", new_location_path(conversation_id: conversation.id) %>
+```
+
+The row appears above the input, **outside** the composer's `<form>`, so `button_to` forms are fine there: a form inside a form is invalid HTML. If the conversation locks, the row goes away together with the composer. Unstyled buttons and links get a small chip look by default. It is applied with zero specificity, so any class you add overrides it.
+
+## ⏱️ One send budget for every composer
+
+`config.send_rate_limit` (60 per minute per sender by default) is enforced by
+the gem's own message controller. A product with its **own** composer that
+still ends in a chats message — a support form, an order note — shares the
+same budget by including one concern, so nobody gets two allowances:
+
+```ruby
+class Support::TicketsController < ApplicationController
+  include Chats::SendRateLimited
+  before_action :enforce_chat_send_rate_limit, only: :create
+
+  private
+
+  def chat_rate_limit_messager = current_user   # whose budget; defaults to the configured current messager
+end
+```
+
+It counts in the host's cache store (atomic increment, so it works on Rails 7.1
+too) and answers `429` with `chats.flashes.rate_limited` when the budget is spent.
+
 ## 🔌 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:
@@ -387,6 +515,7 @@ Ejecting a whole screen to add one row or one button is too coarse. The bundled
 | `inbox_top` | above the first inbox row |
 | `inbox_empty` | inside the empty state |
 | `conversation_header_actions` | the thread's menu (gets `blockable:`) |
+| `composer_actions` | a row of your own buttons above the composer's input, outside its form (gets `conversation:`; gone when the thread locks) |
 | `locked_composer` | the locked composer's body |
 | `message_meta` | after each bubble's timestamp |
 
@@ -497,6 +626,8 @@ 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
+alice.message!(bob, "Let's play!",            # with one button under it
+               action: { label: "Join my room", url: "/play/abcd" })
 Chats::Inbox.for(alice)                       # [Conversation | InboxGroup] + #unread_count
 Chats.verified?(desk)                         # official account? (acts_as_messager verified: true)
 
@@ -509,6 +640,7 @@ conversation.subject_label                    # "Madrid → Barcelona"
 conversation.unread_count_for(user)
 conversation.mark_read_by!(user)
 conversation.post_system_message!("Ride cancelled")
+conversation.post_system_message!("Ride cancelled", action: { label: "Book another", url: "/rides/new" })
 conversation.add_participant!(user)           # idempotent, race-safe
 conversation.locked?                          # the SUBJECT decides (chat_locked?)
 conversation.locked_notice                    # why, in words
@@ -518,6 +650,8 @@ 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
+message.action / message.action?              # the button: a Chats::Action, or nil
+Chats::Action.new(label: "Pay now", url: "/pay")  # .label .url .to_h; Chats::Action.wrap(hash_or_action_or_nil)
 Chats::Reaction.toggle!(message:, reactor:, emoji: "👍")
 
 # Participants (the per-member state)
@@ -531,20 +665,104 @@ participant.reseat!(new_messager)             # hand the seat over, read horizon
 # 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`.
+# Conversations — finding and creating
+Chats::Conversation.direct_between(alice, bob, about: ride)    # nil when none exists
+Chats::Conversation.direct_between!(alice, bob, about: ride)   # find-or-create; checks blocks and can_message(alice, bob)
+Chats::Conversation.group!(alice, [bob, carol], title: "Trip")
+Chats::Conversation.direct .groups .about(ride) .recent_first
+Chats::Conversation.inbox_for(alice) .excluding_blocked_for(alice) .unread_by(alice)
+Chats::Conversation.unread_counts_for(alice, conversations)    # { id => count } in one query
+conversation.direct? / conversation.group?
+conversation.participant_for(alice)                            # the seat, or nil
+ride.chat_conversations                                        # every conversation about a subject
+
+# Messages — reading
+message.system? / message.text? / message.deleted? / message.edited?
+message.visible_body                                           # body, or the tombstone text
+message.attachments?
+message.sent_by?(alice)  message.sender_key
+Chats::Message.visible .oldest_first .recent_first .before_message(message)   # keyset pagination
+Chats::Message.created_since(time) .updated_since(time)                       # what the stale-thread catch-up reads
+
+# Participants — reading
+participant.active? / participant.left? / participant.muted? / participant.owner?
+participant.unread? / participant.unread_count / participant.unread_messages
+participant.display_name
+Chats::Participant.active .muted
+
+# The inbox
+inbox = Chats::Inbox.for(alice, query: "trip", with: sgid)   # search, or filtered to one counterpart's stack
+inbox.rows  inbox.each  inbox.to_a  inbox.size  inbox.any?  inbox.empty?  inbox.filtered?
+inbox.conversations                                          # the flat, unstacked list
+inbox.unread_counts  inbox.unread_count_for(conversation)  inbox.unread_count
+group = inbox.rows.first                                     # a Chats::InboxGroup when the counterpart is inbox: :grouped
+group.messager  group.conversations  group.conversation  group.single?
+group.unread_count  group.unread?  group.open_count  group.last_message  group.last_message_at
+group.title_for(viewer)  group.dom_id  group.with_sgid        # the signed token GET /conversations?with= takes
+
+# Module-level
+Chats.display_name_for(messager)  Chats.avatar_for(messager)  Chats.messager_url_for(messager)
+Chats.message_signature_for(message)                         # "— Lucía G." or nil
+Chats.verified?(m)  Chats.notifications_for?(m)  Chats.blockable?(m)  Chats.grouped_inbox?(m)
+Chats.blocked_ids_for(messager)  Chats.blocked_between?(a, b)  Chats.can_message?(sender, recipient)
+Chats.inbox_with_sgid(messager)                              # the token behind a stack's "see all"
+Chats.messager_key(messager)                                 # "User:42" — what bubbles carry to align own-vs-other
+Chats.messager_class?(klass)  Chats.chat_subject_class?(klass)
+Chats.on(event, key: nil) { … }  Chats.reset_subscribers!  Chats.reset!  Chats.deprecator
+```
+
+Errors are namespaced and meaningful, all under `Chats::Error`:
+`Chats::BlockedError` (a blocked pair opening or sending), `Chats::NotAllowedError`
+(`can_message` / `can_create_group` said no, groups disabled, a reseat that would
+collide) and its subclass `Chats::LockedError` (any non-system write into a
+locked conversation), `Chats::ConfigurationError` (boot).
+
+## 🧰 View helpers
+
+All available in the bundled views **and** in your own templates:
+
+| helper | renders |
+|---|---|
+| `chat_button_to(other, about:, label:, **html)` | a "Message" button, only when the viewer may message them |
+| `chats_unread_badge(messager = viewer)` | the live unread badge with its own stream |
+| `chats_messager_name(messager, css_class:)` | the name, linked through `messager_url`, badged when verified |
+| `chats_messager_avatar(messager)` / `chats_conversation_avatar(conversation, viewer)` | avatar (URL, attachment, variant or initials) |
+| `chats_verified_badge(messager)` | the official-account mark, or nil |
+| `chats_message_signature(message)` | the "— Lucía G." line for a signed message |
+| `chats_preview_for(conversation, viewer)` | the inbox row's last-message preview with its speaker |
+| `chats_timestamp(time)` | "12:04" · "Yesterday" · "12 Sep" |
+| `chats_slot(name, **locals)` / `chats_slot?(name)` | render a host slot partial when it exists |
+| `chats_blockable?(messager)` / `chats_messager_url(messager)` | the duck-typed reads, for your own screens |
+| `chats_group_path(group)` / `chats_group_path_for(messager)` | where a stack opens |
+| `chats_styles` | the bundled stylesheet tag for your `<head>` |
+| `chats_viewer` | the current messager, as the engine resolved it |
+
+## Errors
+
+See the end of [the full Ruby API](#-the-full-ruby-api): `Chats::Error` → `BlockedError`, `NotAllowedError` → `LockedError`, `ConfigurationError`.
+
+## Locales
+
+`en` and `es` ship with the gem under `chats.*` (`inbox`, `thread`, `conversation`, `verified`, `message`, `composer`, `buttons`, `flashes`). Your own locale
+files **outrank** the gem's — Rails loads every engine's locales first and the
+app's last (a 0.2.0 fix; the gem used to re-append its files after yours and
+silently win) — so override any key in your `es.yml` and the gem's copy loses.
+Bubbles, flashes, the empty inbox, the locked composer and the verified label
+(`chats.verified.label`) are all there, and so are the model errors
+(`activerecord.errors.models.chats/message.…`, the action's included).
+
 
 ## 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 generate chats:upgrade   # 0.2.0: message authorship columns · 0.4.0: the message action column
 rails db:migrate
 ```
 
-Nothing in 0.2.0 changes behaviour until you set an option — see the [CHANGELOG](CHANGELOG.md).
+0.4.0 needs that migration (one nullable JSON column, `chats_messages.action`) and nothing else: actions and the `composer_actions` slot are opt-in. The generator is guarded: it doesn't write the action migration where the column already exists (a fresh 0.4.0 install), and re-running it is harmless. Rolling that migration back keeps the column, because a migration must never drop a column it may not have added. If you ejected the composer, read the 0.4.0 [CHANGELOG](CHANGELOG.md) entry: its DOM changed shape. 0.3.x needs no migration and no new configuration: `verified: true` (0.3.0) and `Chats::SendRateLimited` (0.3.2) are opt-in. Nothing in 0.2.0 changes behaviour until you set an option.
 
 ## Database support
 

data/app/assets/stylesheets/chats.css

@@ -417,6 +417,64 @@ turbo-frame[id^="chats_page_"] {
 .chats-message--deleted .chats-message__bubble { background: transparent; border: 1px dashed var(--chats-border); }
 .chats-message__tombstone { color: var(--chats-text-muted); font-size: 0.85rem; }
 
+/* --- Actions (Chats::Action) ------------------------------------------------------- */
+/*
+   A message's one featured button, under its words: full width, so it reads
+   as something to tap rather than a link in the text. It is a sibling of
+   .chats-message__text, never inside it, so the text's pre-wrap stays off it.
+
+   Contrast comes from the pair a host already tunes together: the accent and
+   the text that sits on it. A foreign bubble (and a system note) gets an
+   accent button; an own bubble IS the accent, so its button swaps the pair.
+   Same two colours either way, so whatever passes for the send button and
+   own bubbles passes here — default theme or host theme alike.
+
+   Scoped to the bubble with `>`: 0.1.0's inline actions row used this class
+   name, and views ejected back then may still carry it on other elements.
+   The long-press popup clones .chats-message__bubble, so this applies there
+   too.
+*/
+.chats-message__bubble > .chats-message__action,
+.chats-message__system > .chats-message__action {
+  display: block;
+  margin-top: 0.5rem;
+  padding: 0.55rem 0.9rem;
+  border-radius: calc(var(--chats-radius) * 0.7);
+  background: var(--chats-accent);
+  color: var(--chats-accent-contrast);
+  font-size: 0.88rem;
+  font-weight: 700;
+  line-height: 1.25;
+  text-align: center;
+  text-decoration: none;
+  overflow-wrap: anywhere;
+  cursor: pointer;
+}
+.chats-message--own .chats-message__bubble > .chats-message__action {
+  background: var(--chats-accent-contrast);
+  color: var(--chats-accent);
+}
+.chats-message__bubble > .chats-message__action:hover,
+.chats-message__system > .chats-message__action:hover { filter: brightness(0.92); }
+/* The focus ring sits on the BUBBLE, just outside the button, so it takes
+   the colour of the bubble's own text — which is what contrasts there. */
+.chats-message__bubble > .chats-message__action:focus-visible,
+.chats-message__system > .chats-message__action:focus-visible {
+  outline: 2px solid var(--chats-bubble-text);
+  outline-offset: 2px;
+}
+.chats-message--own .chats-message__bubble > .chats-message__action:focus-visible {
+  outline-color: var(--chats-accent-contrast);
+}
+.chats-message__system > .chats-message__action:focus-visible { outline-color: var(--chats-text); }
+/* A system note is a pill; one holding a button becomes a card, or the
+   button's corners would poke through the pill's rounded ends. */
+.chats-message__system--with-action {
+  border-radius: var(--chats-radius);
+  padding: 0.6rem 0.9rem;
+}
+.chats-message__system > .chats-message__action { margin-top: 0.45rem; }
+
 /* --- Attachments -------------------------------------------------------------------- */
 
 .chats-message__attachments {
@@ -659,12 +717,43 @@ turbo-frame[id^="chats_page_"] {
 
 /* --- Composer ----------------------------------------------------------------------------- */
 
+/* The dock (since 0.4.0 a div holding the host's composer_actions and the
+   form; a composer ejected before that is the form itself, and this box
+   styles it just the same). */
 .chats-composer {
   flex: 0 0 auto;
   background: var(--chats-bg);
   border-top: 1px solid var(--chats-border);
   padding: 0.6rem 0.9rem calc(0.6rem + env(safe-area-inset-bottom, 0px));
 }
+.chats-composer__form { margin: 0; }
+
+/* The composer_actions slot: a row of the host's own buttons above the
+   input. `display: contents` lets button_to's wrapping <form> step aside so
+   its button sits in the row like a link does. Every default here is
+   wrapped in :where() — zero specificity — so ANY class the host puts on
+   its buttons or forms wins, and an unstyled button still looks like it
+   belongs. */
+.chats-composer__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+  margin: 0 0 0.55rem;
+}
+:where(.chats-composer__actions) :where(form) { display: contents; }
+:where(.chats-composer__actions) :where(a, button) {
+  padding: 0.35rem 0.8rem;
+  border: 1px solid var(--chats-border);
+  border-radius: 999px;
+  background: var(--chats-surface);
+  color: var(--chats-text);
+  font: inherit;
+  font-size: 0.8rem;
+  font-weight: 600;
+  text-decoration: none;
+  cursor: pointer;
+}
+:where(.chats-composer__actions) :where(a, button):hover { filter: brightness(0.96); }
 .chats-composer__bar { display: flex; align-items: flex-end; gap: 0.55rem; }
 .chats-composer__input {
   flex: 1;
@@ -760,7 +849,12 @@ turbo-frame[id^="chats_page_"] {
   padding: 0.2rem 0.4rem;
 }
 
-.chats-composer__previews[hidden] { display: none; }
+/* `hidden` loses to any author `display`, so every element here that sets
+   one and starts hidden says so explicitly — the edit cue and the file
+   count used to show in hosts with no CSS reset of their own. */
+.chats-composer__previews[hidden],
+.chats-composer__edit[hidden],
+.chats-composer__file-count[hidden] { display: none; }
 .chats-composer__preview {
   position: relative;
   flex-shrink: 0;

data/app/helpers/chats/engine_helper.rb

@@ -12,6 +12,7 @@ module Chats
       inbox_top
       inbox_empty
       conversation_header_actions
+      composer_actions
       locked_composer
       message_meta
     ].freeze
@@ -147,7 +148,7 @@ module Chats
     #   app/views/chats/slots/_inbox_top.html.erb
     #
     # The slots: inbox_top, inbox_empty, conversation_header_actions,
-    # locked_composer, message_meta.
+    # composer_actions, locked_composer, message_meta.
     def chats_slot(name, **locals)
       return unless chats_slot?(name)
 

data/app/views/chats/conversations/_locked_composer.html.erb

@@ -1,8 +1,8 @@
 <%# What sits where the composer would be when the conversation's SUBJECT
     has locked it (Chats::ChatSubject#chat_locked?). It carries the same DOM
-    id as the composer form, so MessagesController#create can swap one for
+    id as the composer's dock, so MessagesController#create can swap one for
     the other with a single Turbo replace when a thread closes under an open
-    composer.
+    composer — the host's composer_actions leave with it.
 
     The `locked_composer` slot replaces the BODY (a reopen button, a link to
     the closed ticket…) while keeping the id contract intact. %>

data/app/views/chats/conversations/index.html.erb

@@ -14,6 +14,22 @@
     and on return-to-visible. It needs to wrap the <turbo-cable-stream-source>
     that `turbo_stream_from` renders so it can observe its `connected`
     attribute as the heartbeat. %>
+
+<%# The OTHER inbox-staleness case, distinct from a missed broadcast: a Turbo
+    RESTORATION visit (browser back / Hotwire Native stack pop) serves the
+    inbox's cached snapshot with no GET. Open a chat from a profile, send a
+    message, tap back — the snapshot cached before the chat existed comes back
+    and the new conversation is missing until you navigate away and return.
+    The reconciler above can't help (it only fires on reconnect / visibility,
+    not on a restore visit). `turbo-cache-control: no-cache` makes the inbox
+    uncacheable, so a restore visit re-fetches from the network and is always
+    fresh — on the web AND in Hotwire Native, whose back-pop issues a Turbo
+    `.restore` visit that honors this. Requires the host layout to
+    `yield :head` (the Rails convention); harmless no-op otherwise.
+    https://turbo.hotwired.dev/handbook/building#opting-out-of-caching %>
+<% content_for :head do %>
+  <meta name="turbo-cache-control" content="no-cache">
+<% end %>
 <%= chats_styles %>
 <div data-controller="chats--refresh-inbox">
   <%= turbo_stream_from chats_current_messager, :chats_inbox %>

data/app/views/chats/messages/_action.html.erb

@@ -0,0 +1,15 @@
+<%# A message's featured button (Chats::Action): the one place it takes you,
+    under the words it came with. Rendered inside the bubble, so it is part
+    of the single viewer-agnostic broadcast render AND of the clone the
+    long-press popup lifts — which is why it is a plain link and never a
+    form: a form would need a per-viewer CSRF token baked into a render
+    every subscriber shares. An action is a destination, not a mutation.
+
+    data-turbo-frame="_top": older pages of a thread arrive inside lazy
+    `chats_page_…` turbo-frames, and a link inside a frame navigates the
+    FRAME. _top makes it navigate the page, wherever the bubble landed.
+
+    The url was validated at the write (Chats::Message#
+    action_must_be_well_formed): http(s) or a path on this site, never
+    `javascript:` or protocol-relative. %>
+<%= link_to action.label, action.url, class: "chats-message__action", data: { turbo_frame: "_top" } %>