@bycrux/editor 0.12.0 → 1.0.1

package/src/video/timeline/useItemDragDrop.ts

@@ -1,4 +1,17 @@
-import type React from 'react'
+/**
+ * The drag/resize arithmetic the timeline's gestures are built out of.
+ *
+ * This module once also held `useItemDragDrop`, a React hook that wired these
+ * functions to mouse events for the DOM track rows. Those rows are retired
+ * and the hook went with them: the canvas timeline's pointer machine
+ * (`canvas/pointer-machine.ts`) owns gesture handling now, and calls straight
+ * into three of the five pure functions below — `DRAG_THRESHOLD_PX`,
+ * `computeResizedItem`, `resizeWindowedItem` — with times it derived from its
+ * own viewport and snapped with hysteresis (`canvas/snap.ts`). The other two,
+ * `snapToBoundaries` and `snapMovedSpan`, have no production caller any more
+ * (canvas snapping lives in `canvas/snap.ts`) and are kept deliberately,
+ * test-covered only. Nothing here touches the DOM or React any more.
+ */
 
 export interface Draggable {
   id: string
@@ -9,199 +22,159 @@ export interface Draggable {
   normalizedInPoint?: number
   type?: string
   sourceDuration?: number
+  /** Per-clip playback speed S (video only). A clip at S consumes S source
+   *  seconds per timeline second, so every timeline↔source conversion here
+   *  carries it. Absent/1 is a strict no-op. */
+  speed?: number
 }
 
-export interface DragEventContext {
-  /** The item with updated start/end (and inPoint/outPoint for resize) */
-  item: Draggable
-  /** Horizontal delta in timeline seconds from initial position */
-  dx: number
-  /** Vertical delta in raw pixels from initial position */
-  dy: number
-}
-
-export interface UseItemDragDropConfig {
-  totalDuration: number
-  snapBoundaries: number[]
-  snapThresholdPx?: number // default 8
-  /** Element used for getBoundingClientRect() → pixel-to-time conversion */
-  scrollRef: React.RefObject<HTMLDivElement | null>
-  /** Timeline zoom factor — content width is zoom × scrollRef.width. Required so
-   *  pixel-to-time conversion matches the visible scale (without this, drag/resize
-   *  is `zoom`× too sensitive when zoomed in). */
-  zoomRef?: React.RefObject<number>
-  draggedFlagRef?: React.MutableRefObject<boolean> // sets true during drag (click suppression)
-}
+/** The floor on an item's timeline duration. At speed S the source window
+ *  floor follows from it (`MIN_DURATION · S`), so only this one is needed.
+ *  Module-local: it constrains the two resize functions below and nothing
+ *  outside this file (`cuts.ts` has a same-valued constant of its own). */
+const MIN_DURATION = 0.1
 
 /** A press must travel at least this many pixels before it becomes a drag.
  *  Below it the gesture stays a click. Without this threshold, a single pixel of
  *  pointer drift during a click flips the drag flag, and the timeline suppresses
  *  click-to-select — so clips/overlays can't be selected (or deleted), which
- *  bites constantly on trackpads and touchscreens where clicks always jitter. */
-const DRAG_THRESHOLD_PX = 4
-
-export function useItemDragDrop(config: UseItemDragDropConfig) {
-  const {
-    totalDuration,
-    snapBoundaries,
-    snapThresholdPx = 8,
-    scrollRef,
-    zoomRef,
-    draggedFlagRef,
-  } = config
-
-  function beginResize(
-    e: React.MouseEvent,
-    item: Draggable,
-    edge: 'start' | 'end',
-    callbacks: {
-      onLivePreview: (ctx: DragEventContext) => void
-      onCommit: () => void
-    },
-  ): void {
-    e.stopPropagation()
-    e.preventDefault()
-
-    const initX = e.clientX
-    const initTime = edge === 'start' ? item.start : item.end
-
-    function computeResized(moveE: MouseEvent): Draggable {
-      if (!scrollRef.current) return item
-      const rect = scrollRef.current.getBoundingClientRect()
-      const contentWidth = rect.width * (zoomRef?.current ?? 1)
-      const dt = ((moveE.clientX - initX) / contentWidth) * totalDuration
-      const raw = Math.max(0, Math.min(totalDuration, initTime + dt))
-
-      // Snap to any boundary within threshold
-      const snapThreshold = (snapThresholdPx / contentWidth) * totalDuration
-      let t = raw
-      let bestDist = snapThreshold
-      for (const b of snapBoundaries) {
-        const d = Math.abs(raw - b)
-        if (d < bestDist) {
-          bestDist = d
-          t = b
-        }
-      }
-
-      if (edge === 'start') {
-        const newStart = Math.min(t, item.end - 0.1)
-        if (item.type !== 'video') return { ...item, start: newStart }
-        const dtActual = newStart - item.start
-        return {
-          ...item,
-          start: newStart,
-          inPoint: Math.min(
-            Math.max(0, (item.inPoint ?? 0) + dtActual),
-            (item.outPoint ?? (item.inPoint ?? 0) + (item.end - item.start)) - 0.1,
-          ),
-        }
-      } else {
-        const newEnd = Math.max(t, item.start + 0.1)
-        if (item.type !== 'video') return { ...item, end: newEnd }
-        const origOut = item.outPoint ?? (item.inPoint ?? 0) + (item.end - item.start)
-        const dtActual = newEnd - item.end
-        return {
-          ...item,
-          end: newEnd,
-          outPoint: Math.max(
-            (item.inPoint ?? 0) + 0.1,
-            Math.min(origOut + dtActual, item.sourceDuration ?? Infinity),
-          ),
-        }
-      }
+ *  bites constantly on trackpads and touchscreens where clicks always jitter.
+ *
+ *  Exported for the canvas pointer machine (SP5 T5), which has the same
+ *  click-vs-drag decision to make and must make it at the same distance. */
+export const DRAG_THRESHOLD_PX = 4
+
+// ── Pure drag/resize math ────────────────────────────────────────────────
+// Extracted from the retired hook's body so the canvas timeline's pointer
+// machine (SP5 T5) reuses the exact trim arithmetic rather than
+// reimplementing it, and so the arithmetic is testable without a component.
+
+/** Nearest boundary within `threshold` seconds of `raw`, else `raw` itself.
+ *  Ties keep the earlier entry — `<` is strict, as in the original loop. */
+export function snapToBoundaries(raw: number, boundaries: readonly number[], threshold: number): number {
+  let t = raw
+  let bestDist = threshold
+  for (const b of boundaries) {
+    const d = Math.abs(raw - b)
+    if (d < bestDist) {
+      bestDist = d
+      t = b
     }
+  }
+  return t
+}
 
-    function onMove(moveE: MouseEvent) {
-      const resized = computeResized(moveE)
-      callbacks.onLivePreview({ item: resized, dx: 0, dy: 0 })
+/** Snap a moving span of length `duration` by either of its edges, nearest
+ *  first. The end edge is tested before the start edge and both share one
+ *  running best distance, so an exact tie is resolved in favour of the START
+ *  edge — preserved verbatim from the hook's original loop. Returns the raw
+ *  span unchanged when nothing is in range; the caller re-clamps. */
+export function snapMovedSpan(
+  rawStart: number,
+  duration: number,
+  boundaries: readonly number[],
+  threshold: number,
+): { start: number; end: number } {
+  const rawEnd = rawStart + duration
+  let start = rawStart
+  let end = rawEnd
+  let bestDist = threshold
+  for (const b of boundaries) {
+    const dEnd = Math.abs(rawEnd - b)
+    if (dEnd < bestDist) {
+      bestDist = dEnd
+      start = b - duration
+      end = b
     }
-    function onUp() {
-      callbacks.onCommit()
-      document.removeEventListener('mousemove', onMove)
-      document.removeEventListener('mouseup', onUp)
+    const dStart = Math.abs(rawStart - b)
+    if (dStart < bestDist) {
+      bestDist = dStart
+      start = b
+      end = b + duration
     }
-    document.addEventListener('mousemove', onMove)
-    document.addEventListener('mouseup', onUp)
   }
+  return { start, end }
+}
 
-  function beginDrag(
-    e: React.MouseEvent,
-    item: Draggable,
-    callbacks: {
-      onLivePreview: (ctx: DragEventContext) => void
-      onCommit: () => void
-    },
-  ): void {
-    e.stopPropagation()
-
-    const initX = e.clientX
-    const initY = e.clientY
-    const initStart = item.start
-    const initEnd = item.end
-    const duration = initEnd - initStart
-    let dragStarted = false
-
-    function onMove(moveE: MouseEvent) {
-      // Ignore sub-threshold pointer drift — it's a click, not a drag. Only once
-      // the press travels past DRAG_THRESHOLD_PX do we set the drag flag (which
-      // suppresses click-to-select) and start moving the item.
-      if (!dragStarted) {
-        const moved = Math.hypot(moveE.clientX - initX, moveE.clientY - initY)
-        if (moved < DRAG_THRESHOLD_PX) return
-        dragStarted = true
-      }
-      if (draggedFlagRef) draggedFlagRef.current = true
-
-      const rect = scrollRef.current?.getBoundingClientRect()
-      const contentWidth = rect ? rect.width * (zoomRef?.current ?? 1) : 0
-      const dx = contentWidth ? ((moveE.clientX - initX) / contentWidth) * totalDuration : 0
-      const dy = moveE.clientY - initY
-
-      const rawStart = Math.max(0, Math.min(totalDuration - duration, initStart + dx))
-      const rawEnd = rawStart + duration
+/** A clip's speed, defended against a project carrying 0, a negative, or a
+ *  non-finite value — every conversion below divides by it. */
+function speedOf(item: Draggable): number {
+  const s = item.speed ?? 1
+  return Number.isFinite(s) && s > 0 ? s : 1
+}
 
-      // Snap leading/trailing edge to nearest item edge within threshold
-      const snapThreshold = contentWidth ? (snapThresholdPx / contentWidth) * totalDuration : 0
-      let newStart = rawStart
-      let newEnd = rawEnd
-      let bestDist = snapThreshold
-      for (const b of snapBoundaries) {
-        const dEnd = Math.abs(rawEnd - b)
-        if (dEnd < bestDist) {
-          bestDist = dEnd
-          newStart = b - duration
-          newEnd = b
-        }
-        const dStart = Math.abs(rawStart - b)
-        if (dStart < bestDist) {
-          bestDist = dStart
-          newStart = b
-          newEnd = b + duration
-        }
-      }
-      newStart = Math.max(0, Math.min(totalDuration - duration, newStart))
-      newEnd = newStart + duration
+function clamp(v: number, lo: number, hi: number): number {
+  // `hi` last, so a degenerate lo > hi keeps the min-duration constraint
+  // rather than inverting the item.
+  return Math.min(Math.max(v, lo), hi)
+}
 
-      const movedItem = { ...item, start: newStart, end: newEnd }
-      callbacks.onLivePreview({ item: movedItem, dx, dy })
-    }
+/**
+ * Move one edge of a source-windowed item to time `t`.
+ *
+ * THE INVARIANT: the timeline span and the source window stay in lockstep —
+ * `outPoint − inPoint === (end − start) · speed` — for every input, always.
+ * That is what lets the frames, the waveform, the preview and the export all
+ * agree about what a clip is showing.
+ *
+ * The way it is kept is the whole point of this function. The timeline edge is
+ * clamped FIRST, against every limit there is (the item's minimum duration and
+ * the media actually available past the window), and the source window is then
+ * DERIVED from how far the edge really travelled. There is exactly one clamp,
+ * on one value.
+ *
+ * The previous version clamped the two independently — `newStart` against
+ * `end − 0.1`, `inPoint` against `[0, outPoint − 0.1]` — and whichever limit
+ * bit first left the other free to keep going. Drag the in edge of a clip that
+ * already starts at the head of its media and `start` slid left while
+ * `inPoint` stayed pinned at 0; drag the out edge of a clip that already runs
+ * to the end of its media and `end` grew while `outPoint` stayed at
+ * `sourceDuration`. Either way the clip ended up claiming more timeline than
+ * it had source for, silently. Downstream, the filmstrip walked off the end of
+ * the media and froze on the last frame it could find while the waveform,
+ * which windows to inPoint..outPoint, drew the real (shorter) window stretched
+ * across the whole clip — two halves of one clip disagreeing, with no error
+ * anywhere. Trimming past the media now simply stops at the media.
+ */
+export function resizeWindowedItem<T extends Draggable>(item: T, edge: 'start' | 'end', t: number): T {
+  const s = speedOf(item)
+  const inPoint = item.inPoint ?? 0
+  const outPoint = item.outPoint ?? inPoint + (item.end - item.start) * s
+
+  // BOTH window bounds come back written out, even the one this edge did not
+  // move. They were implicit before (an end-trim wrote `outPoint` and left
+  // `inPoint` undefined), and an implicit half of the window is what made this
+  // class of bug invisible: you cannot check `outPoint − inPoint === span · S`
+  // against a field that isn't there.
+  if (edge === 'start') {
+    // Leftward travel is limited by the source ahead of `inPoint`: that is
+    // `inPoint` seconds of media, which is `inPoint / s` of timeline.
+    const newStart = clamp(t, item.start - inPoint / s, item.end - MIN_DURATION)
+    return { ...item, start: newStart, inPoint: inPoint + (newStart - item.start) * s, outPoint }
+  }
 
-    function onUp() {
-      document.removeEventListener('mousemove', onMove)
-      document.removeEventListener('mouseup', onUp)
-      if (draggedFlagRef && draggedFlagRef.current) {
-        callbacks.onCommit()
-        // reset after click event fires
-        setTimeout(() => {
-          draggedFlagRef!.current = false
-        }, 0)
-      }
-    }
+  // Rightward travel is limited by the source after `outPoint`. With no
+  // `sourceDuration` there is no known tail, so the edge stays unbounded —
+  // the same benefit of the doubt the old code gave it.
+  const tail = item.sourceDuration == null ? Infinity : item.sourceDuration - outPoint
+  const newEnd = clamp(t, item.start + MIN_DURATION, item.end + tail / s)
+  return { ...item, end: newEnd, inPoint, outPoint: outPoint + (newEnd - item.end) * s }
+}
 
-    document.addEventListener('mousemove', onMove)
-    document.addEventListener('mouseup', onUp)
+/**
+ * Move one edge of an item to time `t`, keeping its source window consistent.
+ *
+ * `t` is expected to be already clamped to the timeline and already snapped —
+ * this function only enforces the item's own invariants. Non-video items
+ * (images, overlays) carry no source window and only move their timeline edge;
+ * video clips go through `resizeWindowedItem`, which holds the span/window
+ * invariant documented there.
+ */
+export function computeResizedItem(item: Draggable, edge: 'start' | 'end', t: number): Draggable {
+  if (item.type !== 'video') {
+    return edge === 'start'
+      ? { ...item, start: Math.min(t, item.end - MIN_DURATION) }
+      : { ...item, end: Math.max(t, item.start + MIN_DURATION) }
   }
-
-  return { beginDrag, beginResize }
+  return resizeWindowedItem(item, edge, t)
 }

package/src/video/timeline/useTimelineZoom.ts

@@ -1,63 +1,28 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useRef } from 'react'
 
-export function useTimelineZoom(totalDuration: number) {
-  const [zoom, setZoom] = useState(1)
-  const zoomRef = useRef(zoom)
-  zoomRef.current = zoom
+/**
+ * The timeline column's horizontal scroll container.
+ *
+ * All this hook has left is the ref. It used to own a whole zoom model: a
+ * `zoom` multiplier, a pivot-preserving `zoomTo` that wrote `scrollLeft` in the
+ * same layout pass as the new width, and a non-passive wheel listener for
+ * ⌘/Ctrl+wheel zoom and Alt+wheel pan. That model existed because the DOM
+ * track rows laid items out as percentages of the whole project, so the only
+ * way to zoom them was to widen their container and scroll over it.
+ *
+ * The canvas surface zooms a px-per-second viewport held in an external store
+ * (`canvas/viewport.ts`) instead, and owns its own wheel handling — it even
+ * `stopPropagation`s the wheel events it consumes, specifically so this
+ * container could not zoom its multiplier off the same gesture. With the rows
+ * gone there is no second zoom model left to drive: the surface always fits
+ * the width it is given, so the container never overflows and its scroll
+ * position is always 0.
+ *
+ * It is kept as a hook (rather than inlined) because the ref is what makes the
+ * container addressable, and a wide child appearing here should scroll rather
+ * than stretch the page.
+ */
+export function useTimelineZoom() {
   const scrollRef = useRef<HTMLDivElement>(null)
-  const pendingScrollRef = useRef<number | null>(null)
-
-  useLayoutEffect(() => {
-    if (pendingScrollRef.current !== null && scrollRef.current) {
-      scrollRef.current.scrollLeft = pendingScrollRef.current
-      pendingScrollRef.current = null
-    }
-  })
-
-  function zoomTo(newZoom: number, pivotClientX?: number) {
-    const clamped = Math.max(1, Math.min(20, newZoom))
-    if (!scrollRef.current || totalDuration === 0) { setZoom(clamped); return }
-    const container = scrollRef.current
-    const containerWidth = container.clientWidth
-    const currentScrollLeft = container.scrollLeft
-    const rect = container.getBoundingClientRect()
-    const pivotOffset = pivotClientX !== undefined
-      ? Math.max(0, Math.min(containerWidth, pivotClientX - rect.left))
-      : containerWidth / 2
-    const pivotPct = Math.max(0, Math.min(1,
-      (currentScrollLeft + pivotOffset) / (containerWidth * zoomRef.current)
-    ))
-    pendingScrollRef.current = Math.max(0, pivotPct * containerWidth * clamped - pivotOffset)
-    setZoom(clamped)
-  }
-
-  // ⌘/Ctrl + wheel = zoom; Alt + wheel = horizontal scroll. Both call
-  // preventDefault, so the listener MUST be non-passive. React's onWheel prop is
-  // registered passive at the root, which makes preventDefault a no-op and spams
-  // "Unable to preventDefault inside passive event listener" — so attach a native
-  // listener with { passive: false } instead. A ref to the latest handler keeps
-  // it current without re-binding on every render.
-  const wheelHandlerRef = useRef<(e: WheelEvent) => void>(() => {})
-  wheelHandlerRef.current = (e: WheelEvent) => {
-    if (e.ctrlKey || e.metaKey) {
-      e.preventDefault()
-      // Multiplicative step so perceived speed is consistent across zoom levels.
-      // deltaY ≈ 100 per mouse-wheel tick → factor ≈ 0.82 (≈ 18% zoom change).
-      const factor = Math.exp(-e.deltaY * 0.002)
-      zoomTo(zoomRef.current * factor, e.clientX)
-    } else if (e.altKey) {
-      e.preventDefault()
-      if (scrollRef.current) scrollRef.current.scrollLeft += e.deltaY
-    }
-  }
-
-  useEffect(() => {
-    const el = scrollRef.current
-    if (!el) return
-    const onWheel = (e: WheelEvent) => wheelHandlerRef.current(e)
-    el.addEventListener('wheel', onWheel, { passive: false })
-    return () => el.removeEventListener('wheel', onWheel)
-  }, [])
-
-  return { zoom, zoomRef, scrollRef, pendingScrollRef, zoomTo }
+  return { scrollRef }
 }

package/src/video/timeline/utils.ts

@@ -3,15 +3,3 @@ export function formatTime(s: number): string {
   const sec = (s % 60).toFixed(1)
   return `${m}:${sec.padStart(4, '0')}`
 }
-
-export function pct(t: number, totalDuration: number): number {
-  return totalDuration > 0 ? (t / totalDuration) * 100 : 0
-}
-
-export function ratioFromClientX(clientX: number, scrubberRect: DOMRect): number {
-  const x = clientX - scrubberRect.left
-  return Math.max(0, Math.min(1, x / scrubberRect.width))
-}
-
-export const trackRow     = 'relative h-10 bg-gray-100 dark:bg-gray-900 rounded overflow-hidden cursor-pointer'
-export const trackRowTall = 'relative h-14 bg-gray-100 dark:bg-gray-900 rounded overflow-hidden cursor-pointer'

package/src/video/use-report-context.ts

@@ -0,0 +1,75 @@
+import { useEffect, useRef } from 'react'
+
+import type { EditorAdapter, EditorContext } from '../types'
+import type { PlaybackClock } from './playback-clock'
+
+/**
+ * How often the playhead is reported during playback.
+ *
+ * The clock is written ~60Hz; reporting every tick would be 60 POSTs/sec for
+ * information no agent can consume that fast. One per second is well inside
+ * serve's CONTEXT_TTL_SEC while costing effectively nothing.
+ *
+ * Note this is an unconditional heartbeat, not change detection: a paused
+ * editor keeps reporting the same playhead once a second, and must. The TTL
+ * governs freshness, so going quiet while parked would make serve answer
+ * "no editor open" about an editor that is plainly open.
+ */
+export const REPORT_INTERVAL_MS = 1000
+
+interface Options {
+  adapter: EditorAdapter
+  projectId: string
+  clock: PlaybackClock
+  selectedIds: string[]
+  selectedCaptionId: string | null
+}
+
+/**
+ * Report playhead + selection to the host on a throttle.
+ *
+ * The throttle is deliberately asymmetric. The PLAYHEAD is sampled on an
+ * interval — it moves continuously and an agent only needs roughly where it
+ * is. SELECTION is reported the moment it changes — it is discrete, it is
+ * usually the more meaningful half of "this section", and waiting up to a
+ * second to report a click would make the agent answer about the previous
+ * selection.
+ */
+export function useReportContext({
+  adapter, projectId, clock, selectedIds, selectedCaptionId,
+}: Options): void {
+  // Kept in a ref so the interval effect never re-subscribes on a selection
+  // change — it always reads the latest values without depending on them.
+  const latest = useRef({ selectedIds, selectedCaptionId })
+  latest.current = { selectedIds, selectedCaptionId }
+
+  const send = useRef<(ctx: EditorContext) => void>(() => {})
+  send.current = (ctx: EditorContext) => {
+    // Fire and forget. A down serve, a 404, an offline host — none of it is
+    // the editor's problem, and none of it reaches the user.
+    void adapter.reportContext?.(projectId, ctx)?.catch(() => {})
+  }
+
+  // Playhead, on an interval. Reports on mount so an agent asked something the
+  // instant the editor opens still gets an answer.
+  useEffect(() => {
+    if (!adapter.reportContext) return
+    const emit = () => send.current({
+      playheadSec:       clock.get(),
+      selectedIds:       latest.current.selectedIds,
+      selectedCaptionId: latest.current.selectedCaptionId,
+    })
+    emit()
+    const id = setInterval(emit, REPORT_INTERVAL_MS)
+    return () => clearInterval(id)
+  }, [adapter, projectId, clock])
+
+  // Selection, immediately on change. Skips the mount emit above by comparing
+  // against what the interval effect already sent.
+  const mounted = useRef(false)
+  useEffect(() => {
+    if (!adapter.reportContext) return
+    if (!mounted.current) { mounted.current = true; return }
+    send.current({ playheadSec: clock.get(), selectedIds, selectedCaptionId })
+  }, [adapter, clock, selectedIds, selectedCaptionId])
+}