chats 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 233373c7319647cf267ec239c0227e7751deae6ea9a4afd8d94c578994c85a22
-  data.tar.gz: 02b7e37be81c69063969d202094430b1657640ea707a1f63e78c06876eb6877d
+  metadata.gz: a0635f1e1c801684a95223db2e59dbb843a67fd9edfe858973b4e9ac6bb32c2a
+  data.tar.gz: 9273751eca09bf387e640a45760f00dbd9875af8b8a75a1c2c4ae0de9ff2f527
 SHA512:
-  metadata.gz: 9bd561feaae573165ce631dac3e669b892d5d70271435a475bc36d92dc532fcd6f55b0b908415141845b47105600088dd739ae7adfeb520baf4cb4bcc0096127
-  data.tar.gz: ecd69642c82c827c53b5d038b8dd60f5853f5b012368c5d4db846b4549befbd4fd8b153b45d0468228cd77746b77b6c60dadd26ab5d36f73f2a31a4ec84a2edd
+  metadata.gz: 94843453f041d4ff766b577b8ba9c28f4a04123f6532e7c27109836dae84f9c354d3c3051cf7f6ad6ec4b05abcbc46e78deacaaec131d63cd0c1af5631bdf4c1
+  data.tar.gz: 0b61d2704ea93dd153e0b5ff899b9029b561f710f117955dd82f971a232a2891edc903b526af2cfe4438dfd3e655237a9a31dd9512f9406409a75675df138b94

data/CHANGELOG.md

@@ -4,6 +4,124 @@ 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

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.
 
@@ -99,7 +99,7 @@ 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.
+> 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
 
@@ -200,7 +200,7 @@ Triggers that arrive together make one catch-up, and catch-ups are at least five
 
 | 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 |
+| 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 |
@@ -584,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:
@@ -678,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) */
 }
 ```
 
@@ -687,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`, `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.
+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
 
@@ -729,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) { [] }
@@ -902,7 +932,7 @@ rails generate chats:upgrade   # 0.2.0: message authorship columns · 0.4.0: the
 rails db:migrate
 ```
 
-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.
+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
 

data/app/assets/stylesheets/chats.css

@@ -32,6 +32,13 @@
   --chats-bubble-text: #111827;
   --chats-radius: 1.1rem;
   --chats-max-width: 42rem;
+  /* The conversation list beside an open conversation (two panes). */
+  --chats-list-width: 320px;
+  /* --chats-split-height, how tall the two-pane page is, is NOT declared
+     here: the rules read it with the whole screen (100dvh) as the fallback,
+     so a host's own declaration wins wherever it is, even on a :root rule
+     loaded before this file (the bundled views link it in the body).
+     Under a host header: calc(100dvh - <the header's height>). */
 
   /* Safe areas, re-pointable by a host with its own source of truth. */
   --chats-safe-top: env(safe-area-inset-top, 0px);
@@ -1007,6 +1014,110 @@ turbo-frame[id^="chats_page_"] {
 }
 
 
