chats 0.4.1 → 0.5.0

data/app/views/chats/dock/_dock.html.erb

@@ -0,0 +1,130 @@
+<%# The messaging dock (`chats_dock` in the host's layout): fixed to the
+    bottom-right corner, LinkedIn / Steam style. Left to right, the floating
+    conversation WINDOWS (newest nearest the panel), then the PANEL: its
+    header is the collapsed bar (avatar, "Messages", unread badge), and open
+    it holds search, the recent list and the way to the full inbox. On a
+    phone (chats.css: under 700px wide or 500px tall) the closed bar is a
+    round button, the open panel a full-screen sheet.
+
+    data-turbo-permanent: Turbo Drive carries this element from page to page
+    as it is — open windows, scroll positions, drafts and cable
+    subscriptions included — as long as the next page renders a dock with
+    the same id. The id names the VIEWER, so a visit that lands on another
+    account's page (sign out and in, an account switcher) never matches and
+    never carries one person's windows into another's page.
+
+    The panel is a <details>: it opens and closes with no JavaScript at all,
+    and its rows, search and links are real links and forms. The chats--dock
+    controller (dock_controller.js) does the rest. Its live signal is the
+    template on the viewer's own `[messager, :chats_dock]` stream (see
+    chats/dock/_signal and Chats::Broadcasts). %>
+<% key = Chats.messager_key(viewer) %>
+<%= chats_styles %>
+<%= tag.aside id: "chats_dock_#{key}",
+      class: ["chats-dock", ("chats-dock--no-launcher" unless launcher)],
+      "aria-label": t("chats.dock.title"),
+      data: {
+        turbo_permanent: true,
+        chats_messager: key,
+        controller: "chats--dock",
+        "chats--dock-windows-value": windows,
+        "chats--dock-messager-value": key,
+        "chats--dock-everywhere-value": everywhere,
+        "chats--dock-window-url-value": chats_routes.conversation_path("__id__", window: 1),
+        "chats--dock-record-key-value": Chats::Conversation.model_name.param_key,
+        "chats--dock-announcement-value": t("chats.dock.new_message_from", name: "%{name}"),
+        # Plural forms uninterpolated: the controller fills %{count} in.
+        "chats--dock-window-unread-value": I18n.t("chats.dock.window_unread").to_json,
+        action: "keydown->chats--dock#keydown " \
+                "focusin->chats--dock#engage pointerdown->chats--dock#engage wheel->chats--dock#engage " \
+                "touchstart->chats--dock#engage " \
+                "turbo:before-fetch-response->chats--dock#frameResponded " \
+                "turbo:frame-missing->chats--dock#frameMissing " \
+                "turbo:frame-load->chats--dock#frameLoaded " \
+                "turbo:fetch-request-error->chats--dock#frameFailed " \
+                "turbo:submit-end->chats--dock#sent " \
+                "input->chats--dock#typed " \
+                "click@document->chats--dock#delegate " \
+                "turbo:before-stream-render@document->chats--dock#beforeStreamRender " \
+                "turbo:load@document->chats--dock#pageChanged turbo:render@document->chats--dock#pageChanged"
+      } do %>
+  <%= turbo_stream_from viewer, :chats_dock %>
+  <%= render "chats/dock/signal" %>
+
+  <div id="chats_dock_windows" class="chats-dock__windows" data-chats--dock-target="windows"></div>
+
+  <%# What a window shows before its thread arrives, and if it can't. %>
+  <template data-chats--dock-target="loadingShell"><%= render "chats/dock/window_shell", state: :loading %></template>
+  <template data-chats--dock-target="failedShell"><%= render "chats/dock/window_shell", state: :failed %></template>
+
+  <details class="chats-dock__panel"
+           data-chats--dock-target="panel"
+           data-action="toggle->chats--dock#panelToggled">
+    <%# The summary reads "Messages, 3 unread" from its own text; on a phone
+        the closed one is the round launcher (chats.css). %>
+    <summary class="chats-dock__bar chats-dock__toggle">
+      <%= chats_messager_avatar(viewer) %>
+      <svg class="chats-dock__icon" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+           stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
+        <path d="M12 3a9 9 0 0 0-7.8 13.5L3 21l4.6-1.2A9 9 0 1 0 12 3Z" />
+      </svg>
+      <span class="chats-dock__title"><%= t("chats.dock.title") %></span>
+      <%= render "chats/dock/badge", count: viewer.unread_chats_count %>
+      <span class="chats-dock__chevron" aria-hidden="true">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+             stroke-linejoin="round" focusable="false"><path d="m6 15 6-6 6 6" /></svg>
+      </span>
+      <span class="chats-dock__close-glyph" aria-hidden="true">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+             focusable="false"><path d="M6 6l12 12M18 6 6 18" /></svg>
+      </span>
+    </summary>
+
+    <div class="chats-dock__body">
+      <% if Chats.config.search %>
+        <%# The inbox's own search: with JavaScript the results land in the
+            dock's frame (the inbox answers that frame with the dock's list);
+            without it, on the full inbox. %>
+        <%= form_with url: chats_routes.conversations_path,
+              method: :get,
+              class: "chats-search chats-dock__search",
+              role: "search",
+              data: {
+                controller: "chats--debounced-submit",
+                action: "input->chats--debounced-submit#queue search->chats--debounced-submit#queue",
+                "chats--debounced-submit-delay-value": 250,
+                turbo_frame: "chats_dock_list"
+              } do %>
+          <%= hidden_field_tag :recent, recent, id: nil %>
+          <%= search_field_tag :q, nil,
+                id: "chats_dock_q",
+                placeholder: t("chats.inbox.search_placeholder"),
+                "aria-label": t("chats.inbox.search_placeholder"),
+                class: "chats-search__input",
+                autocomplete: "off" %>
+        <% end %>
+      <% end %>
+
+      <%# Lazy: nothing is fetched until the panel first opens; until then,
+          four still rows. The controller reloads it when the signal says. %>
+      <%= turbo_frame_tag "chats_dock_list",
+            src: chats_routes.dock_conversations_path(recent: recent),
+            loading: :lazy,
+            target: "_top",
+            class: "chats-dock__results",
+            # A click here opens a window, never the page: hovering a row
+            # must not prefetch it.
+            data: { "chats--dock-target": "list", turbo_prefetch: false } do %>
+        <div aria-busy="true" aria-label="<%= t("chats.thread.loading") %>">
+          <% 4.times do %><div class="chats-dock__skeleton"><span></span></div><% end %>
+        </div>
+      <% end %>
+
+      <%= link_to t("chats.dock.see_all"), chats_routes.conversations_path, class: "chats-dock__see-all" %>
+      <%= chats_slot :dock_panel_footer, viewer: viewer %>
+    </div>
+  </details>
+
+  <%# "New message from …": polite, one at a time. The badge is not live. %>
+  <div class="chats-visually-hidden" aria-live="polite" aria-atomic="true" data-chats--dock-target="announcer"></div>
+<% end %>

