@proteos/ui 0.77.0 → 0.78.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteos/ui",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "license": "FSL-1.1-Apache-2.0",
   "description": "Proteos React component library (React Aria Components + Tailwind v4).",
   "repository": {
@@ -56,7 +56,8 @@
     "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.2.4",
     "thinking-orbs": "^0.3.1",
-    "@proteos/sdk": "0.77.0"
+    "wavesurfer.js": "8.0.5",
+    "@proteos/sdk": "0.78.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",

package/src/components/data-table/data-table.scroll-restore.test.tsx

@@ -0,0 +1,97 @@
+import { render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { DataTable, type InfiniteQueryLike } from './data-table'
+
+// Deliberately NOT mocking @tanstack/react-virtual: when the virtualizer reads
+// its seed, and what it does while disabled, is exactly what these tests pin.
+// jsdom has no layout, so only the scroller's geometry is stubbed.
+
+type Row = { id: string; name: string }
+
+const VIEWPORT_HEIGHT = 600
+const ROW_HEIGHT = 32
+const columns = [{ id: 'name', accessorKey: 'name', header: 'Name', size: 160 }]
+
+function rows(count: number): Row[] {
+  return Array.from({ length: count }, (_unused, index) => ({
+    id: `r-${index}`,
+    name: `Row ${index}`,
+  }))
+}
+
+function query(data: Row[], isLoading = false): InfiniteQueryLike<Row> {
+  return {
+    data: isLoading ? undefined : { pages: [{ data, meta: { items_total: data.length } }] },
+    isLoading,
+    isFetchingNextPage: false,
+    hasNextPage: false,
+    error: null,
+    fetchNextPage: vi.fn(),
+  }
+}
+
+function table(data: Row[], restored: number, isLoading = false) {
+  return (
+    <DataTable<Row>
+      query={query(data, isLoading)}
+      columns={columns}
+      ariaLabel="Records"
+      rowHeight={ROW_HEIGHT}
+      initialScrollOffset={restored}
+    />
+  )
+}
+
+describe('DataTable scroll restore (real virtualizer)', () => {
+  const scrollTo = vi.fn()
+  const originalScrollTo = HTMLElement.prototype.scrollTo
+
+  beforeEach(() => {
+    scrollTo.mockClear()
+    HTMLElement.prototype.scrollTo = scrollTo
+    for (const prop of ['offsetHeight', 'clientHeight'] as const) {
+      Object.defineProperty(HTMLElement.prototype, prop, {
+        configurable: true,
+        value: VIEWPORT_HEIGHT,
+      })
+    }
+    Object.defineProperty(HTMLElement.prototype, 'offsetWidth', {
+      configurable: true,
+      value: 800,
+    })
+  })
+
+  afterEach(() => {
+    HTMLElement.prototype.scrollTo = originalScrollTo
+    for (const prop of ['offsetHeight', 'clientHeight', 'offsetWidth']) {
+      delete (HTMLElement.prototype as unknown as Record<string, unknown>)[prop]
+    }
+  })
+
+  it('opens cached rows at the saved position', () => {
+    render(table(rows(100), 1600))
+    expect(screen.getByText('Row 50')).toBeInTheDocument()
+    expect(screen.queryByText('Row 0')).toBeNull()
+    expect(scrollTo).toHaveBeenCalledWith(expect.objectContaining({ top: 1600 }))
+  })
+
+  it('clamps to the end of a list that shrank since the visit', () => {
+    render(table(rows(40), 3000))
+    // 40 rows × 32 = 1280; the furthest reachable offset is 1280 - 600 = 680.
+    expect(screen.getByText('Row 39')).toBeInTheDocument()
+    expect(scrollTo).toHaveBeenCalledWith(expect.objectContaining({ top: 680 }))
+  })
+
+  it('shows rows that fit the viewport instead of an empty body', () => {
+    render(table(rows(3), 3000))
+    expect(screen.getByText('Row 0')).toBeInTheDocument()
+    expect(screen.getByText('Row 2')).toBeInTheDocument()
+  })
+
+  it('shows rows that arrive after a loading first render', () => {
+    const { rerender } = render(table([], 3000, true))
+    rerender(table(rows(10), 3000))
+    expect(screen.getByText('Row 0')).toBeInTheDocument()
+  })
+})

package/src/components/data-table/data-table.test.tsx

@@ -47,8 +47,18 @@ function Harness({ onChange }: { onChange?: (ids: Set<string>) => void }) {
 // measure (every rect is 0×0, so the virtualizer yields no items and no row
 // ever renders). Swap the virtualizer for a pass-through that emits every
 // row — the windowing itself is TanStack's to test, not ours.
+const virtualizerOptions = vi.hoisted(() => ({
+  last: undefined as { initialOffset?: number | (() => number) } | undefined,
+}))
+
 vi.mock('@tanstack/react-virtual', () => ({
-  useVirtualizer: ({ count, estimateSize }: { count: number; estimateSize: () => number }) => {
+  useVirtualizer: (options: {
+    count: number
+    estimateSize: () => number
+    initialOffset?: number | (() => number)
+  }) => {
+    virtualizerOptions.last = options
+    const { count, estimateSize } = options
     const size = estimateSize()
     return {
       getTotalSize: () => count * size,
@@ -219,7 +229,12 @@ describe('DataTable scroll restoration', () => {
     try {
       const sorting = [{ id: 'name', desc: false }]
       const { rerender } = render(
-        <DataTable<Row> query={query(ROWS)} columns={columns} ariaLabel="Records" sorting={sorting} />,
+        <DataTable<Row>
+          query={query(ROWS)}
+          columns={columns}
+          ariaLabel="Records"
+          sorting={sorting}
+        />,
       )
       expect(scrollTo).not.toHaveBeenCalled()
 
@@ -236,4 +251,9 @@ describe('DataTable scroll restoration', () => {
       HTMLElement.prototype.scrollTo = original
     }
   })
+
+  it('does not seed an offset on a fresh visit', () => {
+    render(<DataTable<Row> query={query(ROWS)} columns={columns} ariaLabel="Records" />)
+    expect(virtualizerOptions.last?.initialOffset).toBeUndefined()
+  })
 })

package/src/components/data-table/data-table.tsx

@@ -423,13 +423,43 @@ export function DataTable<TRow>({
 
   const headingHeight = groupHeaderHeight ?? rowHeight
 
+  // The virtualizer reads (and caches) `initialOffset` during render, the
+  // first time `getVirtualItems()` runs — before React attaches
+  // `scrollerRef`. When restoring, keep it disabled for that first render (a
+  // disabled virtualizer caches no offset) and enable it once the scroller is
+  // attached; the layout-phase re-render lands before the first paint.
+  const [isScrollerAttached, setIsScrollerAttached] = useState(false)
+  useLayoutEffect(() => setIsScrollerAttached(true), [])
+
   const virtualizer = useVirtualizer({
+    enabled: initialScrollOffset === undefined || isScrollerAttached,
     count: listItems.length,
     getScrollElement: () => scrollerRef.current,
     estimateSize: (index) => (listItems[index]?.kind === 'group' ? headingHeight : rowHeight),
     overscan,
     scrollMargin: listOffset,
-    ...(initialScrollOffset !== undefined ? { initialOffset: initialScrollOffset } : {}),
+    // Read once, with the scroller attached (see `enabled`). Clamp the restored
+    // offset to what the scroller will be able to reach: while the skeleton
+    // shows, or when the list shrank since the visit, the browser clamps
+    // scrollTop WITHOUT firing a scroll event, and the virtualizer — which only
+    // re-reads its offset on scroll events — would sit past the rows and paint
+    // empty. The reach comes from the row data, not `scrollHeight`: the disabled
+    // first render committed an empty spacer, so the DOM can't report it yet.
+    ...(initialScrollOffset !== undefined
+      ? {
+          initialOffset: () => {
+            const el = scrollerRef.current
+            if (!el) return 0
+            const estimatedSize = listItems.reduce(
+              (sum, item) => sum + (item.kind === 'group' ? headingHeight : rowHeight),
+              0,
+            )
+            const listTop = listRef.current?.offsetTop ?? 0
+            const reachable = listTop + estimatedSize - el.clientHeight
+            return Math.max(0, Math.min(initialScrollOffset, reachable))
+          },
+        }
+      : {}),
   })
 
   const sentinelRef = useInfiniteScrollSentinel<HTMLDivElement>({

package/src/components/frame-strip/frame-strip.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { useState } from 'react'
+
+import { FrameStrip, type FrameStripItem } from './frame-strip'
+
+const HUES = [214, 160, 28, 340, 262, 190]
+
+/** A stand-in still: a tinted window with a block somewhere in it. */
+function Still({ index }: { index: number }) {
+  const hue = HUES[index % HUES.length] ?? 214
+  return (
+    <svg viewBox="0 0 160 90" aria-hidden>
+      <rect width="160" height="90" fill={`oklch(0.93 0.03 ${hue})`} />
+      <rect x="18" y="16" width="124" height="58" rx="4" fill={`oklch(0.8 0.08 ${hue})`} />
+      <rect
+        x={28 + ((index * 17) % 90)}
+        y="30"
+        width="30"
+        height="30"
+        rx="3"
+        fill={`oklch(0.5 0.16 ${hue})`}
+      />
+    </svg>
+  )
+}
+
+const makeItems = (count: number): FrameStripItem[] =>
+  Array.from({ length: count }, (_, index) => ({
+    key: `frame-${index + 1}`,
+    label: `Frame ${index + 1}`,
+    at: index * 2.3 + 1.2,
+    thumbnail: <Still index={index} />,
+  }))
+
+function Frame({ count, width = 420 }: { count: number; width?: number }) {
+  const [items] = useState(() => makeItems(count))
+  const [selectedKey, setSelectedKey] = useState('frame-1')
+  return (
+    <div className="border border-rule bg-surface" style={{ width }}>
+      <FrameStrip
+        aria-label="Frames"
+        items={items}
+        selectedKey={selectedKey}
+        onSelect={setSelectedKey}
+      />
+    </div>
+  )
+}
+
+const meta: Meta<typeof FrameStrip> = {
+  title: 'Components/FrameStrip',
+  component: FrameStrip,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof FrameStrip>
+
+export const AFewFrames: Story = { render: () => <Frame count={3} /> }
+export const Scrolling: Story = { render: () => <Frame count={14} /> }
+export const Wide: Story = { render: () => <Frame count={5} width={720} /> }

package/src/components/frame-strip/frame-strip.test.tsx

@@ -0,0 +1,112 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { FrameStrip } from './frame-strip'
+
+const ITEMS = [1, 2, 3].map((index) => ({
+  key: `f${index}`,
+  label: `Frame ${index}`,
+  at: index * 2.5,
+  thumbnail: <img alt="" src={`data:image/png;base64,${index}`} />,
+}))
+
+function Harness({ initial, onSelect }: { initial?: string; onSelect?: (key: string) => void }) {
+  const [selectedKey, setSelectedKey] = useState<string | undefined>(initial)
+  return (
+    <FrameStrip
+      aria-label="Frames"
+      items={ITEMS}
+      {...(selectedKey !== undefined ? { selectedKey } : {})}
+      onSelect={(key) => {
+        setSelectedKey(key)
+        onSelect?.(key)
+      }}
+    />
+  )
+}
+
+const scrollIntoView = vi.fn()
+
+beforeEach(() => {
+  // jsdom lays nothing out and has no scrollIntoView to call.
+  scrollIntoView.mockClear()
+  Element.prototype.scrollIntoView = scrollIntoView
+})
+
+describe('FrameStrip', () => {
+  it('lists the frames as one exclusive group, each named with its time', () => {
+    render(<Harness />)
+    expect(screen.getByRole('radiogroup', { name: 'Frames' })).toBeInTheDocument()
+    expect(screen.getAllByRole('radio').map((radio) => radio.getAttribute('aria-label'))).toEqual([
+      'Frame 1, at 00:02',
+      'Frame 2, at 00:05',
+      'Frame 3, at 00:07',
+    ])
+  })
+
+  it('shows the thumbnail and the caption inside each frame', () => {
+    render(<Harness />)
+    const frame = screen.getByRole('radio', { name: 'Frame 2, at 00:05' })
+    expect(frame.querySelector('img')).not.toBeNull()
+    expect(frame).toHaveTextContent('Frame 2')
+    expect(frame).toHaveTextContent('00:05')
+  })
+
+  it('marks the selected frame', () => {
+    render(<Harness initial="f2" />)
+    expect(screen.getByRole('radio', { name: 'Frame 2, at 00:05' })).toBeChecked()
+    expect(screen.getByRole('radio', { name: 'Frame 1, at 00:02' })).not.toBeChecked()
+  })
+
+  it('selects on click and reports the key', async () => {
+    const user = userEvent.setup()
+    const onSelect = vi.fn()
+    render(<Harness onSelect={onSelect} />)
+    await user.click(screen.getByRole('radio', { name: 'Frame 3, at 00:07' }))
+    expect(onSelect).toHaveBeenLastCalledWith('f3')
+    expect(screen.getByRole('radio', { name: 'Frame 3, at 00:07' })).toBeChecked()
+  })
+
+  it('keeps the selection when the selected frame is pressed again', async () => {
+    const user = userEvent.setup()
+    render(<Harness initial="f1" />)
+    await user.click(screen.getByRole('radio', { name: 'Frame 1, at 00:02' }))
+    expect(screen.getByRole('radio', { name: 'Frame 1, at 00:02' })).toBeChecked()
+  })
+
+  it('moves between frames with the arrow keys and picks with the keyboard', async () => {
+    const user = userEvent.setup()
+    const onSelect = vi.fn()
+    render(<Harness onSelect={onSelect} />)
+    await user.tab()
+    expect(screen.getByRole('radio', { name: 'Frame 1, at 00:02' })).toHaveFocus()
+    await user.keyboard('{ArrowRight}')
+    expect(screen.getByRole('radio', { name: 'Frame 2, at 00:05' })).toHaveFocus()
+    await user.keyboard('{Enter}')
+    expect(onSelect).toHaveBeenLastCalledWith('f2')
+    expect(screen.getByRole('radio', { name: 'Frame 2, at 00:05' })).toBeChecked()
+  })
+
+  it('keeps a selection made elsewhere in view', () => {
+    const { rerender } = render(
+      <FrameStrip aria-label="Frames" items={ITEMS} selectedKey="f1" onSelect={() => {}} />,
+    )
+    rerender(<FrameStrip aria-label="Frames" items={ITEMS} selectedKey="f3" onSelect={() => {}} />)
+    expect(scrollIntoView).toHaveBeenLastCalledWith({ block: 'nearest', inline: 'nearest' })
+    expect(scrollIntoView.mock.contexts.at(-1)).toBe(
+      screen.getByRole('radio', { name: 'Frame 3, at 00:07' }),
+    )
+  })
+
+  it('names the group on its own when no label is given', () => {
+    render(<FrameStrip items={ITEMS} onSelect={() => {}} />)
+    expect(screen.getByRole('radiogroup', { name: 'Frames' })).toBeInTheDocument()
+  })
+
+  it('renders nothing without frames', () => {
+    render(<FrameStrip aria-label="Frames" items={[]} onSelect={() => {}} />)
+    expect(screen.queryByRole('radiogroup')).not.toBeInTheDocument()
+  })
+})

package/src/components/frame-strip/frame-strip.tsx

@@ -0,0 +1,131 @@
+import { type ReactNode, useEffect, useRef } from 'react'
+import {
+  ToggleButton as AriaToggleButton,
+  ToggleButtonGroup as AriaToggleButtonGroup,
+  type ToggleButtonGroupProps as AriaToggleButtonGroupProps,
+} from 'react-aria-components'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+import { formatMediaTime } from '../media-player/media-time'
+
+/* =========================================================================
+   FrameStrip — a sideways row of stills from a recording, each named and
+   stamped with its time, one of them current. Wraps RAC ToggleButtonGroup in
+   single selection: one radiogroup, one tab stop, arrow keys between frames,
+   so picking a frame reads like picking a moment. The strip scrolls
+   horizontally and keeps a selection made elsewhere in view (playback
+   reaching the next frame).
+
+   The thumbnail is the consumer's node (an <img>, a canvas, a placeholder)
+   and fills a 16:9 box; the strip only lays the frames out.
+   ========================================================================= */
+
+export const frameStripStyles = tv({
+  slots: {
+    root: 'flex shrink-0 gap-2 overflow-x-auto overscroll-x-contain scroll-px-[18px] px-[18px] py-3',
+    item: [
+      'group flex w-[120px] shrink-0 cursor-pointer flex-col gap-1.5 rounded-md p-1 outline-none',
+      'transition-[background-color,box-shadow] duration-150',
+      'hovered:bg-surface-2',
+      'pressed:bg-surface-3',
+      'data-[focus-visible]:shadow-[var(--shadow-focus)]',
+    ],
+    thumbnail: [
+      'relative aspect-video w-full overflow-hidden rounded-sm border border-rule bg-surface-2',
+      '*:size-full *:object-cover',
+      'transition-[border-color,box-shadow] duration-150',
+      'group-data-[hovered]:border-rule-strong',
+      'group-data-[selected]:border-ink group-data-[selected]:shadow-[inset_0_0_0_1px_var(--color-ink)]',
+    ],
+    caption: 'flex min-w-0 items-baseline gap-1.5 px-0.5',
+    label: [
+      'min-w-0 flex-1 truncate text-[12px] leading-4 text-ink-2',
+      'group-data-[selected]:font-medium group-data-[selected]:text-ink',
+    ],
+    time: 'shrink-0 font-mono text-[11px] leading-4 tabular-nums text-ink-4',
+  },
+})
+
+export type FrameStripVariants = VariantProps<typeof frameStripStyles>
+
+export interface FrameStripItem {
+  key: string
+  label: string
+  /** Seconds into the recording. */
+  at: number
+  thumbnail: ReactNode
+}
+
+export type FrameStripProps = Omit<
+  AriaToggleButtonGroupProps,
+  | 'children'
+  | 'selectionMode'
+  | 'selectedKeys'
+  | 'defaultSelectedKeys'
+  | 'onSelectionChange'
+  | 'disallowEmptySelection'
+  | 'orientation'
+  | 'className'
+  | 'style'
+> & {
+  items: ReadonlyArray<FrameStripItem>
+  /** The current frame; none when undefined. */
+  selectedKey?: string
+  onSelect: (key: string) => void
+  className?: string
+}
+
+export function FrameStrip({ items, selectedKey, onSelect, className, ...props }: FrameStripProps) {
+  const styles = frameStripStyles()
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  // The selection moved from outside (playback reached the next frame): follow it.
+  useEffect(() => {
+    const root = rootRef.current
+    if (selectedKey === undefined || !root) return
+    for (const element of root.querySelectorAll<HTMLElement>('[data-frame-key]')) {
+      if (element.dataset.frameKey !== selectedKey) continue
+      if (typeof element.scrollIntoView === 'function')
+        element.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+      break
+    }
+  }, [selectedKey])
+
+  if (items.length === 0) return null
+
+  const isLabelled = props['aria-label'] !== undefined || props['aria-labelledby'] !== undefined
+
+  return (
+    <AriaToggleButtonGroup
+      {...(isLabelled ? {} : { 'aria-label': 'Frames' })}
+      {...props}
+      ref={rootRef}
+      orientation="horizontal"
+      selectionMode="single"
+      disallowEmptySelection
+      selectedKeys={selectedKey === undefined ? new Set() : new Set([selectedKey])}
+      onSelectionChange={(keys) => {
+        const [next] = Array.from(keys)
+        if (next !== undefined) onSelect(String(next))
+      }}
+      className={cn(styles.root(), className)}
+    >
+      {items.map((item) => (
+        <AriaToggleButton
+          key={item.key}
+          id={item.key}
+          data-frame-key={item.key}
+          aria-label={`${item.label}, at ${formatMediaTime(item.at)}`}
+          className={styles.item()}
+        >
+          <span className={styles.thumbnail()}>{item.thumbnail}</span>
+          <span className={styles.caption()}>
+            <span className={styles.label()}>{item.label}</span>
+            <span className={styles.time()}>{formatMediaTime(item.at)}</span>
+          </span>
+        </AriaToggleButton>
+      ))}
+    </AriaToggleButtonGroup>
+  )
+}

package/src/components/frame-strip/index.ts

@@ -0,0 +1,2 @@
+export type { FrameStripItem, FrameStripProps, FrameStripVariants } from './frame-strip'
+export { FrameStrip, frameStripStyles } from './frame-strip'

package/src/components/media-player/index.ts

@@ -0,0 +1,22 @@
+export type { MediaControlsProps, MediaControlsVariants } from './media-controls'
+export { MediaControls, mediaControlsStyles } from './media-controls'
+export type { MediaMarker, MediaMarkersVariants, MediaMarkerTrackProps } from './media-markers'
+export { currentMediaMarkers, MediaMarkerTrack, mediaMarkersStyles } from './media-markers'
+export type { DecodedPeaks, MediaSegment } from './media-peaks'
+export { decodePeaks, MAX_DECODE_BYTES, maskPeaks, peaksFromChannels } from './media-peaks'
+export type {
+  MediaPlayerContextValue,
+  MediaPlayerKind,
+  MediaPlayerProps,
+  MediaPlayerSource,
+  MediaPlayerVariants,
+  MediaWaveformStatus,
+} from './media-player'
+export { MediaPlayer, MediaStage, mediaPlayerStyles, useMediaPlayer } from './media-player'
+export { formatMediaTime, spokenMediaTime } from './media-time'
+export type { MediaTimelineProps, MediaTimelineVariants } from './media-timeline'
+export { MediaTimeline, mediaTimelineStyles } from './media-timeline'
+export type { MediaVideoStageProps, MediaVideoStageVariants } from './media-video-stage'
+export { fitMediaBox, MediaVideoStage, mediaVideoStageStyles } from './media-video-stage'
+export type { MediaLane, MediaWaveformProps, MediaWaveformVariants } from './media-waveform'
+export { MediaWaveform, mediaWaveformStyles } from './media-waveform'

package/src/components/media-player/media-controls.tsx

@@ -0,0 +1,145 @@
+import { Pause, Play, RotateCcw, RotateCw, Square } from 'lucide-react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+import { Button } from '../button/button'
+import { Slider } from '../slider/slider'
+import { useMediaPlayer } from './media-player'
+import { formatMediaTime, spokenMediaTime } from './media-time'
+
+/* =========================================================================
+   MediaControls — the transport: a seek slider between elapsed and total
+   time, then stop · back · play · forward · speed. Play is the view's one
+   `cta`. Uses `useMediaPlayer` for everything, so it needs no props beyond
+   an optional spoken description of the moment.
+   ========================================================================= */
+
+export const mediaControlsStyles = tv({
+  slots: {
+    root: 'shrink-0 border-t border-rule-2 px-[18px] pt-3 pb-3.5',
+    seek: 'grid grid-cols-[auto_1fr_auto] items-center gap-2.5',
+    elapsed: 'font-mono text-[12.5px] leading-none tabular-nums text-ink-2',
+    total: 'font-mono text-[12.5px] leading-none tabular-nums text-ink-4',
+    transport: 'mt-2 grid grid-cols-[1fr_auto_1fr] items-center',
+    center: 'flex items-center gap-1.5',
+    end: 'justify-self-end',
+    text: 'font-mono',
+  },
+})
+
+export type MediaControlsVariants = VariantProps<typeof mediaControlsStyles>
+
+const SKIP_SECONDS = 10
+const SPEEDS = [1, 1.25, 1.5, 2] as const
+
+export interface MediaControlsProps {
+  /** Added to the slider's spoken position, e.g. who is speaking at that moment. */
+  describeTime?: (seconds: number) => string | null
+  /** Render the seek row. Off when another scrubber (a `MediaTimeline` with
+   *  markers) already owns seeking, so the player shows ONE timeline. */
+  hasSeek?: boolean
+  className?: string
+}
+
+export function MediaControls({ describeTime, hasSeek = true, className }: MediaControlsProps) {
+  const {
+    isReady,
+    isPlaying,
+    currentTime,
+    duration,
+    playbackRate,
+    toggle,
+    stop,
+    seek,
+    skip,
+    setPlaybackRate,
+  } = useMediaPlayer()
+  const styles = mediaControlsStyles()
+  const description = describeTime?.(currentTime)
+  const valueText = `${spokenMediaTime(currentTime)} of ${spokenMediaTime(duration)}${
+    description ? `, ${description}` : ''
+  }`
+  const nextSpeed =
+    SPEEDS[(SPEEDS.indexOf(playbackRate as (typeof SPEEDS)[number]) + 1) % SPEEDS.length] ?? 1
+
+  return (
+    <div className={cn(styles.root(), className)}>
+      {hasSeek ? (
+        <div className={styles.seek()}>
+          <span className={styles.elapsed()}>{formatMediaTime(currentTime)}</span>
+          <Slider
+            aria-label="Seek"
+            value={currentTime}
+            minValue={0}
+            maxValue={duration || 1}
+            step={1}
+            isDisabled={!isReady}
+            valueText={valueText}
+            onChange={seek}
+          />
+          <span className={styles.total()}>
+            {duration > 0 ? formatMediaTime(duration) : '--:--'}
+          </span>
+        </div>
+      ) : null}
+      <div className={cn(styles.transport(), !hasSeek && 'mt-0')}>
+        <div>
+          <Button
+            variant="ghost"
+            size="icon-md"
+            aria-label="Stop"
+            isDisabled={!isReady}
+            onPress={stop}
+          >
+            <Square />
+          </Button>
+        </div>
+        <div className={styles.center()}>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-label={`Back ${SKIP_SECONDS} seconds`}
+            isDisabled={!isReady}
+            onPress={() => skip(-SKIP_SECONDS)}
+            className={styles.text()}
+          >
+            <RotateCcw />
+            {SKIP_SECONDS}
+          </Button>
+          <Button
+            variant="cta"
+            size="icon-lg"
+            aria-label={isPlaying ? 'Pause' : 'Play'}
+            isDisabled={!isReady}
+            onPress={toggle}
+          >
+            {isPlaying ? <Pause fill="currentColor" /> : <Play fill="currentColor" />}
+          </Button>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-label={`Forward ${SKIP_SECONDS} seconds`}
+            isDisabled={!isReady}
+            onPress={() => skip(SKIP_SECONDS)}
+            className={styles.text()}
+          >
+            {SKIP_SECONDS}
+            <RotateCw />
+          </Button>
+        </div>
+        <div className={styles.end()}>
+          <Button
+            variant="ghost"
+            size="sm"
+            aria-label={`Playback speed ${playbackRate} times`}
+            isDisabled={!isReady}
+            onPress={() => setPlaybackRate(nextSpeed)}
+            className={styles.text()}
+          >
+            {playbackRate}×
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}