@bycrux/editor 1.0.1 → 1.1.0

package/src/video/__tests__/VideoEditor.test.tsx

@@ -12,6 +12,8 @@ import type {
 import type { Captions, VisualItem } from '../../schema'
 import type { OverlayChanges } from '../preview/useDragOverlay'
 import VideoEditor from '../VideoEditor'
+import { CROSSFADE_COMMIT_DELAY_MS } from '../timeline/Timeline'
+import { trackItems } from '../timeline/timeline-model'
 import { dragCanvasItem, installCanvasHarness, selectCanvasItem } from '../timeline/__tests__/_canvasSelect'
 
 // ── Fake adapter ──────────────────────────────────────────────────────────────
@@ -839,4 +841,171 @@ describe('VideoEditor — editor-package integration', () => {
 
     expect(queryByText('Compare')).toBeNull()
   })
+
+  // ── Derived OVERLAY crossfades: the wiring, not the function ─────────────
+  //
+  // `computeVisualCrossfade` (timeline-model.ts, unit-tested in
+  // timeline/__tests__/timeline-model.test.ts) ships INERT without two call
+  // sites, exactly as `computeAutoCrossfade` needs two: the gesture commit
+  // (`commitTimelineEdit` here in VideoEditor) and Timeline.tsx's debounced
+  // catch-all for overlay timing that changes without a gesture. One test each.
+  //
+  // Both assert on the ADAPTER's saveProject payload rather than on local
+  // `onProjectChange` state, for the reason
+  // VideoEditor.rippleDeleteCaptions.test.tsx records in full: only a real
+  // commit reaches `saveProject`, so an assertion on client state can pass on
+  // a transient preview that was never persisted.
+
+  /** The `opacity` keyframe track on `itemId` in a saved project, wherever the
+   *  item lives. `undefined` when the item carries no opacity curve at all. */
+  function opacityTrackOf(project: Project, itemId: string) {
+    for (const items of trackItems(project)) {
+      const item = items.find((i) => i.id === itemId)
+      if (item) return item.keyframes?.find((k) => k.prop === 'opacity')
+    }
+    return undefined
+  }
+
+  /** The item itself, for the span assertions. */
+  function itemOf(project: Project, itemId: string): VisualItem | undefined {
+    for (const items of trackItems(project)) {
+      const item = items.find((i) => i.id === itemId)
+      if (item) return item
+    }
+    return undefined
+  }
+
+  it('a trim that creates an overlay overlap commits the fade in ONE undo step', async () => {
+    onTestFinished(installCanvasHarness())
+    // Fake timers, never advanced: Timeline.tsx's debounced catch-all cannot
+    // fire, so a fade in the saved project can ONLY have come from the gesture
+    // commit. Without this the two call sites are indistinguishable.
+    vi.useFakeTimers()
+    onTestFinished(() => { vi.useRealTimers() })
+
+    const adapter = makeFakeAdapter()
+    // The overlays start APART — the gesture is what creates the overlap.
+    const initial = makeVideoProject({
+      tracks: [
+        {
+          id: 'trk-0',
+          items: [
+            { id: 'clip-0', type: 'video', src: 'a.mp4', start: 0, end: 10, inPoint: 0, outPoint: 10, sourceDuration: 40 },
+          ],
+        },
+        {
+          id: 'trk-1',
+          items: [
+            { id: 'ov-a', type: 'overlay', src: 'A.jsx', start: 0, end: 4 },
+            { id: 'ov-b', type: 'overlay', src: 'B.jsx', start: 5, end: 9 },
+          ],
+        },
+      ],
+    })
+    const { container } = render(
+      <VideoEditor project={initial} adapter={adapter} slots={{ exportActions: <div /> }} />,
+    )
+    await act(async () => { await Promise.resolve() })
+
+    // Drag ov-a's OUT edge from t=4 to t=6, so it runs 1s into ov-b. A trim on
+    // a non-zero track is allowed past a neighbour's near boundary (a partial
+    // overlap is a transition) but not past its far one.
+    dragCanvasItem(container, initial, { id: 'ov-a' }, { fromTime: 4, toTime: 6 })
+    await act(async () => { await Promise.resolve() })
+
+    expect(adapter.saveCalls.length).toBe(1)
+    const trimmed = adapter.saveCalls[0].project
+    expect(itemOf(trimmed, 'ov-a')!.end).toBeCloseTo(6, 5)
+
+    // ov-a fades 1 -> 0 across the overlap, in ITS OWN item-relative seconds.
+    const fadeOut = opacityTrackOf(trimmed, 'ov-a')!
+    expect(fadeOut.origin).toBe('crossfade')
+    expect(fadeOut.points.length).toBe(2)
+    expect(fadeOut.points[0]).toEqual({ t: 5, value: 1 })
+    expect(fadeOut.points[1].value).toBe(0)
+    expect(fadeOut.points[1].t).toBeCloseTo(6, 5)
+
+    // ov-b fades 0 -> 1 across the same span, measured from ITS start (t=5).
+    const fadeIn = opacityTrackOf(trimmed, 'ov-b')!
+    expect(fadeIn.origin).toBe('crossfade')
+    expect(fadeIn.points[0]).toEqual({ t: 0, value: 0 })
+    expect(fadeIn.points[1].value).toBe(1)
+    expect(fadeIn.points[1].t).toBeCloseTo(1, 5)
+
+    // ONE undo takes back the trim AND its derived fade together. The audio
+    // version of this bug recorded dozens of entries for a single drag; a
+    // second undo being needed here, or either curve surviving the first, is
+    // the regression.
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'z', metaKey: true }))
+    })
+    expect(adapter.saveCalls.length).toBe(2)
+    const undone = adapter.saveCalls[1].project
+    expect(itemOf(undone, 'ov-a')!.end).toBe(4)
+    expect(opacityTrackOf(undone, 'ov-a')).toBeUndefined()
+    expect(opacityTrackOf(undone, 'ov-b')).toBeUndefined()
+  })
+
+  it('a ripple-delete that creates an overlay overlap commits a fade without a gesture', async () => {
+    onTestFinished(installCanvasHarness())
+    vi.useFakeTimers()
+    onTestFinished(() => { vi.useRealTimers() })
+
+    const adapter = makeFakeAdapter()
+    // Shift+Delete on clip-A (0-2s) shifts everything starting at or after 2s
+    // left by 2s — across EVERY track. ov-b travels 4->2 while ov-a stays at
+    // 0-4, so the two overlap by 2s without any pointer ever touching them.
+    const initial = makeVideoProject({
+      tracks: [
+        {
+          id: 'trk-0',
+          items: [
+            { id: 'clip-A', type: 'video', src: 'a.mp4', start: 0, end: 2, inPoint: 0, outPoint: 2 },
+            { id: 'clip-B', type: 'video', src: 'a.mp4', start: 2, end: 6, inPoint: 2, outPoint: 6 },
+          ],
+        },
+        {
+          id: 'trk-1',
+          items: [
+            { id: 'ov-a', type: 'overlay', src: 'A.jsx', start: 0, end: 4 },
+            { id: 'ov-b', type: 'overlay', src: 'B.jsx', start: 4, end: 8 },
+          ],
+        },
+      ],
+    })
+    const { container } = render(
+      <VideoEditor project={initial} adapter={adapter} slots={{ exportActions: <div /> }} />,
+    )
+    await act(async () => { await Promise.resolve() })
+
+    selectCanvasItem(container, initial, { id: 'clip-A' })
+    await act(async () => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Delete', shiftKey: true }))
+    })
+
+    // `handleRippleDelete` goes straight to `sync.mutate` — it never passes
+    // through `commitTimelineEdit`, so its own commit carries no fade. That is
+    // precisely the hole the debounced pass fills.
+    expect(adapter.saveCalls.length).toBe(1)
+    const rippled = adapter.saveCalls[0].project
+    expect(itemOf(rippled, 'ov-b')!.start).toBe(2)
+    expect(opacityTrackOf(rippled, 'ov-a')).toBeUndefined()
+    expect(opacityTrackOf(rippled, 'ov-b')).toBeUndefined()
+
+    await act(async () => { vi.advanceTimersByTime(CROSSFADE_COMMIT_DELAY_MS) })
+
+    expect(adapter.saveCalls.length).toBe(2)
+    const faded = adapter.saveCalls[1].project
+    expect(opacityTrackOf(faded, 'ov-a')!.points).toEqual([
+      { t: 2, value: 1 }, { t: 4, value: 0 },
+    ])
+    expect(opacityTrackOf(faded, 'ov-b')!.points).toEqual([
+      { t: 0, value: 0 }, { t: 2, value: 1 },
+    ])
+
+    // Idempotent: the pass re-runs off its own commit and must find nothing,
+    // or it would commit forever.
+    await act(async () => { vi.advanceTimersByTime(CROSSFADE_COMMIT_DELAY_MS * 4) })
+    expect(adapter.saveCalls.length).toBe(2)
+  })
 })