data/app/views/chats/dock/_signal.html.erb

@@ -0,0 +1,26 @@
+<%# What just changed, for the dock's controller (it acts when the replaced
+    element connects, and consumes data-changed so a Turbo Drive visit that
+    reconnects the same node never acts twice). An inert <template>: it
+    renders nothing. The dock renders it bare; Chats::Broadcasts sends it
+    with the signal:
+
+      data-changed               reload the recent list
+      data-conversation-id       the conversation it was about, when the
+                                 viewer can see it
+      data-notify                a message they'd be notified about: its
+                                 window may pop open, and it is announced
+      data-sender-name           who it is from, for the announcement
+      data-unread-count          unread there now, for the window's header
+
+    Strings for people are rendered by the dock in the VIEWER's locale
+    (Stimulus values), never here: a broadcast renders in no one's. %>
+<% signal = local_assigns[:signal] %>
+<%= tag.template id: "chats_dock_signal",
+      data: {
+        "chats--dock-target": "signal",
+        changed: (true if signal),
+        conversation_id: signal&.dig(:conversation_id),
+        notify: (true if signal&.dig(:notify)),
+        sender_name: signal&.dig(:sender_name),
+        unread_count: signal&.dig(:unread_count)
+      } %>

data/app/views/chats/dock/_update.turbo_stream.erb

