chats 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 709f9d9d48f89eaac706a8c974cdfdb05ac89ed02a15677874be21dcd069c951
-  data.tar.gz: b5fcf75df095a3aaf34016e056fbc662def488efcfe502fa797745ac807d0183
+  metadata.gz: 233373c7319647cf267ec239c0227e7751deae6ea9a4afd8d94c578994c85a22
+  data.tar.gz: 02b7e37be81c69063969d202094430b1657640ea707a1f63e78c06876eb6877d
 SHA512:
-  metadata.gz: '09ef3d73a35fb2276770e14cf032925c2d4ebc80c4890e4bc21f3df72cc0ef6ef2ea11cb482ae570bba694dd1aa3047cac22b63b64bd99095bfcc738fe04b377'
-  data.tar.gz: 424502a1634c16786c512f62f246e71f7655fdb11dc13a6386bd5767474b4fdb483e409d4c988258bce54d494eb71eecb52314d469c79ddaa96e0b2cbc8d26b0
+  metadata.gz: 9bd561feaae573165ce631dac3e669b892d5d70271435a475bc36d92dc532fcd6f55b0b908415141845b47105600088dd739ae7adfeb520baf4cb4bcc0096127
+  data.tar.gz: ecd69642c82c827c53b5d038b8dd60f5853f5b012368c5d4db846b4549befbd4fd8b153b45d0468228cd77746b77b6c60dadd26ab5d36f73f2a31a4ec84a2edd

data/CHANGELOG.md