+/* ---------------------------------------------------------------------------
+   0.6.0 — two panes (config.inbox_layout = :split)
+   ---------------------------------------------------------------------------
+
+   The messaging page as LinkedIn has it: from 700px wide (the dock's phone
+   rule, and chats--split's), the list on the left and the open conversation
+   on the right, both as tall as the screen, each scrolling on its own. Below
+   that, one column, exactly as the separate pages: /messages is the list,
+   /messages/:id the thread. Every request renders both panes; this media
+   query alone picks, so it holds before JavaScript runs and without it.
+
+     .chats-split                 the page (.chats.chats-inbox too)
+     .chats-split__list           the list's <nav>
+     .chats-split__conversation   the `chats_conversation` frame
+     .chats-split__pane           a conversation in it (section)
+     .chats-split__thread         its permanent wrapper, around .chats-thread--pane
+     .chats-split__empty          no conversation open (--inbox: no conversations at all)
+
+   The page is as wide as the list plus a thread page (--chats-max-width),
+   so the conversation reads at the width it always had, and as tall as
+   --chats-split-height (the screen; a host with its own header above the
+   page sets what is left: calc(100dvh - 4rem)). */
+.chats-split {
+  max-width: calc(var(--chats-list-width) + var(--chats-max-width));
+  /* The list alone (a phone): at least what is left of the screen, never
+     the shell's whole 100dvh, which would run past it under a host header. */
+  min-height: var(--chats-split-height, 100dvh);
+}
+.chats-split__list { display: flex; flex-direction: column; min-width: 0; }
+.chats-split__conversation {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+.chats-split__pane,
+.chats-split__thread {
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+/* The thread page's body, inside the pane: no shell of its own (the page is
+   the .chats shell), and the pane's height, not the screen's. */
+.chats-thread--pane {
+  flex: 1;
+  min-height: 0;
+  height: auto;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+.chats-split__empty { margin: auto; }
+.chats-row--current .chats-row__link {
+  background: var(--chats-surface);
+  box-shadow: inset 3px 0 0 var(--chats-accent);
+}
+
+@media (min-width: 700px) {
+  .chats-split {
+    box-sizing: border-box;
+    flex-direction: row;
+    height: var(--chats-split-height, 100dvh);
+    min-height: 0;
+    overflow: hidden;
+    /* Its edges, where a page wider than it shows the host's background. */
+    border-inline: 1px solid var(--chats-border);
+  }
+  .chats-split__list {
+    box-sizing: border-box;
+    flex: 0 0 var(--chats-list-width);
+    width: var(--chats-list-width);
+    border-right: 1px solid var(--chats-border);
+  }
+  /* The rows scroll; the title and the search stay. */
+  .chats-split__list > turbo-frame {
+    display: block;
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    overscroll-behavior-y: contain;
+  }
+  .chats-split__conversation { flex: 1 1 0; }
+  /* The list is right there: no way back to it. */
+  .chats-split .chats-thread__back { display: none; }
+}
+
+@media (max-width: 699.98px) {
+  /* A conversation open: the page is the thread, as tall as the screen. */
+  .chats-split:has(.chats-split__pane) {
+    height: var(--chats-split-height, 100dvh);
+    min-height: 0;
+    overflow: hidden;
+  }
+  .chats-split:has(.chats-split__pane) > .chats-split__list { display: none; }
+  .chats-split:has(.chats-split__pane) > .chats-split__conversation { flex: 1; }
+  /* None: the page is the list. The empty pane shows under it only to say
+     there are no conversations at all (the inbox's empty state lives there). */
+  .chats-split:not(:has(.chats-split__pane, .chats-split__empty--inbox)) > .chats-split__conversation {
+    display: none;
+  }
+}
+
 /* ---------------------------------------------------------------------------
    0.5.0 — the messaging dock (chats_dock)
    ---------------------------------------------------------------------------

data/app/controllers/chats/conversations_controller.rb

@@ -14,9 +14,12 @@ module Chats
     # 36): a client past either gets its history re-rendered instead.
     CURSOR_IDS_LIMIT = 200
     CURSOR_ID_LENGTH = 64
+    # The two-pane messaging page's conversation frame (index.html.erb): a
+    # request from it is answered with the pane alone (pane.html.erb).
+    PANE_FRAME = "chats_conversation"
 
     before_action :set_conversation, only: %i[show read typing leave mute unmute refresh]
-    helper_method :chats_counterpart
+    helper_method :chats_counterpart, :chats_two_panes?, :chats_inbox_filter
 
     # The inbox. Everything is preloaded/batched so rendering N rows costs a
     # constant number of queries (conversations + last messages + participants
@@ -29,14 +32,7 @@ module Chats
       # is the dock's own list.
       return dock if turbo_frame_request_id == "chats_dock_list"
 
-      @inbox = Chats::Inbox.for(chats_current_messager, query: params[:q], with: inbox_filter)
-      @rows = @inbox.rows
-      @unread_counts = @inbox.unread_counts
-      # Back-compat for inboxes ejected under 0.1.x, which loop over
-      # @conversations: they keep rendering the flat list (no stacking, i.e.
-      # exactly what they rendered before). Re-eject or delete your copy to
-      # get the stacked rows.
-      @conversations = @inbox.conversations
+      load_inbox
     end
 
     # The messaging dock's recent list (`chats_dock`): the first rows of the
@@ -67,6 +63,12 @@ module Chats
     # `?window=1` from a Turbo frame is the same thread as a floating dock
     # window: the window template (its compact header around the same
     # thread body), no layout.
+    #
+    # With two panes (`config.inbox_layout = :split`, the default) the
+    # thread is the conversation pane of the messaging page: the whole page
+    # (the inbox's template, with the pane open), or, asked from that page's
+    # own conversation frame (a row clicked on a wide screen), the pane
+    # alone. `:stacked` renders the thread page.
     def show
       @participant = @conversation.participant_for(chats_current_messager)
 
@@ -90,10 +92,14 @@ module Chats
           # swallow the unread badge. The thread controller posts #read once
           # the window is actually on screen (`read-pending`).
           render :window, layout: false
-        elsif !prefetch?
+        else
           # Opening the thread reads it. (Live appends while the thread
           # stays open are read via the thread controller's POST to #read.)
-          @participant&.read!
+          # A render the server doesn't read is marked `read-pending`: the
+          # thread controller reads it once it is on screen.
+          @read_pending = !reads_on_render?
+          @participant&.read! unless @read_pending
+          render_split_page if chats_two_panes?
         end
       end
     end
@@ -226,6 +232,90 @@ module Chats
       @conversation = find_conversation
     end
 
+    # The inbox's rows, for the inbox page and for the two-pane page.
+    def load_inbox
+      @inbox = Chats::Inbox.for(chats_current_messager, query: params[:q], with: inbox_filter)
+      @rows = @inbox.rows
+      @unread_counts = @inbox.unread_counts
+      # Back-compat for inboxes ejected under 0.1.x, which loop over
+      # @conversations: they keep rendering the flat list (no stacking, i.e.
+      # exactly what they rendered before). Re-eject or delete your copy to
+      # get the stacked rows.
+      @conversations = @inbox.conversations
+    end
+
+    # The open conversation on the two-pane page: the pane alone for the
+    # page's own conversation frame, else the whole page around it (any
+    # other frame of the page, the search's results among them, finds its
+    # own part in it).
+    def render_split_page
+      return render :pane, layout: false if pane_request?
+
+      load_inbox
+      render :index
+    end
+
+    def pane_request?
+      turbo_frame_request_id == PANE_FRAME
+    end
+
+    # Whether the messaging page is two panes: `config.inbox_layout = :split`
+    # (the default), unless this app ejected its views before there were
+    # two panes. `rails g chats:views` under 0.5 copied an inbox and a
+    # thread page and no conversation pane: that app keeps its own separate
+    # pages, rendered and read exactly as before, until it ejects again (or
+    # deletes its copies). Views ejected since 0.6 carry the pane, and are
+    # two panes like the gem's own.
+    def chats_two_panes?
+      return @chats_two_panes if defined?(@chats_two_panes)
+
+      @chats_two_panes = Chats.config.split_inbox? && !views_ejected_before_two_panes?
+    end
+
+    # The list's filter on the two-pane page: its search (`q`) or the stack
+    # it shows (`with`). A row opened in the pane carries it into its URL,
+    # /messages/:id?with=…, because that URL is what the list's live
+    # refreshes re-request: without it, the next refresh would bring back
+    # the whole inbox under a list that was filtered. The back link to the
+    # list keeps it too.
+    def chats_inbox_filter
+      { q: params[:q], with: params[:with] }.select { |_, value| value.is_a?(String) && value.present? }
+    end
+
+    def views_ejected_before_two_panes?
+      (own_view?("index") || own_view?("show")) && !own_view?("conversation_pane", partial: true)
+    end
+
+    # Whether the app renders its own copy of one of these views, not the gem's.
+    def own_view?(name, partial: false)
+      template = lookup_context.find_all(name, ["chats/conversations"], partial).first
+      template.present? && !template.identifier.to_s.start_with?(Chats::Engine.root.join("app/views").to_s)
+    end
+
+    # Whether showing the conversation reads it, there and then.
+    #
+    # Never a prefetch (Turbo 8 fetches a link the pointer rests on, which
+    # is nobody reading). On the thread page, everything else: opening it
+    # reads it.
+    #
+    # On the two-pane page, the viewer opening it: a row clicked (the
+    # pane's frame) or the page loaded by the browser itself (a link from
+    # elsewhere, a reload, no JavaScript). NOT a Turbo visit of the page,
+    # because one of those is the inbox's own refresh: every live update of
+    # the list re-requests this page, maybe in a hidden tab, and a read
+    # there would say "Seen" to the sender while nobody looks — and, since
+    # a read refreshes the reader's inbox, refresh the page again, forever.
+    # Turbo marks each of its requests (X-Turbo-Request-Id) and a refresh
+    # looks like any other visit, so a Turbo visit renders the pane unread
+    # and its thread reads it once it's on screen. A refresh's pane never
+    # gets that far: the page keeps its permanent one, and drops the new.
+    def reads_on_render?
+      return false if prefetch?
+      return true unless chats_two_panes?
+
+      pane_request? || request.headers["X-Turbo-Request-Id"].blank?
+    end
+
     def time_from_ms(value)
       Time.zone.at(0, value.to_i, :millisecond)
     end

data/app/javascript/chats/dock_controller.js

@@ -44,7 +44,9 @@ import { recoverMissedBroadcasts, renderStreamFrom } from "chats/recovery"
 //                  Every access is guarded: no storage, no memory, no harm.
 //   * hiding       on any page with [data-chats-dock-hide] (the engine's
 //                  inbox and thread), since a permanent element is never
-//                  re-rendered by the server
+//                  re-rendered by the server; and no window for a
+//                  conversation the page renders, after a visit or after a
+//                  frame of the page loads one
 //   * keyboard     Escape unwinds innermost first: the thread's popup or
 //                  photo, an edit, the window menu, then the window
 //                  (minimized), the panel (closed); on a phone, the window
@@ -782,6 +784,18 @@ export default class extends Controller {
     this.save()
   }
 
+  // A frame of the page itself loaded a conversation (the two-pane messaging
+  // page opens one beside its list without a visit): no window keeps a
+  // second copy of it.
+  pageFrameLoaded(event) {
+    if (this.element.contains(event.target)) return
+
+    this.windowTargets.forEach((frame) => {
+      if (this.renderedOnPage(frame.dataset.conversationId)) this.removeWindow(frame)
+    })
+    this.save()
+  }
+
   // A row whose conversation is open in a window says so.
   markOpenRows() {
     if (!this.hasListTarget) return