Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Channels and Messaging
Deleting a channel
The channel owner can permanently delete their channel. A team owner or admin can also delete a team channel belonging to their own team. Being a participant, administering another team, or sharing a team with the channel creator does not grant permission to delete it.
Use Delete from the channel row or title menu, or the mobile long-press menu. Confirm the deletion in the existing delete dialog; it removes the channel for everyone. The same permission rule applies to the delete hotkey and bulk action. If a bulk deletion partly succeeds, confirmed deletions stay removed and only failed items remain in the dialog for retry.
User mentions sent by integrations may contain only userId. For human user
IDs, messages and editors resolve the current name and fall back to the email
local part when lookup fails. Verify that these mentions remain intact when
editing and saving a message; integrations need not supply email or displayName.
Channel calls
A channel call may have its own row and thread in the channel. See calls whose discussion is a channel thread.
Channel list previews
Message text in channel rows and Home cards is display-only, including quoted thread previews. Clicking a link or mention in that text opens the surrounding channel or thread, and Tab skips embedded controls. Screen readers still announce the message text, including link labels and mention names, once per preview. Verify wide and narrow rows and channel/thread cards; links and mentions remain interactive inside the opened conversation.
Conversation headers and shared detail breadcrumbs use the same identity icon: the recipient for human DMs, the persona for agent DMs, and the channel picture or glyph for named channels. Message and thread breadcrumbs resolve identity from their parent channel rather than the message or thread ID.
Message links
A channel search namespace with threadId and no messageId targets the thread
root. Home, Chat, and the full-screen touch conversation normalize this URL in
the shared channel search schema; an explicit message continues to target its
reply within that thread.
Bare URLs, common bare domains, and email addresses are clickable in opened messages, including agent/API messages and older messages. Explicit Markdown links still use their label. Inline code, code blocks, and escaped URLs stay literal. Removing a link in the composer remains effective after sending and reopening the message for editing.
Verify a bare App Store URL on desktop and mobile, a percent-encoded URL, a URL
containing Markdown punctuation, and Remove link → send → reopen. Channel and
Home previews remain display-only as described above. The backend-free browser
check is in
apps/web/src/lib/core/component/LexicalMarkdown/component/core/browser-test/README.md.
Block formatting
Selecting several paragraphs and choosing Quote or a heading in the floating
format toolbar applies it to the same paragraphs in either selection direction.
Verify a selection from the last paragraph back to the start of the first:
the first paragraph must receive the format too. A range ending at the start of
the following paragraph leaves that following paragraph unchanged.
Typing > creates a quote. Pasting text with paragraph breaks into that quote
keeps all pasted paragraphs quoted, including HTML and text copied from another
Macro editor. Inline formatting survives. Verify an empty quote and a selection
within a quote, then type after the paste and save the message; every pasted
paragraph must still have the quote styling.
Selections across adjacent quoted paragraphs preserve quoting too. A selection
that includes unquoted paragraphs keeps the normal paste behavior.
The backend-free quote check is documented in the Markdown browser-test README
linked above.
Query document ownership
Switch between Home and Channels repeatedly, including after backgrounding the
native app. Conversation queries must remain reusable: their operation names and
serialized GraphQL documents must stay consistent. The backend-free desktop and
iPhone WebKit regression is
bunx playwright test --config src/lib/urql-solid/browser-test/playwright.config.ts
from apps/web.
Data and loading state publish together, so automatic pagination observes the new page cursor before deciding whether to request another page.
Empty direct messages
An empty human DM shows the centered conversations illustration and “Say hello” above the composer. The copy explains that recipients without a Macro account receive the message by email. Opening the DM sends nothing.
Opening a person you have no DM with shows this same empty DM, with their name
and avatar in the header, under a temporary pending-dm- id kept only in that
tab. Nothing exists on the server, so the DM is in neither person's list until
the first message creates it and the view becomes the real conversation. Check
that leaving without sending creates nothing, that the other person's list gains
the DM only after the send, and that reloading a pending-dm- URL opens the
Chat list on desktop and closes the pane on touch.
Sending a human message queues an immediate email for nonusers, including follow-up messages, replies, and mentions; registered users retain their notification preferences. Check narrow and wide panes: the composer stays usable, and the empty state vanishes when the first timeline entry appears. Agent DMs keep their own UI.
Create a channel
Chat offers separate New channel and New direct message actions with either sidebar layout. New channel and the global Create menu use this three-step flow:
Create→Channel G. DialogCreate a channelopens on step 1 of 3 with theNametextbox focused.- Fill the name and click
Next. Step 2 of 3 showsVisibility, withTeam — anyone on your teamselected by default. Team channels are always discoverable to teammates. - For a team channel, click
Create. For a private channel, selectPrivate — only specific peopleand clickCreate. Creation navigates to the channel (as a split pane:.../channel/<uuid>); a system rowChannel <name> createdappears. - Step 3 of 3 is an optional invite dialog for either channel type. The recipient combobox searches people and saved agents by name; it also accepts complete email addresses. Select a suggestion or press Enter to tokenize it. An unknown complete email appears as Invite with a paper airplane icon. Raw text left in the input is not submitted. Click
Addwhen recipients are selected, orSkip for nowto finish without invitees. Selected agents are added through the channel's agent membership endpoint. For team channels,Automatically add teammatesdefaults on; turning it off leaves the channel discoverable without automatically adding current or future teammates. The switch choice is applied when the invite dialog is finished or closed.
Team channels are always discoverable to the team. Private channels can only be viewed or joined by invitation. A DM is a private conversation between two people, or between one person and an agent persona.
An external email can be selected as a channel participant. For an unregistered recipient, clicking Add sends an email invite.
The first message in a DM to an unregistered recipient sends an email saying
<sender email> sent you a message on Macro, with the message and a View message
button leading to signup. It must not invite the recipient to #<their own name>.
Named-channel invites still show #<channel name> and Join channel.
Verify both emails in local Mailpit using distinct, unregistered test addresses;
repeat with a plus-addressed DM recipient to check the email-name fallback.
Private conversations with an agent
Agent DM discovery is on in development builds (dev.macro.com and bun run dev)
and off in production; there is no PostHog flag. Override it with
VITE_ENABLE_AGENT_DMS=true or false before starting Vite or building the
frontend. Disabling discovery does not delete existing conversations or cancel
their work.
Choose an agent in Create → Message, or click Message in its settings or bot profile. The picker offers your agents, eligible team agents, and Macro. Choosing an agent removes other recipients. Reopening the same persona returns to your existing private channel. Team ownership of an agent does not share your DM with teammates. Calls and additional participants are unavailable.
With the backend rollout switch enabled, the backing context stays out of the standalone Agents and Home session lists, including earlier contexts and contexts started fresh through the API. The DM remains in Channels/DMs. Opening its session by ID still works for an authorized reader, including streaming, questions, approvals, and Stop. Verify that an ordinary standalone session still appears in Agents/Home, the DM stays available in Channels, and reopening the DM resumes the same context.
DM session hiding has a separate backend rollout switch, initially disabled.
Deploy the warm-marker migration and all updated harness replicas first; once
no old warm reapers remain, set HIDE_AGENT_DM_SESSIONS=true for
agent-harness-service and redeploy.
New contexts are hidden immediately; a bounded startup/60-second backfill also
hides existing contexts, including ones created by a replica still running with
the switch off. The frontend discovery flag alone does not gate existing DMs
or API callers. Until this backend switch is enabled, DM contexts retain their
previous visibility. Before rolling back to code with the old warm predicate,
restore DM visibility by reverting the migration before starting old service
code; merely disabling the switch does not unhide existing contexts.
Updated claim and cleanup require for_warming as well as hidden/unthreaded
state, and exclude conversation reservations; genuine
speculative sessions still expire normally.
Send normally: no @ mention is needed. Attachments, references, and quoted
messages use the channel composer. While the agent works, a typing row sits
under the newest message: the agent's avatar beside the working line, which
names the step the agent is on, or says what the turn is doing (Thinking,
Writing, Working, or Waiting for an answer) between steps and to anyone
who cannot read the session. The owner also gets Stop on that row, which
cancels the active turn, and any live question or permission request beneath
it. Answer those controls to continue. If Stop fails, a failure toast
appears and the control becomes available again so you can retry.
The reply is posted as ordinary messages while the turn runs. Each finished
passage becomes a message, led by the steps the agent took to get to it, so
nothing is posted until the agent has written something and no message shows
a step running. Steps a turn ends on, with no passage after them (Stop, a
failure), are posted with how it ended. The working line is one shimmering
line, led by the working dots, naming the step in progress by its label alone,
such as Ran, Read, Edited, or Searching; the command, query, or file
stays in the session. The next step slides in as it starts, and steps running
at the same time take turns every two seconds. In a DM it is the typing row.
A channel mention's reply in its thread is one message, so the line sits in
it, and reads Thinking whenever the turn is running with no open run, before
the first step or while the agent writes after one.
Once a run closes, it folds to a Used N tools summary (with
· N failed when a step failed), with a caret after it on hover, that opens
to compact rows like the session's tool rows: the label, and Failed or
Interrupted when a step did not finish.
Documents, sessions, pull requests, and contacts an agent's reply mentions are
set in the accent color.
Stored activity snapshots keep the status and label but omit commands and tool
input details, in both shared threads and DMs. A view the agent presents
(execution.views.present) is part of the reply: it is stored with its run and
drawn after the run's line or summary, never folded into it, and each item it
shows loads with the reader's own access. The line follows the session
live while the run is open; the summary shows the snapshot saved in the
message. Readers without session access always see that snapshot. Only the
turn's last message notifies. Previews and search
quote the passages, not the steps. Typing refreshes every 3 seconds and clears
on its own if the agent's replica dies. Follow-up messages queue in order, and
the bar above the composer counts them (1 queued). Editing a sent message
does not invoke the agent again. A reply inside a thread is not part of the
conversation: the agent answers it only when mentioned there, in the thread,
as in any channel.
The local playground at /app/debug/agent-progress shows each of these states
in three tabs: DM, Channel mention (the reply in its thread), and
Agent session, with theme, viewer, and phone-width toggles and a looping
replay of one turn.
Each failed, stopped, or interrupted source message has its own Retry message action in the current context. Retry is explicit because an interrupted attempt may already have performed an external action. Refreshing or reopening the channel does not rerun completed messages. A disconnected live display offers Reconnect without issuing another prompt.
The conversation has no control for resetting the agent's context; it continues in one context. A context keeps the persona instructions, model, tools, and permission choice it started with, across reconnects; later persona edits do not reach it. A harness operator can still revoke permission bypass. Contexts started earlier through the API stay marked by a divider before their first message.
If access to the persona is revoked or the persona is deleted, the transcript remains readable and the composer explains that the agent is unavailable. New prompts, retries, and answers to pending approvals require current access.
For rollout verification, cover a private persona, a team persona as two
different users, simultaneous opens, queued follow-ups, reload during a turn
(the typing row and live steps return without a duplicate reply), a multi-step
turn whose steps tick from running to done, attachments, an inline question,
an approval, and Stop/Retry.
Check both desktop and a narrow viewport. Search the Channels view by persona
name to reopen older DMs, including ones outside the currently loaded page.
Harness traces use macro.event.type=agent_trigger.conversation_message and
agent.session.id; the durable turn journal distinguishes queued, running,
succeeded, failed, stopped, and interrupted attempts. Check completion latency,
failed/interrupted turns, queue age, and duplicate source admissions during
internal rollout. Model usage continues through the existing session metering.
Imported Slack history
Import starts from the Create or import channels card's Import Slack button at the bottom of the Chat sidebar, or Import on the Slack row in Settings → Integrations (team admins). The card's New channel button beside it opens the new channel dialog instead. The card is the shared connector-import card (see Import from connected apps) and is visible to team admins and owners when Slack archive import is enabled. It opens the shared import dialog: a Slack row connects through Pipedream, then Import from Slack hands channel picking to an agent chat in a split, and Import with history closes it and opens the archive upload below. Without an available Slack connector (Slack's Pipedream app is dev-only), the card opens the archive upload directly. Dismiss import from slack hides the card for that user on every device (see Dismissing cards); successful archive imports (including partial imports with a completed channel) and Settings channel imports also hide it. Failed or cancelled imports do not. Dismissing or completing an import keeps the Settings entry available; completion does not close an open progress dialog. Closing the archive dialog returns focus to the card's button when it is still visible. The dialog offers Import with history (recommended) and Import channels without history. The first needs a ZIP export provided by a Slack workspace owner or admin; its upload screen links to Slack's export instructions. Files and attachments are excluded. The second opens a dedicated channel import flow: it reuses an enabled Pipedream Slack connection or requests authorization, then automatically discovers public channels. Select channels and click Import N channels to create their names and matching Macro teammates. It requires no Slack admin role, but workspace app-approval policies still apply. Neither method sets up ongoing message sync. Previous ZIP imports are collapsed under a disclosure. Only explicitly selected Slack IDs create work. Slack public channels become Team channels with automatic team joining off; private channels and group DMs become Private. Two-person DMs keep exactly their mapped pair and never gain the importing admin as a third participant. Existing names, roles, leavers and newer activity are preserved. Imported history keeps source dates and does not produce live message notifications, invitations or bot invocations. Unknown authors display their Slack name through the system bot. Attachments and attachment-only messages are not imported. Cancellation keeps committed history; repeating an archive deduplicates source messages rather than applying later edits.
For verification, use synthetic local history with a root, replies and reactions. Search for an imported author name absent from the body. Verify the result for a participant and its absence for an unrelated viewer after indexing has caught up. Job completion means required search publication finished, not immediate index refresh. Test existing channel live activity is not moved backward.
Hover and click imported external links, channel mentions, root-message and reply references in the actual message body. Check destination channel/message/root UUIDs and that the correct message is revealed, including offscreen replies. Forward references must work regardless of conversation processing order. Prior same-source imports can resolve without being selected again; unselected targets must not be auto-created. Unknown Slack domains remain external links. Missing, skipped, deleted and inaccessible targets retain safe source-only fallbacks, and another viewer must not gain access through a rendered mention. Code examples remain literal; source-controlled tags must not inject entities. Test live edits and deletion before deferred reconciliation: neither may be overwritten or revived. See the rollout/recovery gates.
Collapsed reply chains
Collapsed channel threads show up to the first three replies from the timeline
preview. New replies arriving while the channel is open must not enlarge that
collapsed preview, even when they share a sender with earlier replies. Expanding
shows the full thread; collapsing returns to the three-reply preview. The
N more replies control counts individual hidden replies.
Check a long thread that receives replies while expanded, then collapse it: new replies must be hidden and included in the hidden count. Repeat while it is already collapsed, while its full replies are loading, and after scrolling the row out of view and back. Expanding again must retain every incoming reply.
Standalone thread previews show the first three complete message groups instead. Consecutive replies from the same sender within the five-minute avatar-grouping window count as one group. Different senders, longer gaps, deleted replies, and agent replies triggered by different users preserve their avatar group boundaries.
Channel timelines show system updates alongside messages: participant additions and removals, renames, profile picture changes, and completed calls with their duration. These rows have no reply, edit, or reaction actions. Long descriptions stay on one line; hover to read the full text. Dates, message navigation, and scrolling through older history include these updates. A call's completed row appears when the call ends; active calls retain their existing live indicator. To verify live updates, scroll into history and change the channel from another session. The visible message should stay at the same position. Return to latest and reload to verify that the system entry persists in chronological order. Also reload a short channel containing mostly system updates. Every entry should remain visible when the entire timeline fits without scrolling.
Agent session entities
The Agents list includes owned and shared sessions, except sessions started
from a thread, which list only for people who prompted them from the session
itself (see Home). Rows show the shared agent
icon and session title; opening one navigates to /app/agent/<id>. The session title
menu uses the shared entity actions: Favorite/Unfavorite and Copy link, plus
Rename and Delete for the owner. Rename uses the shared rename dialog, not a
session-specific modal. Folder moves, duplication, and property/tag editing are
not offered because those APIs do not support sessions. Runtime controls remain
session-specific.
A session transcript shows each tool call as a collapsible row (consecutive calls
fold into a Called N tools group; click it to see the rows). A tool reached over
an MCP server - Macro's own (ReadContent) from a Cursor, Claude, or
Codex session, or a third-party server (ask_question) - is titled by
the tool's own name, without a server or workspace label, never by the harness's dispatcher
(mcp). Clicking the row expands the exchange: a Request section with the
tool's own arguments and a Response section with what it returned, both as
syntax-lit, pretty-printed JSON (prose results show as text), each with a copy
button that copies the whole section; a call that failed is faded, shows the
error as its subtitle, and adds an Error section. Rows for a call still running
show whatever has arrived so far.
Inline image actions
An image attached to a channel message renders inline. Hovering it, or focusing
it with the keyboard, reveals a small toolbar at its top right with
Copy image and Download image, the same two actions the lightbox offers;
it fades out when the pointer leaves and stays up while an action runs. Copy writes the full-resolution image to the
clipboard (Copied to clipboard, or Copied image URL to clipboard when the
browser refuses an image write) and Download saves it as
image-<attachment id>.<ext> (Downloaded image). Clicking the image itself
still opens the lightbox. Touch layouts do not get this toolbar: tap the image
and use the lightbox toolbar instead. Videos have their own toolbar; see
Downloading channel videos.
Reading channel attachments through MCP
When an agent reads a channel through Macro MCP, ReadChannelMessages,
ReadChannelThread, and ReadChannelMessageContext include download URLs for
image and video attachments, including attachments in replies and previews.
Up to eight distinct images per response are also returned as inline images.
Videos are linked for inspection with a video-capable tool. If an image cannot
be loaded or exceeds the inline limit, its URL remains available. To check this,
ask the agent to inspect an image on a channel message and a video on a reply;
verify that its tool response includes the matching attachment URLs.
Messages sent through an MCP client
A message, comment, or thread reply a user's MCP client (Claude Code, Cursor,
ChatGPT) posts through Macro MCP, with a direct tool such as
SendChannelMessage or from code mode (ExecuteCode), shows the client as its
sender: Claude Code · Agent with the client's initial as its avatar and a
from pill underneath. The client is the name it registered with
Macro's OAuth broker, or "MCP client" if it registered none. Notifications name
the client as the sender too. A self-hosted agent's message shows the agent as
the sender with from , and a message sent with a pasted Macro API key
shows the Macro bot with from . To check this, connect an MCP client
over OAuth, ask it to post in a channel and to comment on a document, and
confirm both show the client and the user on desktop and at phone width.
Account manager requests
A DM between a person and an agent account has an account manager button
(user-gear icon) in the channel top bar; a DM between two agents or two people
doesn't, because an agent can't be managed and only an agent can manage. It starts
a request: the person asks the agent to manage their account, or the agent asks to
manage the person's. Either way a card appears
in the DM (<m-account-manager-request>{"id":"<grant>"}</...>).
- The side that didn't ask gets Approve and Decline. Approve opens a confirmation stating the access it gives. The side that asked gets Withdraw.
- Approval posts a second card with a one-time link to
/app/account-manager/<grant>. Reveal token on either surface works once, only for the manager, and shows the token in a dialog. - Requests and unclaimed approvals expire after 7 days. Revoke active access from Settings → Account Managers.
- Messages the manager sends with the token show the managed account as sender,
with a
from <agent>line (triggered_by).
Message composer
Channel messages and thread replies have a microphone next to Send on pointer devices. It uses the same OpenAI Whisper dictation and scrolling volume timeline as AI chat. Use dictation appends text to the draft without sending; Cancel dictation or Escape preserves the existing draft. Sending is blocked during dictation, including keyboard and external send actions. Confirming uploads the in-memory audio to Whisper, which is available on all plans without consuming chat credits. Browsers without microphone recording show a disabled button. Touch devices have no microphone in either the collapsed or the expanded composer — their keyboards already dictate — so Send is the only control on that edge.
Composer and conversation body text use text-base (15px at the default root
size) on desktop and mobile. The shared scale uses 14px for text-sm and 12px
for text-xs, with accessibility text scaling preserved.
Desktop message text uses a 16px horizontal inset and a compact gap above the toolbar, consistent at narrow and wide composer widths.
The new-message compose screen and channel message/reply inputs use the same
attachment and send controls on mobile and desktop. On phones, the + drawer
offers Format text beneath Mention to toggle the formatting ribbon.
iOS uses the native media attachment picker.
In the iOS app, both collapsed and expanded channel inputs use the shared
glass press spotlight. Tap the editor and its
enabled actions to check the highlight; the caret, draft, keyboard, and action
timing should remain unchanged. Flat embedded inputs keep their host's surface.
Short top-level drafts place attachment, message text, and send on one row on
both mobile and desktop. Text that wraps onto a second line, explicit line
breaks, non-paragraph blocks (lists, blockquotes, headings, etc.), and attachments
expand the composer with its actions below the editor. Even a short or empty
non-paragraph block uses the expanded layout; converting it back to a single
short paragraph restores the compact layout. A restored block draft that becomes a
wrapping paragraph should stay expanded without briefly collapsing; check this
after reopening the channel with a draft already saved. Open reply composers always place the editor
above the action row, including for empty and single-line drafts, so the
attachment, delete-reply, and send controls have their own space.
Shift+Enter adds a line to the draft; Enter sends. The composer spaces its
paragraphs the way the sent message does, so a multi-line draft reads as what
it will send. Check a multi-line message against the draft that wrote it: the
spacing must not change on send.
Typing 6. then Enter (or 6. ) starts an ordered list at 6; the marker is
not rewritten to 1.
Both the expanded and collapsed composers start with a + button (Add). It
opens a menu on desktop and a bottom drawer on mobile: Mention (opens the @ typeahead), Attach files (the file
picker; the iOS media picker on iOS), GIF (the same picker as /gif), then under Create the same actions as
/task, /poll, /form and /document (poll and form only with forms on),
then Ask Macro (inserts an @Macro mention) and, in a channel, Start a call
(Join call while one is live). On phones, starting a new call opens a
confirmation sheet with centered participant avatars, notification copy, and a
full-width green Start call button, without a divider or close/cancel buttons.
Show up to four avatars including yourself. With more than four participants,
show three unobscured avatars and overlay +N on the fourth; N includes everyone
after the first three (five participants shows +2).
Drag the handle, tap the backdrop, or press Escape to dismiss without starting a
call. Only confirming notifies participants; joining a live call skips the sheet.
Check both DMs and channels, including long names, in light and dark themes.
On phones, a collapsed composer with attachments shows a thumbnail of the
first one between + and the draft, with the number of attachments over it
when there are two or more; a document shows its file icon. It shows with or
without draft text, and tapping it opens the composer with the attachments
below the editor. Check one image, several mixed attachments, and a document
alone, with and without text, in light and dark themes.
Input action and formatting buttons show the app tooltip without a second
native browser tooltip.
On phones, choose + → Format text beneath Mention to show or hide the
ribbon above the editor, including in message and reply edits. It offers bold,
italic, strikethrough, inline code, lists, checklists, and blockquotes; scroll
the ribbon horizontally to reach all controls. Verify that selecting struck-through
text, tapping Strikethrough, and saving removes the formatting while preserving
the text. Toggling the ribbon keeps the draft and returns focus to the editor.
Tapping the ribbon's padding or dividers also keeps the editor focused.
On desktop, select draft text to open the floating formatting toolbar. Its
compact frame uses 4px outer padding with concentric button corners, a white
light-mode background, a thin border, and a soft downward shadow. Check
Bold and the text-style dropdown in both light and dark mode.
When checking this transition, type a long draft without pressing Enter, then
shorten it and resize the pane. It should expand when the text no longer fits
beside the buttons and collapse when it fits again, without flickering between
layouts. Also add and remove a line break or attachment and
confirm the draft and caret position survive. The attachment and send controls
should remain usable in both layouts. Existing message and reply edit inputs show
Add, Discard Edit, and Send on phones; desktop keeps Attach files in place of Add.
Escape also cancels an edit. The iOS app uses its native media picker. Check inline and unified edits
on desktop and touch: attach a file and save, then edit again and discard changes
without changing the original message or attachments.
The iOS share sheet keeps its editor above the attachment and formatting controls.
Check this arrangement at both phone and tablet widths.
With a wrapping draft present, repeatedly narrow and widen the desktop split
and window, then scroll the message history. The composer should settle into
the matching layout without ResizeObserver loop completed with undelivered notifications errors. Resize-triggered wrapping measurements run in the next
animation frame; draft edits still measure before their first paint.
On Android, tap @ on the software keyboard in an empty channel composer or
after a space: the mentions menu should open above the keyboard. Type a name to
filter, then tap a result to insert one mention without sending the draft.
An @ inside a word stays literal text. Check hardware-keyboard input too;
it should open only one menu.
The same software-keyboard check applies to : for emoji and / for formatting
commands: type a search and tap a result without sending the draft.
Type /gif or choose GIF from +. The rounded picker replaces any active
formatting or link menu, opens above the composer on phones, and stays visible
after you choose the action, including with the iOS keyboard open. Both the /
formatting menu and the GIF picker span the available chat width on phones,
using the mentions menu's side gutters.
If the browser has no caret selection or its range has no rendered geometry,
the GIF picker anchors to its editor rather than staying hidden.
The larger desktop GIF picker stays within the viewport on narrow screens.
Repeat after scrolling the page: the picker must stay beside the composer,
without adding the page's scroll offset to its fixed position.
Open and dismiss the keyboard while the picker is open: it must recalculate
its placement and available height. Focusing search must not scroll the page
away from the composer.
Trending GIFs show first, with the large search field focused on both desktop
and phones. Search keeps the composer expanded, and tapping anywhere in the
search field keeps focus there. Tap a GIF to download its original animated bytes
and upload them to Macro's static-file service before insertion, without sending
the draft. The picker shows upload progress and prevents duplicate selections;
a failure removes the unused upload and leaves the picker open for retry. Closing
the picker, changing the draft, or losing edit permission prevents a late insertion.
Cancellation aborts the transfer and discards any completed upload that was not inserted.
On desktop, arrow keys move through the two-column grid and scroll the full
selection outline into view; Enter inserts it and Escape closes the picker.
Check that GIFs animate in the picker, in the draft, after sending, after copying
and pasting, and in the enlarged image viewer. Newly inserted GIFs use static-file references; picker
previews and existing Klipy URL images still load directly with anonymous CORS.
Closed mention menus do not gather, rank, or paginate candidates. When checking
channel-switch performance, include touch navigation back to the list and reopening
a cached channel without typing @. Then open mentions, search, close, and reopen:
results must reflect current people and entities, and scrolling or keyboard
navigation must still load more results. Check both mobile and desktop.
The shared @ menu also offers Recent agent sessions after Channels and
before Companies (the latest 500 accessible sessions, searchable by title or
persona). These inline chips show the shared
agent icon and an underlined session name, and open the existing session when clicked.
They are references, not bot invocations: selecting a session does not start a new
agent run. Sending or editing a message that references a session you own grants
that channel/DM edit access to it. Non-owner references do not create grants.
Access follows active membership; deleting the reference does not revoke the
grant. Inaccessible sessions render a private/deleted label. Chips omit persona
avatars and status; previews refresh periodically while the browser tab is active
to update titles and access.
Placeholder Type @ to share with #<name>. Click it, type_text, press Enter to send.
On touch devices, Send activates on release, not when pressed down. Holding or
cancelling a press does not send; releasing outside the button keeps the draft.
The composer keeps keyboard focus when sending. New local messages lift into place
with a gentle settle on touch devices; history stays still and Reduce Motion
disables the entrance animation.
The message renders immediately with avatar, email, timestamp. Composer extras: Attach files and the Send message button. Replies also include a close-reply control.
Hover a message for its action menu. Reply on a top-level message opens that thread. On
an existing thread reply, it inserts a one-line reply-target reference into the composer;
clicking the reference navigates back to that reply. References to the current
channel navigate in place, including inside the preview panel, without opening
another split. If text in the message is
browser-selected before Reply is clicked, the reference previews only the selected text.
Clicking Reply again for a message already referenced anywhere in the draft keeps
the existing reference and draft unchanged, even if a different text selection is used.
For agent-session messages, the reference previews the resolved answer or current activity
rather than the internal Magic Chip marker.
Agent-session announcements use the same ReplyTarget reference for the prompting channel
message; ordinary Markdown blockquotes remain presentation-only and do not count as replies.
The composer always keeps an editable empty line after a block reference, including after
the user deletes that line, so clicking below the reference can restore the text caret.
The mention menu offers a single @Macro; the enable-chat-v3-agents rollout decides
whether it answers in the thread as the classic bot or opens an agent session. Without the
rollout, @Macro answers in the thread (classic bot). Its tool calls execute immediately — there is
no composer or pending-confirmation card in a channel, so asking it to create a calendar
event without attendees creates the event right away (unlike AI chat, where creation waits
for the user to confirm a composer card). For an event with attendees the bot is prompted to
ask for confirmation in the thread first, since Google sends the invitations the moment the
event is created — no invitation goes out from the initial request. It cannot draft or send
email at all. A bot or agent reply posted for a person shares, as that person, the linked items
(chips, attachments, or forms presented as cards in the reply's steps) that the replying bot created for them while answering: those with a
created activity row by that bot on the person's behalf since the person's latest message in
the thread before the reply, or, for a bot message that starts its own thread (a poll card
posted top-level), their latest message in the channel. Forms and databases an agent creates
through code mode (its SDK token) are attributed to its bot like native tool creations. Activity arrives asynchronously, so missing rows are re-checked
after 5 and 30 seconds. Existing items it links, plain URLs, and bot posts with no person
behind them share nothing. The bot never asks whether to share; it calls ShareWithChannel when asked to
share an existing item. Private and confidential calendar events stay unshared, and a
calendar event can only be shared by someone who holds it on their own calendar.
The bot's prompt carries the current date and time in the mentioning user's
own time zone (their primary calendar's), so it resolves relative times ("tomorrow at 4",
"EOD") without asking; when no calendar is connected the prompt falls back to UTC and the
bot asks before scheduling a specific clock time. Within the rollout, @Macro — plus
@cursor / @codex when available — opens
an agent session; follow-up
@ mentions of that bot in the same thread route to it.
An agent mentioned in a thread reply gets, on its first turn, the images and
videos on the mentioning message and then on the thread root and earlier
replies (at most 8, no duplicates); follow-ups carry only their own files.
Files elsewhere in the channel appear only as <attachment> entries in its
context. To check, post an image on a thread root, mention an agent in a
reply without attaching anything, and confirm it describes the image.
Macro Coding Agent (@coder) is unavailable in mention suggestions, including
when it appears among existing participants or bots. Check with the agents
rollout both enabled and disabled.
Agent-authored messages trigger other agents exactly like a person's: an explicit
mention starts or continues the mentioned agent's session, and an unmentioned reply
in a thread can reach another live agent there by quote-reply or inference. The
originating user's permissions, connected runtime, and usage allowance apply through
the bot message's server-recorded attribution. Autonomous webhook posts without that
attribution trigger nothing, and a bot never triggers its own session. Finalized bot
answers are evaluated like new posts, mentioned or not; streaming updates and
ordinary edits are not. Agents handing the thread back and forth stop after 128
agent turns (64 round trips) with no person writing in between; the next agent
message is logged and triggers nothing, before any classifier runs. The invoked session's
prompt reads "Started by for " (or "Asked by" on a follow-up).
To verify, ask session-backed @Macro to post a mention of @cursor, then have
Cursor post a mention of session-backed Macro in the same thread. Check that the
first mention opens Cursor and the return mention continues Macro's existing
session. Repeat with revoked channel access and confirm no new work starts.
When the backend is configured with AI usage enforcement, a rejected classic
@Macro request gets a thread reply explaining the allowance failure (for example,
ai_allowance_exhausted) or temporary validation failure (ai_billing_unavailable),
without a lingering thinking placeholder. This also applies in document discussions.
Optional unmentioned follow-up inference, including attached-image descriptions,
is skipped when admission fails; silence does not mean the request was approved.
Explicit mentions and reply-target routing still reach downstream execution checks.
To verify after backend wiring, test an exhausted account and unavailable billing:
explicit classic mentions should show the failure, while unmentioned follow-ups
should not generate responses. Repeat with an attached image. Enforcement is off
by default; browser verification requires a configured backend.
A follow-up sent while that session is still working stops the current turn, posts a new Magic Chip on the follow-up message, and steers the agent with that text — the chip appears at the follow-up, not after the cancelled turn finishes. The reply renders a Magic Chip: a fixed 88px two-row card on desktop and mobile, including lazy loading. The header shows a leading status icon, agent name, model (hidden below 600px), an xs status badge, and an outlined Open session button (icon-only and circular on narrow cards). Working and tool calls use a slow Morph; lazy loading and queued states use a gray pulsing dot. Done uses a filled check circle, errors a warning circle, input requests a yellow question circle, and stopped a square. The lower row shows either a full-width PR preview with available line diff counts or one truncated line of agent output. Failure explanations replace that preview; tool commands and other secondary details stay inside the session. There are no tooltips. Click the card or Open session to read the full response or answer a question; click the PR to open its Macro split (GitHub until its entity has synced). While the synced PR is open, not a draft, and every check on its head commit has finished with a success, skipped, or neutral conclusion, a green Merge button sits at the end of the PR row. It asks Merge pull request? first, showing the title and repository/PR number in the shared confirmation dialog (a bottom drawer on phones). Cancel returns to the chip; Merge pull request merges on GitHub with your own linked GitHub account, so GitHub's permissions and branch protections apply; a refusal shows GitHub's reason as a toast, and success flips the chip to merged without a reload. Draft PRs, PRs with no checks, and PRs whose checks are still running or failing show no Merge button. Merged and closed PRs show no Merge button. Expanded session mentions retain their collapse control. The card never expands in place.
Built-in provider agents are offered before account setup, each within its own
rollout: @cursor requires the enable-cursor-agents flag (local override:
VITE_ENABLE_CURSOR_AGENTS), and @codex requires both
enable-chat-v3-agents and enable-codex-agents (local override:
VITE_ENABLE_CODEX_AGENTS). Outside a rollout the entry is absent from
the mention menu and from task agent assignees, even when that bot is already a
channel participant. Custom agents keep their channel visibility rules
regardless of which harness they use.
A mention without a connected account creates no session and replies in the thread
with a Connect Cursor or Connect Codex chip. Each chip
opens Settings → Agents → Runtimes, where the connection cards in the reader's rollout are visible. The same
chip reads connected after setup; mention the bot again to start a session.
Codex also prompts for a cloud environment when ChatGPT is connected but no
environment has been saved. New sessions use that environment on
main; there is no automatic repository selection. Follow-up mentions continue the same agent session. When
the provider URL arrives, the session header offers Open in Codex. Codex
assistant text appears as complete messages while tool activity and thinking
can continue updating during the turn. Mention
eligibility is covered by component/query tests; the channel interaction requires
a configured backend for end-to-end verification.
Within the Cursor rollout, @cursor is offered whether connected or not. A mention from someone with
no Cursor API key opens no session: the Cursor bot replies in the thread that
@cursor runs on their own account and is not connected yet, followed by a
Connect Cursor chip. Clicking the chip opens Settings → Agents → Runtimes; once a key
is saved the same chip reads Cursor connected and stops navigating. The
original mention is not replayed - mention @cursor again after connecting.
Cursor sessions choose a repository from the mentioning user's linked GitHub App installations on their first prompt. A session without a repository can still use Macro and connected MCP tools, but cannot use the Git proxy. For a PR smoke test, link the GitHub account and App installation in the same environment first, then name the repository explicitly in a new session's prompt.
PR status in an open Magic Chip updates from connection-gateway events after webhook sync. Reconnecting refreshes active PR lookups to recover missed updates. A late webhook does not require reloading the page.
When the agent requests permission or input, the Magic Chip displays the waiting
status for its anchored turn. Open the session to answer; editors and owners can
respond there. The chip follows the agent's next activity after the answer.
A tool call explicitly acting as the session owner in a turn somebody else
prompted, held for that owner’s approval reads Waiting for approval; only the owner approves it, in the session.
Coding agents use macro_internal.set_pull_request to register an existing or
new GitHub PR with their session. Macro Internal MCP is hosted by the harness
service at /mcp/internal on its egress listener, separately from workspace MCP.
Cursor, sandbox, and macrod sessions receive session-scoped credentials; the
model supplies only the URL. The tool records the link, not the GitHub PR itself,
and returns the session's /app/agent/<id> URL.
Macro Internal MCP's server instructions ask coding agents to register PRs with
it, to link the returned session URL in the PR description (the PR block reads
that link as the PR's origin), to open them ready for review rather than as
drafts, and to get CI passing before handing off. External MCP clients get the
ready-for-review rule in Macro's MCP instructions, and in-app agents tell coding
agents they dispatch. It is not prepended
to individual user messages. Cursor
enables automatic PR creation when a repository is selected. Its returned URL
is also recorded because
automatic creation can finish after the agent stops. Repeated registration is
idempotent. The PR URL is stored on the session row, independently of conversation
history. Registration sends a session-update gateway notification so mounted
chips reload the current link; reconnecting also refreshes it. Multiple chips
for the same session share its metadata, and loading it leaves the surrounding
editor visible.
When Cursor or Codex reports a pull request, the chip header shows its GitHub link. Codex links can arrive after the assistant finishes; a session-update event refreshes mounted chips without a new conversation message. Codex checks provider PR metadata every 20 seconds while attached. Viewing a disconnected Codex session reads saved history; sending a message reattaches the runtime. Refresh requires its original ChatGPT connection to remain connected. The link remains usable while the webhook mapping is loading or absent, then becomes a Macro PR entity link once synced. On narrow chips, long PR names truncate with an ellipsis; hover the link to inspect the full title. Codex delayed-link discovery, duplicate and changed metadata updates, and opening the exact PR URL were verified in Chromium with mocked session snapshots and realtime invalidation. This UI check does not prove live provider discovery; backend tests separately cover delayed provider metadata.
When an agent links its session to a task with macro_internal.link_task, the
session header (and the side panel's Task row) shows a task chip before the
PR chip: the task title, or Task while loading or without access. Clicking it
opens the task in a new split (in place on touch devices). Linking a different
task sends the same session-update notification, so mounted headers refresh.
When the agent names that task in a reply — after creating or linking it, or
later — the reply includes an <m-document-mention> task chip, not a URL or
MACRO- id.
When the agent stops to ask a question the question takes the area in the passage's
place, cropped and expandable the same way: the prompt, then what is asked - a form's
fields (choice rows with an accent box, an Other row when the agent allows a free-text
answer, text and number inputs, a yes/no), a URL request's host and address, or a Macro
user tool's draft (SendEmail, CreateCalendarEvent) in the tool's own composer - the
same email compose or calendar event form the session shows, editable in place; expand
the area to reach its Send/Create, which answers with the edited draft. A row at the
bottom of the area carries the other decisions, refusal first: Dismiss · Open in session
for a tool draft, Decline · Submit · Open in session (or Open for a URL) for a question.
Only the session's owner can act; other viewers see the question read-only and the header
names who is being waited on. Once answered, the area shows the agent's passage again.
A prompt the agent read out of a channel or document thread opens no review card at all:
the reply writes the whole email or calendar event into the thread and asks whether to go
ahead, and a reply in that same thread approving it ("yes, send it" / "go ahead") is the
confirmation - the agent then sends or creates directly (SendConfirmedEmail and
CreateConfirmedCalendarEvent, or in code mode macro.email.sendConfirmed,
EmailMessage.forwardConfirmed, EmailDraft.send and macro.calendar.createConfirmed),
with no session visit needed. Being asked to send or
schedule something only produces the draft; nothing goes out before that approving reply.
Images made with GenerateImage are saved to static file service. The bot embeds
the returned URL as a Markdown image in its channel reply; generated images have
no document mention or filename card.
Agent replies may contain mention chips (<m-document-mention>) that render like any
other channel mention. A mention of an image document (PNG, JPG, GIF, SVG, WebP)
also unfurls beneath the message text as an image card: a header with the filename
above the picture,
inside the message's [data-message-mentioned-images] element. The chip stays;
clicking the card opens the image document in a split. The same image mentioned
twice unfurls once, mentions of other document types, channels, and chats never
unfurl, and inaccessible images show nothing. This applies to every channel
message, not only bot replies, so a person sharing an image document by @
mention sees the same card. The preview shows Preparing preview until storage
has the bytes. With GraphQL enabled, document mentions and preview cards load
in bounded batches, including task status/priority/assignees and the viewer's edit
permission. Task badges can appear with the initial preview rather than waiting for
separate properties/document-metadata requests; cached titles may appear first while
those edges load. Ordinary document/task mentions do not wait for the built-in skills
list. Built-in skill mentions retain their non-document behavior.
The Magic Chip that streams the agent's reply stays inside the message column: long
thoughts, file paths, and unbreakable tokens wrap or truncate instead of expanding the
thread past the chat's right edge.
Message scrolling and navigation
Thread rails end at the last reply avatar when there is no inline composer or footer below it, including when the parent message was deleted. Grouped replies after that avatar do not extend the rail. On mobile (or with the unified composer), starting a first reply adds no rail to the parent; replying to an existing thread keeps its reply branches without a dangling composer segment. Desktop inline replies still connect to their composer.
Channels open at the latest message, with short conversations aligned above the composer. Incoming messages and growing replies stay in view while the channel is at the bottom. Consecutive sends stay pinned through server acknowledgement and composer resizing, without bouncing upward between messages. Scrolling up more than 1px leaves the viewport on the history being read, even when only slightly above the bottom. Composer and viewport resizing respect the same boundary. Returning to the bottom resumes following; loading older messages preserves the reading position.
On Safari and iOS, open or navigate near the oldest loaded messages and allow the history buffer to fill, then flick into older history. Loading should stop once roughly six screens are available above the viewport and resume as you approach that buffer. Check that pagination retains the visible message, and that latest stays pinned when messages arrive, images load, or the composer resizes. Verify message/reply navigation, restoration, and the custom scrollbar after pagination. Very long flings or slow responses can still exhaust the available scroll range. In the iOS app, fling repeatedly through a long channel, starting each fling before the previous one's momentum ends, then let it settle. The messages must not jump when scrolling comes to rest, nor when it bounces or is held against the top of loaded history. In a channel opened for the first time, fling up through unmeasured history and straight back down: scrolling must stop at the latest message, never in blank space below it.
Inline document mentions should show their stored title before entering the viewport and while preview requests are pending. With a slow preview response, check that a long, unchanged title retains its line wrapping as the preview loads; a renamed document should update to its fetched title afterward.
Message and reply links reveal the target inside its thread. Keyboard message
navigation scrolls only when the selected message is outside the usable viewport.
With a message selected, E edits your own message and does nothing on someone
else's message. Check both root messages and thread replies from a Home split:
an incoming selection must not mark the Home item done or edit the thread root.
Press Escape to clear selection; the parent Home shortcut is then available
again. Typing e in the composer or inline editor should still enter text.
Verify a message link in a fresh browser tab as well as inside an open channel:
the initial page should center the requested message, including older history.
On a cold notification open, the destination shows the three-block Macro loader
while channel metadata and the targeted message window load in parallel. It
must not briefly fetch or display the latest messages before resolving an
uncached message link. Explicit thread replies load their parent window and
replies together; known root messages skip the message-kind lookup. Throttle
these requests and verify the loader transitions directly to the target,
without a blank body or message-shaped placeholders. A newer link supersedes an
unresolved one, while a jump inside an already-mounted conversation preserves its composer.
Returning through split navigation restores the saved message position and expanded
threads. Switching channel tabs and returning restores the Messages position,
expanded threads, and pending reply from when the tab was left. The Scroll to bottom control appears when scrolling down through history;
it returns to the latest page even after opening a link into old history.
On touch devices a round Jump to latest button sits bottom-right above the
composer whenever the list is away from the bottom, in either scroll direction;
tapping it smooth-scrolls to latest and keeps the keyboard open.
The jump waits for that page to reach the rendered list.
A newer message navigation cancels a pending jump to latest. Scrolling manually
or choosing another destination also cancels the initial target's delayed fallback.
A touch tap leaves pending navigation intact; a vertical finger drag cancels it.
The Unread notification chip navigates unread threads whose destinations are outside the viewport. A collapsed thread with hidden unread replies shows a dot and accent border on its show-replies control. While that control is visible, those hidden replies do not contribute to the floating chip; scrolling it out of view restores the chip, pointing toward the control. Expanded threads use actual unread message positions. A visible unread reply does not hide other offscreen unread replies in the same thread. There is one chip, targeting the most recently active eligible unread thread. Its count includes only distinct offscreen unread threads, not notifications. Three replies and a mention in one thread count as one; reactions do not count. Clicking the chip expands the target thread and reveals an unread message. Scrolling an inline indicator into view does not expand the thread or mark its hidden replies seen. Automatic read marking waits until the actual message intersects the visible scroll area, excluding floating header/composer insets. Offscreen overscan, collapsed replies, hidden panes, and background tabs remain unread. Expanded standalone threads and the thread side panel use the same visibility rule. New notifications on an already-mounted offscreen reply remain unread until that reply comes into view. Explicit notification clicks and mark-read actions retain their existing behavior.
Visibility is conservative: moving a partly off-window pane without crossing either observer's visibility threshold can leave a now-visible reply unread until the next intersection update or an explicit mark-read action.
The backend-free regression uses the real message read marker and channel
virtualizer on desktop, phone, and tablet:
bunx playwright test --config src/features/notifications/browser-test/playwright.config.ts.
Check the last channel message with a long collapsed unread thread: at the bottom,
the inline dot and accent border should be visible without a downward chip. With
another unread thread above, an upward chip should remain and count only that offscreen thread.
Scroll the disclosure out of view and back, expand and manually collapse the
thread, and check composer/mobile insets. The indicator must appear even before
full reply data loads. Check a target below the viewport, an unloaded parent, live
notifications, and switching channels while notifications load. Loading this
channel's notification edge must not delay its messages or activate the global
GraphQL notification feed.
On native iOS, tapping a thread reply push in Notification Center or on the lock screen should open its channel, expand the parent thread, and reveal the actual reply. Verify with the app backgrounded and after terminating it. Use an older thread with a reply hidden by the collapsed preview so opening only the channel or parent message cannot satisfy the check. See the native notification regression procedure for simulator setup.
The [data-channel-scroll] element is the scroll surface. Its virtualized rows are
keyed by message ID; offscreen rows are normally absent from the DOM.
On a cold channel open, verify that delayed bot/agent mention requests leave the messages and composer visible. Expand a thread while its replies are still loading: existing preview replies should remain visible until the full list arrives. Repeat after reopening the channel to cover both cold and cached data. For PR mentions, also fail a GitHub connection-status request, scroll through virtualized rows repeatedly, and verify remounts make no new status requests. An explicit retry or completed OAuth must still refresh the status, even if all mentions have unmounted or only disabled preview observers remain. Then paste a mention while the retry is held pending. The composer must stay visible and focused, and messages containing PR mentions must render immediately. Resolve the retry as linked, unlinked, or failed: none should hide the surrounding UI; only a confirmed unlinked/reauthentication status changes the chip to a link. After a confirmed unlinked status, fail a refetch and remount the mention: it must remain a plain GitHub link without hiding the surrounding UI. Scrolling a collapsed thread into view must keep its timeline preview unchanged, without fetching or revealing the full reply list. Cached replies from a previous expansion must not enlarge that preview either. Explicit expansion, replying, and message/unread-chip navigation may still open the thread.
Channel messages, thread replies, reactions, edits, deletions, and typing go
through the shared message API at GET|POST /dss/messages/channel/<id> and its
items, threads, and typing subroutes; the /dss/channels/<id>/message*,
reaction, and typing routes no longer exist. Live updates arrive as one
message_update websocket payload per committed change (posted, edited,
message_deleted, reaction_changed, thread_updated, typing); the older
comms_message, comms_reaction, comms_attachment, and comms_typing
frames are no longer sent. Documents share the same client, cache, and
components (see documents.md).
Reopening a cached channel, reconnecting its live subscription, or returning
from an absence past the presence window revalidates its timeline with
GET /dss/messages/channel/<id>/timeline?selection=<default latest-page selection>.
This replaces stale roots and their reply previews, reactions, and edits, and
removes deleted roots even when no newer top-level message exists. Loaded older
pages are also refetched using the refreshed cursors. A committed live change
restarts any in-flight channel timeline refresh, including when older pages are
still loading, so its result cannot overwrite that change. Idle channels still
apply live events without fetching; cached content stays visible if a refresh
fails. Message links still load around the targeted message.
The channel_messages_load event records path: full and reason
(revalidate, no_cache, cache_not_at_latest, or load_around).
Actual in-flight restarts emit a channel.timeline_restart span, searchable by
channel.id. query.count records the number of restarted queries;
query.fetch_more_directions and query.outcomes are arrays in the same query
order (refetch/forward/backward and fulfilled/rejected). The span also
records fulfilled/rejected counts and is marked as an error if any restart fails.
Idle channels emit no restart span. Request error text and message content are
not included.
To verify recovery, open a root with no replies, disconnect that client's live updates, then add replies and reactions, edit another root, and delete a root from a second client without posting a new top-level message. Reconnect the first client: the collapsed preview, reply count, reactions, text, and deleted row must all catch up without a reload. Repeat with older pages loaded and after a mobile background/foreground cycle.
Message reaction notifications
Message reaction notifications are enabled by default. The message author can turn them off with Message reactions in notification settings. Adding a reaction from another account notifies the author; self-reactions and removing a reaction do not notify.
In Home, reactions belong to the message's thread row: a top-level message uses its own row, and a reply uses its parent thread. Verify that an incoming reaction brings that row back into the inbox, displays the reaction and channel name, and opens the reacted-to message. Marking the row done should clear its reaction notifications along with the other notifications for that thread.
Requests to join
Opening a private or team channel you are not in shows You don't have access to this channel, the signed-in email, and Ask to join. Public channels are open to everyone, and direct messages offer no request. Sending shows Request sent with Withdraw request. After withdrawing, asking again waits a minute; after a denial it waits 24 hours, and the panel shows when.
The request appears in the channel timeline as " () asked to join the channel" with Approve and Deny for any participant. The name and full account email wrap at phone widths so reviewers can identify the requester before answering. If the display name already is the email, it appears only once. Every participant also gets a Requests to join notification (turn it off under notification settings) that opens the channel and marks it unread. The first answer wins: the row then shows Approved by or Denied by for everyone, a withdrawn request shows Request withdrawn, and the other participants' notifications are marked done. Approval adds the requester, who gets the usual "added you" invite notification, and the timeline shows the usual added row. A requester waiting on the denied view is taken into the channel when the approval arrives.
Verify with two accounts: ask from a non-member, approve or deny from a member
in another tab, and check the row, the requester's view, and the member's inbox
update without reloading. Check the panel, full requester email, and the row's
buttons at phone width.
Use a copied /app/channels/<id> link for a private channel absent from the
requester's channel list. The Chat workspace must offer Ask to join there
and open the conversation after approval. A transient loading failure still
offers Retry rather than an access request.
Returning to a denied channel waits for that screen's fresh request read, even when an earlier request is cached or the read is paused offline. A missing channel shows Conversation unavailable with Retry, without cached request controls. Other request-read failures show an inline error and Retry. Retry and background metadata refreshes keep the current unavailable or denied screen in place until the result arrives.
Chat navigation rail
With no conversation open, the desktop Select a conversation pane shows the Chat TutorialPill (from features/video-tutorials) once that video is in its catalog; touch layouts, which have no detail pane, show it in the empty conversation list.
Following a channel mention or browser notification for the conversation already shown in Chat activates that workspace and jumps to the targeted message or reply. It keeps the shared channel detail mounted and does not show a Content already open toast. The same applies to a channel preview in Home; a closed channel opens normally. In Chat, the detail uses the shared channel top bar with Messages, Attachments, Participants, and Calls tabs (when calls are enabled). A message target switches back to Messages; changing unread notifications does not restart navigation.
On desktop, switching conversations selects and mounts the cached conversation immediately. Messages load alongside the notification refresh. Explicit message or search targets apply immediately; ordinary opens start at the bottom. Notification results never change the destination. With a slow connection, switch channels quickly: an earlier response must not switch back or mark that earlier channel read.
A transient notification-fetch failure keeps the conversation and composer mounted while notifications are unavailable. Recovery marks top-level message notifications seen without moving the conversation. No notification read marking runs from an abbreviated list result, even if that result is empty. Access failures and server-confirmed missing channels show Conversation unavailable and stay hidden during retry until access is confirmed. With GraphQL caching enabled, an empty local projection cannot hide a server-confirmed conversation; a stale positive row cannot undo a fresh denial or deletion. Contradictory cache membership triggers a bounded server confirmation. An initially empty cache result waits for that confirmation before declaring the channel unavailable. Unavailable routes still recover from invite notifications and reconnect without mounting a message view first. A route without cached channel metadata shows Loading conversation until its channel arrives. On mobile, opening from the Recent conversation list also navigates immediately: a slow or failed notification lookup must not prevent messages and the composer from loading. Full-edge notification hydration runs only after navigation is accepted; failure leaves unread state unchanged and must not show an “Unable to open conversation” toast. A late response must not reopen the channel or mark it read after the user leaves its mobile pane. Message loading retains its own access/error states. Verify with the notification request held, then failed, and with rapid back-navigation while it is pending.
The title bar's Hide navigation control hides the whole rail. Reopen it with
Show navigation (the hamburger) immediately before the conversation title.
Chat remembers this choice independently of other workspaces and restores it
after reload. While no conversation is selected, the rail stays open regardless
of that choice and offers no Hide navigation control (Cmd+. is inert);
selecting a conversation applies the saved choice again. Chat uses
the shared 256px default sidebar width and resize limits. In splits 720px wide or
narrower, the rail and the conversation take turns at full width instead of a
slide-over: with no conversation selected the rail fills the split (no Hide
navigation, Cmd+. inert), and an open conversation shows Back (left arrow)
where the hamburger was. Back opens the Channels list route, so browser or split
back returns to the conversation. There is no separate skinny sidebar mode.
Sidebar redesign rollout
enable-chat-sidebar-sections gates the desktop layout, not channel or
direct-message creation. It defaults on in development; deployed builds defer to
PostHog. Set VITE_ENABLE_CHAT_SIDEBAR_SECTIONS=true or false to override it locally.
Wait for the flag to resolve before mounting a desktop layout or loading its
lists. An unavailable or disabled remote flag restores All, Recent, and
Threads (the latter still requires enable-channel-threads-preview), the
original independently scrolling groups, and separate creation actions. A saved
Recent or Threads tab survives switching the redesign on and off. Personal-section
queries and new section preferences do not affect the flag-off layout. Existing
labels remain governed by enable-channel-tags. Mobile retains its recent feed
regardless of the redesign flag, including while it is loading.
Original sidebar (flag off)
The desktop rail keeps All and Recent tabs in a shared pill track beside New. All contains optional Favorites and independently paginated Team channels, Channels, and DMs. Channels lists joined public and private channels. Each group collapses and sorts independently; open groups split the available height.
enable-channel-threads-preview adds a Threads tab. It is on in development;
VITE_ENABLE_CHANNEL_THREADS_PREVIEW overrides it locally. All threads clears
the channel filter, while the Conversations section lists channels and DMs with
threads the user participates in. Scrolling loads more. Selecting a conversation
filters the thread view instead of opening that conversation. On desktop, Threads
pins navigation open with no Hide navigation control. In narrow splits the thread
view fills the split like a conversation, and Back returns to All.
Sectioned sidebar (flag on)
With the flag on, desktop Chat has one conversation sidebar, without All, Recent, or Threads view tabs. The default order is Favorites, Direct messages, the team's channels, custom sections, then All channels. All channels lists joined public and private channels, including those assigned to manual or smart custom sections. The team heading is [Team name] channels, with Team channels as the fallback while its name is unavailable. The team section always shows joined team channels, including channels assigned to manual or smart custom sections. Each custom section is a top-level heading, independent of the Team channels disclosure. Empty sections use padded, bordered cards like saved views, with a subtle background and secondary actions; empty Favorites explains how to add a favorite. Private conversations use a lock icon in the sidebar and mobile feed, including favorited private conversations. All section headers use the shared collapsible-section styling without leading icons or top padding; the section stack supplies a compact 2px flex gap. Custom-section drop zones and highlights cover both the header and its content, including the empty state. Rejected drops show a borderless explanation; pending section data keeps drops disabled without covering the section with a loading message. Section, DM, and search containers use the 8px outer sidebar gutter; headings and rows add their own item padding so headings align with the Chat title. Rows are indented by 8px under every section, including Favorites, custom sections, and DMs. Empty-state actions and search results avoid this extra indent. The caret stays hidden in expanded sections until hover and remains visible when collapsed. Team-shared sections show a neutral Shared badge next to the name, before the caret. Below 256px of section width, a users icon replaces the badge to leave more room for the name. Separate short tooltips explain the name and sharing, without overlapping native title hints. Personal sections have no scope icon or badge. Header focus backgrounds fill the entire header row, including its trailing controls, with no extra right padding.
The sidebar uses TanStack Virtual for the section stack, each expanded channel list, and search results. Rows retain stable identities and measured positions through live refreshes and section reordering; focused and dragged rows remain mounted when they leave the visible range. Keyboard navigation scrolls immediately, without animation, only when the highlighted row enters the viewport's two-row context margin, leaving neighboring rows visible above and below. The margin shrinks in short sections. Section jumps also reveal the heading with surrounding context. Sections normally scroll independently. When All channels is last and has no manually saved height, it expands to its full content height and uses the sidebar's scroll area. Moving another section below it restores the usual height cap, without discarding a saved manual height. Lists with more than two items have a resize grip; drag it to choose a height between two rows (68px) and the end of the list, capped by the section's maximum. Shorter lists fit their content and have no resize grip. Favorites and Direct messages default to four visible rows; other sections default to their maximum height within the pane. Focus the grip and use Up/Down to resize by 20px (100px with Shift), or double-click to restore the default. Section heights persist as personal preferences alongside sorting and sidebar width. Heights adapt to filtered content and smaller panes without discarding the saved preference. Search covers channels and DMs regardless of section placement and restores the selected row in its section when closed. Mobile retains the recent-conversation feed below.
Drag a section heading, its name, or the grip in the left gutter to reorder sections, or focus the grip and use Up/Down. Pointer dragging starts only after more than 8px of movement, never from holding still. A normal heading click still toggles the section; releasing a drag does not. Add and menu buttons never start a drag. The bare grip appears only on header hover or keyboard focus and stays fixed when pressed, without its own button background. The drag highlight includes both the grip and section name without shifting the header's text or controls. An insertion line shows the destination. Section order is a personal preference, including for shared sections, and survives reloads. The dragged section appears as a card preview while its source is subdued. Other sections animate into their new positions on drop or keyboard reorder, except with reduced motion enabled. Dragging near the sidebar's top or bottom uses the same edge-scroll mechanism as Gantt; wheel scrolling remains available during a drag. Resizing near the sidebar's top or bottom also scrolls the sidebar, including while the pointer stays still. Resize drags compensate for that movement, and the rounded resize grips retain pointer capture until release or cancellation.
Section membership comes from the server's complete visible channel-ID lists. The sidebar shows available channel rows immediately. One shared by-ID query per batch supplies cached channel data and fetches only missing records using Soup's generic explicit-entity hydration. Channel batching and unread refreshes stay in the channel query layer; the sidebar does not coordinate separate cache and network queries. Each expanded section appends skeleton rows while its remaining channels load, using the same row indentation and icon/text columns as loaded channels. A failed fetch keeps available rows and replaces that section's loading feedback with Retry. Loading sections must not briefly show an empty-state hint. Collapsing a section hides its loading feedback without changing membership or stopping shared channel hydration. The header does not show a Loading sections/Retry strip during normal loading. Section reads use the shared bounded retry policy, retry on focus, and preserve cached sections during a refetch. A failed initial load retains a compact error and Retry action. Until section metadata is available, New section explains its unavailable state in the creation menu; ordinary conversations remain usable.
Favorites open the same channel detail as ordinary rows. A single click opens a row even when channel data refreshes between pressing and releasing the pointer; section and search lists retain row identity through those updates. Shift-clicking a favorite, channel, or DM opens it in a new split. Rejected navigation and failed hydration must not mark notifications read. Context menus retain Mark Read, Open in new split, Unfavorite, notification controls, and Copy Link.
Favorites defaults to Custom order. Drag a favorite onto another favorite to move it to that position; an accent insertion line shows the exact destination above or below the target row. The order saves through the shared favorites API and survives reloads. Hidden favorites and favorites of other entity types keep their positions. Sort → Custom order restores dragging after choosing an automatic sort. Releasing over a favorite preserves the drop target through scroll updates; releasing outside the list leaves the order unchanged. Dropping a favorite does not open its conversation or move it into a custom section. Failed saves roll back and show an error toast.
Sections
Sections reuse channel labels. The existing enable-channel-tags flag controls
section management; VITE_ENABLE_CHANNEL_TAGS=true enables it locally.
Turning the flag off hides section controls and stops label reads without
deleting saved labels. Channel and direct-message creation remain independent of
the label service and its feature flag.
Use New → New section to create a section. The wider dialog has a name field and a Smart section switch in its body. Shared with team sits on the left of the footer, with the action buttons on the right. The question-mark tooltip beside sharing explains that team members can see and organize the section and only team channels can be added; clicking or tapping the help button also reveals the explanation below the footer controls. The form shows a warning-colored Team channels only hint when sharing is on and no scope hint when it is off. With both switches off, the section is personal and manual. Smart grouping reveals a separate input below Name contains and a matching-channel count. Hover or focus that count to preview matched channels; larger results show the remaining count. Switching sharing scope refreshes the preview without replacing the form. A zero shared count explains that only joined team channels match; public and private channels remain personal. Edit and delete through each section's sliders menu. Editing also exposes Shared with team. Turning it on or off preserves the section ID; turning it off requires confirmation and makes the section personal to the current account, removing it from teammates' sidebars. The toggle is disabled with an explanation while channel eligibility is loading or when any current member is unavailable or ineligible for the destination scope. No channels are silently dropped. Personal sections are private to the account, including for team members, and accept joined team, public, or private channels. Shared sections accept only channels from that team. Any current team member can create, edit, change sharing, or delete a shared section; these actions are not admin-only. Neither kind accepts DMs. Scope changes reject duplicate destination names and atomically move manual assignments into the destination scope, replacing other manual assignments there. Smart sections keep their rule and reevaluate matches in the new scope. Ordinary channel assignments stay isolated between personal and shared scopes. Names are unique within each scope, case-insensitively.
Each heading has one sliders-icon menu, also available by right-clicking the header. Sort opens its independent single-select options with a checkmark on the right. Filter contains Unread only. The unread label sits on the left and its switch on the right; toggling it keeps the submenu open. Manual sections have a + header action and Add channels menu entry. The picker searches all eligible joined channels, not just rows loaded in the sidebar, and excludes channels already in the section. The wider, shorter picker keeps its actions visible while the channel list scrolls. Compact helper text explains the scope and assignment move. Adding a channel moves its manual assignment within the same scope without changing the other scope. Partial failures keep successful additions and retry only the failed selection. Empty manual sections offer Add channels, empty smart sections offer Edit rule, and unread-filtered empty sections offer Show all channels. Custom sections also include editing, Mark all as read, notification actions, and a destructive Delete action in the same menu. Click and right-click menus use the same standard context-menu rows, spacing, and selection indicators. Use the heading's caret to expand/collapse it; this is not repeated in the menu. There is no separate all-sections management menu. Sorting and unread filters are personal, even for a team-shared section. Date ordering follows each paginated source; Favorites and custom sections also offer A–Z. Filtered-out channels retain their membership and do not reappear ungrouped. Shared name and rule edits apply to the team; personal edits affect only the account. Deleting a section does not delete its conversations or change channel access.
Every desktop section menu, including Favorites, [team name] channels, and Direct messages, offers Mute all channels, Unmute all channels, and Snooze all channels. These update only your notifications, including for shared sections. Each action uses the section's complete current membership, including filtered-out and unloaded channels; channels added later do not inherit the change. Built-in lists resolve all pages before applying an action and never include unjoined channels. The team section includes its custom-section members. Favorites targets only channel favorites, not documents or other favorite types. Snooze uses the usual duration/date picker and resumes notifications at the chosen time. A partial failure keeps successful updates and reports the failures; snooze retries only failed channels. Mute, unmute, and snooze submit up to 500 item preferences in one atomic backend request, rather than one request per channel. Larger selections use sequential requests. The frontend applies confirmed changes in one cache update, preserving unrelated preferences and successful requests if another fails. Empty or unavailable custom sections and empty Favorites disable these actions. Mobile remains unchanged.
Use a channel's Add to section menu to change the personal or shared assignment. Each section uses a checkbox: checking moves the channel into that section, and unchecking removes it. Only one section per scope is assigned; the personal and shared assignments remain independent.
Choose smart grouping in the section dialog for automatic name matching. Smart sections match channel names literally and without regard to capitalization. They preserve ordinary section permissions and are not manual drop targets. Channels can appear in multiple matching smart sections. Loaded same-team channels join matching shared smart sections immediately, including after a rename; they do not wait for the next section refresh. If a channel's team metadata is missing, only an existing server-authorized match is retained. Channels from another team never become new local matches. Hovering an incompatible item over a section shows a not-allowed cursor and an explanation over the section, including automatic membership, shared-scope restrictions, and channels already in the section. Returning a channel to its matching built-in channel group removes only its existing manual assignment.
Support is organized manually through a personal section. The app does not classify support channels by their names or silently create a Support section.
Verify personal and shared creation, same-name sections in different scopes, private-channel assignment, and rejecting private-channel assignment to a shared section. Check collapse and reload, stale requests after an account change, empty sections, assignment failures, and one channel in both scopes. Check the New menu, both dialog switches, keyboard access, edit-dialog focus, destructive deletion, and per-section unread and sort preferences after reload. Confirm unread filtering does not change section membership or another section's rows. Scroll a long sidebar with many sections, reorder both custom and built-in sections, and confirm the order survives reload. Keyboard navigation and section shortcuts must follow the same order as the rendered rows. Drag a channel between sections and confirm the sidebar stays visible while lookups refetch, including with a slow or paused connection. When a channel belongs to both a personal and a shared section, drag its personal-section row into the ungrouped list. Only the personal assignment is removed; the shared assignment remains. Repeat from the shared-section row to verify the opposite scope.
Creation actions
The sidebar's New dropdown spans its button's full width. New offers separate New channel and New direct message actions in both sidebar layouts. New channel opens the existing name, visibility, and optional invitations flow. New direct message opens the existing recipient picker, including people, external email addresses, private groups, and available agent personas. The sectioned sidebar also offers New section in the same menu.
Check each creation action with the sidebar flag on and off; changing the layout must not change the creation flow.
When calls are enabled, Live appears below the rail's toolbar while an active
quick call is available. It stays visible while browsing sections and during conversation
search, and disappears when no active quick calls remain. Entries are titled
Call with <creator's name>. Clicking a call opens
its camera/microphone setup at /app/meet/join/<token>; it does not join immediately.
Live rows use the shaking incoming-phone icon, respecting reduced motion.
The Channels navigation phone indicator appears for active channel calls or
active quick calls visible to you.
This list includes calls you own, joined, or were invited to during the current
live session. Declining or letting the incoming popup expire stops ringing but
keeps that active call available here. The invitation does not carry forward to
a later session of the same reusable call link.
Leaving and rejoining keeps the row available while another participant remains.
When everyone leaves, the session ends; reopening its link starts a new session.
If a restored Chat selection is already open in another view, its preview stays
closed but the saved selection is retained. Close the other view, then select
the conversation again or reopen Chat to restore its preview. Verify that an
unrelated rail preference change while blocked does not erase the saved selection.
While reading older history or composing in the preview, incoming notifications
(including ones for other channels) must not jump to latest, blank/refetch the
messages, or revoke composer focus. To check this, leave an unsent draft in a
preview scrolled into older history and deliver a notification. Selecting another
conversation or explicitly navigating to a message must still work.
The sidebar search action expands a field under the title. Search results replace
the section list with compact conversation rows and preserve the selected
channel. Closing search restores the section list and scrolls to that selection
when available. Search merges the complete joined-channel list with authorized
service results, deduplicates by channel ID, and retains loaded unread metadata.
Clearing the query restores ordinary pagination.
Each primary channel list and the DM panel keeps its own persisted sort: last viewed, last updated, or date created. Custom section channels follow that section's selected sort, defaulting to alphabetical order. Loading failures show Retry without hiding already loaded rows. Loading another page must preserve keyboard focus and scroll position.
Arrow Down / j follows visible rows, including section headings. h / l
collapse or expand the focused section. [ / ] jump between primary and custom
section headings, including the DM heading. Paging at the last loaded channel
retains focus until the next page arrives.
From a custom-section heading in the middle of the list, use both [ and ];
each shortcut must move to the adjacent heading rather than the Team channels
heading.
On touch layouts, Channels shows only the Recent conversation feed, with channel
and DM message previews. Rows use Home's touch row: the unread dot in the left
rail, a 44px avatar, and a divider inset to the text column. The first six
favorited channels (favorite order) are pinned in a three-across grid above the
feed, iMessage style, and leave the feed below; tapping a pin opens it and a
hold opens its action menu, where Unfavorite unpins it. There are no view tabs or reserved tab-header space;
older saved tab selections and mobile-tab links cannot change the list. It loads
more as the list approaches the end and supports pull to refresh.
Rows use the same touch highlight as Home and Email: taps retain feedback while
opening, holds stay highlighted for the action menu, and scrolling or cancelling
a touch clears the press highlight.
The mobile dock Search button opens the independent Search route. Its Channels
and People categories search the complete channel list, cached channel names,
and people directly; the conversation list does not constrain results. Full-text search is explicit,
and People uses the existing channel-content scope. Closing search resets its
session; the conversation list retains its browse pagination. See
Search for mode, keyboard, and session-reset checks.
With enable-graphql-soup enabled, open an unread conversation from the mobile
list and return to the list: all notifications on top-level messages should be seen,
including mentions and reactions older than the global feed's loaded page.
Replies and mentions inside threads remain unread. Channel-view unread badges
only represent top-level messages and mentions; unread replies and reactions do
not contribute to that badge. Top-level reactions are still marked seen on open. Verify an older unread root behind a newer reply still badges.
Inbox retains its own thread-stack behavior.
Each ordinary conversation click opens the bottom, including re-clicks,
shift-clicks, mobile opens, reloads, and favorites. Explicit search hits and message
links still open their target. Each accepted click marks top-level notifications
from the full loaded edge seen; an abbreviated list edge is never sufficient.
A rejected selection or unavailable split must not mark the conversation read.
Non-participant rows retain their membership status and do not mark notifications.
Shift-click and the row menu's Open in new split open a loaded row without
waiting for notifications: hold the single-channel SoupNotifications request
(UPDATED_AT, limit 1) and the split must still appear at once. Its full edge
loads after the open. A failed load leaves the split open and skips that marking;
messages on screen still mark themselves read as they become visible.
Shift-click a favorite whose channel is not loaded in the rail: its membership
and full notification edge load before the split opens with the same top-level
read policy. Selecting another channel while that request is pending must cancel
the pending open; failed lookups must not open a split or mark anything seen.
With GraphQL enabled, the app-shell Chat badge uses ChannelUnreadPresence: only
channel IDs and at most one unread top-level message/mention ID/state per channel, with a
500-channel candidate bound and no history, message previews, or metadata. It
excludes replies, thread mentions, and reactions, matching the channel-row badges
in both GraphQL and REST modes. It shares the channel lists' refreshes after notification patches, mark-read, and
reconnect. Merely rendering that badge, subscribing to realtime notifications,
or applying local read/done overrides must not start the full SoupNotifications
feed. Check this with document-mention notifications disabled too (the production
default): mention cleanup must wait until a real data/status reader activates the
feed, then continue cleaning up loaded mentions. Full notification selection and
pagination remain unchanged. Automatic/debounced read markers log failures and
leave failed reads unread; they must not produce unhandled promise rejections or
block the separate email read marker. Cold bulk actions wait for loading
and report failures rather than treating pending data as an empty list. The
Inbox badge still uses its own full Soup query for channel/thread membership.
With GraphQL enabled, channel lists request at most one unread message notification
per channel through an aliased, filtered notifications edge. An empty edge means
no unread messages; invites and call notifications do not light the dot. Recent
cards still use the latest-message preview. Full notification edges load only for
an opened unread conversation, so mark-read and message targeting retain their
complete top-level inputs in Chat and thread-scoped inputs in Inbox. Reopening
a conversation must refresh that full
edge even within 30 seconds; mark-read waits for the refresh rather than using
older cached notifications. Failed server lookups and successful server lookups with no matching
channel show Conversation unavailable with Retry, never permanent loading.
Retry rather than marking just the one unread witness. Repeated mobile taps must
open the last selected conversation, not a slower earlier request.
A backend-free cache regression runs on desktop and phone viewports:
bunx playwright test --config src/lib/queries/channel/browser-test/playwright.config.ts.
It uses the production normalized exchange, query adapter, and detail state with a
controlled transport. Confirm a channel, type a draft, then deliver repeated empty
cache projections: the composer must remain mounted. A fresh server absence must
hide it, a cached positive row must leave it hidden, and a fresh grant must recover
it. See the desktop fixture and
phone fixture; these show synthetic data,
not a full app session.
Opening also refreshes that channel's bounded unread edge in the same request. Read a DM on another device while its web sidebar retains an unread dot (for example, with the read-status websocket update withheld), then open it on web. The dot and DM unread count must clear without reloading, even when the complete unread response is empty and no mark-read mutation runs. Another unread DM must keep its dot.
Check cached Home → Chat navigation, section browsing/search, and unread state after a
read, a new notification, deletion, and reconnect, without reloading the page.
With the mark-read response delayed, channel/DM dots, section counts, and new-activity
targets should clear as soon as the local read is applied. A failed read restores
them; a stale unread response for that same notification must not relight them.
A different unread notification must still light the dot. With the normalized
cache enabled, a new channel message notification writes its unread relationship
and adds the channel to the cached Chat badge page locally. Delay the following
HTTP refresh: the channel dot and Chat badge must appear before that response,
without a reload. Also test an initially empty badge page, duplicate deliveries,
multiple channels, and a notification arriving during a read. The local write
must not replay other channels' read states. Invites, calls, and already-read
notifications must not light message dots. Background refreshes still reconcile
the bounded edges and recover missed updates on reconnect; an unavailable/cold
cache falls back to the network path. These updates must not activate
an otherwise-unused full notification feed. Cache reads remain asynchronous:
a brief spinner can still appear, but cached rows must not wait for a background
network refresh. Conversely, cache-and-network refreshes must start without
waiting for a busy cache worker. Successful foreground query results display
before cache persistence finishes; a delayed acknowledgement must not replay old
rows or overwrite an optimistic update. Check initial and continuation pages with
a slow cache, overlapping refreshes, and leaving/reopening Chat during a write.
A cache write failure must not discard successful network rows. Mutations and
cache-only hydration still wait for their durable/cache-projection work.
A late cache snapshot must not replace newer network rows. Check a cold offline
open too: a cache hit arriving
after the network failure must remain usable without erasing the refresh error.
If more unread notifications
remain, the limited edge must refresh to the next one rather than staying empty.
Refreshing unread indicators while composing must preserve the conversation,
scroll position, and input focus. To check stale-cache recovery, mark notifications
read/done in another tab, then repeat the action in a stale tab. Empty or partial
changed-row responses must still reconcile mounted Soup and notification readers,
without resetting loaded pages or starting an unused global notification feed.
With the normalized cache, a Done writes the rows it left out as done
(confirmEntityNotificationsDone), and a mark seen that left out a row the tab
showed unseen reads every reader again; otherwise only readers the cache does not
maintain are read again.
Undo must use only the mutation's returned IDs, not IDs from the subsequent refresh.
The backend must support the new edge arguments before deploying the frontend
that requests them.
Call lifecycle
The active-call panel above the composer, the channel's call tab, and floating call controls share one session. Joining from the panel switches the current channel surface to the live call. Repeated Join clicks while connecting should produce one connection; leaving from either control ends the same call. Navigate away and return while connected to check that the call and its controls remain usable.
The Open chat button at the bottom-right opens chat beside the video.
Copy Meeting Url sits at the bottom-left on desktop and becomes icon-only in narrow panes.
Active phone calls keep the channel header island and place Copy Meeting Url
in a matching header island using the shared CopyButton. The media control bar
fills the space beside the separate chat button, below the video and within side
insets. Back keeps the call running. Controls and header islands stay visible;
idle auto-hide is disabled. Phone calls hide the app's bottom navigation and
channel Invite action; Invite returns when leaving the live call tab. Tap or click a participant to
focus them and tap again to return to the grid; speakers have an accent border.
The panel has a Call chat heading and
spans the full call content height, including the media controls row. The controls
stay centered under the video on wide panes. In narrow desktop panes, chat overlays
the video. On phones, chat opens in the shared bottom sheet; drag the handle, tap the backdrop, or press Escape
to dismiss it. On desktop, Close chat or Escape closes the panel. Closing
returns focus to the chat button, and reopening preserves the draft and scroll
position. The call continues while chat is open or closed.
Signed-in participants in channel, quick, and scheduled calls use the same chat
panel. Guests in quick and scheduled calls can also open chat and read and send
text without signing in. Guest authors appear as Name (Guest). Their composer
uses Enter to send on desktop and the Send button on touch devices, preserves drafts on close, and
keeps failed messages available to retry. Guest chat refreshes while open and is
available only while that guest is connected to the call. Check a signed-in
participant and a guest exchanging messages in both directions, then verify the
guest loses access after leaving or after the call ends. Guest messages remain
in the saved call discussion. Each call session has one persistent message thread;
signed-in participants use the
shared message composer, attachments, reactions, and message actions. The @
menu offers Macro and available owned and team agents. Mention an agent and send
to invoke it in the call thread; follow-up mentions use the same thread. Reply
on your own or another participant’s message inserts a quote into the bottom
composer while preserving its draft and attachments. Enter sends; subsequent
messages and quoted replies join the same thread. Clicking a quote highlights its
message in the live chat; Shift-click opens its durable saved-call link. Participants see new messages without reopening the panel.
Check simultaneous first sends from two participants, edit/delete/reaction
updates, a retained unsent draft after toggling chat, and a new incoming message
while scrolled into history.
After the call ends, its recording page shows a read-only Call chat below
the transcript. A copied chat message link opens
/app/call/<callId>?call_message_id=<messageId> and highlights that message in
the recording's chat. Clicking the highlighted message clears the target from
the pane's route while leaving chat expanded; verify this on standalone and
Drive recording pages. A transcript search result clears any earlier chat
target in that pane. In an already-open Home call preview, follow a second
message link and then open the call without a message target: the highlight
must move to the second message and then clear without remounting the preview.
After following a message link, scroll away and follow that same link again:
the view must return to the message. Check repeated links in Home, Drive, and
standalone recordings, and repeated quote clicks in live chat; navigation must
preserve the mounted thread and any unsent draft.
A new call in the same channel starts a separate thread.
An initial missing thread means the call has no messages yet. If a later chat refresh reports the thread missing or access denied after messages loaded, show the retry error and hide the stale thread. Verify that it never shows the empty-conversation prompt alongside cached messages. A transient server error may retain readable messages; Retry restores the thread when access and the request recover.
For recovery checks, keep another participant connected and briefly interrupt the first participant's network. Recovery may rejoin that same live call. It must not start a replacement call if the original ended, or rejoin after the user chose Leave. A failed join must restore the Try again control even if background cleanup is slow.
If another call prevents joining, the error should say to leave the current call first. Trying to join another channel must keep the current call connected, with its participants and controls intact. A restored live session must clear any earlier join or recovery error. Failed Join, Call Again, and Leave actions must not produce unhandled promise rejections.
On iOS, ending a call during connection must leave Join usable. If CallKit restores or answers another call while an earlier join or leave finishes, the controls must follow the current native call; finishing the old operation must not restore the old call or remove the new call's end handler. An empty native snapshot before the first media update must not cancel a new join. Once native has reported the session, disconnecting or ending it must cancel pending connection/recovery and allow a new join. Cancelling after a token is issued must also remove server membership, even if media has not connected yet. Repeated end events share that cleanup; a newer native call must survive while cleanup for the cancelled attempt finishes. Restore the same channel while transport cleanup is pending and check that no server leave is sent for the restored session. Join must also accept a retry during cancellation cleanup. If a server leave was already sent, the retry shows Connecting and waits for that request before registering again.
Channel tabs
Private and team channels show an Invite button on the right of both the
split header and the inline conversation header for current participants. On
mobile it renders as its own floating glass pill next to the Call pill (the
split header is pointer-events-none, so the button must sit in a
HeaderIsland to be tappable). Click it to open Invite people to <channel>
using the standard dialog at the top of the viewport, matching the create menu
and create-channel dialog (a drawer on mobile). Choose Add all members of <team> to add current teammates once, or Add specific people to search
teammates and enter external email addresses using the same recipient picker as
channel creation. Existing channel members are excluded. Add submits; Cancel,
Close, or Escape dismisses without sending. Failed additions preserve the
selection for retry. The team option is disabled when no team is available.
This action does not enable team auto-join. Check opening and reopening,
switching options, keyboard recipient selection, external email chips,
cancellation, and focus restoration before sending invites.
Inset tabs sit in the channel header:
Messages / Attachments / Calls / Participants.
Ask Macro, Invite, and Call actions remain in channel headers, with the
live-phone-call exceptions described above. On narrow desktop panes, the tabs
collapse from text labels to icons. Standalone mobile channels
keep view selection in the title menu. In both a single channel and an adjacent
channel split, the message composer stays fully visible at the bottom. The
Calls tab lists
recordings for that channel
(same rows as the Calls soup view, filtered to this channel). The live Call tab
appears while a call is in progress. Ask Macro opens a new chat pane with the channel
already @mentioned as context (see ai-chat.md). On mobile it lives in the channel title's
... drawer instead. Clicking the radio input can time out — click the adjacent label text
instead.
In the Chat workspace — and wherever a channel opens inline inside another
view's detail stack (a channel mention followed from the email view, say) — the
conversation renders an inline detail whose top bar holds the channel avatar
and name, the same inset tab strip, live viewer avatars, and the Call and
Ask Macro buttons. An ellipsis follows the name — after the breadcrumb where
the host supplies one, as in Home — and opens the same entity actions as
right-clicking the conversation's rail row: Open in new split (when available),
Rename, Set channel picture,
Remove channel picture (only when the channel has one),
Favorite/Unfavorite, Snooze notifications…, Mute notifications,
Remind me, Copy Link, Copy ID. A channel can therefore be favorited or
given a picture without finding its row, from Chat and from every view that
opens one inline. The menu appears once the conversation itself has loaded,
reusing a cached conversation without another activation fetch. Opening the
conversation still refreshes its unread notifications. The split's own title
... menu offers the same picture actions.
Calls tab: recordings, transcriptions, and summaries for this channel. Click a
row to open the call. The search field above the list matches call names and
transcripts in this channel; queries shorter than 3 characters are not sent.
Empty copy: No calls in this channel. No matches: No results for "…".
Shorter queries: Keep typing to search.
Leaving from the channel's call controls switches to Messages immediately.
Disconnect and server cleanup continue after that switch; slow or failed RTC
teardown must not leave the channel showing the join screen.
In a live call, controls stay centered beneath the participant area when chat opens beside it. Microphone, camera, and background controls each have an icon button on the left and a settings caret on the right, separated by a divider. The icon toggles the feature; hover previews settings and the caret pins them. Check both chat states and narrow layouts, including Escape and keyboard focus in settings. Camera-off tiles use a subtle gradient from the profile picture's average color; missing or unreadable pictures keep the neutral panel background.
Participants tab keeps people and bots within the available page height, with
separate scrolling lists and fixed search/invite controls. Team access appears
between them when available. Search uses the shared
input group; add, invite, and new-bot actions use neutral outline buttons.
The bots section stays compact with few or no bots. Search by display name,
email, or role and clear the search to restore the list; scrolling a long member
list must leave the bots section and participant controls visible.
Participants tab:
Copy invite link, participant search box.- Add: combobox
Add participants by name or email+Add Participantbutton. - Dividers frame the Add Participant controls, not the scrolling list. Each row shows the display name above the email, both on a single truncated line without text tooltips, and a title-cased role badge on the right. Click anywhere on the row or focus it and press Enter to open the DM; Shift-click opens it in a new split.
- The separate
Remove participantbutton never opens the DM (owner and current user showCannot remove participant, disabled). - Team access:
Team channelswitch (disabled until you belong to a team). - Bots:
New bot,Search bots by name or handlecombobox,Invite bot— webhook-powered channel participants. - Bot rows match participant rows: name above a truncated handle/description,
a
Botbadge, and a row link that opens the bot. Copy webhook and Remove are separate actions that do not open the bot.
On touch devices, this page uses People / Bots / Settings bubble tabs.
Bots appears when bot management is enabled; Settings appears for channel owners
and admins when team settings are available. People keeps search and the compact
Copy invite link / Add participants buttons above a virtualized scrolling list.
Add participants opens a bottom sheet; Bots has its own full-height list and an
Invite bot sheet. Bots uses the same search toolbar and plain rows as People;
Search bots filters existing bots by name, handle, or description, with compact
New bot and Invite bot actions beside it. The fallback New button is hidden
throughout this page and returns when leaving it. Channel views have no floating
AI composer. Both sheets use the standard mobile keyboard-aware layout and
close after a successful add. Check switching tabs, closing/reopening both sheets,
and scrolling a long participant list above the bottom dock, with and without the
keyboard open. An invite-bot request from the channel menu opens the Bots tab and
its invite sheet.
Incoming call ringing
For cross-tab ringing checks, sign the recipient into two tabs and start a call from another account. Both tabs may show the incoming call; only one should play the chime. Closing the audible tab lets the other take over while the call is still ringing. Answering or dismissing stops ringing across tabs. An unanswered call stops ringing after 30 seconds, including after a tab takes over.
Declining is per user and per device set, not per tab: the sidebar X and the
rail Decline button send POST /call/record/{call_id}/decline, and every other
signed-in device of the same user (other browsers, the iPhone's CallKit ring)
stops ringing via call_declined. Declining on the iPhone lock screen does the
same for the browser. Other channel members keep ringing, and the call stays
active for them. Closing only the browser notification toast silences the chime
without declining.
Onboarding channel
New users get Macro Support x <name> seeded with a welcome message that @mentions them —
useful as a guaranteed-existing channel in tests.
Locally sent channel messages and thread replies enter with a brief upward slide and fade, without bubble scaling. Opening history or remounting a row does not replay the effect. Reduced-motion preferences disable it. Consecutive messages from the same sender should enter in their grouped layout, without briefly showing an avatar/header and collapsing after acknowledgement. Check this with a delayed send response in both the channel and a thread, sending each follow-up within five minutes of a confirmed message with no replies. Messages from different senders, including bot messages triggered by different users, should retain separate headers.
For mobile send regressions, keep the software keyboard open and send several short and multiline messages consecutively. The keyboard should remain open, the cleared composer should retain focus, and a pinned chat should remain at the bottom through composer resizing and server acknowledgement. Check that restoring the caret after send does not pan the page while the keyboard resizes. Repeat with the keyboard's own dictation and check that sent text does not return. Scroll into history before an incoming message or acknowledgement and verify that it does not pull you to latest.
For composer cleanup, repeatedly open and leave channels and threads, then switch between touch and keyboard/mouse input. Retired composers must not keep reacting to input-modality changes. Memory-pressure crashes still require an iPhone run with the app's native memory diagnostics.
Channel pictures
Channels and group chats can have a custom picture. Anyone who can Rename a
channel can also set its picture: any active participant of a named channel,
from the channel's rail context menu, the Chat title ellipsis, or the split's
own title ... menu. Direct messages can be neither renamed nor given a
picture. Choose Set channel picture to add or replace a picture. Select a PNG,
JPG, WebP, or GIF up to 16 MB. The upload must finish before the picture is
saved; the server accepts only supported images uploaded by the person setting
the picture. An error leaves the previous picture in place. When a picture is
set, the menu also offers Remove channel picture to restore the standard
channel icon. The picture
beside the title is display-only and also appears in shared channel rows.
Picture changes refresh other participants' open sessions, including after
reconnecting.
A team channel the viewer has not joined shows its picture without editing
controls. One-to-one direct messages
continue to show the other person's user picture.
Opening the slash menu with / lists Normal Text, headings, and the other
Markdown options before Query and Database. Typing /query filters to the Query
action; /database creates a new database and inserts its editable card.
When Databases is enabled, type /query in a channel message or thread reply and choose Query to insert a live question. Ask with Enter or the Ask button, then accept the answer before sending the message. Enter in the question box belongs to the question and must not send the channel draft. Recipients can read the live answer subject to their database access. Database @ mentions in message composers remain compact; Expand turns one into an editable database card.
Downloading channel videos
Video messages show Download over the player on hover or keyboard focus; the control stays visible on touch devices. There is no footer below the video. The expanded viewer has the same action. These retrieve the original bytes and filename from static-file metadata; they do not record or transcode playback. If the metadata is unavailable, the fallback extension comes from the response MIME type. Linked video preview cards also offer Download, using the document's current version, name, and file type. See Downloading files for progress, cancellation, retries, and mobile save/share verification.
Opening or reopening the expanded video viewer focuses the video. Press Space to pause or resume immediately. Tab moves through the native player controls and viewer actions; focusing Download explicitly still allows keyboard downloads. With the video focused, Escape closes the viewer and returns focus to the thumbnail that opened it.
Pending message drafts
Sending clears the composer immediately while delivery is pending. If delivery fails and the composer is still empty, its text, mentions, and attachments return. A new draft typed during delivery stays intact if the earlier send fails. Verify this with both the Send button on a phone and the desktop composer.
For tab performance QA, switch Attachments → Calls → Participants → Messages
in both the routed channel and a block split. Each actual selection should
produce one channel.tab interaction with its channel.*.view child; repeat
the current selection and confirm it does not create a new interaction.
Work in a DM with an agent account
Behind enable-agent-work, a 1:1 DM shows the other account's registered work
when that account is an agent (isAgentAccount) and has work you can open. The
rule lives in features/agent-work/core/work-visibility.ts. DMs with people,
group DMs, and channels show nothing.
The side panel toggle appears in the top bar only while there's work, using the
floating SidePanel the agent session uses. When the agent goes from no work to
some, a " started working" label appears beside the toggle for six
seconds without opening the panel; clicking it opens the panel. Clicking a row
opens the session in a new split. Rows keep their order as state changes.
To exercise it, register a session as the agent account through the SDK
(session.registerAsWork()), share it with the viewer, and watch the DM update
live. session.unregisterAsWork() removes it. A registered session the viewer
can't open stays hidden.