@bycrux/editor 0.12.0 → 1.0.1

package/src/video/shuttle.ts

@@ -0,0 +1,159 @@
+import type { PlaybackClock } from './playback-clock'
+
+/**
+ * J/K/L shuttle. L plays forward, J plays backward, K stops. Repeating the same
+ * direction doubles the rate (1x -> 2x -> 4x, capped); the opposite direction
+ * resets to that direction at 1x.
+ *
+ * Two mechanisms, split by what can carry audio:
+ *
+ *  - **Forward (1x/2x/4x) IS real playback, with sound.** The engine has a live
+ *    transport rate (`deps.setRate`): project time advances R× and audio is
+ *    pitch-corrected via a streaming time-stretch, so 2x/4x forward is audible,
+ *    not just faster. A forward press ensures the engine transport is running
+ *    (via `deps.play()` — the same gesture-anchored path Space uses, AudioContext
+ *    resume and all) and sets the rate to the shuttle's magnitude.
+ *  - **Reverse is a silent seek-loop.** The engine has no reverse rate (reversed
+ *    audio is not a thing), so J can only fast-scrub the shared `PlaybackClock`:
+ *    real playback is paused (muting audio) and the transport rate reset to 1x,
+ *    then an rAF loop steps `clock.set(clock.get() + rate * dt)`. This touches
+ *    only the clock, never the engine or <video> elements directly, so it works
+ *    identically over both playback paths.
+ */
+export type ShuttleRate = -4 | -2 | -1 | 0 | 1 | 2 | 4
+
+/**
+ * Pure rate-stepping — unit-testable without rAF. Pressing the same
+ * direction again doubles the magnitude (capped at 4x); pressing the
+ * opposite direction resets to that direction at 1x.
+ */
+export function nextShuttleRate(current: ShuttleRate, direction: 1 | -1): ShuttleRate {
+  const sign = Math.sign(current)
+  if (sign !== 0 && sign === direction) {
+    return (Math.min(4, Math.abs(current) * 2) * direction) as ShuttleRate
+  }
+  return direction
+}
+
+export interface ShuttleDeps {
+  clock: PlaybackClock
+  /** The seekable upper bound — the loop stops when it reaches either end. */
+  getDuration: () => number
+  /** True while playback is running OUTSIDE the shuttle's own loop. Polled
+   *  every tick so a real "user hit play" transport change cancels the
+   *  shuttle instead of racing it. */
+  isPlaying: () => boolean
+  /** Start real forward playback WITH audio — the engine transport (the same
+   *  gesture-anchored path Space uses, AudioContext resume included). Called on a
+   *  forward press; a no-op if already playing. */
+  play: () => void
+  /** Pause real playback (audio implicitly muted). Called when entering the
+   *  reverse seek-loop, and by stop() when the shuttle itself started playback. */
+  pause: () => void
+  /** Set the engine's live transport rate R. A forward press sets it to the
+   *  shuttle magnitude (1/2/4) for audible fast-forward; reverse and stop reset
+   *  it to 1x before pausing/scrubbing so nothing plays at a stale rate. */
+  setRate: (rate: number) => void
+  /** Injectable for tests; defaults to `requestAnimationFrame`/`cancelAnimationFrame`. */
+  raf?: (cb: (ms: number) => void) => number
+  caf?: (id: number) => void
+}
+
+export interface ShuttleController {
+  /** J or L. Forward = real playback at the transport rate; reverse = the silent
+   *  seek-loop. */
+  press: (direction: 1 | -1) => void
+  /** K, or any other transport/seek change — stops the loop. */
+  stop: () => void
+  getRate: () => ShuttleRate
+}
+
+export function createShuttleController(deps: ShuttleDeps): ShuttleController {
+  const raf = deps.raf ?? requestAnimationFrame
+  const caf = deps.caf ?? cancelAnimationFrame
+
+  let rate: ShuttleRate = 0
+  let rafId: number | null = null
+  let lastMs: number | null = null
+  // The value WE last wrote — lets the tick tell "the clock changed because
+  // we changed it" apart from "something external moved the playhead" (a
+  // Scrubber click, an arrow-key step, another editor gesture).
+  let lastWritten: number | null = null
+  // True while the shuttle itself is driving real forward playback (any of
+  // 1x/2x/4x). Tells stop() to pause it back, and tells a move to reverse to
+  // mute first.
+  let realPlaying = false
+
+  function stopLoop() {
+    if (rafId !== null) caf(rafId)
+    rafId = null
+    lastMs = null
+  }
+
+  function stop() {
+    rate = 0
+    stopLoop()
+    deps.setRate(1)
+    if (realPlaying) { deps.pause(); realPlaying = false }
+  }
+
+  // Only ever runs for reverse now (forward is real playback, no loop). Keeps
+  // the existing external-change/isPlaying cancellation guards so a real play or
+  // an external seek during a reverse scrub cancels the shuttle instead of
+  // racing it.
+  function tick(ms: number) {
+    if (rate === 0) { stopLoop(); return }
+    if (deps.isPlaying()) { stop(); return }
+    if (lastWritten !== null && deps.clock.get() !== lastWritten) { stop(); return }
+
+    if (lastMs !== null) {
+      const dt = (ms - lastMs) / 1000
+      const duration = deps.getDuration()
+      const next = Math.max(0, Math.min(duration, deps.clock.get() + rate * dt))
+      deps.clock.set(next)
+      lastWritten = next
+      if (next <= 0 || next >= duration) { stop(); return }
+    }
+    lastMs = ms
+    rafId = raf(tick)
+  }
+
+  function startLoopIfNeeded() {
+    if (rafId !== null) return
+    lastMs = null
+    lastWritten = deps.clock.get()
+    rafId = raf(tick)
+  }
+
+  return {
+    press(direction: 1 | -1) {
+      const next = nextShuttleRate(rate, direction)
+
+      if (next > 0) {
+        // FORWARD 1x/2x/4x = REAL playback at the engine transport rate — with
+        // audio, pitch-corrected. Drop any reverse seek-loop, make sure the
+        // engine is playing (resuming the AudioContext), then set the rate.
+        // Ownership (`realPlaying`) is only claimed when the shuttle itself
+        // starts playback from idle — if playback was already running (e.g.
+        // the user pressed Space first), stop() must leave it running rather
+        // than pausing playback the shuttle never started.
+        stopLoop()
+        if (!deps.isPlaying()) { deps.play(); realPlaying = true }
+        deps.setRate(next)
+        rate = next
+        return
+      }
+
+      // REVERSE = the silent seek-loop. Reset the transport rate and pause real
+      // playback before scrubbing, so nothing plays at a stale rate and nothing
+      // double-drives the clock while the loop fast-scrubs it.
+      deps.setRate(1)
+      if (deps.isPlaying()) deps.pause()
+      realPlaying = false
+      rate = next
+      startLoopIfNeeded()
+    },
+    stop,
+    getRate: () => rate,
+  }
+}