@@ -0,0 +1,10 @@
+<%# One dock update (Chats::Broadcasts.update_dock_of), rendered per
+    participant and sent on their own `[messager, :chats_dock]` stream:
+    the badges when the unread count moved, and the signal. %>
+<% if count %>
+  <%= turbo_stream.replace_all ".chats-dock [data-chats-unread-badge]",
+        partial: "chats/dock/badge", locals: { count: count } %>
+<% end %>
+<% if signal %>
+  <%= turbo_stream.replace "chats_dock_signal", partial: "chats/dock/signal", locals: { signal: signal } %>
+<% end %>

data/app/views/chats/dock/_window.html.erb

@@ -0,0 +1,23 @@
+<%# A floating window's FRAME, loading its thread from `?window=1`
+    (conversations/window.html.erb). Appended to #chats_dock_windows by
+    ConversationsController#create (`chat_button_to …, dock: true`); the
+    dock's controller builds the identical element itself when a row or a
+    live message opens one (dock_controller.js, buildWindow) — keep the two
+    in step. A conversation already open in a window is focused instead of
+    reloaded (the controller intercepts the append).
+
+    `target: "_top"`: links inside a window open the page, never the frame.
+    `data-chats-active`: the viewer opened it, so it may mark messages read.
+    `data-focus`: and the composer takes the focus once the thread arrives. %>
+<%= turbo_frame_tag dom_id(conversation, :window),
+      src: chats_routes.conversation_path(conversation, window: 1),
+      target: "_top",
+      class: "chats-window",
+      data: {
+        "chats--dock-target": "window",
+        conversation_id: conversation.id,
+        chats_active: true,
+        focus: (true if local_assigns[:focus])
+      } do %>
+  <%= render "chats/dock/window_shell", state: :loading, title: conversation.title_for(chats_current_messager) %>
+<% end %>

data/app/views/chats/dock/_window_header.html.erb

