@linktr.ee/messaging-react 4.2.0-rc-1787083791 → 4.2.0-rc-1787181113

package/src/components/MessageAttachment/MessageAttachment.test.tsx

@@ -1,9 +1,4 @@
 import React from 'react'
-import {
-  ChatProvider,
-  WithAudioPlayback,
-  type ChatContextValue,
-} from 'stream-chat-react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { renderWithProviders, screen, fireEvent } from '../../test/utils'
@@ -12,21 +7,6 @@ import { triggerDownload } from './_shared/triggerDownload'
 
 import MessageAttachment, { bubbleGroupPositionFromStream } from '.'
 
-// `MessageAttachment.Audio`'s playback comes from `stream-chat-react`'s
-// pooled `AudioPlayer`, which `<Channel>` mounts in production. Mounting
-// the pool directly is the same contract without needing a channel that
-// can `watch()`. The player reads only `client` off the chat context —
-// optional-chained, for error notifications — so a stub is enough; its
-// presence is what stops `useChatContext` warning.
-const AUDIO_CHAT_CONTEXT = {} as ChatContextValue
-
-const renderAudio = (ui: React.ReactElement) =>
-  renderWithProviders(
-    <ChatProvider value={AUDIO_CHAT_CONTEXT}>
-      <WithAudioPlayback>{ui}</WithAudioPlayback>
-    </ChatProvider>
-  )
-
 vi.mock('./_shared/triggerDownload', () => ({
   triggerDownload: vi.fn(() => Promise.resolve()),
 }))