package/src/video/source-preview.ts

@@ -0,0 +1,66 @@
+import { useSyncExternalStore } from 'react'
+
+/**
+ * The source-preview override: "show this OFF-TIMELINE clip's frame in the main
+ * preview instead of the timeline's picture", or null for "show the timeline".
+ *
+ * A sibling of `hover-scrub.ts`, and for the same structural reason: it repaints
+ * the preview on every hover move without touching the playback clock. But where
+ * hover-scrub resolves a NUMBER against the timeline, this carries a directly
+ * loadable proxy `url` and a `fraction` into it — a clip the timeline knows
+ * nothing about, driven by a host's footage bin as the pointer travels one of
+ * its cards.
+ *
+ * The seam is entirely opt-in. A host that never creates the store (Hub, LP, the
+ * classic layout) passes nothing; `useSourcePreview(undefined)` returns null and
+ * no overlay is ever mounted, so the main preview behaves exactly as before.
+ *
+ * An external store rather than React state because it is written on every
+ * mousemove: only the preview-stage overlay subscribes, so the editor shell, the
+ * timeline and the caption row don't re-render as the pointer travels a card.
+ */
+export interface SourcePreviewValue {
+  /** A directly-loadable proxy URL (the host resolves it before setting). */
+  url: string
+  /** Position within the source, in [0, 1]. */
+  fraction: number
+}
+
+export interface SourcePreviewStore {
+  get(): SourcePreviewValue | null
+  set(v: SourcePreviewValue | null): void
+  subscribe(cb: () => void): () => void
+}
+
+export function createSourcePreviewStore(): SourcePreviewStore {
+  let value: SourcePreviewValue | null = null
+  const subs = new Set<() => void>()
+  return {
+    get: () => value,
+    set(v) {
+      // Skip the notify when nothing actually changed — a host may re-set the
+      // same url+fraction on repeated pointer events over the same tile.
+      if (v === value) return
+      if (v && value && v.url === value.url && v.fraction === value.fraction) return
+      value = v
+      subs.forEach((cb) => cb())
+    },
+    subscribe(cb) {
+      subs.add(cb)
+      return () => { subs.delete(cb) }
+    },
+  }
+}
+
+/** Stable snapshot for an absent store, so `useSyncExternalStore` isn't handed
+ *  a fresh closure per render when a host omits source-preview entirely. */
+const NO_SUBSCRIBE = () => () => {}
+const NO_VALUE = () => null
+
+export function useSourcePreview(store?: SourcePreviewStore): SourcePreviewValue | null {
+  return useSyncExternalStore(
+    store?.subscribe ?? NO_SUBSCRIBE,
+    store?.get ?? NO_VALUE,
+    store?.get ?? NO_VALUE,
+  )
+}