@@ -0,0 +1,75 @@
+<%# A dock window's header. Rendered with the thread (window.html.erb) and,
+    with only a name, as the shell a window shows while it loads or after it
+    failed (chats/dock/_window_shell) — so minimize and close always work.
+
+    Locals: conversation (nil in the shell), title, counterpart (or nil). %>
+<% conversation = local_assigns[:conversation] %>
+<% counterpart = local_assigns[:counterpart] %>
+<header class="chats-window__header">
+  <%# Phones show one full-screen window: back returns to the list. %>
+  <button type="button" class="chats-window__icon chats-window__back"
+          aria-label="<%= t("chats.dock.back") %>" title="<%= t("chats.dock.back") %>"
+          data-action="chats--dock#back">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+         stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M19 12H5m6-6-6 6 6 6"/></svg>
+  </button>
+
+  <button type="button" class="chats-window__title" aria-expanded="true" title="<%= title %>"
+          data-chats-dock-minimize data-action="chats--dock#minimize">
+    <% if counterpart %>
+      <%= chats_messager_avatar(counterpart) %>
+    <% elsif conversation %>
+      <%= chats_conversation_avatar(conversation, chats_current_messager) %>
+    <% end %>
+    <span class="chats-window__identity">
+      <span class="chats-window__name-row">
+        <span class="chats-window__name" data-chats-dock-name><%= title %></span>
+        <%= chats_verified_badge(counterpart) %>
+      </span>
+      <% if conversation&.subject_label %>
+        <span class="chats-window__subject"><%= conversation.subject_label %></span>
+      <% end %>
+    </span>
+    <%# The conversation's unread count while the window waits to be seen
+        (filled in by the dock's controller). %>
+    <span class="chats-badge chats-window__unread" data-chats-dock-window-unread hidden></span>
+  </button>
+
+  <%# The host's own thread actions (block, report, view profile), as on
+      the page's ⋯ menu, with the same locals. %>
+  <% if conversation && chats_slot?(:conversation_header_actions) %>
+    <details class="chats-menu chats-window__menu">
+      <summary class="chats-window__icon" aria-label="<%= t("chats.thread.options") %>"
+               title="<%= t("chats.thread.options") %>">⋯</summary>
+      <div class="chats-menu__panel">
+        <%= chats_slot :conversation_header_actions,
+              conversation: conversation,
+              viewer: chats_current_messager,
+              counterpart: counterpart,
+              blockable: chats_blockable?(counterpart) %>
+      </div>
+    </details>
+  <% end %>
+
+  <% if conversation %>
+    <%= link_to chats_routes.conversation_path(conversation),
+          class: "chats-window__icon chats-window__expand",
+          title: t("chats.dock.open_full"), "aria-label": t("chats.dock.open_full"),
+          data: { turbo_frame: "_top" } do %>
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+           stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M15 3h6v6M9 21H3v-6M21 3l-7 7M3 21l7-7"/></svg>
+    <% end %>
+  <% end %>
+  <button type="button" class="chats-window__icon chats-window__minimize"
+          aria-label="<%= t("chats.dock.minimize") %>" title="<%= t("chats.dock.minimize") %>"
+          data-action="chats--dock#minimize">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+         aria-hidden="true" focusable="false"><path d="M5 12h14"/></svg>
+  </button>
+  <button type="button" class="chats-window__icon chats-window__close"
+          aria-label="<%= t("chats.dock.close") %>" title="<%= t("chats.dock.close") %>"
+          data-action="chats--dock#close">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+         aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6 6 18"/></svg>
+  </button>
+</header>

data/app/views/chats/dock/_window_shell.html.erb

@@ -0,0 +1,17 @@
+<%# What a window shows before its thread arrives, and if it never does: the
+    header (so minimize and close work) and a status line. The dock renders
+    it once, as <template>s its controller clones; `chats/dock/_window`
+    renders the loading one inside the frame it sends.
+
+    Locals: state (:loading or :failed), title (the name when known). %>
+<section class="chats-window__card" role="region" aria-label="<%= local_assigns[:title] || t("chats.dock.title") %>">
+  <%= render "chats/dock/window_header", title: local_assigns[:title] || t("chats.thread.loading") %>
+  <% if local_assigns[:state] == :failed %>
+    <div class="chats-window__status" role="alert">
+      <p><%= t("chats.dock.load_error") %></p>
+      <button type="button" class="chats-window__retry" data-action="chats--dock#retry"><%= t("chats.dock.retry") %></button>
+    </div>
+  <% else %>
+    <div class="chats-window__status"><%= t("chats.thread.loading") %></div>
+  <% end %>
+</section>

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

@@ -57,6 +57,7 @@
       <% if Chats.config.attachments %>
         <label class="chats-composer__attach" aria-label="<%= t("chats.composer.attach") %>">
           <%= form.file_field :files, multiple: true, hidden: true,
+                id: dom_id(conversation, :message_files),
                 accept: (Chats.config.attachments == :images ? "image/*" : nil),
                 data: { "chats--composer-target": "files", action: "change->chats--composer#filesChanged" } %>
           <span aria-hidden="true">📎</span>
@@ -64,14 +65,23 @@
         </label>
       <% end %>
 
+      <%# Ids per conversation, not form_with's `message_body`: a page can
+          hold several composers (the dock's windows), and Turbo restores
+          focus BY ID after rendering a stream — a shared id sent the cursor
+          into another window's composer. %>
       <%= form.text_area :body,
+            id: dom_id(conversation, :message_body),
             rows: 1,
             placeholder: t("chats.composer.placeholder"),
             class: "chats-composer__input",
             autocomplete: "off",
             data: {
               "chats--composer-target": "input",
-              action: "input->chats--composer#typed keydown.enter->chats--composer#enterSend"
+              # In a dock window, the dock puts a saved draft back the moment
+              # this field appears (dock_controller.js, composerTargetConnected).
+              "chats--dock-target": "composer",
+              action: "input->chats--composer#typed keydown.enter->chats--composer#enterSend " \
+                      "keydown.esc->chats--composer#escape"
             } %>
 
       <%# pointerdown/mousedown keepFocus: keeps the textarea focused (and the

data/app/views/chats/shared/_unread_badge.html.erb

@@ -1,6 +1,9 @@
 <%# The live unread badge (embed anywhere via the chats_unread_badge helper).
     Fixed id: it's the target Chats::Broadcasts.update_badge_of replaces.
-    Always rendered (hidden at zero) so the broadcast has an element to update. %>
+    Always rendered (hidden at zero) so the broadcast has an element to update.
+    data-chats-unread-badge marks every unread badge, the dock's included, for
+    host CSS and JS that want them all. %>
 <span id="chats_unread_badge"
       class="chats-badge chats-badge--floating"
+      data-chats-unread-badge
       <%= "hidden" unless count.positive? %>><%= count > 99 ? "99+" : count %></span>

data/config/importmap.rb

@@ -15,3 +15,4 @@ pin "controllers/chats/thread_controller", to: "chats/thread_controller.js"
 pin "controllers/chats/composer_controller", to: "chats/composer_controller.js"
 pin "controllers/chats/debounced_submit_controller", to: "chats/debounced_submit_controller.js"
 pin "controllers/chats/refresh_inbox_controller", to: "chats/refresh_inbox_controller.js"
+pin "controllers/chats/dock_controller", to: "chats/dock_controller.js"

data/config/locales/en.yml

@@ -54,6 +54,23 @@ en:
       send: "Send"
       attach: "Attach images"
       locked: "This conversation is closed."
+    dock:
+      title: "Messages"
+      unread_suffix: "unread"
+      see_all: "See all messages"
+      window_label: "Conversation with %{name}"
+      open_full: "Open full conversation"
+      minimize: "Minimize"
+      close: "Close conversation"
+      back: "Back to messages"
+      hello: "Say hello to %{name}."
+      load_error: "Couldn't load this conversation."
+      retry: "Try again"
+      new_message_from: "New message from %{name}"
+      window_unread:
+        one: "%{count} new message"
+        other: "%{count} new messages"
+      muted: "Muted"
     buttons:
       chat: "Message"
     flashes:
@@ -82,6 +99,7 @@ en:
             base:
               locked: "This conversation is closed."
               blocked: "You can't message this person."
+              not_allowed: "You can't message this person right now."
             action:
               invalid: "needs a label of up to %{count} characters and a link to an http(s) address or to a path on this site that starts with /"
             author:

data/config/locales/es.yml

@@ -54,6 +54,23 @@ es:
       send: "Enviar"
       attach: "Adjuntar imágenes"
       locked: "Esta conversación está cerrada."
+    dock:
+      title: "Mensajes"
+      unread_suffix: "sin leer"
+      see_all: "Ver todos los mensajes"
+      window_label: "Conversación con %{name}"
+      open_full: "Abrir la conversación completa"
+      minimize: "Minimizar"
+      close: "Cerrar conversación"
+      back: "Volver a los mensajes"
+      hello: "Saluda a %{name}."
+      load_error: "No se ha podido cargar esta conversación."
+      retry: "Reintentar"
+      new_message_from: "Nuevo mensaje de %{name}"
+      window_unread:
+        one: "%{count} mensaje nuevo"
+        other: "%{count} mensajes nuevos"
+      muted: "Silenciada"
     buttons:
       chat: "Mensaje"
     flashes:
@@ -82,6 +99,7 @@ es:
             base:
               locked: "Esta conversación está cerrada."
               blocked: "No puedes enviar mensajes a esta persona."
+              not_allowed: "Ahora mismo no puedes enviar mensajes a esta persona."
             action:
               invalid: "necesita un texto de hasta %{count} caracteres y un enlace a una dirección http(s) o a una ruta de este sitio que empiece por /"
             author:

data/config/routes.rb

@@ -5,6 +5,11 @@ Chats::Engine.routes.draw do
   # `mount Chats::Engine => "/messages"` the inbox is /messages, a thread is
   # /messages/:id, sending is POST /messages/:conversation_id/messages.
   resources :conversations, path: "", only: %i[index show create] do
+    # The messaging dock's recent list (`chats_dock`), served into its turbo
+    # frame. A collection route, so it is drawn before /:id and never read as
+    # a conversation id.
+    get :dock, on: :collection
+
     member do
       post :read    # advance the viewer's read horizon (mark as read)
       post :typing  # ephemeral "X is typing…" ping (see Chats::Broadcasts.typing)

data/gemfiles/rails_7.1.gemfile

@@ -26,6 +26,8 @@ group :test do
   gem "mysql2"
   gem "pg"
   gem "sqlite3"
+  gem "capybara", require: false
+  gem "selenium-webdriver", require: false
   gem "bootsnap", require: false
   gem "importmap-rails"
   gem "propshaft"

data/gemfiles/rails_7.2.gemfile

@@ -26,6 +26,8 @@ group :test do
   gem "mysql2"
   gem "pg"
   gem "sqlite3"
+  gem "capybara", require: false
+  gem "selenium-webdriver", require: false
   gem "bootsnap", require: false
   gem "importmap-rails"
   gem "propshaft"

data/gemfiles/rails_8.1.gemfile

@@ -26,6 +26,8 @@ group :test do
   gem "mysql2"
   gem "pg"
   gem "sqlite3"
+  gem "capybara", require: false
+  gem "selenium-webdriver", require: false
   gem "bootsnap", require: false
   gem "importmap-rails"
   gem "propshaft"

data/lib/chats/broadcasts.rb

@@ -4,7 +4,7 @@ require "action_view/record_identifier"
 
 module Chats
   # ALL of the gem's real-time fan-out, in one file — read this and you know
-  # the entire live behavior. Three streams exist:
+  # the entire live behavior. Four streams exist:
   #
   #   1. The CONVERSATION stream (`turbo_stream_from @conversation` on the
   #      thread page): surgical message append/replace/remove, the read-state
@@ -30,6 +30,23 @@ module Chats
   #      Deliberately separate from the inbox stream — if badges rode on it,
   #      every page embedding a badge would full-refresh on every message.
   #
+  #   4. The per-messager DOCK stream (`[messager, :chats_dock]`, subscribed
+  #      by the messaging dock — `chats_dock`). One render per participant
+  #      per event (chats/dock/_update), carrying up to two things:
+  #        * the dock's BADGES, with the same count as stream 3, whenever the
+  #          badge moves (a message for them, a read of theirs);
+  #        * the SIGNAL (chats/dock/_signal), replaced so the dock's
+  #          controller sees it connect: reload the recent list, and — for a
+  #          new message the participant should hear about — which
+  #          conversation it was, from whom, how much is unread there, and
+  #          that its window may pop open. Senders and edits/deletes get the
+  #          signal too (their lists reorder), never the pop-up.
+  #      The hint names a conversation only to a participant who can SEE it
+  #      (`messager.chats`: blocks and `inbox_scope` applied) — the dock's
+  #      own list and window endpoints refuse anything else, and the stream
+  #      must not tell them what those hide. No polling, no Action Cable
+  #      channel of our own.
+  #
   # Everything uses the `_later` variants (rendering happens in background
   # jobs, never inline in the request) except `message_destroyed`, where the
   # record is gone and can't be serialized for a job.
@@ -38,6 +55,7 @@ module Chats
 
     MESSAGE_PARTIAL = "chats/messages/message"
     BADGE_PARTIAL = "chats/shared/unread_badge"
+    DOCK_UPDATE_PARTIAL = "chats/dock/update"
     READ_STATE_PARTIAL = "chats/conversations/read_state"
 
     class << self
@@ -51,7 +69,7 @@ module Chats
           locals: { message: message }
         )
 
-        fan_out_inboxes(conversation, skip_badge_for: message.sender)
+        fan_out_inboxes(conversation, skip_badge_for: message.sender, message: message)
       end
 
       def message_updated(message)
@@ -111,7 +129,17 @@ module Chats
         Turbo::StreamsChannel.broadcast_refresh_later_to(messager, :chats_inbox)
       end
 
-      def update_badge_of(messager)
+      # The unread badges of +messager+: the nav badge (stream 3) and the
+      # dock's (stream 4), with the signal that tells the dock what changed.
+      # +conversation+ and +message+ say what happened (both nil for a
+      # read); +participant+ is the messager's seat there.
+      def update_badge_of(messager, conversation: nil, message: nil, participant: nil)
+        # Counted at broadcast-enqueue time: the badge is advisory UI; a
+        # count that's seconds stale self-heals on the next event. The SAME
+        # count the page renders (`chats_unread_badge`), so what the inbox
+        # scope hides never lights the badge. Counted once for both.
+        count = messager.unread_chats_count
+
         # REPLACE, not update: the partial renders the whole badge element
         # (its id included) — an `update` would nest it inside the existing
         # element and duplicate the id. Replace keeps it idempotent.
@@ -119,11 +147,23 @@ module Chats
           messager, :chats_badge,
           target: "chats_unread_badge",
           partial: BADGE_PARTIAL,
-          # Counted at broadcast-enqueue time: the badge is advisory UI; a
-          # count that's seconds stale self-heals on the next event. The
-          # SAME count the page renders (`chats_unread_badge`), so what the
-          # inbox scope hides never lights the badge.
-          locals: { count: messager.unread_chats_count }
+          locals: { count: count }
+        )
+
+        update_dock_of(messager, count: count, conversation: conversation, message: message, participant: participant)
+      end
+
+      # The dock's update (stream 4): the badges when +count+ is given, and
+      # the signal. A conversation the messager cannot see is never named:
+      # its badge count is still truthful, the signal is simply not sent.
+      def update_dock_of(messager, count: nil, conversation: nil, message: nil, participant: nil)
+        signal = dock_signal(messager, conversation, message, participant)
+        return if count.nil? && signal.nil?
+
+        Turbo::StreamsChannel.broadcast_render_later_to(
+          messager, :chats_dock,
+          partial: DOCK_UPDATE_PARTIAL,
+          locals: { count: count, signal: signal }
         )
       end
 
