@bycrux/editor 0.11.2 → 1.0.1

package/src/video/preview/PreviewPlayer.tsx

@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useRef, useState, type PointerEvent as ReactPointerEvent, type WheelEvent as ReactWheelEvent } from 'react'
+import { useEffect, useMemo, useRef, useState, type MutableRefObject, type PointerEvent as ReactPointerEvent, type WheelEvent as ReactWheelEvent } from 'react'
+import { containsTime } from '@bycrux/timeline-core'
 import { videoTransformContainerStyle, videoTransformBoxPct, type VideoTransform } from './transformStyle'
 import type { EditorProject as Project } from '../../schema'
 import type { OverlayFactory } from '../../types'
@@ -9,12 +10,49 @@ import type { OverlayChanges } from './useDragOverlay'
 import type { CaptionEditPatch } from '../timeline/makeCaptionEdit'
 import OverlayItemsLayer from './OverlayItemsLayer'
 import { useVideoPlayback } from './useVideoPlayback'
+import { useEnginePlayback, type EnginePlayback } from './useEnginePlayback'
+import EngineSurface from './EngineSurface'
+import { evaluateEngineEligibility } from '../../engine/eligibility'
+import type { AcquiredDemux } from '../../engine'
 import { usePlaybackTime, type PlaybackClock } from '../playback-clock'
+import { gateTimeSink, handOverToHover, useHoverScrubTime, type HoverScrub } from '../hover-scrub'
 import { sourceCropVideoStyle } from './sourceCropStyle'
 import CarouselPreview from './CarouselPreview'
+import SocialSafeZoneOverlay, { type SocialPreviewPlatform } from './SocialSafeZoneOverlay'
 
 // ---------------------------------------------------------------------------
 