package/src/video/timecode.ts

@@ -0,0 +1,59 @@
+/**
+ * Parse a user-typed timecode into seconds, for the command palette's
+ * "go to time" entry. Accepted shapes:
+ *
+ *   - bare seconds:  "90", "12.5"
+ *   - mm:ss:         "1:30", "12:03.5"
+ *   - hh:mm:ss:      "01:02:03", "1:02:03.25"
+ *
+ * A fractional part is only valid on the LAST component (seconds) — "1.5:30"
+ * is rejected. Minutes/seconds components (everywhere except the leading
+ * hours) must be < 60. Anything that doesn't match — empty input, letters,
+ * too many `:` groups, out-of-range minutes/seconds — returns `null`.
+ */
+export function parseTimecode(input: string): number | null {
+  const trimmed = input.trim()
+  if (!/^\d+(:\d+){0,2}(\.\d+)?$/.test(trimmed)) return null
+
+  const parts = trimmed.split(':').map(Number)
+  if (parts.length === 1) return parts[0]
+
+  const seconds = parts[parts.length - 1]
+  if (seconds >= 60) return null
+
+  if (parts.length === 2) {
+    const [minutes] = parts
+    return minutes * 60 + seconds
+  }
+
+  const [hours, minutes] = parts
+  if (minutes >= 60) return null
+  return hours * 3600 + minutes * 60 + seconds
+}
+
+/**
+ * Format seconds for the preview transport row's timecode readout, as
+ * `m:ss.f` (or `h:mm:ss.f` once the value reaches an hour) — one decimal
+ * place, rounded to the nearest tenth of a second.
+ *
+ * Deliberately NOT frames (no CapCut-style `hh:mm:ss:ff`): `parseTimecode`
+ * above has no notion of frames — its trailing fractional part is seconds
+ * only — so a frames-style display would silently mis-parse if a user
+ * copied it into the command palette's "go to time" field (a trailing
+ * `:18` would be read as 18 SECONDS, not 18 frames). Emitting the same
+ * `m:ss[.f]` shape `parseTimecode` already accepts keeps the two in sync;
+ * see the round-trip tests in `__tests__/timecode.test.ts`.
+ */
+export function formatTimecode(sec: number): string {
+  const clamped = Number.isFinite(sec) ? Math.max(0, sec) : 0
+  const totalTenths = Math.round(clamped * 10)
+  const wholeSeconds = Math.floor(totalTenths / 10)
+  const tenths = totalTenths % 10
+  const hours = Math.floor(wholeSeconds / 3600)
+  const minutes = Math.floor((wholeSeconds % 3600) / 60)
+  const seconds = wholeSeconds % 60
+  const secondsStr = `${String(seconds).padStart(2, '0')}.${tenths}`
+  return hours > 0
+    ? `${hours}:${String(minutes).padStart(2, '0')}:${secondsStr}`
+    : `${minutes}:${secondsStr}`
+}