@@ -736,186 +716,50 @@ describe('MessageAttachment.File', () => {
 })
 
 describe('MessageAttachment.Audio', () => {
-  // 12 samples so the resample path is exercised on the way to the
-  // design's 35 bars.
-  const WAVEFORM = [
-    0.1, 0.8, 0.65, 0.2, 0.3, 0.45, 0.5, 0.7, 1, 0.85, 0.4, 0.15,
-  ]
-
-  it('renders the waveform card: bars, play toggle, duration and seek', () => {
-    renderAudio(
+  it('renders the native audio player only (no title, no extra download)', () => {
+    renderWithProviders(
       <MessageAttachment.Audio.Sent
         src="https://cdn.example.com/song.mp3"
         mimeType="audio/mpeg"
         filename="song.mp3"
-        durationSeconds={12}
-        waveformData={WAVEFORM}
       />
     )
-
     const bubble = screen.getByTestId('audio-attachment')
-    expect(bubble.querySelectorAll('[data-testid="amplitude-bar"]')).toHaveLength(
-      35
-    )
-    // The native player is gone — playback is our own control set now.
-    expect(bubble.querySelector('audio')).toBeNull()
-    expect(
-      screen.getByRole('button', { name: 'Play audio — song.mp3' })
-    ).toBeInTheDocument()
-    expect(screen.getByText('00:12')).toBeInTheDocument()
-
-    const seek = screen.getByRole('slider', { name: 'Seek audio — song.mp3' })
-    expect(seek).toHaveAttribute('aria-valuetext', '00:00 of 00:12')
-    expect(seek).toHaveValue('0')
-
-    // The bars duplicate what the slider already announces, so they
-    // must stay out of the accessibility tree — otherwise they read as
-    // 35 unnamed nodes and (in Stream's own version of this widget) as
-    // an unnamed `progressbar`.
-    const track = bubble.querySelector('.mes-audio-wave__track')
-    expect(track).toHaveAttribute('aria-hidden', 'true')
-  })
-
-  it('renders the full bar count as a flat placeholder when no waveform exists', () => {
-    // The total fallback: a decode failure, an unsupported codec, a
-    // re-staged zero-byte placeholder, or anything sent before
-    // `waveform_data` was persisted. Passing `[]` straight through
-    // would render no bars at all, so the card must supply its own
-    // all-zero row — the card's silhouette has to be unchanged.
-    renderAudio(
-      <MessageAttachment.Audio.Received src="https://cdn.example.com/legacy.mp3" />
-    )
-
-    const bars = screen.getAllByTestId('amplitude-bar')
-    expect(bars).toHaveLength(35)
-    bars.forEach((bar) => {
-      expect(bar).not.toHaveClass('mes-audio-wave__bar--played')
-    })
+    expect(bubble.querySelector('audio')).not.toBeNull()
+    // No filename title — the native `<audio>` element doesn't expose
+    // a title slot, so we render just the player.
+    expect(screen.queryByText('song.mp3')).toBeNull()
+    // Native player handles its own download in the kebab menu, so
+    // no extra Download button should be rendered.
+    expect(screen.queryByRole('button', { name: /download/i })).toBeNull()
   })
 
-  it.each([3, 12, 35, 200])(
-    'resamples a %i-sample waveform to the rendered bar count',
-    (sampleCount) => {
-      const data = Array.from({ length: sampleCount }, (_, i) =>
-        Math.abs(Math.sin(i))
-      )
-      renderAudio(
-        <MessageAttachment.Audio.Sent
-          src="https://cdn.example.com/song.mp3"
-          waveformData={data}
-        />
-      )
-      expect(screen.getAllByTestId('amplitude-bar')).toHaveLength(35)
-    }
-  )
-
-  it('shows an unknown duration without collapsing the slot', () => {
-    renderAudio(
-      <MessageAttachment.Audio.Sent src="https://cdn.example.com/legacy.mp3" />
-    )
-
-    expect(screen.getByText('--:--')).toBeInTheDocument()
-    expect(screen.getByRole('slider', { name: 'Seek audio' })).toHaveAttribute(
-      'aria-valuetext',
-      '00:00 of --:--'
-    )
-  })
-
-  it('removes the draft from the composer trailing action', () => {
-    // There is no product-owned overflow menu on audio attachments in
-    // production, so the design's trailing control carries forward the
-    // one action each surface already had: Remove in the composer…
+  it('shows an inline dismiss button next to the player on Composer state', () => {
     const onDismiss = vi.fn()
-    renderAudio(
+    renderWithProviders(
       <MessageAttachment.Audio.Composer
         src="https://cdn.example.com/song.mp3"
-        filename="song.mp3"
         onDismiss={onDismiss}
       />
     )
-
-    expect(
-      screen.queryByRole('button', { name: /download/i })
-    ).not.toBeInTheDocument()
-    fireEvent.click(screen.getByRole('button', { name: 'Remove attachment' }))
+    const dismiss = screen.getByLabelText('Dismiss attachment')
+    expect(dismiss).toBeInTheDocument()
+    fireEvent.click(dismiss)
     expect(onDismiss).toHaveBeenCalledTimes(1)
   })
 
-  it('downloads from the sent trailing action', () => {
-    // …and Download once sent, preserving the capability the native
-    // `<audio controls>` kebab used to provide.
-    renderAudio(
-      <MessageAttachment.Audio.Sent
-        src="https://cdn.example.com/song.mp3"
-        filename="song.mp3"
-      />
-    )
-
-    fireEvent.click(
-      screen.getByRole('button', { name: 'Download audio — song.mp3' })
-    )
-    expect(mockTriggerDownload).toHaveBeenCalledWith(
-      'https://cdn.example.com/song.mp3',
-      'song.mp3'
-    )
-  })
-
-  it('renders one waveform row per item for stacked audio', () => {
-    renderAudio(
+  it('renders one native player per item for stacked audio', () => {
+    renderWithProviders(
       <MessageAttachment.Audio.Sent
         items={[
-          { src: 'https://cdn.example.com/a.mp3', durationSeconds: 12 },
-          { src: 'https://cdn.example.com/b.mp3', durationSeconds: 30 },
-          { src: 'https://cdn.example.com/c.mp3', durationSeconds: 65 },
+          { src: 'https://cdn.example.com/a.mp3', mimeType: 'audio/mpeg' },
+          { src: 'https://cdn.example.com/b.mp3', mimeType: 'audio/mpeg' },
+          { src: 'https://cdn.example.com/c.mp3', mimeType: 'audio/mpeg' },
         ]}
       />
     )
-
     const bubble = screen.getByTestId('audio-attachment')
-    expect(
-      bubble.querySelectorAll('[data-testid="audio-attachment-row"]')
-    ).toHaveLength(3)
-    expect(screen.getByText('01:05')).toBeInTheDocument()
-  })
-
-  it('disables playback for a MIME type the browser cannot play, but keeps the download', () => {
-    // `canPlayType` gates playback, and clicking play on an unplayable
-    // track is a no-op inside the player anyway — so the control says
-    // so. The file must still be retrievable.
-    renderAudio(
-      <MessageAttachment.Audio.Received
-        src="https://cdn.example.com/master.flac"
-        mimeType="audio/flac"
-        filename="master.flac"
-      />
-    )
-
-    expect(
-      screen.getByRole('button', { name: /^Play audio/ })
-    ).toBeDisabled()
-    expect(screen.getByRole('slider', { name: /^Seek audio/ })).toBeDisabled()
-    expect(
-      screen.getByRole('button', { name: /^Download audio/ })
-    ).toBeEnabled()
-  })
-
-  it('still renders the card without the audio-playback provider', () => {
-    // The pooled player lives on `<Channel>`. Outside one the card must
-    // degrade to an inert card rather than rendering nothing — a blank
-    // bubble is undiagnosable, and it would silently break every
-    // consumer that mounts an attachment outside a channel.
-    renderWithProviders(
-      <MessageAttachment.Audio.Sent
-        src="https://cdn.example.com/song.mp3"
-        durationSeconds={12}
-        waveformData={WAVEFORM}
-      />
-    )
-
-    expect(screen.getByTestId('audio-attachment')).toBeInTheDocument()
-    expect(screen.getAllByTestId('amplitude-bar')).toHaveLength(35)
-    expect(screen.getByText('00:12')).toBeInTheDocument()
-    expect(screen.getByRole('button', { name: /^Play audio/ })).toBeDisabled()
+    expect(bubble.querySelectorAll('audio')).toHaveLength(3)
   })
 })
 
@@ -1107,6 +951,60 @@ describe('MessageAttachment lazy-loading defaults', () => {
       expect(video?.getAttribute('preload')).toBe('metadata')
     })
   })
+
+  describe('Audio', () => {
+    it('defaults a single-track bubble to preload="metadata"', () => {
+      renderWithProviders(
+        <MessageAttachment.Audio.Received
+          src="https://cdn.example.com/song.mp3"
+          mimeType="audio/mpeg"
+        />
+      )
+      const audio = screen
+        .getByTestId('audio-attachment')
+        .querySelector('audio')
+      expect(audio?.getAttribute('preload')).toBe('metadata')
+    })
+
+    it('defaults a stacked (3-track) bubble to preload="none" on every player', () => {
+      renderWithProviders(
+        <MessageAttachment.Audio.Sent
+          items={[
+            { src: 'https://cdn.example.com/a.mp3', mimeType: 'audio/mpeg' },
+            { src: 'https://cdn.example.com/b.mp3', mimeType: 'audio/mpeg' },
+            { src: 'https://cdn.example.com/c.mp3', mimeType: 'audio/mpeg' },
+          ]}
+        />
+      )
+      const audios = Array.from(
+        screen.getByTestId('audio-attachment').querySelectorAll('audio')
+      )
+      expect(audios).toHaveLength(3)
+      audios.forEach((audio) => {
+        expect(audio.getAttribute('preload')).toBe('none')
+      })
+    })
+
+    it('honors a per-track AudioItem.preload override', () => {
+      renderWithProviders(
+        <MessageAttachment.Audio.Sent
+          items={[
+            { src: 'https://cdn.example.com/a.mp3', mimeType: 'audio/mpeg' },
+            {
+              src: 'https://cdn.example.com/b.mp3',
+              mimeType: 'audio/mpeg',
+              preload: 'metadata',
+            },
+          ]}
+        />
+      )
+      const audios = Array.from(
+        screen.getByTestId('audio-attachment').querySelectorAll('audio')
+      )
+      expect(audios[0]?.getAttribute('preload')).toBe('none')
+      expect(audios[1]?.getAttribute('preload')).toBe('metadata')
+    })
+  })
 })
 
 describe('bubbleGroupPositionFromStream', () => {

package/src/components/MessageAttachment/index.tsx

@@ -56,7 +56,7 @@ import VideoAttachment, {
  *   - Pdf / Audio / File render their compact rows / players in a
  *     vertical stack with an 8px gap between rows. Each row keeps
  *     its own activation target — Pdf opens the carousel-aware
- *     `PdfViewer` at that index, Audio gets its own waveform player,
+ *     `PdfViewer` at that index, Audio gets its own native player,
  *     and File downloads the asset for that row.
  *
  * The Composer surface accepts only a single attachment at a time,
@@ -74,29 +74,12 @@ import VideoAttachment, {
  * download button to the chrome; the Video viewer relies on the
  * native `<video controls>` download menu, and the Pdf viewer
  * inherits the browser's built-in PDF download. Sibling-row Download
- * buttons on Pdf / File and the Audio card's trailing action expose
+ * buttons on Pdf / File and the native `<audio>` controls expose
  * downloads outside the viewer too. The lightbox chrome is styled
  * with plain CSS (`.mes-media-viewer*`) so the package's shipped
  * stylesheet is enough to render the viewer correctly without a
  * Tailwind dependency in the consumer.
  *
- * # Audio requires a `<Channel>` ancestor
- *
- * `MessageAttachment.Audio.*` renders the waveform player card —
- * a 32px play toggle, a 35-bar waveform with a progress fill and a
- * native seek control, the duration, and a 32px trailing action
- * (Remove in the composer, Download once sent). Playback is
- * `stream-chat-react`'s pooled `AudioPlayer`, which is what supplies
- * single-player-at-a-time across a thread, pause-on-navigation and
- * saved-position restore across virtualized remounts.
- *
- * That pool is provided by `<Channel>`. Rendered outside one the card
- * still draws in full, but its play and seek controls are disabled —
- * so a story or a new consumer surface must mount `<Channel>` (or
- * `stream-chat-react`'s `WithAudioPlayback`) for the card to be
- * playable. The waveform bars themselves are styled with plain CSS
- * (`.mes-audio-wave*`), so the shipped stylesheet is enough.
- *
  * # Lazy-loading defaults
  *
  * Media attachments bake in network-friendly defaults for long chat
@@ -117,12 +100,13 @@ import VideoAttachment, {
  *     `VideoItem.preload` per item). Once the viewer is open the
  *     active item bumps to `preload="metadata"` so duration / the
  *     first frame appear immediately.
- *   - **Audio** — no audio bytes are fetched until the user presses
- *     play: the pooled `AudioPlayer` acquires the shared `<audio>`
- *     element lazily. A card whose `durationSeconds` is unknown makes
- *     one `preload="metadata"` header request to fill the duration
- *     slot; supplying `durationSeconds` (which `StreamAttachmentMessage`
- *     maps from the attachment's persisted `duration`) avoids even that.
+ *   - **Audio** — a single audio bubble defaults to
+ *     `preload="metadata"` so the native player surfaces duration
+ *     immediately. A stacked audio bubble (`items.length > 1`)
+ *     defaults to `preload="none"` for every player so a thread of
+ *     voice memos doesn't fan out N parallel metadata requests on
+ *     first paint. Override via the attachment's `preload` prop
+ *     (or `AudioItem.preload` per track).
  *   - **Pdf** / **File** — no inline media element to throttle; the
  *     bubble renders compact rows that download / open lazily on
  *     activation. No `loading` / `preload` props on these surfaces.

package/src/components/MessageAttachment/types.ts

@@ -119,31 +119,21 @@ export interface PdfItem {
 /** A single audio file inside an Audio attachment (single or stacked). */
 export interface AudioItem {
   src: string
-  /** MIME type hint — gates playability via the player's `canPlayType` probe. */
+  /** MIME type hint — typed onto the inline `<source>` element. */
   mimeType?: string
   /**
-   * Filename — the download default name for the card's trailing
-   * action, and part of the card's accessible name.
+   * Filename — used as the download default name (consumed by the
+   * native player's kebab menu).
    */
   filename?: string
   /**
-   * Track length in seconds. Rendered as `MM:SS` before playback
-   * starts, so the duration is correct on first paint with no network
-   * request. Sourced from the Stream attachment's `duration` field,
-   * which the composer writes at send time. When omitted the card
-   * shows `--:--` until a one-shot `loadedmetadata` probe resolves.
+   * Per-track override for the `<audio preload>` hint. Defaults to
+   * the parent attachment's `preload` value, which itself defaults
+   * to `'metadata'` for a single audio (so the native player can
+   * surface duration immediately) and `'none'` for a stacked thread
+   * (so a fan-out of metadata requests doesn't happen on first paint).
    */
-  durationSeconds?: number
-  /**
-   * Waveform amplitudes, each `0..1`, in track order. Resampled to the
-   * rendered bar count, so any length is accepted. Sourced from the
-   * Stream attachment's `waveform_data`, which the composer computes
-   * from the local file and writes at send time.
-   *
-   * When omitted, the card renders a flat placeholder row: every bar at
-   * the minimum height, with the progress fill still tracking playback.
-   */
-  waveformData?: number[]
+  preload?: MediaPreloadMode
 }
 
 /** A single generic file inside a File attachment (single or stacked). */

package/src/components/MessagingShell/MessagingShell.test.tsx

@@ -125,6 +125,26 @@ describe('MessagingShell', () => {
     })
   })
 
+  it('forwards attachmentPreviewList to the selected channel view', async () => {
+    queryChannelsMock.mockResolvedValue([makeChannel('existing-1')])
+    const AttachmentPreviewList = () => <div>staged attachment</div>
+
+    renderWithProviders(
+      <MessagingShell
+        initialParticipantFilter="other-1"
+        attachmentPreviewList={AttachmentPreviewList}
+      />
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('channel-view')).toBeInTheDocument()
+    })
+
+    expect(capturedChannelViewProps.attachmentPreviewList).toBe(
+      AttachmentPreviewList
+    )
+  })
+
   it('calls onExitConversation and renders "Conversation ended" when the user leaves the conversation', async () => {
     queryChannelsMock.mockResolvedValue([makeChannel('existing-1')])
     const onExit = vi.fn()

package/src/components/MessagingShell/index.tsx

@@ -43,6 +43,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
   onMessageLinkClick,
   showChannelInfo,
   composerInput,
+  attachmentPreviewList,
 }) => {
   const {
     client,
@@ -269,6 +270,7 @@ export const MessagingShell: React.FC<MessagingShellProps> = ({
           onMessageLinkClick={onMessageLinkClick}
           showChannelInfo={showChannelInfo}
           composerInput={composerInput}
+          attachmentPreviewList={attachmentPreviewList}
         />
       </div>
     </div>

package/src/index.ts

@@ -7,6 +7,7 @@ export { ChannelList } from './components/ChannelList'
 export { ChannelView } from './components/ChannelView'
 export { default as ActionButton } from './components/ActionButton'
 export { default as LockedAttachment } from './components/CustomMessage/LockedAttachment'
+export { TipMessage, isTipMessage } from './components/CustomMessage/TipMessage'
 export { default as LinkAttachment } from './components/LinkAttachment'
 export { default as RichCard } from './components/RichCard'
 export { default as MessageAttachment } from './components/MessageAttachment'
@@ -28,11 +29,13 @@ export type {
 
 // Providers
 export { MessagingProvider } from './providers/MessagingProvider'
+export { MessagingLoggerProvider } from './logging'
 export { CustomMessageProvider } from './components/CustomMessage/context'
 
 // Hooks
 export { useComposerLocked } from './components/CustomMessageInput'
 export { useMessaging } from './hooks/useMessaging'
+export { useMessagingLogger } from './logging'
 export { useCustomMessage } from './components/CustomMessage/context'
 
 // Utils
@@ -135,3 +138,4 @@ export type { CustomMessageRegistry } from './components/CustomMessage/context'
 export type { AttachmentSourceType } from './components/AttachmentCard/utils/mimeType'
 export type { Faq, FaqListProps } from './components/FaqList'
 export type { FaqListItemProps } from './components/FaqList/FaqListItem'
+export type { Logger } from '@linktr.ee/messaging-core'

package/src/logging/index.test.tsx

@@ -0,0 +1,136 @@
+import type { Logger } from '@linktr.ee/messaging-core'
+import { render } from '@testing-library/react'
+import React from 'react'
+import { describe, it, expect, vi, afterEach } from 'vitest'
+
+import {
+  MessagingLoggerProvider,
+  consoleLogger,
+  resolveLogger,
+  useMessagingLogger,
+} from './index'
+
+const ERROR_MESSAGE = '[MessagingShell] Failed to load channels:'
+
+/** Logs one error through the seam the way a call site would. */
+const ErrorEmitter: React.FC<{ error: Error }> = ({ error }) => {
+  const logger = useMessagingLogger()
+  logger.error(ERROR_MESSAGE, error)
+  return null
+}
+
+/** Emits one line at every level so partial-sink fallback is observable. */
+const AllLevelsEmitter: React.FC = () => {
+  const logger = useMessagingLogger()
+  logger.debug('debug line', 1)
+  logger.info('info line', 2)
+  logger.warn('warn line', 3)
+  logger.error('error line', 4)
+  return null
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('logger seam', () => {
+  it('routes error to an injected sink with the exact message and raw error object', () => {
+    const error = new Error('boom')
+    const sink = { error: vi.fn() }
+
+    render(
+      <MessagingLoggerProvider logger={sink}>
+        <ErrorEmitter error={error} />
+      </MessagingLoggerProvider>
+    )
+
+    expect(sink.error).toHaveBeenCalledTimes(1)
+    expect(sink.error).toHaveBeenCalledWith(ERROR_MESSAGE, error)
+    // The raw Error instance, not a serialized copy.
+    expect(sink.error.mock.calls[0][1]).toBe(error)
+  })
+
+  it('passes identical arguments to console.error when no sink is injected', () => {
+    const error = new Error('boom')
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const sink = { error: vi.fn() }
+
+    render(
+      <MessagingLoggerProvider logger={sink}>
+        <ErrorEmitter error={error} />
+      </MessagingLoggerProvider>
+    )
+    const injectedArgs = sink.error.mock.calls[0]
+
+    // No provider at all, and a provider with no logger prop: both must produce
+    // byte-identical console output to what the injected sink received.
+    render(<ErrorEmitter error={error} />)
+    render(
+      <MessagingLoggerProvider>
+        <ErrorEmitter error={error} />
+      </MessagingLoggerProvider>
+    )
+
+    expect(consoleError).toHaveBeenCalledTimes(2)
+    expect(consoleError.mock.calls[0]).toEqual(injectedArgs)
+    expect(consoleError.mock.calls[1]).toEqual(injectedArgs)
+    expect(consoleError.mock.calls[0][1]).toBe(error)
+  })
+
+  it('falls back to console for the levels a partial sink omits', () => {
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const sink: Logger = { warn: vi.fn(), error: vi.fn() }
+
+    render(
+      <MessagingLoggerProvider logger={sink}>
+        <AllLevelsEmitter />
+      </MessagingLoggerProvider>
+    )
+
+    expect(sink.warn).toHaveBeenCalledWith('warn line', 3)
+    expect(sink.error).toHaveBeenCalledWith('error line', 4)
+    expect(consoleWarn).not.toHaveBeenCalled()
+    expect(consoleError).not.toHaveBeenCalled()
+    // debug and info are unset on the sink, so both land on console.log.
+    expect(consoleLog.mock.calls).toEqual([
+      ['debug line', 1],
+      ['info line', 2],
+    ])
+  })
+
+  it('defaults every level to console when the hook is used with no provider', () => {
+    const consoleLog = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    render(<AllLevelsEmitter />)
+
+    expect(consoleLog.mock.calls).toEqual([
+      ['debug line', 1],
+      ['info line', 2],
+    ])
+    expect(consoleWarn).toHaveBeenCalledWith('warn line', 3)
+    expect(consoleError).toHaveBeenCalledWith('error line', 4)
+  })
+
+  it('resolveLogger keeps provided levels and fills the rest from console', () => {
+    const warn = vi.fn()
+    const resolved = resolveLogger({ warn })
+
+    expect(resolved.warn).toBe(warn)
+    expect(resolved.debug).toBe(consoleLogger.debug)
+    expect(resolved.info).toBe(consoleLogger.info)
+    expect(resolved.error).toBe(consoleLogger.error)
+    expect(resolveLogger()).toEqual(consoleLogger)
+  })
+
+  it('consoleLogger dispatches through console at call time, not bind time', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    consoleLogger.error('late spy', 'arg')
+
+    expect(consoleError).toHaveBeenCalledWith('late spy', 'arg')
+  })
+})

package/src/logging/index.tsx

@@ -0,0 +1,48 @@
+import type { Logger } from '@linktr.ee/messaging-core'
+import React, { createContext, useContext, useMemo } from 'react'
+
+/**
+ * Default sink: the console calls the package makes today. Wrappers, not
+ * `console.error.bind(console)`, so a later-installed spy is still observed.
+ */
+export const consoleLogger: Required<Logger> = {
+  debug: (message, ...args) => console.log(message, ...args),
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args),
+}
+
+/**
+ * Merge a partial sink over the console defaults, so a consumer can route only
+ * the levels it cares about (e.g. `error`) and leave the rest on console.
+ */
+export const resolveLogger = (logger?: Logger): Required<Logger> => ({
+  debug: logger?.debug ?? consoleLogger.debug,
+  info: logger?.info ?? consoleLogger.info,
+  warn: logger?.warn ?? consoleLogger.warn,
+  error: logger?.error ?? consoleLogger.error,
+})
+
+const LoggerContext = createContext<Required<Logger>>(consoleLogger)
+
+/**
+ * Provides the resolved logger sink to the messaging subtree. Rendered by
+ * `MessagingProvider`; usable standalone in tests or in a subtree that needs a
+ * different sink.
+ */
+export const MessagingLoggerProvider: React.FC<{
+  logger?: Logger
+  children: React.ReactNode
+}> = ({ logger, children }) => {
+  const value = useMemo(() => resolveLogger(logger), [logger])
+  return (
+    <LoggerContext.Provider value={value}>{children}</LoggerContext.Provider>
+  )
+}
+
+/**
+ * The logger sink for the current subtree. Falls back to console when no
+ * provider (or no `logger` prop) is present, so call sites never branch.
+ */
+export const useMessagingLogger = (): Required<Logger> =>
+  useContext(LoggerContext)