@@ -133,15 +173,41 @@ module Chats
       # the sender's — their OTHER tabs/devices need the new ordering; the
       # originating tab skips its own refresh via Turbo's request-id dedup),
       # and every participant except the sender gets a fresh unread badge.
-      def fan_out_inboxes(conversation, skip_badge_for: nil, badges: true)
+      # Everyone else — the sender, and every seat on an edit or a delete —
+      # gets the dock's list refresh alone.
+      def fan_out_inboxes(conversation, skip_badge_for: nil, badges: true, message: nil)
         conversation.participants.active.includes(:messager).each do |participant|
           messager = participant.messager
           next if messager.nil?
 
           refresh_inbox_of(messager)
-          update_badge_of(messager) if badges && messager != skip_badge_for
+          if badges && messager != skip_badge_for
+            update_badge_of(messager, conversation: conversation, message: message, participant: participant)
+          else
+            update_dock_of(messager, conversation: conversation)
+          end
         end
       end
+
+      # What the dock is told, or nil for nothing at all. A read (no
+      # conversation) only reloads the list. A conversation the messager
+      # can't see (blocked, scoped out) is never named. A new message the
+      # participant would be notified about (Participant#notifiable_for?:
+      # not theirs, not muted, not a headless seat) may pop its window and
+      # be announced, with who it is from and how much is unread there.
+      def dock_signal(messager, conversation, message, participant)
+        return {} if conversation.nil?
+        return nil unless messager.chats.exists?(conversation.id)
+
+        signal = { conversation_id: conversation.id }
+        return signal unless message && participant&.notifiable_for?(message)
+
+        signal.merge(
+          notify: true,
+          sender_name: message.sender ? Chats.display_name_for(message.sender) : conversation.title_for(messager),
+          unread_count: participant.unread_count
+        )
+      end
     end
   end
 end