package/src/video/timeline/EditableSegment.tsx

@@ -22,7 +22,7 @@ export function EditableSegment({ seg, onEdit }: { seg: CaptionSegment; onEdit:
       suppressContentEditableWarning
       onBlur={handleBlur}
       onKeyDown={handleKeyDown}
-      className="cursor-text rounded px-0.5 hover:bg-white/5 focus:bg-white/10 focus:outline-none focus:ring-1 focus:ring-purple-500/40"
+      className="cursor-text rounded px-0.5 hover:bg-[var(--editor-text)]/5 focus:bg-[var(--editor-text)]/10 focus:outline-none focus:ring-1 focus:ring-purple-500/40"
     >
       {seg.text}
     </span>

package/src/video/timeline/Scrubber.tsx

@@ -1,186 +1,58 @@
-import { formatTime, pct, ratioFromClientX } from './utils'
+import { formatTime } from './utils'
 import { useTimelineContext } from './TimelineContext'
 import { usePlaybackTime } from '../playback-clock'
-
+import { Tooltip } from '../../ui/Tooltip'
+
+/**
+ * The strip above the tracks: current time on the left, project duration on
+ * the right.
+ *
+ * ── Why there is no bar here any more ────────────────────────────────────
+ * This used to also render an overview BAR — a track, an elapsed fill and a
+ * draggable red handle spanning the whole project across the full width. The
+ * canvas timeline owns its own zoom and scroll, so at any zoom but "fit" that
+ * handle sat at a different x than the canvas playhead for the same instant:
+ * two red markers disagreeing about where you are. The bar came out with the
+ * DOM timeline and its per-bar affordances (drag-to-scrub with boundary
+ * snapping, the hover-time tooltip) went with it — the canvas surface has its
+ * own playhead grab band and its own preview axis for those.
+ *
+ * The readouts stay, because they are TIMES rather than positions: they read
+ * from the same clock the canvas paints from and cannot disagree with it.
+ */
 interface ScrubberProps {
-  hoverPct: number | null
-  draggingPlayhead: boolean
-  setDraggingPlayhead: (v: boolean) => void
-  keyNavTime: number | null
-  onSplit?: (at: number) => void
-  onCut?: (cut: { start: number; end: number }) => void
-  cutButtonLabel: string
+  /** SP5 T9 — opens the command palette's "go to time" input. Absent →
+   *  the time readout stays plain, non-interactive text. */
+  onOpenGoToTime?: () => void
 }
 
-export default function Scrubber({
-  hoverPct,
-  draggingPlayhead,
-  setDraggingPlayhead,
-  keyNavTime,
-  onSplit,
-  onCut,
-  cutButtonLabel,
-}: ScrubberProps) {
-  const { clock, totalDuration, contentDuration, markers, setMarkers, snapBoundaries, scrubberRef, selection } = useTimelineContext()
+export default function Scrubber({ onOpenGoToTime }: ScrubberProps) {
+  const { clock, contentDuration } = useTimelineContext()
   const currentTime = usePlaybackTime(clock)
 
-  function handleScrubClick(e: React.MouseEvent<HTMLDivElement>) {
-    e.stopPropagation()
-    if (totalDuration === 0) return
-    clock.set(ratioFromClientX(e.clientX, scrubberRef.current!.getBoundingClientRect()) * totalDuration)
-  }
-
-  function handleScrubDoubleClick(e: React.MouseEvent<HTMLDivElement>) {
-    if (totalDuration === 0) return
-    e.preventDefault()
-    const t = ratioFromClientX(e.clientX, scrubberRef.current!.getBoundingClientRect()) * totalDuration
-    setMarkers(([a, b]) => {
-      if (a === null) return [t, null]       // place first marker
-      if (b === null) return [a, t]          // place second → selection complete
-      return [t, null]                       // reset: start fresh with new first marker
-    })
-  }
-
   return (
-    <>
-      {/* ── Scrubber ── */}
-      <div
-        ref={scrubberRef}
-        className={`relative h-4 rounded-full bg-gray-200 dark:bg-gray-800 group ${markers[0] !== null && markers[1] === null ? 'cursor-cell' : 'cursor-crosshair'}`}
-        onClick={handleScrubClick}
-        onDoubleClick={handleScrubDoubleClick}
-      >
-        {/* Elapsed fill */}
-        <div
-          className="absolute inset-y-0 left-0 rounded-full bg-gray-400 dark:bg-gray-600 pointer-events-none"
-          style={{ width: `${pct(currentTime, totalDuration)}%` }}
-        />
-
-        {/* Selection range fill (both markers placed) */}
-        {selection && (
-          <div
-            className="absolute inset-y-0 bg-amber-500/25 pointer-events-none"
-            style={{ left: `${pct(selection.start, totalDuration)}%`, width: `${pct(selection.end - selection.start, totalDuration)}%` }}
-          />
-        )}
-
-        {/* Marker A */}
-        {markers[0] !== null && (
-          <div className="absolute top-0 bottom-0 w-px bg-amber-400 pointer-events-none" style={{ left: `${pct(markers[0], totalDuration)}%` }}>
-            <div className="absolute -top-0.5 -translate-x-1/2 w-2 h-2 bg-amber-400 rotate-45" />
-          </div>
-        )}
-
-        {/* Marker B */}
-        {markers[1] !== null && (
-          <div className="absolute top-0 bottom-0 w-px bg-amber-400 pointer-events-none" style={{ left: `${pct(markers[1], totalDuration)}%` }}>
-            <div className="absolute -top-0.5 -translate-x-1/2 w-2 h-2 bg-amber-400 rotate-45" />
-          </div>
-        )}
-
-        {/* Playhead handle */}
-        <div
-          className={`absolute top-1/2 -translate-y-1/2 -translate-x-1/2 w-3 h-3 rounded-full bg-red-500 ring-2 ring-red-500/30 transition-transform group-hover:scale-125 ${draggingPlayhead ? 'cursor-grabbing scale-125' : 'cursor-grab'}`}
-          style={{ left: `${pct(currentTime, totalDuration)}%` }}
-          onMouseDown={(e) => {
-            e.stopPropagation()
-            if (totalDuration === 0) return
-            setDraggingPlayhead(true)
-            const boundaries = snapBoundaries
-            let snappedTo: number | null = null   // which boundary we're currently locked to
-            function onMove(me: MouseEvent) {
-              const rect = scrubberRef.current?.getBoundingClientRect()
-              if (!rect) return
-              const attractPx = 18   // cursor enters this range → snaps in
-              const releasePx = 28   // cursor must leave this range → breaks free
-              const attract = (attractPx / rect.width) * totalDuration
-              const release = (releasePx / rect.width) * totalDuration
-              const rawT = ratioFromClientX(me.clientX, scrubberRef.current!.getBoundingClientRect()) * totalDuration
-              // Already snapped — hold until cursor escapes release radius
-              if (snappedTo !== null) {
-                if (Math.abs(rawT - snappedTo) < release) { clock.set(snappedTo); return }
-                snappedTo = null
-              }
-              // Scan for attraction
-              for (const b of boundaries) {
-                if (Math.abs(rawT - b) < attract) { snappedTo = b; clock.set(b); return }
-              }
-              clock.set(rawT)
-            }
-            function onUp() {
-              setDraggingPlayhead(false)
-              document.removeEventListener('mousemove', onMove)
-              document.removeEventListener('mouseup', onUp)
-            }
-            document.addEventListener('mousemove', onMove)
-            document.addEventListener('mouseup', onUp)
-          }}
-          onDoubleClick={(e) => {
-            e.stopPropagation()
-            handleScrubDoubleClick(e as React.MouseEvent<HTMLDivElement>)
-          }}
-        >
-          {keyNavTime !== null && (
-            <div className="absolute -top-7 left-1/2 -translate-x-1/2 bg-gray-800 border border-gray-700 text-white text-[10px] font-mono px-1.5 py-0.5 rounded pointer-events-none whitespace-nowrap z-20">
-              {formatTime(keyNavTime)}
-            </div>
-          )}
-        </div>
-
-        {/* Time tooltip */}
-        {hoverPct !== null && totalDuration > 0 && (
-          <div
-            className="absolute -top-7 -translate-x-1/2 bg-gray-800 border border-gray-700 text-white text-[10px] font-mono px-1.5 py-0.5 rounded pointer-events-none whitespace-nowrap z-20"
-            style={{ left: `${hoverPct}%` }}
+    /* `cursor-pointer`: the row is a strip of timeline background, and
+       Timeline's container click seeks through it (see `handleContainerClick`),
+       so it should look live rather than dead. */
+    <div className="flex items-center justify-between text-[10px] font-mono text-[var(--editor-text)]/35 cursor-pointer">
+      {onOpenGoToTime ? (
+        <Tooltip label="Go to time">
+          <button
+            type="button"
+            aria-label="Go to time"
+            onClick={(e) => { e.stopPropagation(); onOpenGoToTime() }}
+            className="hover:text-[var(--editor-text)]/80 transition-colors"
           >
-            {formatTime((hoverPct / 100) * totalDuration)}
-          </div>
-        )}
-      </div>
-
-      {/* Time readout + marker / selection range */}
-      <div className="flex items-center justify-between text-[10px] font-mono text-gray-600 -mt-1">
+            {formatTime(currentTime)}
+          </button>
+        </Tooltip>
+      ) : (
         <span>{formatTime(currentTime)}</span>
-        {markers[0] !== null && markers[1] === null && (
-          <span className="flex items-center gap-2 text-amber-400/80">
-            {onSplit && (
-              <button
-                className="px-2 py-0.5 rounded bg-amber-500/80 hover:bg-amber-400 text-black text-[10px] font-medium transition-colors"
-                onClick={(e) => { e.stopPropagation(); onSplit(markers[0]!); setMarkers([null, null]) }}
-              >
-                Split
-              </button>
-            )}
-            {formatTime(markers[0])} — double-click to set end
-            <button
-              className="text-gray-600 hover:text-gray-400"
-              onClick={(e) => { e.stopPropagation(); setMarkers([null, null]) }}
-            >✕</button>
-          </span>
-        )}
-        {selection && (
-          <span className="flex items-center gap-2 text-amber-400">
-            <button
-              className="text-gray-600 hover:text-gray-400"
-              onClick={(e) => { e.stopPropagation(); setMarkers([null, null]) }}
-            >✕</button>
-            {formatTime(selection.start)} – {formatTime(selection.end)}
-            {onCut && (
-              <button
-                className="px-2 py-0.5 rounded bg-red-600/80 hover:bg-red-500 text-white text-[10px] font-medium transition-colors"
-                onClick={(e) => {
-                  e.stopPropagation()
-                  onCut(selection)
-                  setMarkers([null, null])
-                }}
-              >
-                {cutButtonLabel}
-              </button>
-            )}
-          </span>
-        )}
-        <span>{formatTime(contentDuration)}</span>
-      </div>
-    </>
+      )}
+      {/* `data-timeline-chrome`: a readout, not a place to seek to. Clicking
+          it would otherwise jump the playhead to the far right of the view,
+          since it sits at the right edge of a strip that IS a time axis. */}
+      <span data-timeline-chrome className="cursor-default">{formatTime(contentDuration)}</span>
+    </div>
   )
 }

package/src/video/timeline/SpeedControl.tsx

@@ -0,0 +1,95 @@
+/**
+ * A controlled speed picker: a slider plus a row of clickable preset chips
+ * snapping it to a common value. Shared by the per-clip inspect modal (host
+ * `montaj_assets/ui` package) and the track-wide settings popover
+ * (TrackSettingsPopover.tsx) — one control, one look, wherever speed is set.
+ *
+ * Controlled, not stateful: the caller owns `value` and reacts to `onChange`,
+ * exactly like the range inputs elsewhere in this rail (volume, fontsize).
+ * That keeps the two mount points free to wire it up differently — the clip
+ * modal previews live and commits on an explicit Save button; the track popover
+ * previews into local state and commits directly via `onCommit` (on slider
+ * release and on a chip click), so touching a track control just applies, no
+ * button, the same live-preview-then-commit split the volume fader uses.
+ *
+ * The slider itself is the shared `<Slider>` (ui/Slider.tsx) — see
+ * `VolumeControl`'s twin comment for the one behaviour change it brings
+ * (commit only on an actual gesture change, not on every pointerup/keyup).
+ */
+import { Slider } from '../../ui'
+
+export interface SpeedControlProps {
+  value: number
+  onChange: (v: number) => void
+  /** Optional commit signal, fired on slider release (pointer/keyboard) and on
+   *  a chip click, carrying the value to commit. Callers that commit on their
+   *  own control (e.g. a Save button) omit it and just read `onChange`. */
+  onCommit?: (v: number) => void
+  min?: number
+  max?: number
+  step?: number
+  presets?: number[]
+  label?: string
+  /** Base id for the slider input, so a caller can wire a `<label htmlFor>`
+   *  to it. Optional — the control is already self-labelled via `aria-label`. */
+  idBase?: string
+}
+
+const DEFAULT_PRESETS = [0.25, 0.5, 1, 2, 4]
+
+export default function SpeedControl({
+  value,
+  onChange,
+  onCommit,
+  min = 0.25,
+  max = 4,
+  step = 0.05,
+  presets = DEFAULT_PRESETS,
+  label,
+  idBase,
+}: SpeedControlProps) {
+  const sliderId = idBase ? `${idBase}-speed-slider` : undefined
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className={`flex items-center text-[11px] text-[var(--editor-text)]/70 ${label ? 'justify-between' : 'justify-end'}`}>
+        {label && <span>{label}</span>}
+        <span className="font-mono text-[10px] text-[var(--editor-text)]/50">{value.toFixed(2)}×</span>
+      </div>
+      <Slider
+        id={sliderId}
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        aria-label={label ?? 'Speed'}
+        onChange={onChange}
+        onCommit={onCommit}
+      />
+      {/* Quick-set chips under the slider — a click snaps straight to that
+          value rather than dragging for it. The active one is marked with
+          `aria-pressed` and the accent fill, mirroring the toolbar's own
+          bold/italic toggle buttons (TextFormattingToolbar.tsx). */}
+      <div role="group" aria-label={label ? `${label} presets` : 'Speed presets'} className="flex flex-wrap gap-1">
+        {presets.map(p => {
+          const active = Math.abs(value - p) < 1e-6
+          return (
+            <button
+              key={p}
+              type="button"
+              aria-pressed={active}
+              onClick={() => { onChange(p); onCommit?.(p) }}
+              className={`rounded-md border px-2 py-0.5 text-[11px] font-mono transition-colors focus:outline-none focus:ring-1 focus:ring-[var(--editor-accent)] ${
+                active
+                  ? 'border-[var(--editor-accent)] bg-[var(--editor-accent)] text-[var(--editor-accent-foreground)]'
+                  : 'border-[var(--editor-border)] bg-[var(--editor-surface)] text-[var(--editor-text)]/70 hover:text-[var(--editor-text)] hover:border-[var(--editor-accent)]'
+              }`}
+            >
+              {p}×
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}