support_desk 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66ba1a32f86acca1b4068bbca4091fcb16c4e6840a9d57ae5dc44bea25572ea2
-  data.tar.gz: 2433e492636e42eeffde1652a2c7d21915267c6f0a9180bea8bb010d902cdfad
+  metadata.gz: f20ef59f51139224d4dc822bc4d96eced0d5517e6b308399f707d43eef11d229
+  data.tar.gz: fde3321433991bb1c7aa89a944e57a5fa4cd7cf19da1ba3444f8a81289b962ab
 SHA512:
-  metadata.gz: ac1246120f4c2aa2763f81866006f054e0dfd14901d42120ddc25d754b08dad350b1627552faaa9e4fd62d37a50d785eeae9abe6dab1c5dc9adbb9f9bb44acd1
-  data.tar.gz: 66fca7c4ddad8c9b41358448ec24beda2a3dcd9bade8bd373fe7433a565700d500c212f863c1755048faa7dd803c79c1fa92d3fb0b029a072322d1eff6672994
+  metadata.gz: 0fcd4009a005176029c7f2c07dc5f4a4dd7c6bee5a46428025d9ccc56d30f9b2a76170713d9362a3f5aab658f34c0f9c0ad151d048969fc7b7a0ea3b641ec724
+  data.tar.gz: ae545aeec1cac66db40a3df1777fd2c7747dda0103c99d7424b55d06cbbd6dd67cb9cb8b1685e642d97f82153afc2ea149257967957da63b2e1524a7c437bf52

data/CHANGELOG.md

