Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(channels): share channel and DM icons across surfaces (#9196)

gbirmanb057b98f5a4d
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index 249073c0e5..013f5f0e4e 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -827,3 +827,7 @@ Keep existing tags and apply to the selected rows when the drop row is selected.
Use the shared scoped drag helpers and overlayIcon for the tag chip.
The backend-free browser regression is
`bunx playwright test --config src/features/property/tags/browser-test/playwright.config.ts`.
+
+Use `features/channel/channel-icon.tsx` for conversation identity in rows,
+favorites, and headers: channel pictures or hashtags, human/self-DM avatars,
+and bot personas share one renderer; keep surface sizing in the caller.
diff --git a/apps/web/src/features/channel/channel-icon.tsx b/apps/web/src/features/channel/channel-icon.tsx
new file mode 100644
index 0000000000..4f3c731f63
--- /dev/null
+++ b/apps/web/src/features/channel/channel-icon.tsx
@@ -0,0 +1,116 @@
+import { PersonaAvatar } from '@app/features/agent-dms/components/persona-avatar';
+import { EntityIcon, type EntityIconProps } from '@core/component/EntityIcon';
+import { UserIcon, type UserIconSize } from '@core/component/UserIcon';
+import { useChannelsContext } from '@core/context/channels';
+import { useUserId } from '@core/context/user';
+import type { ChannelType } from '@service-storage/generated/schemas/channelType';
+import { Show } from 'solid-js';
+import { ChannelAvatar } from './channel-avatar';
+
+export type ChannelIconProps = {
+ channelId: string;
+ channelType?: ChannelType | null;
+ participantIds?: readonly string[];
+ name?: string;
+ avatarSize?: UserIconSize;
+ class?: string;
+ suppressClick?: boolean;
+ showTooltip?: boolean;
+ weight?: EntityIconProps['weight'];
+ theme?: EntityIconProps['theme'];
+};
+
+function DirectMessageIcon(props: ChannelIconProps) {
+ const userId = useUserId();
+ const channels = useChannelsContext();
+ const channel = () => channels.channelsById()[props.channelId];
+ const agentDm = () => channel()?.agent_dm;
+ const participantId = () => {
+ const participants =
+ props.participantIds ??
+ channel()?.participants.map((participant) => participant.user_id) ??
+ [];
+ return participants.find((id) => id !== userId()) ?? participants[0];
+ };
+
+ return (
+ <div class="size-full flex">
+ <Show
+ when={agentDm()}
+ fallback={
+ <Show
+ when={participantId()}
+ fallback={
+ <EntityIcon
+ targetType="direct_message"
+ size="fill"
+ class={props.class}
+ weight={props.weight}
+ theme={props.theme}
+ />
+ }
+ >
+ {(id) => (
+ <Show
+ when={id().startsWith('bot|')}
+ fallback={
+ <UserIcon
+ id={id()}
+ isDeleted={false}
+ size={props.avatarSize ?? 'fill'}
+ class={props.class}
+ suppressClick={props.suppressClick}
+ showTooltip={props.showTooltip}
+ />
+ }
+ >
+ <PersonaAvatar
+ botId={id().slice(4)}
+ name={props.name ?? channel()?.name ?? ''}
+ size={props.avatarSize ?? 'fill'}
+ class={props.class}
+ />
+ </Show>
+ )}
+ </Show>
+ }
+ >
+ {(persona) => (
+ <PersonaAvatar
+ botId={persona().bot_id}
+ name={persona().name}
+ avatarUrl={persona().avatar_url}
+ size={props.avatarSize ?? 'fill'}
+ class={props.class}
+ />
+ )}
+ </Show>
+ </div>
+ );
+}
+
+/** Shared conversation identity for entity rows, favorites, and headers. */
+export function ChannelIcon(props: ChannelIconProps) {
+ return (
+ <Show
+ when={props.channelType === 'direct_message'}
+ fallback={
+ <ChannelAvatar
+ channelId={props.channelId}
+ class={`size-full ${props.class ?? ''}`}
+ fallback={
+ <EntityIcon
+ targetType="channel"
+ size="fill"
+ class={props.class}
+ weight={props.weight}
+ theme={props.theme}
+ />
+ }
+ />
+ }
+ >
+ <DirectMessageIcon {...props} />
+ </Show>
+ );
+}
diff --git a/apps/web/src/features/channel/components/ChannelTopIcon.tsx b/apps/web/src/features/channel/components/ChannelTopIcon.tsx
index 5b21ab4f55..5c00df20b2 100644
--- a/apps/web/src/features/channel/components/ChannelTopIcon.tsx
+++ b/apps/web/src/features/channel/components/ChannelTopIcon.tsx
@@ -1,13 +1,10 @@
-import { PersonaAvatar } from '@app/features/agent-dms/components/persona-avatar';
-import { ChannelAvatar } from '@channel/channel-avatar';
-import { UserIcon } from '@core/component/UserIcon';
-import { useChannel, useChannelType } from '@core/context/channels';
-import { useUserId } from '@core/context/user';
+import { useChannelType } from '@core/context/channels';
import { useChannelParticipantsQuery } from '@queries/channel/channel-participants';
import type { ChannelParticipant } from '@queries/channel/types';
import { queryReadyGate } from '@queries/gate';
-import { ChannelType } from '@service-storage/generated/schemas/channelType';
+import type { ChannelType } from '@service-storage/generated/schemas/channelType';
import { Show } from 'solid-js';
+import { ChannelIcon } from '../channel-icon';
export type ChannelTopIconProps = {
channelId: string;
@@ -18,46 +15,20 @@ export type ChannelTopIconProps = {
/** Channel avatar, or the other participant's avatar for a direct message. */
export function ChannelTopIcon(props: ChannelTopIconProps) {
- const channel = useChannel(props.channelId);
- const userId = useUserId();
- const recipient = () => {
- return props.participants.find((p) => p && p.user_id !== userId());
- };
-
return (
- <Show
- when={channel()?.agent_dm}
- fallback={
- <Show
- when={props.channelType === ChannelType.direct_message && recipient()}
- fallback={
- <ChannelAvatar
- channelId={props.channelId}
- class="size-4 [&_img]:rounded-full"
- />
- }
- >
- {(recipient) => (
- <UserIcon
- id={recipient().user_id}
- isDeleted={false}
- size="sm"
- suppressClick={props.suppressClick}
- showTooltip={props.suppressClick ? false : undefined}
- />
- )}
- </Show>
- }
- >
- {(persona) => (
- <PersonaAvatar
- botId={persona().bot_id}
- name={persona().name}
- avatarUrl={persona().avatar_url}
- size="sm"
- />
- )}
- </Show>
+ <span class="inline-flex size-4">
+ <ChannelIcon
+ channelId={props.channelId}
+ channelType={props.channelType}
+ participantIds={props.participants.map(
+ (participant) => participant.user_id
+ )}
+ avatarSize="sm"
+ class="[&_img]:rounded-full"
+ suppressClick={props.suppressClick}
+ showTooltip={props.suppressClick ? false : undefined}
+ />
+ </span>
);
}
diff --git a/apps/web/src/features/entity/extractors/entity-icon.tsx b/apps/web/src/features/entity/extractors/entity-icon.tsx
index e6246f51e3..12a1a58f0d 100644
--- a/apps/web/src/features/entity/extractors/entity-icon.tsx
+++ b/apps/web/src/features/entity/extractors/entity-icon.tsx
@@ -1,19 +1,14 @@
-import { PersonaAvatar } from '@app/features/agent-dms/components/persona-avatar';
-import { ChannelAvatar } from '@channel/channel-avatar';
+import { ChannelIcon } from '@channel/channel-icon';
import {
EntityIcon as CoreEntityIcon,
type EntityIconProps as CoreEntityIconProps,
getEntityIconType,
} from '@core/component/EntityIcon';
import { TaskStatusIcon } from '@core/component/TaskStatusIcon';
-import { UserIcon } from '@core/component/UserIcon';
-import { useChannelsContext } from '@core/context/channels';
-import { useUserId } from '@core/context/user';
import type { StreamEvent } from '@service-connection/generated/schemas';
-import { Match, Show, Switch } from 'solid-js';
+import { Match, Switch } from 'solid-js';
import { ChatProviderIcon } from '../components/ChatProviderIcon';
import {
- type ChannelEntity,
type ChatEntity,
type EntityData,
isTaskEntity,
@@ -30,92 +25,26 @@ interface EntityIconProps {
theme?: CoreEntityIconProps['theme'];
}
-function DirectMessageIcon(props: {
- entity: ChannelEntity;
- class?: string;
- suppressClick?: boolean;
- showTooltip?: boolean;
- weight?: CoreEntityIconProps['weight'];
-}) {
- const userId = useUserId();
- const channels = useChannelsContext();
- const agentDm = () => channels.channelsById()[props.entity.id]?.agent_dm;
- const participantId = () => {
- const participants = props.entity.participantIds ?? [];
- return participants.find((id) => id !== userId());
- };
-
- return (
- <div class="size-full flex">
- <Show
- when={agentDm()}
- fallback={
- <Show
- when={participantId()}
- fallback={
- <CoreEntityIcon
- targetType="direct_message"
- size="fill"
- class={props.class}
- weight={props.weight}
- />
- }
- >
- {(id) => (
- <Show
- when={id().startsWith('bot|')}
- fallback={
- <UserIcon
- id={id()}
- isDeleted={false}
- size="fill"
- class={props.class}
- suppressClick={props.suppressClick}
- showTooltip={props.showTooltip}
- />
- }
- >
- <PersonaAvatar
- botId={id().slice(4)}
- name={props.entity.name}
- size="fill"
- class={props.class}
- />
- </Show>
- )}
- </Show>
- }
- >
- {(persona) => (
- <PersonaAvatar
- botId={persona().bot_id}
- name={persona().name}
- avatarUrl={persona().avatar_url}
- size="fill"
- class={props.class}
- />
- )}
- </Show>
- </div>
- );
-}
-
export function EntityIcon(props: EntityIconProps) {
const iconType = () => getEntityIconType(props.entity);
const task = () => (isTaskEntity(props.entity) ? props.entity : undefined);
- const isDirectMessage = () =>
- props.entity.type === 'channel' &&
- props.entity.channelType === 'direct_message';
-
const isChatEntity = () => props.entity.type === 'chat';
- const channelId = () => {
+ const channel = () => {
const entity = props.entity;
- if (entity.type === 'channel') return entity.id;
+ if (entity.type === 'channel') {
+ return {
+ channelId: entity.id,
+ channelType: entity.channelType,
+ participantIds: entity.participantIds,
+ name: entity.name,
+ };
+ }
if (
entity.type === 'channel_message' &&
entity.channelType !== 'direct_message'
- )
- return entity.channelId;
+ ) {
+ return { channelId: entity.channelId, channelType: entity.channelType };
+ }
};
return (
@@ -142,29 +71,15 @@ export function EntityIcon(props: EntityIconProps) {
/>
)}
</Match>
- <Match when={isDirectMessage()}>
- <DirectMessageIcon
- entity={props.entity as ChannelEntity}
- class={props.class}
- suppressClick={props.suppressClick}
- showTooltip={props.showTooltip}
- weight={props.weight}
- />
- </Match>
- <Match when={channelId()}>
- {(id) => (
- <ChannelAvatar
- channelId={id()}
- class={`size-full ${props.class ?? ''}`}
- fallback={
- <CoreEntityIcon
- targetType={iconType()}
- size="fill"
- class={props.class}
- weight={props.weight}
- theme={props.theme}
- />
- }
+ <Match when={channel()}>
+ {(identity) => (
+ <ChannelIcon
+ {...identity()}
+ class={props.class}
+ suppressClick={props.suppressClick}
+ showTooltip={props.showTooltip}
+ weight={props.weight}
+ theme={props.theme}
/>
)}
</Match>
diff --git a/apps/web/src/features/entity/tests/entity-icon.test.tsx b/apps/web/src/features/entity/tests/entity-icon.test.tsx
index 882c9ec973..cb00fa6aa8 100644
--- a/apps/web/src/features/entity/tests/entity-icon.test.tsx
+++ b/apps/web/src/features/entity/tests/entity-icon.test.tsx
@@ -1,3 +1,5 @@
+import { FavoriteIcon } from '@app/features/favorites/FavoriteIcon';
+import { ChannelTopIcon } from '@channel/components/ChannelTopIcon';
import GitMergeBold from '@icon/system/bold/git-merge-bold.svg';
import CalendarIcon from '@icon/system/regular/calendar.svg';
import EnvelopeIcon from '@icon/system/regular/envelope.svg';
@@ -19,6 +21,23 @@ import type {
UnknownForeignEntity,
} from '../types/entity';
+type CachedIconChannel = {
+ channel_type: 'direct_message';
+ name: string;
+ participants: { user_id: string }[];
+ agent_dm?: { bot_id: string; name: string; avatar_url?: string | null };
+};
+
+const channelCache = vi.hoisted(() => ({
+ read: (): Record<string, CachedIconChannel> => ({}),
+}));
+vi.mock('@queries/channel/channel-participants', () => ({
+ useChannelParticipantsQuery: vi.fn(),
+}));
+vi.mock('@app/util/favorites', () => ({
+ favoriteIconType: () => 'channel',
+}));
+
const channelPicture = vi.hoisted(() => ({
url: undefined as string | undefined,
channelIds: [] as string[],
@@ -37,7 +56,8 @@ vi.mock('@core/constant/allBlocks', () => ({
}));
vi.mock('@core/context/user', () => ({ useUserId: () => () => 'user' }));
vi.mock('@core/context/channels', () => ({
- useChannelsContext: () => ({ channelsById: () => ({}) }),
+ useChannelsContext: () => ({ channelsById: () => channelCache.read() }),
+ useChannelType: (id: string) => () => channelCache.read()[id]?.channel_type,
}));
vi.mock('@app/features/agent-dms/components/persona-avatar', () => ({
PersonaAvatar: (props: { botId: string; name: string }) => (
@@ -107,6 +127,7 @@ describe('Entity.Icon', () => {
beforeEach(() => {
channelPicture.url = undefined;
channelPicture.channelIds = [];
+ channelCache.read = () => ({});
});
const channel: ChannelEntity = {
@@ -182,6 +203,138 @@ describe('Entity.Icon', () => {
).toBe('Researcher');
});
+ it('updates favorite, row, and header DM avatars when participant data arrives', () => {
+ const [cached, setCached] = createSignal<Record<string, CachedIconChannel>>(
+ {}
+ );
+ channelCache.read = cached;
+ const { container } = render(() => (
+ <>
+ <FavoriteIcon
+ favorite={{
+ entityType: 'channel',
+ entityId: 'dm',
+ channelType: 'direct_message',
+ sortOrder: 0,
+ createdAt: '2026-01-01',
+ }}
+ />
+ <EntityIcon
+ entity={{ ...channel, id: 'dm', channelType: 'direct_message' }}
+ />
+ <ChannelTopIcon
+ channelId="dm"
+ channelType="direct_message"
+ participants={(cached().dm?.participants ?? []).map(
+ (participant) => ({
+ ...participant,
+ channel_id: 'dm',
+ role: 'member' as const,
+ joined_at: '2026-01-01',
+ })
+ )}
+ suppressClick
+ />
+ </>
+ ));
+ expect(container.querySelector('[data-testid="user-avatar"]')).toBeNull();
+ expect(channelPicture.channelIds).toEqual([]);
+
+ setCached({
+ dm: {
+ channel_type: 'direct_message',
+ name: 'Direct message',
+ participants: [{ user_id: 'user' }, { user_id: 'other-user' }],
+ },
+ });
+ expect(
+ [...container.querySelectorAll('[data-testid="user-avatar"]')].map(
+ (avatar) => avatar.getAttribute('data-user-id')
+ )
+ ).toEqual(['other-user', 'other-user', 'other-user']);
+
+ setCached({
+ dm: {
+ channel_type: 'direct_message',
+ name: 'Self DM',
+ participants: [{ user_id: 'user' }],
+ },
+ });
+ expect(
+ [...container.querySelectorAll('[data-testid="user-avatar"]')].map(
+ (avatar) => avatar.getAttribute('data-user-id')
+ )
+ ).toEqual(['user', 'user', 'user']);
+ });
+
+ it('uses the same persona for favorites, rows, and headers as cached identity changes', () => {
+ const [cached, setCached] = createSignal<Record<string, CachedIconChannel>>(
+ {
+ dm: {
+ channel_type: 'direct_message',
+ name: 'Assistant',
+ participants: [{ user_id: 'user' }, { user_id: 'bot|assistant' }],
+ },
+ }
+ );
+ channelCache.read = cached;
+ const { container } = render(() => (
+ <>
+ <FavoriteIcon
+ favorite={{
+ entityType: 'channel',
+ entityId: 'dm',
+ channelType: 'direct_message',
+ sortOrder: 0,
+ createdAt: '2026-01-01',
+ }}
+ />
+ <EntityIcon
+ entity={{
+ ...channel,
+ id: 'dm',
+ channelType: 'direct_message',
+ name: 'Assistant',
+ }}
+ />
+ <ChannelTopIcon
+ channelId="dm"
+ channelType="direct_message"
+ participants={(cached().dm?.participants ?? []).map(
+ (participant) => ({
+ ...participant,
+ channel_id: 'dm',
+ role: 'member' as const,
+ joined_at: '2026-01-01',
+ })
+ )}
+ suppressClick
+ />
+ </>
+ ));
+ expect(container.querySelector('[data-testid="user-avatar"]')).toBeNull();
+ expect(
+ [...container.querySelectorAll('[data-testid="agent-avatar"]')].map(
+ (avatar) => avatar.getAttribute('data-bot-id')
+ )
+ ).toEqual(['assistant', 'assistant', 'assistant']);
+
+ setCached({
+ dm: {
+ channel_type: 'direct_message',
+ name: 'Assistant',
+ participants: [],
+ agent_dm: { bot_id: 'researcher', name: 'Researcher' },
+ },
+ });
+ expect(
+ [...container.querySelectorAll('[data-testid="agent-avatar"]')].map(
+ (avatar) => avatar.textContent
+ )
+ ).toEqual(['Researcher', 'Researcher', 'Researcher']);
+ expect(channelPicture.channelIds).toEqual([]);
+ });
+
it.each(['user', 'other-user'])(
'keeps DM message rows on their DM glyph without fetching channel pictures (sender %s)',
(senderId) => {
diff --git a/apps/web/src/features/favorites/FavoriteIcon.tsx b/apps/web/src/features/favorites/FavoriteIcon.tsx
index f1b1e90038..f4baeca8e5 100644
--- a/apps/web/src/features/favorites/FavoriteIcon.tsx
+++ b/apps/web/src/features/favorites/FavoriteIcon.tsx
@@ -1,67 +1,56 @@
-import {
- favoriteIconType,
- useFavoriteDmRecipientId,
-} from '@app/util/favorites';
-import { ChannelAvatar } from '@channel/channel-avatar';
+import { favoriteIconType } from '@app/util/favorites';
+import { ChannelIcon } from '@channel/channel-icon';
import { EntityIcon } from '@core/component/EntityIcon';
-import { UserIcon, type UserIconSize } from '@core/component/UserIcon';
+import type { UserIconSize } from '@core/component/UserIcon';
+import { useChannelsContext } from '@core/context/channels';
import type { Favorite } from '@service-storage/generated/schemas/favorite';
+import { cn } from '@ui';
import { Show } from 'solid-js';
-/**
- * Icon for a favorite. DM channel favorites show the other participant's
- * avatar, and other channels show their channel picture, matching channel
- * rows elsewhere in the sidebar. Other favorites keep their entity icon.
- *
- * The favorite's identity must be stable for the component's lifetime
- * (favorites lists key rows by entity, so it is).
- */
-export function FavoriteIcon(props: {
+type FavoriteIconProps = {
favorite: Favorite;
avatarSize?: UserIconSize;
class?: string;
-}) {
- const dmRecipientId = useFavoriteDmRecipientId(props.favorite);
+};
+
+function FavoriteChannelIcon(props: FavoriteIconProps & { channelId: string }) {
+ const channels = useChannelsContext();
+ const channel = () => channels.channelsById()[props.channelId];
+
+ return (
+ <span class={cn('inline-flex size-4 shrink-0', props.class)}>
+ <ChannelIcon
+ channelId={props.channelId}
+ channelType={channel()?.channel_type ?? props.favorite.channelType}
+ name={channel()?.name ?? undefined}
+ avatarSize={props.avatarSize ?? 'sm'}
+ suppressClick
+ showTooltip={false}
+ />
+ </span>
+ );
+}
+
+/** Favorites adapt their identity to the same channel/DM renderer as rows. */
+export function FavoriteIcon(props: FavoriteIconProps) {
+ const channelId = () => {
+ if (props.favorite.entityType === 'channel') return props.favorite.entityId;
+ if (props.favorite.entityType === 'channel_message')
+ return props.favorite.channelId;
+ };
+
return (
<Show
- when={dmRecipientId()}
+ when={channelId()}
fallback={
- <Show
- when={
- props.favorite.entityType === 'channel' &&
- props.favorite.channelType !== 'direct_message'
- }
- fallback={
- <EntityIcon
- size="xs"
- targetType={favoriteIconType(props.favorite)}
- class={props.class}
- />
- }
- >
- <ChannelAvatar
- channelId={props.favorite.entityId}
- class={`size-4 ${props.class ?? ''}`}
- fallback={
- <EntityIcon
- size="xs"
- targetType={favoriteIconType(props.favorite)}
- class={props.class}
- />
- }
- />
- </Show>
- }
- >
- {(recipientId) => (
- <UserIcon
- id={recipientId()}
- size={props.avatarSize ?? 'sm'}
- suppressClick
- showTooltip={false}
+ <EntityIcon
+ size="xs"
+ targetType={favoriteIconType(props.favorite)}
class={props.class}
/>
- )}
+ }
+ >
+ {(id) => <FavoriteChannelIcon {...props} channelId={id()} />}
</Show>
);
}
diff --git a/apps/web/src/lib/utils/favorites.ts b/apps/web/src/lib/utils/favorites.ts
index e0565ac659..13688d99fd 100644
--- a/apps/web/src/lib/utils/favorites.ts
+++ b/apps/web/src/lib/utils/favorites.ts
@@ -6,16 +6,13 @@ import type { SplitContent } from '@components/app/split-layout/layoutManager';
import type { EntityIconSelector } from '@core/component/EntityIcon';
import { getIconConfig } from '@core/component/EntityIcon';
import { fileTypeToBlockName } from '@core/constant/allBlocks';
-import { useChannelsContext } from '@core/context/channels';
-import { useUserId } from '@core/context/user';
import {
type ItemEntity,
isAccessiblePreviewItem,
useItemPreview,
} from '@queries/preview';
-import { ChannelTypeEnum } from '@service-storage/client';
import type { Favorite } from '@service-storage/generated/schemas/favorite';
-import { type Accessor, createMemo } from 'solid-js';
+import type { Accessor } from 'solid-js';
/** Icon and legacy block name for a favorite; hosted details use their own route. */
export function favoriteBlockName(favorite: Favorite) {
@@ -103,36 +100,6 @@ export function favoriteDisplayName(favorite: Favorite): string {
);
}
-/**
- * The user whose avatar represents a DM channel favorite: the other
- * participant, resolved from the channels list like the channel rows in the
- * rest of the sidebar. Undefined for non-DM favorites (and while the channel
- * list loads), so callers can fall back to the entity icon.
- *
- * Call during component setup. The favorite's identity must be stable for
- * the component's lifetime (favorites lists key rows by entity, so it is).
- */
-export function useFavoriteDmRecipientId(
- favorite: Favorite
-): Accessor<string | undefined> {
- const entity = favoritePreviewEntity(favorite);
- const channelId = entity?.type === 'channel' ? entity.id : undefined;
- if (!channelId) return () => undefined;
- const ctx = useChannelsContext();
- const userId = useUserId();
- return createMemo(() => {
- const channel = ctx.channelsById()[channelId];
- if (channel?.channel_type !== ChannelTypeEnum.DirectMessage) {
- return undefined;
- }
- // A self-DM has no other participant; show the viewer's own avatar.
- const recipient =
- channel.participants.find((p) => p.user_id !== userId()) ??
- channel.participants[0];
- return recipient?.user_id;
- });
-}
-
/**
* Reactive display name for a favorite: subscribes to the entity's preview
* (fetching it if needed) and resolves like `favoriteDisplayName`.
diff --git a/docs/agent-guide/channels.md b/docs/agent-guide/channels.md
index 6b62a683cf..9a1aa726ee 100644
--- a/docs/agent-guide/channels.md
+++ b/docs/agent-guide/channels.md
@@ -867,7 +867,10 @@ that order. `Team channels` lists team channels; `Channels` lists every other
non-DM channel (public and private). Each section collapses on its own and
keeps its own sort; open sections split the column evenly, and the bottom-most
open one takes any remaining height. Favorites appears when
-the user has channel favorites and only lists channels. Channel favorites open
+the user has channel favorites and only lists channels. Favorites show a custom
+channel picture when set; otherwise all non-DM channels use a hashtag, including
+team channels. Favorites, regular rows, and headers share the same channel/DM
+icon renderer, including participant avatars, self-DMs, and bot personas. Channel favorites open
in the shared channel detail. Shift-clicking a favorite, channel, or DM opens that
conversation in a new split instead. Shift-click refreshes the notification
selection and opens at latest. Split opens mark top-level notifications seen,