@open-mercato/ui 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/backend/inputs/__tests__/TagsInput.test.tsx

@@ -2,8 +2,11 @@
 import * as React from 'react'
 import { act, fireEvent, screen } from '@testing-library/react'
 import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from '../../../primitives/dialog'
 import { TagsInput } from '../TagsInput'
 
+const escapeSuggestions = [{ value: 'user-admin', label: 'admin@acme.com' }]
+
 describe('TagsInput', () => {
   it('does not add the typed query when selecting a suggestion', () => {
     function Harness() {
@@ -112,4 +115,82 @@ describe('TagsInput', () => {
 
     jest.useRealTimers()
   })
+
+  describe('Escape on the suggestions list', () => {
+    it('closes only the suggestions and keeps Escape away from the host', () => {
+      const onHostKeyDown = jest.fn()
+
+      renderWithProviders(
+        <div onKeyDown={onHostKeyDown}>
+          <TagsInput value={[]} onChange={jest.fn()} suggestions={escapeSuggestions} />
+        </div>,
+      )
+
+      const input = screen.getByRole('textbox')
+      fireEvent.change(input, { target: { value: 'adm' } })
+      expect(screen.getByRole('button', { name: /admin@acme\.com/ })).toBeInTheDocument()
+
+      fireEvent.keyDown(input, { key: 'Escape' })
+
+      expect(screen.queryByRole('button', { name: /admin@acme\.com/ })).not.toBeInTheDocument()
+      expect(onHostKeyDown).not.toHaveBeenCalled()
+      expect(input).toHaveValue('adm')
+    })
+
+    it('lets Escape reach the host once the suggestions are closed', () => {
+      const onHostKeyDown = jest.fn()
+
+      renderWithProviders(
+        <div onKeyDown={(event) => onHostKeyDown(event.key)}>
+          <TagsInput value={[]} onChange={jest.fn()} suggestions={escapeSuggestions} />
+        </div>,
+      )
+
+      const input = screen.getByRole('textbox')
+      fireEvent.change(input, { target: { value: 'adm' } })
+      fireEvent.keyDown(input, { key: 'Escape' })
+      fireEvent.keyDown(input, { key: 'Escape' })
+
+      expect(onHostKeyDown).toHaveBeenCalledTimes(1)
+      expect(onHostKeyDown).toHaveBeenCalledWith('Escape')
+    })
+
+    it('reopens the suggestions when the user keeps typing', () => {
+      renderWithProviders(
+        <TagsInput value={[]} onChange={jest.fn()} suggestions={escapeSuggestions} />,
+      )
+
+      const input = screen.getByRole('textbox')
+      fireEvent.change(input, { target: { value: 'adm' } })
+      fireEvent.keyDown(input, { key: 'Escape' })
+      fireEvent.change(input, { target: { value: 'admi' } })
+
+      expect(screen.getByRole('button', { name: /admin@acme\.com/ })).toBeInTheDocument()
+    })
+
+    it('keeps an enclosing dialog open', () => {
+      const onOpenChange = jest.fn()
+
+      renderWithProviders(
+        <Dialog open onOpenChange={onOpenChange}>
+          <DialogContent>
+            <DialogTitle>Compose</DialogTitle>
+            <DialogDescription>Compose a message.</DialogDescription>
+            <TagsInput value={[]} onChange={jest.fn()} suggestions={escapeSuggestions} />
+          </DialogContent>
+        </Dialog>,
+      )
+
+      const input = screen.getByRole('textbox')
+      fireEvent.change(input, { target: { value: 'adm' } })
+      fireEvent.keyDown(input, { key: 'Escape' })
+
+      expect(screen.queryByRole('button', { name: /admin@acme\.com/ })).not.toBeInTheDocument()
+      expect(onOpenChange).not.toHaveBeenCalled()
+
+      fireEvent.keyDown(input, { key: 'Escape' })
+
+      expect(onOpenChange).toHaveBeenCalledWith(false)
+    })
+  })
 })

package/src/backend/messages/EmailThreadsPanel.tsx

@@ -27,6 +27,16 @@ export type EmailThreadMessage = {
   direction: EmailThreadDirection
   fromName: string | null
   fromEmail: string | null
+  /**
+   * True when the viewer wrote this message — the only thing that earns a "You"
+   * label. Outbound direction alone does NOT imply authorship: a shared
+   * conversation or team mailbox puts a colleague's sent mail in this list, and
+   * labelling that "You" attributes their email to the reader. Optional and
+   * fail-safe: omitted (or false) renders the sender identity instead.
+   */
+  authoredByViewer?: boolean
+  /** Display label of the sending colleague, when the viewer is not the author. */
+  authorName?: string | null
   to: string[]
   cc: string[]
   subject: string | null
@@ -259,6 +269,16 @@ function EmailMessageCard({
   const fromLabel = message.fromName
     ? `${message.fromName}${message.fromEmail ? ` <${message.fromEmail}>` : ''}`
     : message.fromEmail ?? t('ui.email.threads.unknownParticipant', 'Unknown sender')
+  // Outbound mail carries no `from` address, so a colleague's message falls back
+  // to their resolved name and then to a generic label — never to "You", which
+  // would credit the reader with an email they did not send.
+  const senderLabel = isOutbound
+    ? message.authoredByViewer
+      ? t('ui.email.threads.you', 'You')
+      : message.authorName?.trim() ||
+        message.fromEmail ||
+        t('ui.email.threads.teammate', 'A teammate')
+    : fromLabel
   return (
     <div
       className={`min-w-0 rounded-md border border-border p-3 ${isOutbound ? 'bg-accent' : 'bg-muted'}`}
@@ -272,7 +292,7 @@ function EmailMessageCard({
               <ArrowDownLeft className="h-3.5 w-3.5 shrink-0" />
             )}
             <span className="min-w-0 break-words font-medium text-foreground">
-              {isOutbound ? t('ui.email.threads.you', 'You') : fromLabel}
+              {senderLabel}
             </span>
           </div>
           {message.to.length > 0 ? (

package/src/backend/messages/MessageComposer.tsx

@@ -18,6 +18,7 @@ export type {
   MessageComposerRequiredActionConfig,
   MessageComposerRequiredActionOption,
   MessageComposerVariant,
+  MessageSenderOption,
   MessageTypeItem,
 } from './message-composer.types'
 

package/src/backend/messages/__tests__/EmailThreadsPanel.senderLabel.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { screen } from '@testing-library/react'
+import { renderWithProviders } from '@open-mercato/shared/lib/testing/renderWithProviders'
+import { EmailThreadsPanel, type EmailThread, type EmailThreadMessage } from '../EmailThreadsPanel'
+
+/**
+ * Who an email is credited to in the thread view.
+ *
+ * Before conversation/channel sharing, the panel labelled every OUTBOUND message
+ * "You", because the only person who could read their own sent mail was its
+ * author. Sharing is precisely the feature that breaks that premise: a teammate
+ * reads a colleague's sent mail, and "You" would then attribute that colleague's
+ * email to the reader. Direction is therefore no longer a proxy for authorship.
+ */
+
+function message(overrides: Partial<EmailThreadMessage> = {}): EmailThreadMessage {
+  return {
+    id: 'L1',
+    messageId: 'M1',
+    rfcMessageId: null,
+    references: [],
+    direction: 'outbound',
+    fromName: null,
+    fromEmail: null,
+    to: ['contact@example.com'],
+    cc: [],
+    subject: 'Quarterly review',
+    bodyText: 'Sending the numbers over.',
+    sentAt: '2026-05-20T11:00:00.000Z',
+    providerKey: 'gmail',
+    ...overrides,
+  }
+}
+
+function thread(messages: EmailThreadMessage[]): EmailThread {
+  return {
+    threadKey: 'T1',
+    subject: 'Quarterly review',
+    preview: 'Sending the numbers over.',
+    participants: ['contact@example.com'],
+    lastMessageAt: '2026-05-20T11:00:00.000Z',
+    messageCount: messages.length,
+    providerKey: 'gmail',
+    lastDirection: messages[messages.length - 1]?.direction ?? 'outbound',
+    messages,
+  }
+}
+
+function renderPanel(messages: EmailThreadMessage[]) {
+  return renderWithProviders(<EmailThreadsPanel threads={[thread(messages)]} />)
+}
+
+describe('EmailThreadsPanel sender label', () => {
+  it('labels the viewer\'s own outbound message "You"', () => {
+    renderPanel([message({ authoredByViewer: true })])
+    expect(screen.getByText('You')).toBeInTheDocument()
+  })
+
+  it('credits a colleague\'s shared outbound message to them, never to the reader', () => {
+    renderPanel([message({ authoredByViewer: false, authorName: 'Ada Owner' })])
+    expect(screen.getByText('Ada Owner')).toBeInTheDocument()
+    expect(screen.queryByText('You')).not.toBeInTheDocument()
+  })
+
+  it('falls back to the sending address when the colleague has no resolved name', () => {
+    renderPanel([message({ authoredByViewer: false, authorName: null, fromEmail: 'ada@org.com' })])
+    expect(screen.getByText('ada@org.com')).toBeInTheDocument()
+    expect(screen.queryByText('You')).not.toBeInTheDocument()
+  })
+
+  it('falls back to a generic label when neither name nor address is known', () => {
+    renderPanel([message({ authoredByViewer: false, authorName: null, fromEmail: null })])
+    expect(screen.getByText('A teammate')).toBeInTheDocument()
+    expect(screen.queryByText('You')).not.toBeInTheDocument()
+  })
+
+  it('does not claim authorship when the flag is absent (fail-safe for older payloads)', () => {
+    renderPanel([message({ fromEmail: 'ada@org.com' })])
+    expect(screen.queryByText('You')).not.toBeInTheDocument()
+    expect(screen.getByText('ada@org.com')).toBeInTheDocument()
+  })
+
+  it('names the external sender on inbound mail, ignoring the authorship flag', () => {
+    renderPanel([
+      message({
+        direction: 'inbound',
+        fromName: 'Casey Contact',
+        fromEmail: 'casey@example.com',
+        authoredByViewer: true,
+      }),
+    ])
+    expect(screen.getByText('Casey Contact <casey@example.com>')).toBeInTheDocument()
+    expect(screen.queryByText('You')).not.toBeInTheDocument()
+  })
+})

package/src/backend/messages/__tests__/MessageComposer.test.tsx

@@ -511,6 +511,50 @@ describe('MessageComposer draft flow', () => {
     expect(composeRequest).toBeUndefined()
   })
 
+  it('keeps the inline composer open when Escape closes a nested Select dropdown (#6447)', async () => {
+    const onCancel = jest.fn()
+    const pointerCaptureTarget = Element.prototype as Element & {
+      hasPointerCapture?: (pointerId: number) => boolean
+      releasePointerCapture?: (pointerId: number) => void
+      scrollIntoView?: () => void
+    }
+    pointerCaptureTarget.hasPointerCapture ??= () => false
+    pointerCaptureTarget.releasePointerCapture ??= () => undefined
+    pointerCaptureTarget.scrollIntoView ??= () => undefined
+
+    renderWithProviders(
+      <MessageComposer
+        inline
+        variant="compose"
+        onCancel={onCancel}
+        contextObject={{ entityModule: 'sales', entityType: 'order', entityId: 'order-1' }}
+        requiredActionConfig={{
+          mode: 'required',
+          options: [{ id: 'approve', label: 'Approve order' }],
+        }}
+      />,
+      { dict: {} },
+    )
+
+    const actionTypeTrigger = await screen.findByRole('combobox', { name: 'Action type' })
+    fireEvent.pointerDown(actionTypeTrigger, { button: 0, ctrlKey: false })
+    fireEvent.click(actionTypeTrigger)
+    const option = await screen.findByRole('option', { name: 'Approve order' })
+
+    fireEvent.keyDown(option, { key: 'Escape' })
+
+    await waitFor(() => {
+      expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+    })
+    expect(onCancel).not.toHaveBeenCalled()
+
+    fireEvent.keyDown(screen.getByPlaceholderText('Search recipients...'), { key: 'Escape' })
+
+    await waitFor(() => {
+      expect(onCancel).toHaveBeenCalledTimes(1)
+    })
+  })
+
   it('uses inline cancel action for embedded reply composer', async () => {
     const onCancel = jest.fn()
 

package/src/backend/messages/__tests__/useMessageCompose.test.tsx

@@ -58,3 +58,72 @@ describe('useMessageCompose recipient suggestions', () => {
     expect(requestedUrl.searchParams.get('scopeToActiveOrganization')).toBe('1')
   })
 })
+
+describe('useMessageCompose Escape handling', () => {
+  beforeEach(() => {
+    jest.resetAllMocks()
+    ;(apiCall as jest.Mock).mockResolvedValue({
+      ok: true,
+      status: 200,
+      result: { items: [] },
+      response: { status: 200 },
+    })
+  })
+
+  function buildEscapeEvent(options: { defaultPrevented?: boolean, targetInsideComposer?: boolean }) {
+    const composer = document.createElement('div')
+    const insideField = document.createElement('input')
+    composer.appendChild(insideField)
+    const portaledContent = document.createElement('div')
+    const preventDefault = jest.fn()
+    const event = {
+      key: 'Escape',
+      metaKey: false,
+      ctrlKey: false,
+      defaultPrevented: options.defaultPrevented ?? false,
+      currentTarget: composer,
+      target: options.targetInsideComposer === false ? portaledContent : insideField,
+      preventDefault,
+    } as unknown as React.KeyboardEvent<HTMLDivElement>
+    return { event, preventDefault }
+  }
+
+  function renderInlineCompose(onCancel: jest.Mock) {
+    return renderHook(() => useMessageCompose({ variant: 'compose', inline: true, onCancel }), {
+      wrapper: createWrapper(),
+    })
+  }
+
+  it('cancels on a plain Escape from inside the composer', () => {
+    const onCancel = jest.fn()
+    const { result } = renderInlineCompose(onCancel)
+    const { event, preventDefault } = buildEscapeEvent({})
+
+    result.current.handleKeyDown(event)
+
+    expect(preventDefault).toHaveBeenCalledTimes(1)
+    expect(onCancel).toHaveBeenCalledTimes(1)
+  })
+
+  it('ignores an Escape a nested layer already handled', () => {
+    const onCancel = jest.fn()
+    const { result } = renderInlineCompose(onCancel)
+    const { event, preventDefault } = buildEscapeEvent({ defaultPrevented: true })
+
+    result.current.handleKeyDown(event)
+
+    expect(preventDefault).not.toHaveBeenCalled()
+    expect(onCancel).not.toHaveBeenCalled()
+  })
+
+  it('ignores an Escape bubbling from portaled content outside the composer', () => {
+    const onCancel = jest.fn()
+    const { result } = renderInlineCompose(onCancel)
+    const { event, preventDefault } = buildEscapeEvent({ targetInsideComposer: false })
+
+    result.current.handleKeyDown(event)
+
+    expect(preventDefault).not.toHaveBeenCalled()
+    expect(onCancel).not.toHaveBeenCalled()
+  })
+})

package/src/backend/messages/__tests__/useMessageComposeSender.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import * as React from 'react'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { I18nProvider } from '@open-mercato/shared/lib/i18n/context'
+import { useMessageCompose } from '../useMessageCompose'
+import { apiCall, withScopedApiRequestHeaders } from '../../utils/apiCall'
+import type { MessageSenderOption } from '../message-composer.types'
+
+jest.mock('../../utils/apiCall', () => ({
+  apiCall: jest.fn(),
+  withScopedApiRequestHeaders: jest.fn((_headers: unknown, run: () => unknown) => run()),
+}))
+
+jest.mock('../../FlashMessages', () => ({
+  flash: jest.fn(),
+}))
+
+const senderOptions: MessageSenderOption[] = [
+  { id: 'mailbox-primary', label: 'Primary inbox', description: 'me@example.com', isDefault: true },
+  { id: 'mailbox-other', label: 'Other inbox', description: 'other@example.com' },
+]
+
+function createWrapper() {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        {/* @ts-expect-error shared provider accepts a loose dict shape */}
+        <I18nProvider locale="en" dict={{}}>
+          {children}
+        </I18nProvider>
+      </QueryClientProvider>
+    )
+  }
+}
+
+function mockApiCall(overrides: (url: string) => unknown = () => null) {
+  ;(withScopedApiRequestHeaders as jest.Mock).mockImplementation(
+    (_headers: unknown, run: () => unknown) => run(),
+  )
+  ;(apiCall as jest.Mock).mockImplementation(async (url: string) => {
+    const override = overrides(url)
+    if (override) return override
+    if (url.startsWith('/api/messages/types')) {
+      return {
+        ok: true,
+        status: 200,
+        result: { items: [{ type: 'default', module: 'messages', labelKey: 'default', icon: 'mail', allowReply: true, allowForward: true, isCreateableByUser: true }] },
+      }
+    }
+    return { ok: true, status: 200, result: { items: [] } }
+  })
+}
+
+function findComposeCall(): [string, { method?: string; body?: string }] | undefined {
+  return (apiCall as jest.Mock).mock.calls.find(
+    ([url, init]) => url === '/api/messages' && init?.method === 'POST',
+  ) as [string, { method?: string; body?: string }] | undefined
+}
+
+/**
+ * A successful send parks `handleSubmit` on a promise the composer only resolves
+ * when it next closes, so the call is awaited through the request it made rather
+ * than through its return value.
+ */
+async function submitAndReadPayload(
+  submit: () => Promise<boolean>,
+): Promise<Record<string, unknown>> {
+  await act(async () => {
+    void submit()
+  })
+  await waitFor(() => expect(findComposeCall()).toBeDefined())
+  return JSON.parse(findComposeCall()![1].body as string) as Record<string, unknown>
+}
+
+async function fillExternalCompose(result: { current: ReturnType<typeof useMessageCompose> }) {
+  await waitFor(() => expect(result.current.createableMessageTypes.length).toBeGreaterThan(0))
+  act(() => {
+    result.current.setVisibility('public')
+    result.current.setExternalEmail('client@example.com')
+    result.current.setSubject('Quote')
+    result.current.setBody('Here it is')
+  })
+}
+
+describe('useMessageCompose sender selection', () => {
+  beforeEach(() => {
+    jest.resetAllMocks()
+    mockApiCall()
+  })
+
+  it('offers no senders until the compose addresses an external recipient', async () => {
+    const { result } = renderHook(
+      () => useMessageCompose({ variant: 'compose', inline: true, senderOptions }),
+      { wrapper: createWrapper() },
+    )
+
+    expect(result.current.senderOptions).toEqual([])
+
+    act(() => {
+      result.current.setVisibility('public')
+    })
+
+    expect(result.current.senderOptions).toEqual(senderOptions)
+  })
+
+  it('defaults to the platform sender and posts the unchanged payload', async () => {
+    const { result } = renderHook(
+      () => useMessageCompose({ variant: 'compose', inline: true, senderOptions }),
+      { wrapper: createWrapper() },
+    )
+
+    await fillExternalCompose(result)
+    expect(result.current.senderChannelId).toBe('')
+
+    const payload = await submitAndReadPayload(() => result.current.handleSubmit())
+
+    expect(payload).not.toHaveProperty('senderChannelId')
+  })
+
+  it('posts the chosen mailbox on the send', async () => {
+    const { result } = renderHook(
+      () => useMessageCompose({ variant: 'compose', inline: true, senderOptions }),
+      { wrapper: createWrapper() },
+    )
+
+    await fillExternalCompose(result)
+    act(() => {
+      result.current.setSenderChannelId('mailbox-other')
+    })
+
+    const payload = await submitAndReadPayload(() => result.current.handleSubmit())
+
+    expect(payload.senderChannelId).toBe('mailbox-other')
+  })
+
+  it('drops a mailbox that is no longer offered', async () => {
+    const { result } = renderHook(
+      () => useMessageCompose({ variant: 'compose', inline: true, senderOptions }),
+      { wrapper: createWrapper() },
+    )
+
+    await fillExternalCompose(result)
+    act(() => {
+      result.current.setSenderChannelId('mailbox-other')
+      result.current.setVisibility('internal')
+    })
+
+    expect(result.current.senderChannelId).toBe('')
+  })
+
+  it('never routes a saved draft through a mailbox', async () => {
+    const { result } = renderHook(
+      () => useMessageCompose({ variant: 'compose', inline: true, senderOptions }),
+      { wrapper: createWrapper() },
+    )
+
+    await fillExternalCompose(result)
+    act(() => {
+      result.current.setSenderChannelId('mailbox-other')
+    })
+
+    const payload = await submitAndReadPayload(() =>
+      result.current.handleSubmit({ saveAsDraft: true }),
+    )
+
+    expect(payload).not.toHaveProperty('senderChannelId')
+  })
+
+  it('surfaces a send-as-user 422 as a field error on the sender control', async () => {
+    mockApiCall((url) =>
+      url === '/api/messages'
+        ? {
+            ok: false,
+            status: 422,
+            result: {
+              error: 'This channel needs reconnection before it can send messages.',
+              fieldErrors: {
+                senderChannelId: 'This channel needs reconnection before it can send messages.',
+              },
+            },
+          }
+        : null,
+    )
+
+    const { result } = renderHook(
+      () => useMessageCompose({ variant: 'compose', inline: true, senderOptions }),
+      { wrapper: createWrapper() },
+    )
+
+    await fillExternalCompose(result)
+    act(() => {
+      result.current.setSenderChannelId('mailbox-other')
+    })
+
+    await act(async () => {
+      await result.current.handleSubmit()
+    })
+
+    expect(result.current.submitFieldErrors).toEqual({
+      senderChannelId: 'This channel needs reconnection before it can send messages.',
+    })
+  })
+})

package/src/backend/messages/index.ts

@@ -3,6 +3,7 @@ export type {
   MessageComposerContextObject,
   MessageComposerProps,
   MessageComposerVariant,
+  MessageSenderOption,
   MessageTypeItem,
 } from './MessageComposer'
 

package/src/backend/messages/message-compose-form-groups.tsx

@@ -184,6 +184,45 @@ function MarkdownBodySection({
   )
 }
 
+const PLATFORM_SENDER_VALUE = '__platform__'
+
+function SenderSelector({ compose }: ComposeProps) {
+  if (compose.senderOptions.length === 0) return null
+
+  const fieldError = compose.submitFieldErrors?.senderChannelId ?? null
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="messages-compose-sender">{compose.t('messages.sendFrom', 'Send from')}</Label>
+      <Select
+        value={compose.senderChannelId || PLATFORM_SENDER_VALUE}
+        onValueChange={(value) => compose.setSenderChannelId(value === PLATFORM_SENDER_VALUE ? '' : value)}
+      >
+        <SelectTrigger id="messages-compose-sender" aria-invalid={fieldError ? true : undefined}>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={PLATFORM_SENDER_VALUE}>
+            {compose.t('messages.sendFromPlatform', 'Platform sender (default)')}
+          </SelectItem>
+          {compose.senderOptions.map((option) => (
+            <SelectItem key={option.id} value={option.id}>
+              {option.description ? `${option.label} (${option.description})` : option.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      {fieldError ? (
+        <p className="text-sm text-destructive" role="alert">{fieldError}</p>
+      ) : (
+        <p className="text-xs text-muted-foreground">
+          {compose.t('messages.sendFromHint', 'Replies to a message sent from your own mailbox come back into this thread.')}
+        </p>
+      )}
+    </div>
+  )
+}
+
 function ComposeModeFields({ compose }: ComposeProps) {
   return (
     <>
@@ -213,6 +252,8 @@ function ComposeModeFields({ compose }: ComposeProps) {
           </div>
         </div>
 
+        <SenderSelector compose={compose} />
+
         <ContextActionsSection compose={compose} />
       </div>
 

package/src/backend/messages/message-composer.types.ts

@@ -26,6 +26,26 @@ export type AttachmentListResponse = {
 
 export type MessageComposerVariant = 'compose' | 'reply' | 'forward'
 
+/**
+ * One entry of the composer's "Send from" list, in provider-agnostic terms.
+ *
+ * The composer never learns what backs an option — the host module supplies the
+ * list and the API route decides how a selected id is routed. An empty list
+ * hides the control entirely, which is what a host without any configured
+ * sender renders.
+ */
+export type MessageSenderOption = {
+  id: string
+  label: string
+  description?: string | null
+  /**
+   * The option to reach for first when the user opts out of the platform
+   * sender. It orders the list; it does not preselect, because the platform
+   * sender stays the default.
+   */
+  isDefault?: boolean
+}
+
 export type MessageComposerContextObject = {
   entityModule: string
   entityType: string
@@ -60,6 +80,12 @@ export type MessageComposerProps = {
   contextObject?: MessageComposerContextObject | null
   requiredActionConfig?: MessageComposerRequiredActionConfig | null
   contextPreview?: React.ReactNode
+  /**
+   * Alternative senders offered next to the default platform sender. Rendered
+   * only in the compose variant addressing an external recipient, and only when
+   * non-empty.
+   */
+  senderOptions?: MessageSenderOption[]
   /**
    * Expected `updated_at` of the existing draft being edited. When present, the
    * composer attaches the OSS optimistic-lock header to the draft save/send