@@ -4,6 +4,140 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-10-19
+
+Intended as **0.5.0**: "Need help?" in the corner. **Requires chats >= 0.7.1**
+(its tray and its `:unread_changed` event). No migration; nothing changes
+until you render the launcher.
+
+### Added
+
+- **The launcher.** `support_launcher` puts a "Need help?" tab in the
+  bottom-right corner: in chats' messaging dock's tray, beside its bar
+  (`chats_dock { support_launcher }`), or in a corner of its own when there is
+  no dock. Its panel is this engine's own screens in a frame — their open
+  cases, a new case (the wizard, with the promise under the form), a case's
+  thread — so nobody leaves the page they are on. chats draws and runs the
+  chrome (one menu open at a time, the windows giving it room, Escape,
+  memory, the phone's round button and full-screen sheet); this engine ships
+  no JavaScript for it. `show_for: :everyone` shows it to visitors who are
+  signed out too, whose panel says how to reach the desk (sign in through
+  `/support`, the desk's `config.email`, the host's `help_url:`).
+- **The panel is the pages.** A request from the panel's frame
+  (`Turbo-Frame: support_desk_panel`, `SupportDesk::Launcher.panel_request?`)
+  is answered with the screen's panel template (`support_desk/panel/home`,
+  `new`, `case`, and the limit wall) inside `layouts/support_desk/panel`;
+  every other request renders exactly as before. In the panel a new case
+  opens in the panel, and so does any case, whatever `thread_page` says. A
+  case there is chats' compact thread body (`window: true`), which reads
+  itself once the panel is open (the server never reads a panel render: a
+  frame loading behind a closed panel must not put the badge out). The limit
+  wall has its own panel screen (`support_desk/panel/rate_limited`, the
+  page's content from `tickets/_limit_wall`).
+- **A live badge.** `unread_support_count` on the requester's
+  `[requester, :support_desk]` stream, replaced wherever chats says an unread
+  count in a case may have moved (`Chats.on(:unread_changed)`), the case's own
+  notices included, and asked again from `GET /support/tickets/badge` when the
+  stream missed one. The Messages badge never counts it. One small job per
+  message in a case, counting as it renders, whether or not the host renders
+  a launcher: a job cannot tell whether anybody listens, and a switch would
+  let a launcher's badge silently never move.
+- `support_panel?`, `support_desk_top_frame` (the frame a link that leaves a
+  step targets: `"_top"` on a page, the panel in the panel), and
+  `support_desk_slot` with two slots, `panel_top` and `panel_footer`.
+- `support_desk.launcher.*` in en and es; `rails g support_desk:views` ejects
+  the launcher and its panel's screens too (`--views launcher`).
+
+### Changed
+
+- The requester partials that targeted `_top` (`_pick_topic`, `_pick_thing`,
+  `_write`, `_wizard_header`) use `support_desk_top_frame`, and
+  `support_thread_path` leads to the ticket page in the panel. **If you
+  ejected them and use the launcher**, make the same change in your copies,
+  or their links leave the panel for the page.
+- The dummy app loads Turbo and Stimulus for real (its importmap pinned
+  neither, so the browser tests ran on plain HTML), and two tests that leaned
+  on that were corrected: the console's refused send is rendered in place by
+  Turbo, and the thread page under chats 0.6's two panes shows the inbox's
+  badged desk row beside the thread.
+
+## [0.4.0] - 2026-10-18
+
+### Added
+
+- **Support apart from the inbox.** `config.thread_page = :support` reads a
+  case on the engine's own page, `/support/tickets/T-AB12CD`, which renders
+  chats' thread template (same bubbles, composer and realtime) with its way
+  back leading to the support list. `support_thread_path`, the list rows and
+  the redirect after opening a case follow the setting. The default,
+  `:chats`, is unchanged. A third Hotwire Native rule pushes the ticket page
+  under `:support`.
+- **A requester's own case always opens through chats.** chats finds every
+  thread and composer request through `viewer.chats`, which applies the
+  host's `inbox_scope`; a host keeping support out of its inbox would 404 its
+  requesters inside their own cases. The engine adds the viewer's own cases
+  to chats' `conversation_lookup_scopes` (`SupportDesk::ConversationAccess`,
+  `SupportDesk::Ticket.conversations_of`): by participation and blocks,
+  without the listing scope, each a direct conversation whose subject is that
+  very case. Nothing else the scope hides becomes reachable.
+- **`acknowledgement`**, a desk setting: the system line posted right under a
+  requester's first message, in the same transaction, and read for them as
+  it is posted (a receipt for their own words is never news). Same values and
+  interpolations as `opening_line`; nil by default, and the gem ships
+  `support_desk.thread.acknowledgement` to opt into.
+- An I18n key given as a line reads its `<key>_with_promise` variant when the
+  desk promises a time and the variant exists (the assistant lines already
+  did): the shipped acknowledgement is "Thanks, we got it." on a desk with
+  `reply_within = nil`, and adds the promise otherwise.
+- `SupportDesk.humanize_promise` and `DeskConfiguration#reply_promise`: the
+  promise in the unit the desk wrote it in, from the new
+  `support_desk.durations.*` keys.
+- `support_desk.thread.closed_notice` can interpolate `%{reply_within}`,
+  `%{desk}` and `%{label}`.
+
+### Changed
+
+- The answer promise (`support_reply_promise`, the wizard's line, and
+  `%{reply_within}` in every line) is now said in the unit `reply_within`
+  was configured in: `24.hours` reads "24 hours" where it read "1 day", and
+  `8.hours` reads "8 hours" where it read "about 8 hours". A duration of more
+  than one unit, or a fractional one, reads as before. Waits in the console
+  are unchanged.
+
+### Fixed
+
+- `SupportDesk::ConversationAccess` adds a requester's own cases as a lookup
+  scope (`conversation_lookup_scopes`, chats 0.5.1) instead of rescuing chats'
+  404: no exception is inspected, and a host's own `find_conversation` that
+  refuses a case is final. It only ever adds a scope beside the host's: a host
+  that returns no scopes for a viewer (a suspended account) opens nothing for
+  them, their cases included.
+- The ticket page resolves its conversation through chats' own
+  `find_conversation` (a chats controller bound to the request), so whatever
+  refuses a case at the chats URL refuses it on the ticket page too.
+- The access fallback and the ticket page require the case and its
+  conversation to point at each other (a direct conversation whose subject is
+  that case): a ticket mislinked to a group or to another conversation opens
+  nothing.
+- The ticket page resolves its conversation through chats' participation and
+  block rules: owning the case is no longer enough once the seat is gone.
+- The support list's "showing the N most recent" line under a long closed
+  section (`support_desk.tickets.closed_capped`) had no copy in English or
+  Spanish, so a requester with more than 20 closed cases read "translation
+  missing".
+
+### Compatibility
+
+- Requires chats >= 0.5.1; take both from GitHub by tag until they are on
+  rubygems. (The old `~> 0.3, >= 0.3.2` already admitted 0.4 and 0.5: `~> 0.3`
+  is `>= 0.3, < 1.0`.) 0.5.1 brings the lookup seam the access to a
+  requester's own case is built on. The whole suite runs on chats 0.5.1, the
+  reviewed package in `vendor/cache` built from tag v0.5.1 (6159ea1). The
+  chats 0.4.2 CI leg is gone: the constraint no longer admits it. Every CI job
+  asserts the chats it resolved (`CHATS_VERSION_UNDER_TEST`), so a later chats
+  release never silently becomes what CI tests. The dummy app's chats
+  migration is chats' current install template.
+
 ## [0.3.2] - Unreleased
 
 ### Fixed