@@ -4,6 +4,237 @@ 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.5.1] - 2026-10-18
+
+A page that missed a broadcast is never left stale: every live surface
+catches up on its own, without polling (fixes
+[#1](https://github.com/rameerez/chats/issues/1)). Also: the dock's unread
+count in every language's plural forms, one extension point for a
+conversation that must open although the inbox hides it
+(`conversation_lookup_scopes`), and real conversations told from
+system-only threads. **No migration, nothing to configure.**
+
+### Added
+- **Real conversations vs system-only threads.** `with_messages` asks whether
+  a conversation holds anything at all, system lines and tombstones
+  included; ops walls, moderation lists and analytics ask whether a messager
+  wrote something there that still stands. Four additive reads answer that:
+  `Chats::Message.human` (kind `text`, not deleted: written by a messager,
+  person or not, as opposed to posted by the app, so a bot's or a headless
+  desk's text message counts and a photo with no caption counts too), `Chats::Conversation.with_human_messages` and
+  `.without_human_messages` (one correlated `EXISTS` / `NOT EXISTS` built
+  from `Message.human`, so they compose with `alice.chats`, `inbox_for`,
+  `about`, `unread_by` and `with_messages` and never multiply rows),
+  `Conversation#last_human_message` (a query, not the `last_message`
+  pointer), and its batch twin `Chats::Message.last_human_in(conversations)`:
+  the newest human message of each conversation in ONE query, for a loaded
+  page, ids, a single record, or an unloaded relation, which is read as a
+  subquery and never loaded first. It returns a relation, so a `.select` can
+  narrow the columns. Viewer-facing lists start from `alice.chats`, which
+  applies blocks and `config.inbox_scope`; the bare `Chats::Conversation`
+  scopes see every conversation and belong behind staff authorization.
+  Nothing changes by default: system messages still bump `messages_count`
+  and `last_message`, and the inbox still lists system-only threads.
+- **`Chats::ApplicationController#conversation_lookup_scopes`, the one
+  extension point for a conversation that must open although the inbox
+  hides it.** Every engine endpoint (the thread, a dock window, sending,
+  editing, reacting, reading) finds a conversation through
+  `find_conversation(id)`, which now asks each relation
+  `conversation_lookup_scopes` returns, in order (`find_by(id:)`), and
+  raises `ActiveRecord::RecordNotFound` when none has it. By default that is
+  `[chats_current_messager.chats]`, exactly the old lookup. A product gem
+  (support_desk: a requester's own ticket, which the host's `inbox_scope`
+  keeps out of the inbox) prepends a module whose
+  `conversation_lookup_scopes` returns `super + [its own scope]`, instead of
+  re-implementing the lookup and recognising a miss by the exception's
+  details. Later scopes are asked only on a miss; each scope must hold only
+  conversations the viewer may open, so nothing outside them becomes
+  reachable; and an error a scope raises is not rescued into a 404.
+
+### Fixed
+- **The dock's window count used the right plural form only in two-form
+  languages.** `dock_controller.js` picked `one` for exactly 1 and `other`
+  for everything else, so Polish, Russian, Ukrainian, Croatian or Serbian
+  (one/few/many, with 21 read like 1 in the East Slavic ones) and
+  Arabic-style zero/two read wrong. The dock now renders every plural form
+  the locale provides for `chats.dock.window_unread` (`zero`, `one`, `two`,
+  `few`, `many`, `other`; new helper `chats_plural_forms`), and the
+  controller picks one with `Intl.PluralRules` in the page's language
+  (`<html lang>`, else the browser's), reading a missing form as `other`
+  and falling back to the old rule where `Intl` is unavailable. The gem's
+  `en` and `es` keep `one`/`other`; a host adds the forms its languages need
+  in its own locale files.
+- **Every live surface catches up on the broadcasts it missed.** Action
+  Cable has no replay, so a broadcast sent while a page's socket was down
+  (a laptop asleep, a backgrounded tab or Hotwire Native WebView, a network
+  blip) never reached it, and the inbox, a thread, the unread badge or the
+  dock could sit on old content until the next navigation. One shared
+  module, `chats/recovery` (pinned for importmap hosts, like the
+  controllers), now watches each surface's own
+  `<turbo-cable-stream-source>` and the page, and asks for what was missed
+  when the stream reconnects, when the page comes back after 10 seconds or
+  more hidden, when the network comes back online (it asks Action Cable to
+  check its socket at once instead of after its backoff, and catches up
+  anyway: after a short outage the socket can look open while what was
+  sent during it is gone) and when the page
+  is restored from the back/forward cache or from Turbo's snapshot cache (a
+  back navigation, a Hotwire Native stack pop). Never otherwise: a healthy,
+  visible page fetches nothing. A hidden page never fetches; what it missed
+  waits until it is seen. Triggers that arrive together make one catch-up,
+  and catch-ups are at least five seconds apart.
+- **A reconnect Action Cable never reported is seen.** When Action Cable
+  reopens a socket that went quiet (the half-open connection of a phone that
+  slept), it drops the old socket's handlers before its close event can
+  arrive: subscribers hear "connected" again and never "disconnected", and
+  the `reconnected: true` detail reaches only the first subscription
+  confirmed. Every confirmation after the first now counts.
+- **A page restored from Turbo's snapshot cache catches up.** It came back
+  as old as when it was left, with no request: a thread restored by a back
+  navigation missed every message sent since. Its stream sources are marked
+  as they go into the cache, and a restored one catches up once it is live.
+- **The inbox** reruns a refresh that arrived while another visit was
+  loading, which Turbo ignores (`Session#refresh` skips one while
+  `navigator.currentVisit` is set): a message landing mid-refresh was lost
+  with a healthy socket. A refresh no longer rewrites the field you're
+  typing in, no longer drops the search (see Changed), and a morph no longer
+  strips the stream source's `connected` attribute.
+- **The inbox refresh is durable.** `refresh_inbox_of` enqueues
+  `Chats::InboxRefreshJob` straight from the after_commit instead of calling
+  `broadcast_refresh_later_to`, which parked the refresh for half a second
+  in an in-process timer (`Turbo::Debouncer`) before enqueueing it, so a
+  deploy or a crash inside that window dropped it. At most one is queued
+  per recipient: while one is queued and hasn't started, it stands for
+  every write that commits before it runs (a short-lived marker in
+  `Rails.cache`, removed by the job as it starts, before it broadcasts), so
+  a burst is one job per recipient. A lost marker costs an extra job, never
+  a missed refresh, and the marker expires after two seconds. Only a
+  marker that is really there counts as "queued": a store that can't hold
+  it (RedisCacheStore answers nil when a write fails; any store may raise)
+  means the write queues its own refresh. Since another
+  write may count on a refresh whose enqueue is still in flight, a failed
+  enqueue is retried once, then the refresh is broadcast on the spot. Every
+  refusal goes to `Rails.error` (raised, `false`, or a job the adapter
+  declined), never up through the write that committed. The refresh
+  tag carries `method="morph" scroll="preserve"`, so the inbox morphs
+  whatever the host layout's refresh meta says, and no request id, since
+  it may stand for several requests' writes.
+- **The thread's catch-up asks on two cursors.** It sent only the newest
+  `updated_at` it had rendered and the server appended what was created
+  after it, so a message created at 10:15 and missed, while a bubble on
+  screen was edited at 10:20, never came. Now `after=` (the newest creation
+  on screen) decides what is appended and `changed=` (the newest change)
+  what is replaced, and both scopes split on the same creation cursor
+  (`created_after` / `created_through(…).updated_after(…)`). Each cursor is
+  a moment to the microsecond plus the ids on screen at it (`after_ids=`,
+  `changed_ids=`): a message missed in the very instant of one on screen,
+  or a change missed inside the same millisecond as one on screen (the old
+  cursor rounded up to the millisecond), is no longer lost. The cursors
+  are reconciled moments: a complete render sets them (the page, a window,
+  a history re-render), and so does a catch-up that arrived (its
+  `chats_caught_up` action); a live bubble never moves them, since it can
+  arrive after one that was missed (a message missed at 10:15, then one
+  live at 10:20). What arrived live is named instead, at most 200 ids
+  (`after_ids`, `changed_ids`, each id at most 64 characters); past that,
+  or with `full=1`, the history is re-rendered. Kept on the element
+  (`data-chats-reconciled`), so a dock window moved by a Turbo visit, or a
+  restored snapshot, keeps them. Each catch-up is bound to one render of
+  the thread (`render=`, echoed by the answer): an answer that arrives
+  after the page or a dock window rendered the conversation again is
+  dropped unrendered, and its cursors ignored — checked again by every
+  stream of it at the moment Turbo applies it, a repaint later, so a visit
+  or a window reload in between can't hand the old streams the new render.
+  A history re-render is followed by one more catch-up from its own
+  cursors once Turbo has actually applied it, however late that is, so a
+  message written while that page was being built isn't lost. Every
+  catch-up is bounded: a request with no answer after 15 seconds is
+  aborted (a fetch can hang across a network interruption, and would
+  otherwise stand in for every later one), a thread has at most one answer
+  waiting for Turbo (a newer one, or the thread going away, drops the
+  older one's leftover streams and stops watching for them — going away
+  for good: a dock window Turbo carries across a visit is off the page
+  until that render ends, which a host's asynchronous `turbo:before-render`
+  can make last many tasks, and keeps its answer, decided only once every
+  `turbo:before-render` has had its `turbo:render`, paired first in, first
+  out; a render that runs past 10 seconds stops holding things up but stays
+  paired until its own end, and one that never ends is forgotten after a
+  minute), and only the
+  answer's own streams are guarded (`data-chats-answer`), never a host's
+  stream rendered at the same moment. A thread whose catch-up didn't apply,
+  for any reason (its page rendered it away, the request failed, Turbo
+  never got to it), is marked behind (`data-chats-stale`, on the thread
+  element itself, so the mark travels with the dock and can't be
+  forgotten while the thread exists) and catches up again when it
+  connects, on its stream's confirmation and after every page render,
+  through the same coalescing and 5-second spacing as every other trigger;
+  only the answer of the newest catch-up clears it (they are numbered on
+  the element, `data-chats-catch-up`), so an older answer that applies
+  after a newer one failed leaves the thread marked; and nothing older
+  than the newest catch-up that has applied (`data-chats-applied`) may
+  apply after it, so an older answer arriving last can't put back older
+  bubbles, read state or cursors. A catch-up always gets an answer built
+  after it was asked: the same request asked in the same instant is made
+  once, but asked while it is already on its way, it is made once more as
+  soon as that one has its answer from the network (never waiting on
+  Turbo to apply it), for everyone who asked meanwhile, each keeping its
+  own `when` and its own outcome. An answer Turbo hasn't applied 10
+  seconds after it joined the page is cancelled (its callers settle, and a
+  thread stays marked behind), and neither a caller's hook that throws nor
+  a stream that fails to render can leave an answer half-applied or its
+  callers waiting. An empty
+  thread, which used to ask nothing, asks from the epoch: its first message
+  may be the one it missed.
+- **The thread's catch-up is complete.** `GET /:id/refresh` now also
+  replaces the read state (a read the stream missed left "Sent" where it
+  should say "Seen"), catches reactions (a reaction now moves its message's
+  `updated_at`, with `update_columns`, so the bubble is not broadcast twice),
+  and, under `deletion: :hard`, lists the messages that still exist from the
+  oldest rendered bubble on (`from=`), so the thread removes the ones that
+  are gone (the `chats_prune` stream action). Catching up still reads
+  nothing.
+- **The unread badge and the dock catch up.** The viewer's own
+  `chats_unread_badge` is wrapped in a `chats--unread-badge` controller (a
+  `span.chats-unread-badge-live`, `display: contents`, so it changes no
+  layout) that asks the new `GET /badge` for every unread badge on the page:
+  the nav badge and the dock's, with the count the badge streams send
+  (`unread_chats_count`). Someone else's badge stays live but doesn't catch
+  up. The dock fetches the same, and reloads its recent list; each open
+  window's thread catches up by itself. A message missed while offline
+  never pops a window open late.
+
+- **Both search forms are search landmarks.** `form_with … role: "search"`
+  rendered no `role` at all (`form_with` drops HTML attributes it doesn't
+  know unless they go through `html:`), on the inbox and in the dock.
+
+### Changed
+- A page now counts as having been away after 10 seconds hidden, not 60
+  (the inbox and the thread used 60).
+- A thread more than a page behind no longer gets a page refresh, which
+  cleared the composer's draft and, in a dock window, refreshed the host's
+  whole page: its history (`chats/conversations/_history`, inside
+  `#history_conversation_<id>`) is re-rendered at the latest page, the
+  composer untouched. An ejected thread whose scroller has no
+  `id="<%= dom_id(conversation, :history) %>"` keeps getting the page
+  refresh.
+- The inbox's search keeps its query in the URL (`data-turbo-action=
+  "replace"`, submitting to the inbox's own path), so a refresh re-renders
+  the same results instead of the unfiltered list. The dock's recent list
+  frame has `refresh="morph"`, so a reload keeps its scroll and its search.
+- New: the `GET /badge` collection route, the `chats--unread-badge`
+  controller, `Chats::InboxRefreshJob`, and `data-message-id`,
+  `data-created-at-us` and `data-updated-at-us` on every bubble, which no
+  longer carries `data-updated-at-ms`.
+- **If you wrapped the inbox in a reconciler of your own** (a
+  stream-reconciler controller around `turbo_stream_from … :chats_inbox`),
+  remove it: two on one page both fire, and the gem's covers what yours did.
+  **If you ejected the inbox**, keep the
+  `data-controller="chats--refresh-inbox"` element around its
+  `turbo_stream_from chats_current_messager, :chats_inbox` (an inbox without
+  it doesn't catch up), and add `turbo_action: "replace"` to the search
+  form's `data` and `url: request.original_fullpath.split("?").first`. An
+  ejected message partial (with only `data-updated-at-ms`) keeps the one
+  cursor it had (`since=`), and a hard delete missed while offline stays on
+  screen until the next load.
+
 ## [0.5.0] - 2026-10-18
 
 The messaging dock. LinkedIn and Steam keep your conversations in small

data/README.md

@@ -98,6 +98,8 @@ Or give every page LinkedIn-style floating chat windows with one line in your la
 
 > [!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.
+>
+> A product on chats may need a conversation to open although your `inbox_scope` keeps it out of the inbox (a requester's own ticket). `Chats::ApplicationController#conversation_lookup_scopes` is the one extension point for that: every engine endpoint looks a conversation up through it, in order (by default `[viewer.chats]`), and the product appends its own relation, `super + [own_cases_scope]`, from a prepended module. Each scope must hold only conversations the viewer may open: nothing outside them becomes reachable, a miss is still a plain 404, and an error inside a scope is not rescued.
 
 ## 🧱 The data model
 
@@ -114,6 +116,30 @@ Two deliberate design decisions worth knowing:
 1. **Read state is a horizon, not per-message receipts.** A participant has ONE `last_read_at`; a message is unread iff it's newer. That's unread counts, badges, and "Seen" indicators with zero extra writes per message (a receipts table writes N rows per message — the classic chat-schema scaling trap), and it's exactly how Basecamp's Campfire models it.
 2. **Direct conversations have a deterministic identity** (`direct_key`, unique-indexed): two people DMing each other in the same instant race into the SAME conversation, guaranteed by the database, not by hope.
 
+### Real conversations vs system-only threads
+
+A system message is a message: `post_system_message!` bumps `messages_count`, moves `last_message` and re-sorts the inbox like a human one, and a deleted message stays behind as a tombstone. That is on purpose: "Your ride was cancelled" matters to the passenger, so the inbox lists a thread only your app has spoken in. Two questions, two scopes:
+
+- **`with_messages`** asks *is there anything here?*: any message, system lines and tombstones included. Every list the gem renders reads through it, so a thread that was opened and never used is not listed.
+- **`with_human_messages`** asks *did a messager write something here that still stands?*: at least one `text` message that isn't deleted. "Human" is the gem's word for a `text` message: written by a messager, person or not, as opposed to posted by the app. So a bot's or a headless desk's message counts, and so does a photo with no caption. It is for ops walls, moderation lists and "conversations started this week" charts, which must not count a thread holding only "Alice joined".
+
+```ruby
+# What a viewer sees: start from alice.chats, so blocks and config.inbox_scope apply
+alice.chats.with_human_messages                    # threads where somebody actually wrote
+alice.chats.with_messages.without_human_messages   # listed, but only the app has spoken
+conversation.last_human_message                    # the newest human message, or nil (a query, not the pointer)
+Chats::Message.last_human_in(alice.chats.limit(20))  # the same for a page of threads, in ONE query
+
+# Admin-wide: no viewer, so no blocks and no inbox_scope. Only behind your staff authorization.
+Chats::Conversation.with_human_messages.count
+Chats::Conversation.about(ride).without_human_messages
+Chats::Message.last_human_in(page)                 # page: records, ids, or a relation (read as a subquery, see below)
+              .select(:id, :conversation_id, :body)  # narrow the columns if you like
+              .index_by(&:conversation_id)         # { id => message }; no key means nobody wrote
+```
+
+Both conversation scopes are a single correlated `EXISTS` built from `Chats::Message.human` (kind `text`, not deleted), so they compose with anything (`about`, `unread_by`, `with_messages`) and never multiply rows. `last_human_in` reads an unloaded relation as a subquery without its `includes` (they only load records), so a relation that filters on an associated table needs that table joined explicitly, with `joins` or `left_joins`; `includes(:participants).references(:participants).where(chats_participants: …)` loses the join and raises. Or pass the loaded page, or its ids. Counting what messagers wrote per conversation is the plain `Chats::Message.human.where(conversation_id: ids).group(:conversation_id).count`. None of this changes the inbox, unread counts, `messages_count` or `last_message`.
+
 ## 🧩 The macros
 
 ### `acts_as_messager(notifications: true, blockable: true, inbox: :default, group_path: nil, verified: false)`
@@ -155,12 +181,34 @@ All three are inert by default (the label falls back to the record's `to_s`, not
 
 - **The thread** subscribes to one conversation stream. New messages append surgically; edits/deletes replace bubbles in place; the sender's own bubble comes straight back in the form response (no cable round-trip), and Turbo's same-id dedup makes the echo broadcast a no-op.
 - **Bubbles are broadcast viewer-agnostic** — one render shared by every subscriber. A tiny Stimulus controller aligns own-vs-other client-side by comparing sender keys. This is what makes single-render broadcasts possible at all.
-- **The inbox** receives Turbo 8 page *refreshes* (morphing, scroll-preserving) instead of surgically patched rows: inbox rows are intensely per-viewer (unread badges, bold states, ordering), so each client re-requests and gets a correct, personalized render. Refreshes are debounced and tagged so the tab that caused the change skips its own.
+- **The inbox** receives Turbo 8 page *refreshes* (morphing, scroll-preserving) instead of surgically patched rows: inbox rows are intensely per-viewer (unread badges, bold states, ordering), so each client re-requests and gets a correct, personalized render. Each refresh carries `method="morph" scroll="preserve"` itself, so it morphs whatever your layout's refresh meta says. A search keeps its query in the URL, so a refresh re-renders the same results, and the field you're typing in is never rewritten under you.
 - **Unread badges** get their own stream (`chats_unread_badge` helper) so any page can host a live badge without inheriting inbox refreshes.
 - **The messaging dock** has one more per-messager stream (`[messager, :chats_dock]`): its badges, and a signal naming the conversation that changed and whether its window may pop open. The signal only names a conversation the participant can see (blocks and `inbox_scope` applied). No polling, no channel of its own.
 - **Typing indicators** are a Turbo Stream *custom action* — ephemeral, nothing persisted, no Action Cable channel class, no connection identification requirements.
 - **Cable down?** Everything still works request/response. Real-time is an enhancement, not a requirement.
 
+### What happens when a broadcast is missed
+
+Action Cable has no replay: a broadcast sent while a page's socket is down (a laptop asleep, a phone in a pocket, a backgrounded Hotwire Native WebView, an elevator) never reaches it. So every live surface catches up by itself, with no polling and nothing to configure. It fetches what it missed at the moments it may have missed something, and only then:
+
+- **its stream reconnects.** Every confirmation of the subscription after the first counts, including a socket Action Cable reopened without ever reporting it closed (the half-open TCP of a phone that slept);
+- **the page comes back after 10 seconds or more hidden** (an app foregrounded, a tab returned to). A hidden page never fetches; what it missed waits until it is seen;
+- **the network comes back online.** Action Cable is asked to check its socket right away instead of waiting out its backoff (a dead one reconnects: the first trigger), and the surface catches up anyway, because after a short outage the socket can still look open while what was sent during it is gone;
+- **the page is restored**, from the browser's back/forward cache or from Turbo's own snapshot cache (a back navigation, a Hotwire Native stack pop).
+
+Triggers that arrive together make one catch-up, and catch-ups are at least five seconds apart, so a flapping connection can't turn into a fetch loop. While the socket is healthy and the page is on screen, nothing is fetched. What each surface fetches:
+
+| surface | catches up with |
+|---|---|
+| the inbox | the same morphing page refresh a broadcast triggers. A refresh that arrives while another visit is still loading, which Turbo would otherwise ignore, runs when that visit completes |
+| a thread (page or dock window) | `GET /:id/refresh?after=…&changed=…`, on two cursors: messages created after the newest one on screen are appended (an empty thread asks from the beginning), and edits, tombstones and reactions made to the ones on screen since the newest change it saw are replaced. Two, because a message created at 10:15 and missed is older than a 10:20 edit that did arrive. Each cursor is a moment to the microsecond up to which the thread knows it has everything: set by a complete render or by a catch-up that arrived, never by a live bubble, which can arrive after one that was missed. What arrived live since is named instead (at most 200 ids; past that the history is re-rendered), so it isn't sent twice, and two messages that share a timestamp are never mistaken for each other. Each catch-up belongs to one render of the thread: an answer that arrives after the page or the window rendered the conversation again is dropped unrendered. The read receipts are updated too, the read receipts updated, and, under `deletion: :hard`, bubbles whose messages are gone removed. The composer, its draft and your scroll position are never touched. A thread more than a page behind gets its history re-rendered at the latest page |
+| `chats_unread_badge` and the dock's badges | `GET /badge`, every unread badge on the page in one Turbo Stream |
+| the dock's recent list | a reload of its frame, morphed in place so it keeps its scroll position and your search |
+
+None of these requests marks anything read, and none can be prefetched (they are not links). On the server, the inbox refresh is enqueued straight into your job queue when the write commits (`Chats::InboxRefreshJob`), and not parked first in Turbo's in-process half-second debounce, where a deploy or a crash inside that window would drop it. A burst is one job per recipient, not one per write: a refresh carries no data (the inbox re-requests itself), so while one is queued and hasn't started it stands for every write that commits before it runs. A short-lived marker in `Rails.cache` says one is queued, and the job removes it as it starts, before it broadcasts, so a write that still finds the marker is covered and a write after it queues the next job. Because another write may already be counting on it, an enqueue that fails is tried once more, and if the queue refuses again the refresh is broadcast on the spot. Every refusal goes to `Rails.error`, whether the adapter raised, returned `false` or declined the job. Whatever happens to the marker costs an extra job, never a missed refresh: a cache that can't hold it (a null store, a per-process memory store, a Redis that refuses the write) only means no coalescing, and it expires after two seconds, so a job lost from the queue holds nothing back for longer than that. The refresh names no request id, because it may stand for several requests' writes. Refreshes that still arrive close together merge in the browser: Turbo runs one page refresh for those within 150 ms of each other.
+
+**Hotwire Native** needs nothing. The catch-up is the same code path a broadcast takes (the inbox's is a Turbo page refresh, which Turbo hands to the native adapter as it does any refresh), and a back navigation is a Turbo restore, which catches up like any other. A WebView that lives for the whole app session is the case all of this is for: when the app comes back to the foreground, the WebView reports the page visible again, and in any case the socket that died in the background reconnects, and that reconnect is a trigger of its own. **If you wrapped the inbox in a reconciler of your own** (a stream-reconciler controller around `turbo_stream_from … :chats_inbox`), remove it: two reconcilers on one page both fire, and the gem's now covers everything yours did.
+
 ## 🛡️ Trust & Safety: snaps onto the [`moderate`](https://github.com/rameerez/moderate) gem
 
 Messages are user-generated content — App Store Guideline 1.2, Google Play's UGC policy, and the EU DSA all expect **report**, **block**, and **filter** capabilities before you ship a chat. Instead of re-implementing any of that, `chats` exposes the exact seams the `moderate` gem expects, with **no hard dependency in either direction**: each gem runs standalone, and together they behave like one system. This section is the complete recipe.
@@ -552,7 +600,7 @@ LinkedIn and Steam don't send you to another page to answer a message: chats liv
 - **The bar** sits flush with the bottom-right corner: your avatar, "Messages" and the live unread badge (the same number as `chats_unread_badge`).
 - **The panel** opens from it: the inbox's search, your ten most recent conversations exactly as the inbox renders them (stacks, verified badges, a bell-slash on muted ones, previews, unread counts) and "See all messages". It is a `<details>`: it opens without JavaScript, and every row, the search and the link are real links and forms.
 - **A window** is the same thread the full page shows (live messages, read receipts, typing, the long-press menu, attachments, action buttons, your `composer_actions`, the locked composer) under a compact header: the name (click it to minimize, as on LinkedIn), the `conversation_header_actions` slot in a ⋯ menu, ⤢ for the full page, – and ×. As many windows open as fit beside the panel, up to three: two at 1280px, one at 768px. Opening one more closes the least recently used window that isn't **in use**. A window in use (it has the focus, or text you haven't sent) is never closed to make room: it folds to a narrow header (its avatar and ×) beside the new window instead. Two limits always hold: never more than `windows:` windows, folded ones included, and never wider than the screen beside the panel. When a conversation can't fit even with every window in use folded, the dock doesn't open it: the row's link opens the conversation's page instead (a pop-up simply doesn't happen). Unfolding a folded window makes room the same way; when it can't, the window stays folded. Narrowing the browser closes idle windows and folds the ones in use, the focused one last; if even a row of folded headers is too wide, the least recently used windows close too, their unsent text kept for when you reopen them. Text in a window that goes away (you close it, it makes room, its conversation becomes unreachable, its load fails) is kept for when you reopen it, and goes back into the composer the moment it appears, unless you've already started typing there.
-- **Live**: a new message updates the badge and the list, and opens its conversation's window without taking the focus. That never happens for your own messages, for a conversation you muted, on a phone, for one you closed in the last five minutes, or by closing a window you're using. The window waits with the accent header and its count, and "New message from …" is announced politely. Edits, deletes and your own sends from another tab keep the list in order.
+- **Live**: a new message updates the badge and the list, and opens its conversation's window without taking the focus. That never happens for your own messages, for a conversation you muted, on a phone, for one you closed in the last five minutes, or by closing a window you're using. The window waits with the accent header and its count, and "New message from …" is announced politely. Edits, deletes and your own sends from another tab keep the list in order. A message that arrived while you were offline doesn't pop a window late: the badge and the list [catch up](#what-happens-when-a-broadcast-is-missed), and so does every open window's thread.
 - **Reading** waits for you. A minimized window never marks anything read (the thread checks the window's state, not just its size), and a window that popped open marks messages read once you focus it, press in it or scroll it. One you opened yourself reads right away.
 - **It stays put**: the dock is `data-turbo-permanent`, so Turbo Drive carries its windows, drafts and scroll positions from page to page. Its id names the viewer, so a visit that lands on another account's page never inherits it. Open windows, minimized ones, recently closed ones, the panel and unsent drafts are kept in `localStorage` under keys that name the viewer (`chats:dock:v1:<key>`, `chats:draft:<key>:<id>`), so a reload brings them back as they were, folded ones included (fitted to the width there is). A browser that refuses storage only means the dock forgets.
 - **Keyboard**: Escape unwinds from the inside out (the long-press popup, an edit, the ⋯ menu, then the window minimizes, then the panel closes). Focus rings are inset; the history scrolls with the arrow keys.
@@ -605,7 +653,7 @@ It needs `chats_dock` on the same page: without the dock, the button's response
 }
 ```
 
-The `dock_panel_footer` [slot](#-view-slots) puts your own link next to "See all messages". `rails generate chats:views` ejects the dock's partials (`chats/dock/`) along with everything else. All labels are localized under `chats.dock.*`.
+The `dock_panel_footer` [slot](#-view-slots) puts your own link next to "See all messages". `rails generate chats:views` ejects the dock's partials (`chats/dock/`) along with everything else. All labels are localized under `chats.dock.*`. The window's unread count (`chats.dock.window_unread`) is pluralized in the browser with `Intl.PluralRules` in the page's `<html lang>`: the gem ships `one`/`other`, so add the forms your languages need (`zero`, `two`, `few`, `many`) in your own locale file, e.g. Polish `few: "%{count} nowe wiadomości"`, `many: "%{count} nowych wiadomości"`.
 
 ## 🔗 Profile links
 
@@ -639,7 +687,7 @@ Want full control? Eject the views Devise-style and restyle with your own stack
 rails generate chats:views
 ```
 
-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`, `controllers/chats/refresh_inbox_controller`, and `controllers/chats/dock_controller`.
+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`, `controllers/chats/refresh_inbox_controller`, `controllers/chats/unread_badge_controller`, and `controllers/chats/dock_controller`. What the inbox, thread, badge and dock controllers share to catch up on missed broadcasts is `chats/recovery` (`recoverMissedBroadcasts`, `renderStreamFrom`); a controller of your own can import it too.
 
 ## Configuration reference
 
@@ -706,6 +754,7 @@ alice.message!(bob, "hi", about: ride)        # send (resolves the thread)
 alice.message!(conversation, "hi", files: []) # send into a conversation
 alice.chats                                   # every conversation she's in (what she may open), newest first
 alice.chats.with_messages                     # ...the ones with a message: what lists show
+alice.chats.with_human_messages               # ...the ones a messager wrote in (system lines and tombstones don't count)
 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
@@ -755,6 +804,8 @@ 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.with_messages                              # has at least one message, system messages and tombstones included (`last_message_id` set); every list reads through this
+Chats::Conversation.with_human_messages .without_human_messages # a messager wrote / only system lines, tombstones or nothing
+conversation.last_human_message                                # newest text, non-deleted message, or nil (a query)
 Chats::Conversation.unread_counts_for(alice, conversations)    # { id => count } in one query
 conversation.direct? / conversation.group?
 conversation.participant_for(alice)                            # the seat, or nil
@@ -767,6 +818,8 @@ 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
+Chats::Message.human                                                          # kind text, not deleted: what messagers wrote
+Chats::Message.last_human_in(conversations)                                   # newest human message per conversation, one query
 
 # Participants — reading
 participant.active? / participant.left? / participant.muted? / participant.owner?
@@ -809,7 +862,7 @@ All available in the bundled views **and** in your own templates:
 | helper | renders |
 |---|---|
 | `chat_button_to(other, about:, label:, dock:, **html)` | a "Message" button, only when the viewer may message them; `dock: true` opens a dock window instead of navigating |
-| `chats_unread_badge(messager = viewer)` | the live unread badge with its own stream |
+| `chats_unread_badge(messager = viewer)` | the live unread badge with its own stream; the viewer's own also [catches up](#what-happens-when-a-broadcast-is-missed) on updates it missed |
 | `chats_dock(windows: 3, recent: 10, launcher: true, everywhere: false)` | the [messaging dock](#-messaging-dock): bar, panel and floating windows |
 | `chats_dock_opener(conversation)` / `chats_dock_toggle` | data for your own links: open that conversation's dock window, or open the dock's panel |
 | `chats_muted?(conversation, viewer)` | whether the viewer muted it (read from the preloaded seats) |
@@ -849,7 +902,7 @@ rails generate chats:upgrade   # 0.2.0: message authorship columns · 0.4.0: the
 rails db:migrate
 ```
 
-0.5.0 needs no migration: the messaging dock is opt-in (`chats_dock`). A few things change on their own: a conversation with no messages is no longer listed (it used to show as a "No messages yet" row), a thread the host's policy no longer allows shows the notice in the composer's place, a Turbo hover prefetch no longer marks a thread read, and the thread body moved into `chats/conversations/_thread.html.erb`. Read the 0.5.0 [CHANGELOG](CHANGELOG.md) entry if you ejected `show.html.erb` or the unread badge. 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.
+0.5.1 needs no migration and nothing to configure: every live surface now [catches up](#what-happens-when-a-broadcast-is-missed) on missed broadcasts by itself. If you wrapped the inbox in a reconciler of your own, remove it; if you ejected the inbox, the thread or the message partial, read the 0.5.1 [CHANGELOG](CHANGELOG.md) entry. 0.5.0 needs no migration: the messaging dock is opt-in (`chats_dock`). A few things change on their own: a conversation with no messages is no longer listed (it used to show as a "No messages yet" row), a thread the host's policy no longer allows shows the notice in the composer's place, a Turbo hover prefetch no longer marks a thread read, and the thread body moved into `chats/conversations/_thread.html.erb`. Read the 0.5.0 [CHANGELOG](CHANGELOG.md) entry if you ejected `show.html.erb` or the unread badge. 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

@@ -133,6 +133,9 @@
   flex-shrink: 0;
 }
 .chats-badge--floating[hidden] { display: none; }
+/* chats_unread_badge's wrapper (its catch-up controller): no box of its own,
+   so the badge sits in the host's layout exactly as if it weren't there. */
+.chats-unread-badge-live { display: contents; }
 
 /* --- Empty states ------------------------------------------------------------ */
 

data/app/controllers/chats/application_controller.rb

@@ -55,11 +55,52 @@ module Chats
       Chats.config.layout
     end
 
-    # Conversations are ALWAYS resolved through the viewer's own inbox
-    # relation: not-a-participant, left, or blocked-counterpart threads all
-    # come back as a plain 404 — existence is never leaked to outsiders.
+    # Conversations are ALWAYS resolved through relations that only hold
+    # what this viewer may open (conversation_lookup_scopes): not a
+    # participant, left, or a blocked counterpart all come back as a plain
+    # 404, the same 404 as an id that doesn't exist — existence is never
+    # leaked to outsiders. Every engine endpoint (the thread, a dock window,
+    # sending, editing, reacting, reading) looks a conversation up here.
+    #
+    # The first scope that has it wins; later scopes are asked only on a
+    # miss. Errors a scope raises are not rescued: a broken product scope
+    # must fail loudly, never turn into a quiet 404.
     def find_conversation(id = params[:id])
-      chats_current_messager.chats.find(id)
+      conversation_lookup_scopes.each do |scope|
+        conversation = scope.find_by(id: id)
+        return conversation if conversation
+      end
+
+      raise ActiveRecord::RecordNotFound.new(
+        "Couldn't find Chats::Conversation with 'id'=#{id}", Chats::Conversation.name, "id", id
+      )
+    end
+
+    protected
+
+    # Where find_conversation looks, in order: by default the viewer's own
+    # inbox relation (`Messager#chats`: their active seats, blocks and
+    # `config.inbox_scope` applied).
+    #
+    # THE extension point for a conversation that must open although the
+    # inbox hides it. A product gem built on chats (support_desk: a
+    # requester's own ticket, which the host's inbox_scope keeps out of the
+    # inbox) prepends a module that appends its own relation:
+    #
+    #   module SupportDesk::ConversationLookup
+    #     protected
+    #
+    #     def conversation_lookup_scopes
+    #       super + [SupportDesk::Ticket.conversations_of(chats_current_messager)]
+    #     end
+    #   end
+    #   Chats::ApplicationController.prepend(SupportDesk::ConversationLookup)
+    #
+    # Each scope must hold only conversations this viewer may open: the
+    # union of the scopes IS the authorization. Nothing the scopes don't
+    # name becomes reachable.
+    def conversation_lookup_scopes
+      [chats_current_messager.chats]
     end
   end
 end