chats 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 709f9d9d48f89eaac706a8c974cdfdb05ac89ed02a15677874be21dcd069c951
-  data.tar.gz: b5fcf75df095a3aaf34016e056fbc662def488efcfe502fa797745ac807d0183
+  metadata.gz: a0635f1e1c801684a95223db2e59dbb843a67fd9edfe858973b4e9ac6bb32c2a
+  data.tar.gz: 9273751eca09bf387e640a45760f00dbd9875af8b8a75a1c2c4ae0de9ff2f527
 SHA512:
-  metadata.gz: '09ef3d73a35fb2276770e14cf032925c2d4ebc80c4890e4bc21f3df72cc0ef6ef2ea11cb482ae570bba694dd1aa3047cac22b63b64bd99095bfcc738fe04b377'
-  data.tar.gz: 424502a1634c16786c512f62f246e71f7655fdb11dc13a6386bd5767474b4fdb483e409d4c988258bce54d494eb71eecb52314d469c79ddaa96e0b2cbc8d26b0
+  metadata.gz: 94843453f041d4ff766b577b8ba9c28f4a04123f6532e7c27109836dae84f9c354d3c3051cf7f6ad6ec4b05abcbc46e78deacaaec131d63cd0c1af5631bdf4c1
+  data.tar.gz: 0b61d2704ea93dd153e0b5ff899b9029b561f710f117955dd82f971a232a2891edc903b526af2cfe4438dfd3e655237a9a31dd9512f9406409a75675df138b94

data/CHANGELOG.md