data/README.md

@@ -153,6 +153,7 @@ configuration mistake is a boot failure, never a 3 a.m. `NoMethodError`.
 | `current_agent_method` | `:current_user` | how the console finds the person answering (or define `current_agent` in your controller) |
 | `authenticate_method` | `:authenticate_user!` | your own filter, run before every requester screen |
 | `visible_desks_for` | `nil` (every desk) | `->(agent) { … }` returning the desks this agent may work; scopes the whole console |
+| `thread_page` | `:chats` | where a requester reads a case: `:chats` (its thread in the chats inbox) or `:support` (this engine's own ticket page, for support kept apart from the inbox; see [Support apart from the inbox](#support-apart-from-the-inbox)) |
 | `authorize_console` | `nil` (allow) | `->(agent, ticket, action) { … }`; asked before every console action, `ticket` is nil for `index`, `new`, `next` and `open_conversation`; a hook that raises **denies** |
 | `assistant(key) { … }` | — | declare an assistant (see [Assistants](#-assistants)); `config.assistants`, `config.assistant?(key)` read them back |
 | `default_assistant` | the only one declared | which assistant the `:default` desk gets when more than one exists |
@@ -185,7 +186,7 @@ SupportDesk.desk(:billing)  # another one (nil if nobody configured it)
 | `reply_policy` | `:anyone` | `:anyone` (a drop-in posts, signed; an unheld case is taken by whoever answers) · `:take_over` (replying reassigns) · `:assignee_only` (raises `NotAllowed`) |
 | `announce_assignments` | `:first_only` | `:first_only` ("Lucía is taking care of your request" once) · `:always` (hand-offs too) · `:never` |
 | `closed_tickets` | `:reopen_on_reply` | `:reopen_on_reply` (a requester writing reopens the case) · `:locked` (composer replaced by a notice) |
-| `reply_within` | `24.hours` | the SLA breach threshold **and** the promise the requester reads |
+| `reply_within` | `24.hours` | the SLA breach threshold **and** the promise the requester reads, said in the unit you write it in (`72.hours` reads "72 hours") |
 | `at_risk_after` | `4.hours` | when a waiting case starts showing as at risk |
 | `open_rate_limit` | `{ to: 5, within: 1.hour }` | how often one requester may **ask**; `nil` disables. Counts only cases the requester opened |
 | `max_open_tickets` | `5` | how many cases one requester may have open; `nil` disables. Same rule |
@@ -195,6 +196,7 @@ SupportDesk.desk(:billing)  # another one (nil if nobody configured it)
 | `auto_close_after` | `nil` | reserved for the sweep job: a duration after which an answered case closes itself |
 | `opening_line` | `nil` | the system line a requester-opened thread starts with (see [Writing first](#writing-first)) |
 | `opening_line_from_support` | the gem's I18n copy | the same line for a case the desk opened |
+| `acknowledgement` | `nil` | the system line posted right under a requester's first message ("Thanks, we got it…"; see [Writing first](#the-line-a-thread-opens-with)) |
 | `find_requester { \|query\| … }` | `nil` | how a console turns what an agent typed into a requester record |
 
 `SupportDesk.doctor.print` checks all of it against a running app (see
@@ -410,7 +412,7 @@ mount SupportDesk::Engine => "/support"   # CarHey mounts it at "/messages/suppo
 | `GET /support` | their cases — open ones as chats rows, closed ones folded away, and the door into a new one |
 | `GET /support/new` | the wizard: pick a topic, pick the thing, write. One URL, three Turbo frames |
 | `POST /support/tickets` | `ask_support!`, then straight into the conversation |
-| `GET /support/tickets/:id` | a stable URL for a case (`/support/tickets/T-AB12CD` works too), redirecting to its thread |
+| `GET /support/tickets/:id` | a stable URL for a case (`/support/tickets/T-AB12CD` works too): a redirect to its thread, or the page it is read on under `thread_page = :support` |
 
 The screens inherit `config.parent_controller`, so your layout, your
 authentication (`config.authenticate_method`) and your locale switching all
@@ -440,6 +442,54 @@ door in its place (`config.inbox_entry = :always | :when_tickets | :never`) —
 a support entry that only exists once you already have a ticket is
 undiscoverable.
 
+### Support apart from the inbox
+
+Some products want support to be a place of its own: a Support button that
+leads to the person's cases, rather than an official row among their
+conversations. Three settings say so:
+
+```ruby
+# config/initializers/support_desk.rb
+config.thread_page = :support     # a case is read at /support/tickets/T-AB12CD
+config.inbox_entry = :never       # no door in the chats inbox
+
+# config/initializers/chats.rb: support conversations out of the inbox, the unread badge and everything else that lists
+config.inbox_scope = ->(relation, _viewer) {
+  relation.where(subject_type: nil).or(relation.where.not(subject_type: "SupportDesk::Ticket"))
+}
+```
+
+(`subject_type: nil` keeps the conversations that are about nothing, which is
+most of them: `where.not` alone would hide those too.)
+
+The ticket page **is chats' thread**: the engine renders chats' own template,
+so the bubbles, the composer, read state, typing and realtime are the ones
+every other conversation has, with the desk's verified name in the header.
+Only the way back differs: it leads to the support list. Older pages, the
+composer and the live updates still go to chats' endpoints.
+
+Those endpoints find a conversation through the relations chats'
+`conversation_lookup_scopes` returns (chats >= 0.5.1), by default the viewer's
+inbox with the host's `inbox_scope` applied, so a scope that keeps support out
+of the inbox would also keep a requester out of their own case. The engine
+adds one relation after chats' own (`SupportDesk::ConversationAccess`): the
+viewer's **own** cases (`SupportDesk::Ticket.conversations_of`), through the
+same participation and block rules (`Chats::Conversation.inbox_for`) without
+the listing scope, each a direct conversation whose subject is that very
+case. Nobody gains a conversation they are not seated in, anything else the
+scope hides stays a 404, and a host's own `find_conversation` that refuses a
+case still refuses it. support_desk only ever adds a scope beside the host's:
+a host that must refuse a viewer entirely returns no scopes, and then nothing
+opens for them, their cases included. The ticket page asks chats the same
+question (chats' own `find_conversation`), so it never shows what the chats
+URL would refuse.
+
+Links follow the setting: `support_thread_path`, the list's rows and the
+redirect after a case is opened all lead to the ticket page, by reference.
+Telling the requester an answer arrived is then yours, since the chats
+badge no longer counts it: subscribe to `agent_replied` (see [Events](#events))
+and link the notification to `support_desk.ticket_path(ticket.reference)`.
+
 Hotwire Native hosts merge the engine's path rules into their own, AFTER any
 rule that could swallow them:
 
@@ -455,14 +505,90 @@ Both surfaces are pushed screens, never modals: every wizard step is a real
 URL, so the back gesture and cold-boot deep links work.
 
 
+### "Need help?" in the corner: the launcher
+
+The support pages are where help lives; the launcher is the door that is
+always there. One line puts a **Need help?** tab in the bottom-right corner,
+and its panel is the same screens in a frame: their open cases, a new case
+(the wizard, with the promise under the form), a case's thread. Nobody leaves
+the page they were on.
+
+```erb
+<%# A host with chats' messaging dock: the launcher sits in the dock's tray, beside its bar %>
+<%= chats_dock do %>
+  <%= support_launcher %>
+<% end %>
+
+<%# A host without the dock: the launcher brings the corner with it %>
+<%= support_launcher %>
+```
+
+![The launcher beside the messaging dock's bar](https://raw.githubusercontent.com/rameerez/support_desk/main/screenshots/launcher/bar.png)
+
+| Their cases | A case, in the panel | A new one |
+| --- | --- | --- |
+| ![The panel: the way to a new case with its promise, and the open cases](https://raw.githubusercontent.com/rameerez/support_desk/main/screenshots/launcher/panel.png) | ![A case's thread in the panel, an answer signed by the agent](https://raw.githubusercontent.com/rameerez/support_desk/main/screenshots/launcher/case.png) | ![The wizard's last step in the panel, the promise under the form](https://raw.githubusercontent.com/rameerez/support_desk/main/screenshots/launcher/new.png) |
+
+It is an item of chats' **tray** (chats >= 0.7.1), so chats draws the tab,
+the panel's chrome and the phone's sheet, and runs them: one menu open at a
+time with the Messages panel, the windows giving it room rather than being
+covered, Escape, the open item remembered on a desk, a 48px round button and a
+full-screen sheet on a phone (`chats_dock launcher: false` takes the buttons
+away). The look is the dock's, themed with the same `--chats-dock-*`
+variables. This engine ships no JavaScript of its own for it.
+
+- **The panel is the pages.** A request from the panel's frame
+  (`Turbo-Frame: support_desk_panel`) is answered with the screen's panel
+  template (`support_desk/panel/home`, `new`, `case`) inside
+  `layouts/support_desk/panel`; every other request renders exactly as before.
+  Links that leave a step target the panel instead of the page
+  (`support_desk_top_frame`), a case opens in the panel whatever
+  `thread_page` says (`support_thread_path`), and a new case opens there
+  after it is sent. ⤢ opens the case's page; "All your conversations" the
+  list, closed ones included.
+- **A case in the panel is chats' thread**, the compact body a dock window
+  renders: live, the composer at the bottom, the desk's signature, the way to
+  a person. It is read only while the panel is open (the tray item is the
+  thread's read gate), and when the page itself shows the same case (its
+  page, or a dock window), the panel goes back to the list rather than show
+  it twice.
+- **The badge** is `unread_support_count`, unread messages across their own
+  cases (the number `support_unread_badge` shows), live on the requester's
+  `[requester, :support_desk]` stream: it moves wherever chats says an unread
+  count may have moved (`:unread_changed`), the case's own notices included,
+  and catches up from `GET /support/tickets/badge` when the stream missed one.
+  It never touches the Messages badge, which counts the inbox (your
+  `inbox_scope` applied): a host that keeps support out of the inbox gets two
+  separate numbers. The open list reloads in place when it moves.
+- **Signed out**, `support_launcher show_for: :everyone` shows the same tab,
+  and its panel says how to reach you: sign in (through `/support`, so your
+  own authentication asks and brings them back), the desk's `config.email`
+  for those who can't, and your help centre (`help_url:`).
+
+<img src="https://raw.githubusercontent.com/rameerez/support_desk/main/screenshots/launcher/phone-sheet.png" alt="A phone: the panel is a full-screen sheet" width="240"> <img src="https://raw.githubusercontent.com/rameerez/support_desk/main/screenshots/launcher/signed-out.png" alt="Signed out: how to reach the desk" width="400">
+
+```erb
+<%= support_launcher show_for: :everyone, help_url: "https://example.com/help" %>
+```
+
+The words are `support_desk.launcher.*` (override them in your own locale
+files); the icon is `support_desk/launcher/_icon` (eject it to draw your own).
+Two slots put your own content in the panel, above and below it:
+`app/views/support_desk/slots/_panel_top.html.erb` and `_panel_footer.html.erb`
+(both get `requester:`, nil when signed out). The `/support` pages stay the
+place support lives; keep your Support links to them.
+
 ### Every helper the requester views can use
 
 | helper | what it renders |
 |---|---|
 | `link_to_support(about:, text:, **html)` | the door into the wizard (nothing when there is nobody to ask, or nothing they may ask about) |
+| `support_launcher(show_for: :signed_in, help_url: nil)` | the ["Need help?" launcher](#need-help-in-the-corner-the-launcher), in chats' tray |
 | `support_unread_badge` | unread support messages, counted against the chats read horizon |
+| `support_panel?` / `support_desk_top_frame` | whether this render answers the launcher's panel; the frame a link that leaves a step targets (`"_top"`, or the panel) |
+| `support_desk_slot(name, **locals)` | the launcher panel's `panel_top` / `panel_footer` slots |
 | `support_desk_styles` | the bundled stylesheet tag for your `<head>` |
-| `support_reply_promise` | "We usually reply in under 24 hours", from `reply_within` |
+| `support_reply_promise` | "We usually reply in under 24 hours", from `reply_within` (also `SupportDesk.config.desk(key).reply_promise`) |
 | `support_ticket_state(ticket)` | "We're on it" · "We replied" · "We wrote to you" · "Closed" |
 | `support_inbox_door?(viewer)` | whether the inbox should show the door instead of a row (`inbox_entry`) |
 | `support_desk_record(key)`, `support_desk_avatar`, `support_desk_badge` | the desk as a counterpart: record, avatar (initials fallback), verified badge |
@@ -482,8 +608,9 @@ the screens yours:
 rails generate support_desk:views
 ```
 
-That copies `app/views/support_desk/tickets/**` and the two rows this engine
-contributes to chats' screens (`app/views/chats/slots/**`) into your app,
+That copies `app/views/support_desk/tickets/**`, the launcher and its panel's
+screens (`support_desk/launcher/**`, `support_desk/panel/**`) and the two rows
+this engine contributes to chats' screens (`app/views/chats/slots/**`) into your app,
 where they shadow the gem's copies — the Devise move. Delete your copy and
 the default comes back; upgrade the gem and your copy is untouched. Every
 view helper the templates use stays available afterwards, so an ejected copy
@@ -682,6 +809,33 @@ existing threads open exactly as they do today; `opening_line_from_support`
 has the gem's own copy as its default, because a message from a desk
 somebody never wrote to has to explain itself.
 
+And one line goes **under** the first message, for a case the requester
+opened: the answer to "did that go through?", posted in the same
+transaction, before anybody on the desk has read it.
+
+```ruby
+config.acknowledgement = :"support_desk.thread.acknowledgement"
+# => "Thanks, we got it. We usually reply in under 72 hours."
+```
+
+An I18n key reads its `<key>_with_promise` variant when the desk promises a
+time and the variant exists (the shipped key has one), so a desk with
+`reply_within = nil` says "Thanks, we got it." and nothing it cannot keep.
+The requester's read horizon moves through the acknowledgement as it is
+posted: it is a receipt for what they just wrote, never news to them.
+
+Same values and interpolations as the opening lines, nil by default. It
+never moves the clocks (it is a system message), it is pinned one database
+tick after the message when the clock did not move between the two inserts,
+and it is then the conversation's last message, which is what a list row
+previews. A reply into a case already open is not acknowledged again.
+
+`%{reply_within}` is the promise in the unit it was configured in
+(`SupportDesk.humanize_promise`: `72.hours` is "72 hours", never "3 days"),
+from `support_desk.durations.*`. The closed notice
+(`support_desk.thread.closed_notice`) takes the same three interpolations,
+so a locked case can say how soon a new one will be answered.
+
 ### From the console
 
 Add `new` to your routes and the queue grows a "Write to someone" button:
@@ -1603,7 +1757,7 @@ that is exactly when a seat gets stranded.
 
 ## Compatibility
 
-Rails 7.2, 8.0 and 8.1; Ruby >= 3.2; PostgreSQL, SQLite and MySQL; bigint or UUID primary keys (the migration follows your app's `primary_key_type`).
+Rails 7.2, 8.0 and 8.1; Ruby >= 3.2; PostgreSQL, SQLite and MySQL; bigint or UUID primary keys (the migration follows your app's `primary_key_type`). chats >= 0.7.1 (0.5.0 and later: the launcher sits in chats' tray and its badge listens to chats' `:unread_changed`).
 
 PostgreSQL and SQLite enforce unique new-case creation, one open assignment per ticket and
 one pending proposal per ticket with **partial unique indexes**. New submissions reuse an existing open case. Reopening
@@ -1674,7 +1828,8 @@ SupportDesk.find_topic("billing/invoice")
 SupportDesk.on(event, key: nil) { … }  SupportDesk.off(event, key)
 SupportDesk.doctor
 SupportDesk.native_path_rules(mount:, title:)   # Hotwire Native path rules for the requester screens
-SupportDesk.humanize_duration(24.hours)          # "1 day", in the reader's language
+SupportDesk.humanize_duration(24.hours)          # "1 day", in the reader's language (a wait: rounded)
+SupportDesk.humanize_promise(72.hours)           # "72 hours" (a promise: in the unit it was made in)
 SupportDesk.actor_key(record)                    # a stable key for an actor (GlobalID param); what event payloads store
 SupportDesk.requester_class?(klass)  .supportable_class?(klass)  .agent_class?(klass)
 SupportDesk.eligible?(record, condition)         # how both macros read their `if:`
@@ -1686,7 +1841,7 @@ SupportDesk::VERSION
 
 After checking out the repo, run `bundle install`, then `bundle exec rake ci`. The dummy app lives in `test/dummy` and mounts all three surfaces the way a real host does: the requester engine at `/messages/support`, `chats` at `/messages`, and the turnkey console at `/admin/support` — plus the same console again inside a host-owned `madmin` namespace, because "the console uses only the public API" is a claim that needs a second implementation to be worth anything.
 
-`chats` is the kernel this gem is a product on and the two are developed in lockstep, so the Gemfile points at a sibling checkout (`../chats`) whenever this gem needs a `chats` that is not on rubygems yet. It currently requires `chats` ~> 0.3 (the `verified:` messager option).
+`chats` is the kernel this gem is a product on and the two are developed in lockstep. support_desk requires `chats >= 0.7.1, < 1.0`. Until that is on rubygems, the bundle takes the reviewed chats package from `vendor/cache` (provenance, checksum and the step that adds it in `vendor/cache/README.md`), so `bundle exec rake ci` needs no network and no sibling checkout.
 
 ## Contributing
 

data/app/assets/stylesheets/support_desk.css

@@ -250,3 +250,80 @@
      only the error notice carries colours of its own. */
   .support-desk-error { background: #3f1d1d; color: #fecaca; }
 }
+
+/* --- The launcher's panel (0.5.0) ------------------------------------------- *
+ *
+ * `support_launcher` is an item of chats' tray: chats draws its tab, the
+ * panel's chrome and the phone's sheet. This is the content: a frame that
+ * fills the panel and scrolls inside it. Rows, the empty state, "All your
+ * conversations" and a case's header wear the dock's own classes
+ * (.chats-dock__list, .chats-dock__see-all, .chats-window__header), so a
+ * host's dock theme reaches them too.
+ */
+.support-desk-launcher__name { overflow: hidden; text-overflow: ellipsis; }
+
+.support-desk-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  font-size: 0.875rem;
+}
+.support-desk-panel__screen {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+.support-desk-panel__screen > .support-desk-door { margin: 0.75rem; }
+.support-desk-panel__all { margin-top: auto; gap: 0.4rem; }
+/* inline-block: the link's underline (a host's, on hover) stops at the count. */
+.support-desk-panel__count { display: inline-block; font-weight: 400; color: var(--support-desk-text-muted); }
+.support-desk-panel__loading { margin: auto; padding: 1.5rem; text-align: center; }
+
+/* The wizard, compacted to the panel's width. */
+.support-desk-panel__wizard .support-desk-wizard__header { padding: 0.85rem 0.85rem 0.15rem; }
+.support-desk-panel__wizard .support-desk-wizard__ask { font-size: 1.05rem; }
+.support-desk-panel__wizard :is(.support-desk-choice, .support-desk-card, .support-desk-error, .support-desk-notice) {
+  margin-inline: 0.75rem;
+}
+.support-desk-panel__wizard .support-desk-choice { padding: 0.7rem 0.85rem; }
+.support-desk-panel__wizard .support-desk-form { padding: 0 0.75rem 1rem; }
+.support-desk-panel__wizard .support-desk-form__input { padding: 0.65rem 0.8rem; }
+
+/* A case: the dock window's header, and the way to a person under it. */
+.support-desk-panel__nav { padding: 0 4px; gap: 2px; }
+.support-desk-panel__heading { padding: 0 6px; }
+.support-desk-panel__human {
+  flex: none;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--chats-dock-edge, var(--support-desk-border));
+}
+.support-desk-panel__human .support-desk-notice__title { margin: 0; font-size: 0.8125rem; }
+
+/* Signed out: how to reach the desk. */
+.support-desk-panel__signed-out { gap: 0.75rem; padding: 1rem; }
+.support-desk-panel__lead,
+.support-desk-panel__promise,
+.support-desk-panel__note { margin: 0; }
+.support-desk-panel__lead { font-size: 0.9375rem; font-weight: 600; }
+.support-desk-panel__promise,
+.support-desk-panel__note { color: var(--support-desk-text-muted); }
+.support-desk-panel__note a,
+.support-desk-panel__link { color: inherit; font-weight: 600; }
+
+/* A phone: the sheet fills the screen; fields at 16px, or iOS zooms in. */
+@media (max-width: 699.98px), (max-height: 499.98px) {
+  .support-desk-panel { font-size: 1rem; }
+  .support-desk-panel__wizard .support-desk-form__input { font-size: 16px; }
+}
+
+/* The wall in the panel: its title at the panel's size, room around it. */
+.support-desk-panel__wall { padding-bottom: 1rem; }
+.support-desk-panel__wall .chats-inbox__header { padding: 0.85rem 0.85rem 0.25rem; }
+.support-desk-panel__wall .chats-inbox__title { font-size: 1.05rem; margin: 0; }
+.support-desk-panel__wall :is(.support-desk-notice__title, .support-desk-form) { margin-inline: 0.75rem; padding-inline: 0; }
+.support-desk-panel__wall > .support-desk-button,
+.support-desk-panel__wall .support-desk-button { margin: 0.5rem 0.75rem 0; }

data/app/controllers/support_desk/application_controller.rb

@@ -81,10 +81,29 @@ module SupportDesk
       respond_to?(:chats) ? chats : Chats::Engine.routes.url_helpers
     end
 
-    # Where a case is read and answered: its chats conversation, never a
-    # second thread UI of our own.
+    # Whether this request is the launcher's panel (SupportDesk::Launcher):
+    # then the screens answer with the panel's templates.
+    def support_panel?
+      SupportDesk::Launcher.panel_request?(request)
+    end
+
+    # A screen: +page+ on the page, or, in the launcher's panel, +panel+
+    # inside the panel's frame (layouts/support_desk/panel) and nothing else
+    # of the layout.
+    def render_screen(page, panel: page, **options)
+      return render(page, **options) unless support_panel?
+
+      render panel, layout: "support_desk/panel", **options
+    end
+
+    # Where a case is read and answered: its chats conversation, in the
+    # chats inbox (`thread_page = :chats`) or on this engine's ticket page
+    # (`:support`). Never a second thread UI of our own: that page renders
+    # chats' thread. In the launcher's panel, always the ticket page, which
+    # answers the panel with the case inside it.
     def conversation_path_for(ticket)
       return root_path if ticket.conversation.nil?
+      return ticket_path(ticket.reference) if support_panel? || SupportDesk.config.support_thread_page?
 
       chats_routes.conversation_path(ticket.conversation)
     end