package/src/video/captionStyleDefaults.ts

@@ -22,7 +22,7 @@
  *   highlight-box.jsx, outline.jsx
  * (all under montaj_assets/render/templates/captions/).
  */
-import type { Captions } from '../schema'
+import type { Captions, CaptionTextTransform } from '../schema'
 
 type Style = Captions['style']
 
@@ -95,6 +95,6 @@ export const CAPTION_STYLE_TEXT_ALIGN: Record<Style, string> = {
  *  `renderSegment` call site); the no-timestamps fallback branch renders the
  *  segment text as-is, never uppercased. Every other style has no default in
  *  any branch. */
-export const CAPTION_STYLE_TEXT_TRANSFORM: Partial<Record<Style, string>> = {
+export const CAPTION_STYLE_TEXT_TRANSFORM: Partial<Record<Style, CaptionTextTransform>> = {
   outline: 'uppercase',
 }

package/src/video/preview/OverlayItemsLayer.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react'
-import { containsTime, geometryAt, geometryFor } from '@bycrux/timeline-core'
+import { containsTime, geometryAt, geometryFor, resolveAt } from '@bycrux/timeline-core'
 import { isProxyUsable, markProxyFailed } from './proxySupport'
 import type { EditorProject as Project, VisualItem } from '../../schema'
 import type { OverlayFactory } from '../../types'
@@ -8,7 +8,7 @@ import { getOverlayDesignCanvas } from '../design-canvas'
 import { ensureGoogleFontsLoaded } from '../../lib/google-fonts'
 import type { Corner, Edge, OverlayChanges } from './useDragOverlay'
 import type { useDragOverlay } from './useDragOverlay'
-import { enabledTrackItems } from '../timeline/timeline-model'
+import { enabledTrackItems, withEnabledItemTracks } from '../timeline/timeline-model'
 
 // Mount video items this many seconds before item.start so the frame is ready.
 //
@@ -421,6 +421,62 @@ export default function OverlayItemsLayer({
   // Enabled only: a skipped track must not be draggable in the preview either.
   const interactiveTracks = isCanvasProject ? enabledTrackItems(project) : overlayTracks
 
+  // Split from the `scene` memo below ON PURPOSE. `withEnabledItemTracks`
+  // spreads the project and re-runs `normalizeTracks` plus a `.map()` over every
+  // track — work that depends on `project` alone. Folded into one memo keyed
+  // `[project, currentTime]` it re-ran on EVERY frame of playback, rebuilding an
+  // identical track array 30-60 times a second. Keyed on `project` it runs once
+  // per edit, and only the genuinely time-dependent `resolveAt` runs per frame.
+  const previewProject = useMemo(() => withEnabledItemTracks(project), [project])
+
+  // The resolver's Scene at this instant — the SAME `resolveAt` call the canvas
+  // engine's `previewResolver` makes (engine/scheduler.ts), so this layer and
+  // the engine read the identical `crossfade` stamp for a clip that happens to
+  // sit on an overlay track. `ResolvedItem.item` is the project's own object by
+  // reference (timeline-core's contract), so the blocks below look their
+  // resolved counterparts up by identity rather than recomputing anything.
+  const scene = useMemo(
+    () => resolveAt(previewProject, currentTime, { variant: 'preview' }),
+    [previewProject, currentTime],
+  )
+
+  // The transition weight for ONE clip at this instant, shared by BOTH render
+  // blocks below — the tracks[0] images and the interactive tracks. Both are
+  // fed by `enabledTrackItems(project)` (`useVideoPlayback.ts` / this file's own
+  // `previewProject`), so the identity lookup resolves in either.
+  //
+  // ONLY THE INCOMING SIDE RAMPS. The outgoing side keeps its own full opacity —
+  // factor 1, not `1-p` — and that is not a shortcut, it is what this kind of
+  // compositor requires:
+  //
+  //   - The EXPORT is a SPLIT-AND-LERP compositor: `encode-segment.js` splits
+  //     the canvas, composites each side down its own branch at its OWN full
+  //     opacity, then lerps the two finished frames with
+  //     `blend=all_expr='A+(B-A)*p'` — `(1-p)*from + p*to`.
+  //   - THIS layer is a SEQUENTIAL source-over compositor: each item is a DOM
+  //     node painted over the ones before it. Leaving `from` at 1 and giving
+  //     `to` alpha p produces exactly `p*to + (1-p)*from` — the same lerp,
+  //     reached by a different route.
+  //
+  // Feeding the symmetric `1-p` / `p` pair into a sequential stack does NOT
+  // reproduce the lerp; it yields `p*to + (1-p)^2*from + p(1-p)*bg`, which at
+  // p=0.5 shows the outgoing clip at QUARTER weight and lets the background leak
+  // through the middle of every transition.
+  //
+  // `createCanvasPainter.paintBlend` (engine/index.ts) is the shared reference
+  // for the sequential form: `globalAlpha = 1` for `from`, then `globalAlpha = p`
+  // for `to`. `render/sample-frame.js` — also sequential — carries the same
+  // factor. Do not "restore" the symmetric form; it is the obvious-looking wrong
+  // answer for this compositor.
+  //
+  // `crossfade` is CLIPS-ONLY and null outside an overlap
+  // (@bycrux/timeline-core's `crossfadesAt`), so this returns 1 — a no-op —
+  // everywhere a transition is not actually in play.
+  const crossfadeFactor = (item: VisualItem) => {
+    const xf = scene.items.find((r) => r.item === item)?.crossfade ?? null
+    return xf?.role === 'to' ? xf.p : 1
+  }
+
   return (
     <>
       {/* tracks[0] non-video items (background images) — rendered with drag support at base z-level */}
@@ -438,9 +494,20 @@ export default function OverlayItemsLayer({
         // buildImageItemFilterParts, which since SP9d compiles their curves into
         // ffmpeg expressions. Leaving this branch on the static resolve would
         // put back a preview/render divergence in the one place nobody would
-        // look for it. Opacity stays static here too — ffmpeg cannot vary it.
+        // look for it. The opacity CURVE stays ignored here too — ffmpeg cannot
+        // vary clip alpha.
+        //
+        // A TRANSITION is the one thing that does move this opacity, and these
+        // items need it as much as the interactive block below does:
+        // `crossfadesAt` stamps IMAGE clips exactly like video ones, and the
+        // export blends a track[0] image pair through the same
+        // `encode-segment.js` `blend` branch. The canvas engine skips them
+        // (`scheduler.ts` filters its scan to `trackIdx === 0 && kind ===
+        // 'video'`), so this block is the ONLY thing drawing them in non-canvas
+        // mode — leave it static and the preview hard-cuts a pair the export
+        // dissolves. Same shared factor, same reasoning: see `crossfadeFactor`.
         const gAnimated = geometryAt(item, 'image', currentTime - item.start)
-        const g        = { ...gAnimated, opacity: geometryFor(item, 'image').opacity }
+        const g        = { ...gAnimated, opacity: geometryFor(item, 'image').opacity * crossfadeFactor(item) }
         const fit      = g.fit ?? 'cover'
         const offsetX  = (liveOffset?.id   === item.id ? liveOffset.x       : null) ?? g.offsetX
         const offsetY  = (liveOffset?.id   === item.id ? liveOffset.y       : null) ?? g.offsetY
@@ -542,9 +609,21 @@ export default function OverlayItemsLayer({
           // unaffected — they are baked per frame in a browser, where opacity is
           // just another CSS value.
           const animated = geometryAt(item, item.type, currentTime - item.start)
-          const g        = item.type === 'overlay'
+          // SP9d's pin STANDS: a clip's opacity CURVE is still ignored here,
+          // because ffmpeg cannot animate clip alpha and preview must not
+          // promise a fade the export cannot produce.
+          //
+          // A TRANSITION is different, and is not an exception to that rule but
+          // an application of it: the export really does blend a transitioning
+          // pair (`encode-segment.js`'s `blend` branch), so showing the blend
+          // here is what keeps preview honest. The factor comes from the shared
+          // resolver via `crossfadeFactor` above — read its note for WHY only
+          // the incoming side ramps while the outgoing side stays at 1. That is
+          // the compositing model, not an oversight.
+          const factor = crossfadeFactor(item)
+          const g      = item.type === 'overlay'
             ? animated
-            : { ...animated, opacity: geometryFor(item, item.type).opacity }
+            : { ...animated, opacity: geometryFor(item, item.type).opacity * factor }
           const fit      = g.fit ?? 'cover'
           const offsetX  = (liveOffset?.id   === item.id ? liveOffset.x       : null) ?? g.offsetX
           const offsetY  = (liveOffset?.id   === item.id ? liveOffset.y       : null) ?? g.offsetY

package/src/video/preview/PreviewPlayer.tsx

@@ -12,7 +12,7 @@ import OverlayItemsLayer from './OverlayItemsLayer'
 import { useVideoPlayback } from './useVideoPlayback'
 import { useEnginePlayback, type EnginePlayback } from './useEnginePlayback'
 import EngineSurface from './EngineSurface'
-import { evaluateEngineEligibility } from '../../engine/eligibility'
+import { evaluateEngineEligibility, engineRequiredReason } from '../../engine/eligibility'
 import type { AcquiredDemux } from '../../engine'
 import { usePlaybackTime, type PlaybackClock } from '../playback-clock'
 import { gateTimeSink, handOverToHover, useHoverScrubTime, type HoverScrub } from '../hover-scrub'
@@ -630,6 +630,33 @@ function PreviewSurface({
           internal ordering). No-ops on an absent/unrecognized platform, so
           this is unconditional. */}
       <SocialSafeZoneOverlay platform={socialPreview} />
+
+      {/* Task 10b — legacy has no compositing stage (one <video> element per
+          clip), so it cannot blend a clip crossfade the way render does. v4's
+          rule is against a preview that SILENTLY disagrees with the export;
+          a visible, persistent notice satisfies that without blocking
+          preview outright, which would make a whole project un-previewable
+          over one transition (and would make every background-removed
+          project, legacy-only in v1, never previewable at all — see
+          `engineRequiredReason`'s doc in eligibility.ts).
+
+          Deliberately NOT folded into `useEngineMode`/`mode` above: that hook
+          evaluates once per project LOAD, on purpose, so the PLAYER never
+          remounts mid-edit (the anti-flapping rule — see its comment). This
+          check is the opposite by design: cheap, synchronous, recomputed on
+          every render, so the banner appears the instant an operator drags
+          two clips into overlap and disappears the instant they pull them
+          apart, without ever touching which player is mounted. */}
+      {playback.mode === 'legacy' && engineRequiredReason(project) !== null && (
+        <div
+          className="montaj-legacy-crossfade-banner absolute inset-x-0 bottom-0 flex justify-center pointer-events-none"
+          style={{ zIndex: 90 }}
+        >
+          <div className="mb-2 rounded bg-black/70 px-3 py-1.5 text-center text-xs text-white/90">
+            Crossfades will not appear in this preview. They will render in the export.
+          </div>
+        </div>
+      )}
     </div>
   )
 }

package/src/video/preview/__tests__/OverlayItemsLayer.keyframes.test.tsx

@@ -361,3 +361,94 @@ describe('OverlayItemsLayer — per-axis scale', () => {
     expect(nw.style.transform).toBe('scale(0.5, 0.5) translate(-50%, -50%)')
   })
 })
+
+// ---------------------------------------------------------------------------
+// Layered-clip transition blend (Task 11). SP9d's pin — a clip's opacity
+// CURVE is ignored in this layer — still holds; it is not what this section
+// tests. What's new is the resolver's `crossfade` stamp: two clips on the
+// SAME overlay track that overlap now blend, because the export genuinely
+// blends that pair (encode-segment.js's `blend` branch, SP9d/T8). Showing the
+// same blend here is an application of the SP9d rule, not an exception to it.
+//
+// Unlike `renderLayer` above (which renders its item from the `overlayTracks`
+// prop while `project.tracks` stays empty), these tests need `project.tracks`
+// itself to carry the items: the component looks its resolved crossfade stamp
+// up via `resolveAt(project, ...)`, matched back to the rendered item BY
+// REFERENCE — so the fixture's `project.tracks` and its `overlayTracks` prop
+// must share the exact same item objects.
+// ---------------------------------------------------------------------------
+
+function renderLayeredClips(overlayItems: VisualItem[], currentTime: number) {
+  const project = {
+    id: 'p',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [[], overlayItems],
+  } as unknown as EditorProject
+
+  const utils = render(
+    <OverlayItemsLayer
+      project={project}
+      currentTime={currentTime}
+      isPlaying={false}
+      isCanvasProject={false}
+      overlayTracks={[overlayItems]}
+      tracks0NonVideo={[]}
+      renderScale={0.2}
+      selectedOverlayId={undefined}
+      containerRef={{ current: document.createElement('div') }}
+      dragState={null}
+      setDragState={vi.fn()}
+      liveOffset={null}
+      liveScale={null}
+      liveRotation={null}
+      snapGuides={emptySnap}
+      snapRotation={null}
+      compileOverlay={vi.fn(async (): Promise<OverlayFactory> => () => null)}
+      fileUrl={(pth: string) => pth}
+    />,
+  )
+  // Each clip's <img> sits directly inside its own wrapper div — the wrapper
+  // is where `opacity` actually lands (OverlayItemsLayer.tsx's `wrapperStyle`).
+  const styleOf = (src: string) =>
+    (utils.container.querySelector(`img[src="${src}"]`) as HTMLElement).parentElement!.style
+  return { ...utils, styleOf }
+}
+
+describe('OverlayItemsLayer — layered clip transition blend (Task 11)', () => {
+  it('a layered clip mid-transition renders at its blended opacity', () => {
+    // a: [0,4), b: [3,7) — overlap [3,4). At t=3.5 the pair is exactly
+    // half-through: p=0.5.
+    //
+    // ONLY THE INCOMING SIDE RAMPS. `a` (role 'from') stays at 1 and `b` (role
+    // 'to') gets 0.5, because this layer stacks DOM nodes with source-over: `b`
+    // at alpha 0.5 over an opaque `a` composites to `0.5*b + 0.5*a`, which is
+    // exactly the lerp `encode-segment.js` emits as `blend=all_expr='A+(B-A)*p'`.
+    //
+    // The old expectation was '0.5' / '0.5', and it was WRONG: symmetric factors
+    // in a sequential stack give `p*b + (1-p)^2*a + p(1-p)*bg` — `a` at quarter
+    // weight with the background leaking through mid-transition. It passed only
+    // because it was written against the same mistaken model as the code.
+    // `createCanvasPainter.paintBlend` (engine/index.ts) is the reference.
+    const a = { id: 'a', type: 'image', src: 'a.png', start: 0, end: 4 } as VisualItem
+    const b = { id: 'b', type: 'image', src: 'b.png', start: 3, end: 7 } as VisualItem
+    const { styleOf } = renderLayeredClips([a, b], 3.5)
+
+    expect(styleOf('a.png').opacity).toBe('1')
+    expect(styleOf('b.png').opacity).toBe('0.5')
+  })
+
+  it('a layered clip outside a transition still reads its STATIC opacity', () => {
+    // A lone clip on its track has no partner to pair with, so the resolver
+    // stamps `crossfade: null` — this is the SP9d regression guard: the
+    // opacity keyframe curve must stay ignored, and the wrapper must show the
+    // STATIC `opacity` field (0.4), not a sampled curve value.
+    const item = {
+      id: 'a', type: 'image', src: 'a.png', start: 0, end: 10, opacity: 0.4,
+      keyframes: [{ prop: 'opacity', points: [{ t: 0, value: 0 }, { t: 10, value: 1 }] }],
+    } as VisualItem
+    const { styleOf } = renderLayeredClips([item], 1)
+
+    expect(styleOf('a.png').opacity).toBe('0.4')
+  })
+})

package/src/video/preview/__tests__/PreviewPlayer.engine.test.tsx

@@ -15,7 +15,7 @@
  * here is which surface mounts, not what it paints.
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { render, waitFor } from '@testing-library/react'
+import { render, screen, waitFor } from '@testing-library/react'
 import PreviewPlayer from '../PreviewPlayer'
 import { createPlaybackClock } from '../../playback-clock'
 import { __setEngineCapabilityForTests } from '../../../engine/eligibility'
@@ -48,6 +48,27 @@ function makeProject(clipOverrides: Record<string, unknown> = {}): Project {
   } as unknown as Project
 }
 
+/**
+ * Two overlapping track-0 video clips — c1 starts (3) before c0 ends (5) and
+ * does not contain it, a real `transitionPairs()` pair per
+ * `engineRequiredReason`'s test in eligibility.test.ts. `withProxy` controls
+ * whether the pair is also engine-shape-eligible, so the same fixture serves
+ * both the "still building proxies" legacy case and the "engine running"
+ * case.
+ */
+function makeCrossfadeProject(withProxy: boolean): Project {
+  const proxy = withProxy ? { proxySrc: 'proxy.mp4' } : {}
+  return {
+    id: withProxy ? 'p-crossfade-proxy' : 'p-crossfade-no-proxy',
+    status: 'draft',
+    settings: { resolution: [1080, 1920], fps: 30 },
+    tracks: [[
+      { id: 'c0', type: 'video', src: 'a.mp4', start: 0, end: 5, ...proxy },
+      { id: 'c1', type: 'video', src: 'b.mp4', start: 3, end: 8, ...proxy },
+    ]],
+  } as unknown as Project
+}
+
 function renderPreview(project: Project, engine?: { enabled: boolean }) {
   return render(
     <PreviewPlayer
@@ -137,3 +158,30 @@ describe('PreviewPlayer engine branch', () => {
     expect(root.querySelectorAll('svg')).toHaveLength(1)
   })
 })
+
+describe('PreviewPlayer legacy crossfade banner (Task 10b)', () => {
+  it('warns that crossfades are missing when a crossfading project falls back to legacy', async () => {
+    // No proxySrc => shape-ineligible => legacy player, which cannot blend.
+    renderPreview(makeCrossfadeProject(false))
+    await screen.findByText(/crossfades will not appear/i)
+  })
+
+  it('shows no such warning when the engine is running', async () => {
+    __setEngineCapabilityForTests(true)
+    renderPreview(makeCrossfadeProject(true), { enabled: true })
+
+    // Wait for the engine to actually take over (canvas mounted, legacy
+    // <video> slots gone) before asserting the banner's absence — otherwise
+    // the assertion could pass trivially on the pre-decision render.
+    await waitFor(() => expect(document.querySelector('canvas')).not.toBeNull())
+    expect(screen.queryByText(/crossfades will not appear/i)).toBeNull()
+  })
+
+  it('shows no such warning on a legacy project that has no crossfade', () => {
+    // A single track-0 clip: engineRequiredReason is trivially null
+    // (transitionPairs needs 2+ items), and the flag is absent so this is
+    // legacy synchronously, same as the "flag absent" test above.
+    renderPreview(makeProject())
+    expect(screen.queryByText(/crossfades will not appear/i)).toBeNull()
+  })
+})

package/src/video/timeline/Timeline.tsx

@@ -18,7 +18,7 @@ import { VISUAL_EDGE_TOLERANCE_PX } from './canvas/hit-test'
 import { keyframeUnionTimes } from './canvas/keyframe-strip'
 import { mapTrackItems, normalizeTracks, updateAudioTrack } from './timeline-model'
 import { deleteSelection, toggleSelection } from './multiSelectOps'
-import { computeAutoCrossfade, computeDerivedTiming, trackItems } from './timeline-model'
+import { computeAutoCrossfade, computeDerivedTiming, computeVisualCrossfade, trackItems } from './timeline-model'
 import TimelineCanvas, { useCanvasZoomControls, type ZoomControls } from './canvas/TimelineCanvas'
 import type { KeyframeSelection } from './canvas/pointer-machine'
 import { timeToX, useViewportStore, useViewportValue, xToTime, type ViewportStore } from './canvas/viewport'
@@ -657,6 +657,48 @@ export default function Timeline({ project, clock, onProjectChange, onOverlayEdi
   // re-runs on real edits (see above for why the fades belong in the key).
   }, [audioTracks.map(t => `${t.id}:${t.start}:${t.end}:${t.muted}:${t.fadeIn ?? ''}:${t.fadeOut ?? ''}`).join('|')])
 
+  // The VISUAL sibling of the pass above: two OVERLAYS overlapping on the same
+  // track get complementary derived `opacity` curves (`computeVisualCrossfade`
+  // in timeline-model.ts, so the decision logic is shared and testable away
+  // from React).
+  //
+  // A separate effect, deliberately NOT folded into the one above. That one's
+  // dependency digest is keyed on the audio FADES on purpose — the digest is
+  // what clears a pending timer instead of letting a stale one fire — and
+  // mixing a second, independently-changing key into it would re-arm the audio
+  // timer on every unrelated overlay edit, and the visual timer on every
+  // unrelated audio edit. Two passes, two digests, two timers.
+  //
+  // Same debounce, for the same reason: an overlay's span moves on every
+  // mousemove of a drag, and committing each one is the per-move-undo bug. A
+  // gesture's own commit (`commitTimelineEdit`) folds the visual fade into its
+  // one undo step, so mid-drag this timer is cleared and rescheduled every
+  // frame and never fires, and right after a gesture it no-ops because
+  // `computeVisualCrossfade` is idempotent. This pass is therefore only the
+  // catch-all for overlay timing that changes OUTSIDE a gesture — ripple-
+  // delete, gap-collapse — which reach `sync.mutate` directly and never pass
+  // through `commitTimelineEdit` at all. Commits only; a preview via
+  // `onProjectChange` would change the digest below and clear the timer before
+  // it fired, so a ripple-delete's fade would never get saved.
+  useEffect(() => {
+    if (!onOverlayEdit) return
+    const next = computeVisualCrossfade(project)
+    if (!next) return
+    const timer = setTimeout(() => onOverlayEdit(next), CROSSFADE_COMMIT_DELAY_MS)
+    return () => clearTimeout(timer)
+  // Keyed on every visual item's SPAN and its DERIVED opacity curve, for
+  // exactly the reason the audio digest above includes the fades: the
+  // gesture's own crossfade commit changes this digest, which re-runs the
+  // effect and clears the pending timer rather than letting a stale one fire.
+  // `origin` is what makes a curve derived, and this pass is its only writer,
+  // so a hand-authored curve (no `origin`) contributes nothing to the key —
+  // it can never be the reason this pass needs to run again.
+  }, [allTracks.map(items => items.map(i => {
+    const fade = i.keyframes?.find(k => k.prop === 'opacity')
+    const curve = fade?.origin ? fade.points.map(p => `${p.t},${p.value}`).join(';') : ''
+    return `${i.id}:${i.start}:${i.end}:${curve}`
+  }).join('|')).join('||')])
+
   // The tabIndex={0} root below — Delete/Enter's guards below check focus is
   // inside it before firing (see the useKeymap block), restoring the pre-T9
   // scoping those two bindings had (arrows/Escape were already document-level