@@ -4,6 +4,355 @@ 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.6.0] - 2026-10-18
+
+The messaging page is two panes, LinkedIn-style: on a wide screen
+`/messages` is the conversation list beside the open conversation, and
+`/messages/:id` is that same page with its conversation open. Phones keep
+the separate pages. **No migration; `config.inbox_layout = :stacked` keeps
+the old pages everywhere.**
+
+### Added
+- **Two panes (`config.inbox_layout = :split`, the default).** From 700px
+  wide (the width at which the dock turns into a phone sheet) the list sits
+  on the left in a `<nav>` named "Messages", `--chats-list-width` (320px)
+  wide, and the open conversation on the right in a
+  `turbo_frame_tag "chats_conversation"`; with none open, the pane says
+  "Select a conversation" (`chats.inbox.select_hint`), and with no
+  conversations at all it holds the inbox's empty state and the
+  `inbox_empty` slot (rendered once, in the pane, no longer in the list
+  too). Both panes are as tall as `--chats-split-height` (the screen,
+  `100dvh`, by default; a host with its own header above the page sets what
+  is left, `calc(100dvh - 4rem)`, which a phone's list page also takes as
+  its least height) and scroll on their own; the page is as
+  wide as the list plus a thread page (`--chats-max-width`).
+  Below 700px it is one column, exactly the separate pages: `/messages` is
+  the list, `/messages/:id` the thread with its back link. One media query
+  decides, so the layout holds before JavaScript and without it.
+- **A row opens its conversation in the pane.** Each row is a real link to
+  `/messages/:id` aimed at the frame (`data-turbo-frame`); the frame is
+  `data-turbo-action="advance"`, so the address bar and history follow, and
+  the server answers the frame with the pane alone (new `pane.html.erb`: the
+  header over `chats/conversations/_thread`, no list, no layout). A reload, a
+  deep link or back/forward renders the whole page, the row current
+  (`.chats-row--current`, `aria-current="page"`). The new `chats--split`
+  controller (`controllers/chats/split_controller`, pinned like the others)
+  enables the frame only on a wide screen; on a phone, before it connects
+  and without JavaScript, the same link opens the page. It also skips the
+  hover prefetch of a row while the frame is disabled (Turbo would ask for
+  the pane alone and then render it as the page), marks the row the pane
+  opened current at once, and takes the viewer into it, as LinkedIn does:
+  the focus goes to its composer, inside the pane a screen reader names
+  after the conversation; on a touch screen (`pointer: coarse`), and in a
+  locked conversation, to the pane's title (`tabindex="-1"`), so no
+  keyboard rises over a conversation not read yet.
+- **A filtered list stays filtered.** A row of a search's results or of a
+  stack (`?with=`) links to `/messages/:id?q=…` / `?with=…`: the address
+  bar names the list the page shows, so the list's refreshes, which
+  re-request it, keep it, and the pane's back link (phones) returns to it.
+- **The open conversation survives the list's refreshes.** The inbox's live
+  updates are Turbo 8 morphs of the whole page; the pane's thread sits in a
+  `data-turbo-permanent` element keyed by the conversation and the viewer
+  (`chats_conversation_pane_<id>_<viewer key>`), so a refresh re-renders the
+  rows and leaves the draft, the scroll position, the read state and the
+  stream subscription alone, while another conversation (another id)
+  replaces it. The pane's header (avatar, name, verified badge, subject, the
+  ⋯ menu) stays outside it, so a mute or a renamed group still shows. The
+  list and the pane each catch up on missed broadcasts once: a page refresh
+  for the list, the thread catch-up for the conversation.
+- **`config.inbox_layout`**, `:split` or `:stacked`, checked at boot (a
+  wrong value fails the initializer), in the generated initializer and the
+  README.
+
+### Changed
+- **When `/messages/:id` reads.** Opening a conversation still reads it: a
+  row clicked (the pane's frame), a link from elsewhere, a reload, a page
+  loaded without JavaScript. A Turbo visit of the two-pane page does not
+  read on the server, because the inbox's own refresh is one: it may arrive
+  in a background tab, and a read there said "Seen" while nobody looked and
+  refreshed the inbox again, in a loop. The pane renders `read-pending`
+  instead and its thread reads once it is on screen, as a dock window does.
+  A prefetched thread page (`:stacked`), which nothing used to read when
+  Turbo showed it, now reads itself the same way.
+- **The inbox's search form has no `action`**, so it searches whatever page
+  it is on (an HTML form without one submits to the page's URL): after a row
+  opened a conversation and moved the address bar to `/messages/:id`, a
+  search keeps that conversation open (`/messages/:id?q=…`) instead of
+  going back to `/messages`.
+- **The dock** drops a window whose conversation a frame of the page loads
+  (`turbo:frame-load`), as it did after a visit: one copy of a thread's DOM
+  ids per page, with `chats_dock everywhere: true` too.
+- **Templates.** Hosts with ejected views are unaffected: an app whose own
+  `index` or `show` came from a `rails generate chats:views` before 0.6
+  (no `_conversation_pane` of its own) keeps its separate pages, rendered
+  and read exactly as before; re-eject to get the panes. The bundled
+  templates that changed:
+  - `chats/conversations/index.html.erb`: the two-pane page (the list in
+    `nav.chats-split__list`, the `chats_conversation` frame), rendered for
+    `/messages/:id` too; the list alone under `:stacked`. The search form is
+    a bare `<form>` with no `action`.
+  - `chats/conversations/show.html.erb`: the thread page, now only under
+    `:stacked` (or for views ejected before 0.6); its header moved to the new
+    `chats/conversations/_thread_header.html.erb`, shared with the pane.
+  - new `chats/conversations/_conversation_pane.html.erb` (the pane:
+    `section.chats-split__pane`, labelled by its `h2` title, the header, and
+    the permanent `.chats-split__thread` around the thread),
+    `chats/conversations/_empty_pane.html.erb` (`.chats-split__empty`,
+    `--inbox` for an empty inbox) and `chats/conversations/pane.html.erb`
+    (the frame's answer).
+  - `chats/conversations/_thread.html.erb`: `pane:` (rooted at
+    `.chats-thread--pane`, inside the page's `.chats` shell) and
+    `read_pending:` locals.
+  - `chats/conversations/_conversation_row.html.erb` and `_group.html.erb`:
+    with `pane: true` the link carries
+    `data-turbo-frame="chats_conversation"` (a stack only when it holds one
+    conversation) and the list's `filter:` (`q`, `with`) in its URL, and
+    with `current:` the current row its class and `aria-current="page"`;
+    the `<li>`'s classes come from `class_names` (no trailing space).
+  - `chats/conversations/_thread_header.html.erb` takes `back_path:` (the
+    pane's keeps the list's filter) and gives a titled pane's heading
+    `tabindex="-1"`.
+  - `chats/dock/_dock.html.erb`: one more action,
+    `turbo:frame-load@document->chats--dock#pageFrameLoaded`.
+  - `chats.css`: the `chats-split`, `chats-split__list`,
+    `chats-split__conversation`, `chats-split__pane`, `chats-split__thread`,
+    `chats-split__empty` and `chats-thread--pane` rules and
+    `--chats-list-width`; `--chats-split-height` is read with a `100dvh`
+    fallback and never declared by the gem, so a host's declaration wins
+    wherever it is. The existing class names are unchanged, so a theme on
+    `.chats`, `.chats-row` or `.chats-thread` keeps applying.
+
+## [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

@@ -11,7 +11,7 @@ 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) · [Messaging dock](#-messaging-dock) · [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)
+**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) · [Two panes](#-two-panes) · [Messaging dock](#-messaging-dock) · [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
 
@@ -68,7 +68,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 bundled 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 — on a wide screen, the conversation list and the open conversation side by side, as on LinkedIn ([two panes](#-two-panes)). 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.
 
 An inbox lists the conversations that have **at least one message** (a system message or a deleted one counts). Opening a conversation (`chat_with`, the Message button) creates it, but until a first message exists it appears nowhere — not in the inbox, its stacks, search, the dock or any count — so nobody's inbox fills with "No messages yet" rows. It still opens when you go to it, which is where the first message gets written.
 
@@ -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 host's word is final: a host that must refuse a viewer entirely returns no scopes, and a product only ever adds a scope beside the host's, returning `super` unchanged when it is empty. A product page that renders a conversation on its own screen resolves it through this same lookup, so a host refusal holds there too.
 
 ## 🧱 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. On the [two-pane page](#-two-panes) the list and the open conversation are two surfaces: one refresh for the list, one thread catch-up for the conversation, which the refresh leaves alone |
+| 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.
@@ -536,6 +584,33 @@ Ejecting a whole screen to add one row or one button is too coarse. The bundled
 
 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.
 
+## 🪟 Two panes
+
+`/messages` is LinkedIn's messaging page: the conversation list on the left, the open conversation on the right. `/messages/:id` is that same page with its conversation open and its row highlighted, so a link to a conversation, a reload, back and forward all land where they should.
+
+![Two panes](docs/screenshots/split-inbox.png)
+
+Each row is a real link to `/messages/:id` (keeping the list's search or stack in its query, so the page's URL always names the list it shows). On a wide screen it opens the conversation in the right pane, a `turbo_frame_tag "chats_conversation"` whose `data-turbo-action="advance"` moves the address bar and history with it, and the server answers that frame with the pane alone. The pane's thread sits in a `data-turbo-permanent` element keyed by the conversation (and the viewer), so the inbox's live refreshes (Turbo 8 morphs of the whole page) re-render the list and leave the conversation alone: its draft, scroll position, read state and stream subscription. Opening one takes you into it, as on LinkedIn: the focus goes to its composer (on a touch screen, to its title, so the keyboard waits until you ask for it), inside a pane a screen reader names after the conversation.
+
+**On a phone** (under 700px wide, where the dock turns into a full-screen sheet) it is one column, exactly the separate pages as before: `/messages` is the list, and a row opens the conversation's page, with its back link to the list. One media query decides, so the layout holds before JavaScript runs and without it; with JavaScript off a row always opens the page.
+
+<img src="docs/screenshots/split-inbox-phone-list.png" alt="A phone: the messaging page is the conversation list" width="240"> <img src="docs/screenshots/split-inbox-phone-thread.png" alt="A phone: a conversation fills the screen, with its back link to the list" width="240">
+
+**Reads** happen when you open a conversation: a row clicked, a link, a reload. The page's own refreshes never read (one may arrive in a background tab), and a conversation the page renders unread reads itself as soon as it's on screen.
+
+The [messaging dock](#-messaging-dock) stays off this page, as on every engine page; its "See all messages" opens it, and a window's ⤢ opens its conversation here.
+
+```ruby
+config.inbox_layout = :split    # the default: two panes from 700px wide
+config.inbox_layout = :stacked  # separate pages at every width, as before 0.6
+```
+
+The list pane is `--chats-list-width` wide (320px), and the page as wide as the list plus a thread (`--chats-max-width`). It is as tall as the screen, so each pane scrolls on its own and the composer stays at the bottom. If your layout puts a header above it, say how much is left, or the page will scroll by the header's height:
+
+```css
+:root { --chats-split-height: calc(100dvh - 4rem); } /* 4rem: your header */
+``` Views ejected with `rails generate chats:views` before 0.6 keep their own separate pages; re-eject to get the panes.
+
 ## 🪟 Messaging dock
 
 LinkedIn and Steam don't send you to another page to answer a message: chats live in small windows in the bottom-right corner while you keep doing what you were doing. One line in your layout, for signed-in viewers, gives your app the same:
@@ -552,7 +627,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 +680,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
 
@@ -630,6 +705,8 @@ The bundled UI is intentionally framework-free (semantic `chats-*` classes + one
   --chats-accent: #facc15;           /* own bubbles, send button, badges */
   --chats-accent-contrast: #111827;
   --chats-verified: #0284c7;         /* the "official account" badge */
+  --chats-list-width: 320px;         /* the list beside an open conversation */
+  --chats-split-height: calc(100dvh - 4rem); /* the two-pane page under a 4rem header (default 100dvh) */
 }
 ```
 
@@ -639,7 +716,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`, `controllers/chats/dock_controller`, and `controllers/chats/split_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
 
@@ -681,6 +758,7 @@ Chats.configure do |config|
   # Inbox shaping
   config.inbox_limit = 200
   config.inbox_scope = ->(relation, viewer) { relation }
+  config.inbox_layout = :split              # :split (two panes from 700px wide) | :stacked
 
   # Ecosystem seams (no-op defaults; chats runs standalone)
   config.blocked_messager_ids = ->(messager) { [] }
@@ -706,6 +784,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 +834,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 +848,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 +892,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 +932,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.6.0 needs no migration: the messaging page becomes [two panes](#-two-panes) on wide screens by itself; `config.inbox_layout = :stacked` keeps the separate pages. Views you ejected before 0.6 keep rendering as they are (the separate pages); the [CHANGELOG](CHANGELOG.md) lists the templates that changed. 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