+/**
+ * SP5 T9 — the transport seam. The ONE cross-component API a host-level
+ * keymap needs to drive play/pause without knowing which playback path
+ * (legacy `<video>` slots or the WebCodecs engine) is actually running.
+ * `PreviewPlayer` fills it from whichever hook is active; see
+ * `PreviewSurface` below.
+ */
+export interface TransportHandle {
+  togglePlay: () => void
+  isPlaying: () => boolean
+  /** The J/K/L shuttle's live transport rate. Engine mode drives the engine's
+   *  own rate (audible fast-forward); the legacy path has no rate knob, so it is
+   *  a no-op there. */
+  setRate: (rate: number) => void
+}
+
+/**
+ * The audible drag-scrub source's (`../../engine/scrub-source.ts`) seam onto
+ * the engine's shared demux LRU — mirrors `TransportHandle`'s shape. Filled
+ * only on the WebCodecs engine path (see the effect beside `transportRef`'s,
+ * below); stays null on the legacy `<video>` fallback, since a fallback
+ * project's clips either lack a `proxySrc` or can't be engine-decoded — this
+ * absence IS the capability gate the scrubber needs.
+ */
+export interface ScrubHandle {
+  acquireDemux: (src: string) => Promise<AcquiredDemux>
+}
+
+/** Stable no-op for the legacy playback path, which has no transport-rate knob. */
+const NO_RATE = (_rate: number) => {}
+
 interface PreviewPlayerProps {
   project: Project
   clock: PlaybackClock
@@ -33,11 +71,195 @@ interface PreviewPlayerProps {
   selectedCaptionId?: string
   onSelectCaption?: (id: string | null) => void
   onCaptionSegmentChange?: (segmentId: string, patch: CaptionEditPatch) => void
+  /**
+   * SP4 — mirrors `VideoEditorProps['engine']` (see `../../types.ts`).
+   * Absent/`{enabled: false}` (default): no effect, the legacy `<video>` slots
+   * render exactly as before — the eligibility probe is never even run.
+   * `{enabled: true}` asks for the WebCodecs engine; whether this project
+   * actually gets it is decided by `useEngineMode` below.
+   */
+  engine?: { enabled: boolean; debugHud?: boolean }
+  /**
+   * SP5 T9 — imperative play/pause handle for a host-level keymap/command
+   * palette. Filled from whichever playback hook is active (legacy or
+   * engine). Absent → no-op; nothing reads or writes it.
+   */
+  transportRef?: MutableRefObject<TransportHandle | null>
+  /**
+   * The audible drag-scrub source's engine seam — mirrors `transportRef`.
+   * Absent → no-op; nothing reads or writes it.
+   */
+  scrubHandleRef?: MutableRefObject<ScrubHandle | null>
+  /**
+   * The preview-axis override: while the pointer is over the timeline with the
+   * axis on, this holds the time under it and the preview paints THAT frame
+   * instead of the playhead's. Null (or the store absent) → the playhead's
+   * frame, which is every other moment and every other host.
+   *
+   * Deliberately not folded into `clock`: the playhead must not follow the
+   * pointer, or the red line and the scrubber handle would chase the mouse and
+   * Space would start playing from wherever it happened to rest. See
+   * `../hover-scrub.ts`.
+   */
+  hoverScrub?: HoverScrub
+  /**
+   * Social-platform preview chrome (mirrors CapCut's "Preview your video for
+   * social media" picker) — see `SocialSafeZoneOverlay`. Absent/falsy/
+   * unrecognized → no-op, same contract as that component's own `platform`
+   * prop, which this passes straight through. Threaded in here (rather than
+   * mounted by the host as a sibling of `PreviewPlayer`) so it lands INSIDE
+   * the same stacking context as the rest of the picture — see the z-index
+   * note at its render site below.
+   */
+  socialPreview?: SocialPreviewPlatform | string | null
+}
+
+export default function PreviewPlayer(props: PreviewPlayerProps) {
+  if (props.project.projectType === 'carousel') {
+    // CarouselPreview renders into normal document flow (no `isolation:
+    // isolate` stacking context of its own — see VideoPreviewPlayer/
+    // PreviewSurface below), so the social-preview overlay composes correctly
+    // as a plain sibling here; it only needs to move INSIDE the video path.
+    return (
+      <>
+        <CarouselPreview project={props.project} />
+        <SocialSafeZoneOverlay platform={props.socialPreview} />
+      </>
+    )
+  }
+  return <VideoPreviewPlayer {...props} />
+}
+
+// ── Which playback path owns this project ────────────────────────────────────
+
+type EngineMode = 'legacy' | 'engine'
+
+/**
+ * Plan decision 2, at its call site.
+ *
+ * Eligibility is evaluated ONCE per project LOAD — re-run only when the project
+ * IDENTITY changes (a different `project.id`), never on an edit. Two
+ * consequences the plan states explicitly and this hook is the enforcement of:
+ *
+ *   - a project that was eligible stays on the engine for the whole session,
+ *     even if a clip added later has no proxy yet (that clip alone shows
+ *     `EngineSurface`'s Preparing placeholder — the engine never hands a
+ *     running project back to the legacy player);
+ *   - a project that was INELIGIBLE stays on the legacy player for the whole
+ *     session, even if its proxies finish encoding a minute later. A reload
+ *     picks up engine mode. The alternative — swapping playback engines under a
+ *     playing editor — is the mode-flapping the decision exists to forbid.
+ *
+ * Returns `null` while the (async) capability probe is still outstanding, which
+ * can only happen with the flag ON: with it off the answer is `'legacy'`
+ * synchronously, on the first render, with no probe and no console line.
+ */
+function useEngineMode(
+  engine: PreviewPlayerProps['engine'],
+  project: Project,
+): EngineMode | null {
+  const enabled = !!engine?.enabled
+  const projectId = project.id
+  const [decision, setDecision] = useState<{ id: string; mode: EngineMode } | null>(null)
+
+  useEffect(() => {
+    if (!enabled) return
+    let cancelled = false
+    void evaluateEngineEligibility(project).then((result) => {
+      if (cancelled) return
+      if (!result.eligible) {
+        // ONE line, with the reason. Not a warning: falling back is the
+        // designed behavior, not a fault.
+        console.info(
+          `[montaj] playback engine unavailable for this project — using the legacy player (${result.reason ?? 'ineligible'})`,
+        )
+      }
+      setDecision({ id: projectId, mode: result.eligible ? 'engine' : 'legacy' })
+    })
+    return () => { cancelled = true }
+  // Deliberately NOT `[project]`: an edit must not re-evaluate. The `project`
+  // captured here is the one loaded under this id, which is what "evaluated
+  // once per project-load" means.
+  }, [enabled, projectId])
+
+  if (!enabled) return 'legacy'
+  if (!decision || decision.id !== projectId) return null
+  return decision.mode
+}
+
+function VideoPreviewPlayer(props: PreviewPlayerProps) {
+  const { project, clock, engine } = props
+  // Subscribe to the playhead store. PreviewPlayer legitimately re-renders per
+  // tick — activeClip/cropStyle memos and the video/overlay/caption children all
+  // depend on the current time.
+  const playheadTime = usePlaybackTime(clock)
+  // Hover-scrub wins while it is set. Everything downstream — the playback
+  // hooks' seeking, the active-clip memo, the overlay and caption layers —
+  // reads this one number, so the previewed frame, the overlays drawn on it and
+  // the highlighted caption all describe the same instant.
+  const hoverTime = useHoverScrubTime(props.hoverScrub)
+  const currentTime = hoverTime ?? playheadTime
+  const mode = useEngineMode(engine, project)
+
+  // See `gateTimeSink` — never hand the hooks `clock.set` directly, or seeking
+  // to show a hovered frame writes that position back and the red playhead
+  // chases the yellow cursor.
+  const hoverScrub = props.hoverScrub
+  const timeSink = useMemo(() => gateTimeSink(clock, hoverScrub), [clock, hoverScrub])
+
+  const [RENDER_W, RENDER_H] = getOverlayDesignCanvas(project.settings?.resolution)
+
+  // Flag on, probe outstanding. Holding the frame for the (sub-frame, cached
+  // after the first project) probe is what keeps the legacy hook from mounting,
+  // loading a <video>, wiring Web Audio and tearing it all down again one tick
+  // later. The two playback hooks are DIFFERENT components on purpose: mounting
+  // one and only one of them is what makes a single hook call per path legal.
+  if (mode === null) {
+    return (
+      <div
+        className="relative bg-black h-full max-w-full overflow-hidden rounded"
+        style={{ aspectRatio: `${RENDER_W} / ${RENDER_H}`, isolation: 'isolate' }}
+      />
+    )
+  }
+
+  return mode === 'engine'
+    ? <EnginePreview {...props} currentTime={currentTime} timeSink={timeSink} />
+    : <LegacyPreview {...props} currentTime={currentTime} timeSink={timeSink} />
 }
 
-export default function PreviewPlayer({
+/**
+ * The two playback paths, discriminated. `PreviewSurface` reads the shared keys
+ * off the union directly and narrows on `mode` for the surface itself; nothing
+ * else in the component tree knows which path is running.
+ */
+type PlaybackBinding =
+  | ({ mode: 'legacy' } & ReturnType<typeof useVideoPlayback>)
+  | ({ mode: 'engine' } & EnginePlayback)
+
+type SurfaceProps = PreviewPlayerProps & {
+  currentTime: number
+  /** `clock.set`, gated on hover-preview — see `timeSink` above. Never pass
+   *  `clock.set` directly here, or hover-seeking writes back into the clock. */
+  timeSink: (t: number) => void
+}
+
+function LegacyPreview(props: SurfaceProps) {
+  const playback = useVideoPlayback(props.project, props.currentTime, props.timeSink, props.fileUrl)
+  return <PreviewSurface {...props} playback={{ mode: 'legacy', ...playback }} />
+}
+
+function EnginePreview(props: SurfaceProps) {
+  const playback = useEnginePlayback(props.project, props.currentTime, props.timeSink, props.fileUrl)
+  return <PreviewSurface {...props} playback={{ mode: 'engine', ...playback }} />
+}
+
+function PreviewSurface({
   project,
   clock,
+  hoverScrub,
+  currentTime,
+  playback,
   selectedOverlayId,
   onOverlayChange,
   onEditOverlay,
@@ -49,16 +271,19 @@ export default function PreviewPlayer({
   selectedCaptionId,
   onSelectCaption,
   onCaptionSegmentChange,
-}: PreviewPlayerProps) {
-  if (project.projectType === 'carousel') return <CarouselPreview project={project} />
-
-  // Subscribe to the playhead store. PreviewPlayer legitimately re-renders per
-  // tick — activeClip/cropStyle memos and the video/overlay/caption children all
-  // depend on the current time.
-  const currentTime = usePlaybackTime(clock)
-
+  engine,
+  transportRef,
+  scrubHandleRef,
+  socialPreview,
+}: SurfaceProps & { playback: PlaybackBinding }) {
   const [RENDER_W, RENDER_H] = getOverlayDesignCanvas(project.settings?.resolution)
 
+  // Play from the yellow line, and bring the red one with it — see
+  // `handOverToHover`. No-op on every ordinary press of play.
+  useEffect(() => {
+    if (playback.isPlaying) handOverToHover(clock, hoverScrub)
+  }, [playback.isPlaying, hoverScrub, clock])
+
   const containerRef = useRef<HTMLDivElement>(null)
   const [renderScale, setRenderScale] = useState<number>(1)
   // Frame pixel size — used to compute the sourceCrop CSS transform that mirrors
@@ -88,22 +313,39 @@ export default function PreviewPlayer({
   } = useDragOverlay(containerRef, onOverlayChange)
 
   const {
-    video0Ref,
-    video1Ref,
-    activeSlotRef,
-    activeSlot,
     showVideo,
     isPlaying,
-    setIsPlaying,
-    handleTimeUpdate,
-    handlePause,
-    handleEnded,
     togglePlay,
     isCanvasProject,
     clips,
     tracks0NonVideo,
     overlayTracks,
-  } = useVideoPlayback(project, currentTime, clock.set, fileUrl)
+  } = playback
+
+  // The transport seam (SP5 T9): fill the host's ref with the ACTIVE path's
+  // togglePlay/isPlaying, identically shaped for both legacy and engine
+  // playback — a host-level keymap never needs to know which one is running.
+  // `isPlaying` is exposed as a getter (not the boolean itself) so a poller
+  // (the J/K/L shuttle) always reads the current value, not a stale closure
+  // from the render that last wrote the ref.
+  // Engine mode carries the real rate knob; the legacy path has none (no-op).
+  const setRate = playback.mode === 'engine' ? playback.setRate : NO_RATE
+  useEffect(() => {
+    if (!transportRef) return
+    transportRef.current = { togglePlay, isPlaying: () => isPlaying, setRate }
+    return () => { transportRef.current = null }
+  }, [transportRef, togglePlay, isPlaying, setRate])
+
+  // The scrub seam: only the engine path can decode a grain, so the legacy
+  // `<video>` fallback simply never fills this — that absence is the audible
+  // drag-scrub's capability gate. `acquireDemux` is a stable-identity callback
+  // (see `useEnginePlayback`), so this effect only re-runs on a mode change.
+  const acquireDemux = playback.mode === 'engine' ? playback.acquireDemux : undefined
+  useEffect(() => {
+    if (!scrubHandleRef || !acquireDemux) return
+    scrubHandleRef.current = { acquireDemux }
+    return () => { scrubHandleRef.current = null }
+  }, [scrubHandleRef, acquireDemux])
 
   const captionTrack = useMemo(() => project.captions, [project])
 
@@ -113,8 +355,19 @@ export default function PreviewPlayer({
   // playhead (same selection the playback hook uses internally). Only the active
   // <video> slot is opaque, so applying the active clip's crop to both slots is
   // safe — the inactive slot is invisible.
+  //
+  // Activation is `containsTime` from @bycrux/timeline-core — the shared
+  // half-open `start <= t < end` predicate, so at an exact cut the LATER clip
+  // wins here exactly as it does in the renderer.
+  //
+  // The `?? clips[clips.length - 1]` tail is deliberately NOT part of the
+  // resolver: `resolveAt` returns an EMPTY Scene inside a gap or past the end of
+  // the timeline. Falling back to the last clip is editor-side PRESENTATION —
+  // it keeps the trailing frame's crop/transform on screen instead of snapping
+  // to an untransformed frame — so it stays local. See the `containsTime` note
+  // in timeline-core/index.d.ts.
   const activeClip = useMemo(
-    () => clips.find(c => currentTime >= c.start && currentTime < c.end) ?? clips[clips.length - 1],
+    () => clips.find(c => containsTime(c.start, c.end, currentTime)) ?? clips[clips.length - 1],
     [clips, currentTime],
   )
   const cropStyle = useMemo(() => {
@@ -211,42 +464,59 @@ export default function PreviewPlayer({
           No clips
         </div>
       ) : (
-        // Transform container — applies the active clip's scale/offset to both
-        // slots (the inactive one is invisible). The frame's overflow-hidden clips
-        // anything pushed outside. Mirrors the renderer's crop→scale→position.
+        // Transform container — applies the active clip's scale/offset to the
+        // picture surface. On the legacy path that surface is the two <video>
+        // slots (the inactive one is invisible); on the engine path it is one
+        // canvas. The div itself, its styles and its z-order are IDENTICAL for
+        // both — the frame's overflow-hidden clips anything pushed outside, and
+        // the whole thing mirrors the renderer's crop→scale→position.
         <div className="absolute inset-0" style={transformContainerStyle}>
-          {/* Slot 0 */}
-          <video
-            ref={video0Ref}
-            // Clips load cross-origin from R2; without this the media is CORS-tainted
-            // and the Web Audio createMediaElementSource graph outputs silence. R2
-            // sends Access-Control-Allow-Origin, so anonymous CORS keeps it audible.
-            crossOrigin="anonymous"
-            // Fetch enough to render the seeked poster frame on load (before play).
-            preload="auto"
-            onLoadedMetadata={(e) => { const v = e.currentTarget; if (v.videoWidth && v.videoHeight) setVideoDims({ w: v.videoWidth, h: v.videoHeight }) }}
-            onTimeUpdate={() => { if (activeSlotRef.current === 0) handleTimeUpdate() }}
-            onEnded={() => { if (activeSlotRef.current === 0) handleEnded() }}
-            onPlay={() => { if (activeSlotRef.current === 0) setIsPlaying(true) }}
-            onPause={() => { if (activeSlotRef.current === 0) handlePause() }}
-            playsInline
-            style={{ ...baseVideoStyle, opacity: showVideo && activeSlot === 0 ? 1 : 0, pointerEvents: activeSlot === 0 ? 'auto' : 'none', zIndex: activeSlot === 0 ? 1 : 0 }}
-          />
-          {/* Slot 1 */}
-          <video
-            ref={video1Ref}
-            // See slot 0: anonymous CORS so R2 cross-origin clips aren't tainted
-            // (which would mute the Web Audio graph).
-            crossOrigin="anonymous"
-            preload="auto"
-            onLoadedMetadata={(e) => { const v = e.currentTarget; if (v.videoWidth && v.videoHeight) setVideoDims({ w: v.videoWidth, h: v.videoHeight }) }}
-            onTimeUpdate={() => { if (activeSlotRef.current === 1) handleTimeUpdate() }}
-            onEnded={() => { if (activeSlotRef.current === 1) handleEnded() }}
-            onPlay={() => { if (activeSlotRef.current === 1) setIsPlaying(true) }}
-            onPause={() => { if (activeSlotRef.current === 1) handlePause() }}
-            playsInline
-            style={{ ...baseVideoStyle, opacity: showVideo && activeSlot === 1 ? 1 : 0, pointerEvents: activeSlot === 1 ? 'auto' : 'none', zIndex: activeSlot === 1 ? 1 : 0 }}
-          />
+          {playback.mode === 'engine' ? (
+            <EngineSurface
+              attach={playback.attachCanvas}
+              picture={playback.status.picture}
+              reason={playback.status.reason}
+              debugHud={engine?.debugHud}
+              getStats={playback.getStats}
+            />
+          ) : (
+            <>
+              {/* Slot 0 */}
+              <video
+                ref={playback.video0Ref}
+                // Clips load cross-origin from R2; without this the media is CORS-tainted
+                // and the Web Audio createMediaElementSource graph outputs silence. R2
+                // sends Access-Control-Allow-Origin, so anonymous CORS keeps it audible.
+                crossOrigin="anonymous"
+                // Fetch enough to render the seeked poster frame on load (before play).
+                preload="auto"
+                onLoadedMetadata={(e) => { const v = e.currentTarget; if (v.videoWidth && v.videoHeight) setVideoDims({ w: v.videoWidth, h: v.videoHeight }) }}
+                onTimeUpdate={() => { if (playback.activeSlotRef.current === 0) playback.handleTimeUpdate() }}
+                onEnded={() => { if (playback.activeSlotRef.current === 0) playback.handleEnded() }}
+                onError={() => playback.handleVideoError(0)}
+                onPlay={() => { if (playback.activeSlotRef.current === 0) playback.setIsPlaying(true) }}
+                onPause={() => { if (playback.activeSlotRef.current === 0) playback.handlePause() }}
+                playsInline
+                style={{ ...baseVideoStyle, opacity: showVideo && playback.activeSlot === 0 ? 1 : 0, pointerEvents: playback.activeSlot === 0 ? 'auto' : 'none', zIndex: playback.activeSlot === 0 ? 1 : 0 }}
+              />
+              {/* Slot 1 */}
+              <video
+                ref={playback.video1Ref}
+                // See slot 0: anonymous CORS so R2 cross-origin clips aren't tainted
+                // (which would mute the Web Audio graph).
+                crossOrigin="anonymous"
+                preload="auto"
+                onLoadedMetadata={(e) => { const v = e.currentTarget; if (v.videoWidth && v.videoHeight) setVideoDims({ w: v.videoWidth, h: v.videoHeight }) }}
+                onTimeUpdate={() => { if (playback.activeSlotRef.current === 1) playback.handleTimeUpdate() }}
+                onEnded={() => { if (playback.activeSlotRef.current === 1) playback.handleEnded() }}
+                onError={() => playback.handleVideoError(1)}
+                onPlay={() => { if (playback.activeSlotRef.current === 1) playback.setIsPlaying(true) }}
+                onPause={() => { if (playback.activeSlotRef.current === 1) playback.handlePause() }}
+                playsInline
+                style={{ ...baseVideoStyle, opacity: showVideo && playback.activeSlot === 1 ? 1 : 0, pointerEvents: playback.activeSlot === 1 ? 'auto' : 'none', zIndex: playback.activeSlot === 1 ? 1 : 0 }}
+              />
+            </>
+          )}
         </div>
       )}
 
@@ -334,7 +604,7 @@ export default function PreviewPlayer({
         fileUrl={fileUrl}
       />
 
-      {/* Audio elements are managed programmatically in useVideoPlayback */}
+      {/* Audio elements are managed programmatically in the playback hook */}
 
       {/* Caption preview */}
       {captionTrack && (
@@ -349,6 +619,17 @@ export default function PreviewPlayer({
           onCaptionSegmentChange={onCaptionSegmentChange}
         />
       )}
+
+      {/* Social-preview chrome — see `SocialSafeZoneOverlay` and the
+          `socialPreview` prop doc above. Rendered HERE, inside this same
+          `isolation: isolate` container as the video/overlays/captions above
+          and the play glyph below, so its z-index (48) is compared directly
+          against theirs rather than being evaluated one stacking context up
+          (where a positive z-index sibling of an isolated box paints over
+          the ENTIRE box, glyph included, regardless of that box's own
+          internal ordering). No-ops on an absent/unrecognized platform, so
+          this is unconditional. */}
+      <SocialSafeZoneOverlay platform={socialPreview} />
     </div>
   )
 }