@bycrux/editor 1.0.2 → 1.2.0

package/src/video/cuts.ts

@@ -481,19 +481,47 @@ function splitAudioTrack(track: AudioTrack, at: number): [AudioTrack, AudioTrack
   const outPoint = track.outPoint ?? track.sourceDuration ?? (track.end - track.start)
   const splitPoint = inPoint + (at - track.start)
 
+  // A FADE BELONGS TO AN EDGE, NOT TO THE CLIP. Spreading `...track` into both
+  // halves gave both fragments both fades, which is wrong on the two edges the
+  // split just created: the left half fades OUT into the cut and the right half
+  // fades IN out of it, neither of which anyone asked for. On a voiceover
+  // carrying the usual trailing fade-out that is very visible — every cut
+  // produced a fragment that ramps to silence at the razor, and the operator
+  // has to zero it by hand each time. Fades are added deliberately; a cut is
+  // not a request for one.
+  //
+  // So each half keeps only the fade whose EDGE it still owns:
+  //   • the left half keeps the original START, so it keeps `fadeIn`;
+  //   • the right half keeps the original END, so it keeps `fadeOut`;
+  //   • the two new edges at the cut carry no fade at all.
+  // The paired curve goes with its fade — a `fadeOutCurve` describing a
+  // fade-out that no longer exists is dead data, and the operator's next
+  // hand-drawn fade should start from the default shape like any other new one.
+  //
+  // The kept fade is then clamped to its own fragment's span. A 3s fade-out on
+  // a 20s track is fine; split that track 1s from its end and the 3s fade no
+  // longer fits inside the 1s fragment it lands on. Nothing downstream
+  // re-clamps for us — the pointer-machine and the properties panel each clamp
+  // their OWN edits, and the renderer just anchors `st = end - fadeOut`, which
+  // for an oversized fade starts before the fragment's audio does.
+  const { fadeOut: _outAmt, fadeOutCurve: _outCurve, ...leftBase } = track
+  const { fadeIn: _inAmt, fadeInCurve: _inCurve, ...rightBase } = track
+
   const left: AudioTrack = {
-    ...track,
+    ...leftBase,
     end: at,
     inPoint,
     outPoint: splitPoint,
   }
   const right: AudioTrack = {
-    ...track,
+    ...rightBase,
     id: uniqueId(track.id),
     start: at,
     inPoint: splitPoint,
     outPoint,
   }
+  if (left.fadeIn !== undefined)  left.fadeIn  = Math.min(left.fadeIn, at - track.start)
+  if (right.fadeOut !== undefined) right.fadeOut = Math.min(right.fadeOut, track.end - at)
   return [left, right]
 }
 

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/preview/__tests__/useVideoPlayback.canvasClock.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The canvas rAF clock's CEILING, driven through the real effect.
+ *
+ * `canvasMaxEndRef` is the only thing standing between "space plays" and "space
+ * does nothing" on a project with no track-0 video. It used to read
+ * `overlayTracks` (`tracks.slice(1)`), which silently skips track 0 — and track
+ * 0 in canvas mode is not the primary footage track, it is content: the
+ * background images, and on an agent-authored project frequently the overlays
+ * themselves. A project that is ONE track of nothing but overlays (what the
+ * animations workflow emits) therefore got a ceiling of 0, and the first tick
+ * clamped the playhead to 0 and called `setIsPlaying(false)` in the same frame.
+ *
+ * These drive the hook's own rAF effect rather than asserting on a helper: the
+ * ceiling lives in a ref that nothing exports, so the only honest way to pin it
+ * is to run the clock and watch where time goes. Each case fails on the
+ * pre-fix `overlayTracks` read.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { useVideoPlayback } from '../useVideoPlayback'
+import type { EditorProject, VisualItem } from '../../../schema'
+
+const overlay = (id: string, start: number, end: number): VisualItem =>
+  ({ id, type: 'overlay', src: `/overlays/${id}.jsx`, start, end }) as VisualItem
+
+const image = (id: string, start: number, end: number): VisualItem =>
+  ({ id, type: 'image', src: `/img/${id}.png`, start, end }) as VisualItem
+
+/** The last emission. Not `.at(-1)` — this package targets ES2020. */
+const last = (xs: number[]): number | undefined => xs[xs.length - 1]
+
+function projectOf(...tracks: VisualItem[][]): EditorProject {
+  return {
+    id: 'canvas-clock',
+    status: 'draft',
+    settings: { resolution: [1920, 1080] },
+    tracks: tracks.map((items, i) => ({ id: `trk-${i}`, items })),
+  } as EditorProject
+}
+
+/**
+ * Mount the hook on a canvas project and run the clock for one second of wall
+ * time, returning every playhead value it emitted.
+ *
+ * Two ticks, because the first only anchors `rafLastMs` — it has no `dt` yet
+ * and emits nothing. The second is the first that can move the playhead, and
+ * the one the collapsed ceiling used to kill.
+ */
+function runClock(project: EditorProject) {
+  const times: number[] = []
+  const scheduled: FrameRequestCallback[] = []
+  vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((cb: FrameRequestCallback) => {
+    scheduled.push(cb)
+    return scheduled.length
+  })
+
+  const view = renderHook(() => useVideoPlayback(project, 0, (t) => times.push(t), (p) => p))
+  expect(view.result.current.isCanvasProject).toBe(true)
+
+  scheduled.length = 0
+  act(() => { view.result.current.setIsPlaying(true) })
+  expect(scheduled.length).toBeGreaterThan(0)
+
+  act(() => { scheduled[0](0) })          // anchor only
+  act(() => { scheduled[scheduled.length - 1](1000) })  // +1s of wall clock
+
+  return { times, isPlaying: view.result.current.isPlaying }
+}
+
+describe('useVideoPlayback — the canvas clock counts track 0', () => {
+  afterEach(() => { vi.restoreAllMocks() })
+
+  it('advances on a single track holding nothing but overlays', () => {
+    // The Daubert-demo shape: one track, 14 overlays, no captions, no video.
+    const { times, isPlaying } = runClock(projectOf([overlay('o1', 0, 5), overlay('o2', 5, 12)]))
+    expect(last(times)).toBeCloseTo(1, 6)
+    expect(isPlaying).toBe(true)
+  })
+
+  it('advances on a track-0 image that outlasts every overlay track', () => {
+    // Same defect, other content kind — the background image was invisible to
+    // the ceiling, so a slideshow stopped at its last overlay.
+    //
+    // The overlay track has to end INSIDE the second this clock runs (0.4 < 1),
+    // or `overlayTracks` alone already carries the playhead to 1 and the case
+    // passes on the broken code without ever reading track 0.
+    const { times } = runClock(projectOf([image('bg', 0, 20)], [overlay('o', 0, 0.4)]))
+    expect(last(times)).toBeCloseTo(1, 6)
+  })
+
+  it('still stops at the ceiling rather than running past the content', () => {
+    // The clamp itself is not what was wrong, and must survive: one second of
+    // wall clock against a half-second project lands on the end, not past it,
+    // and playback stops there.
+    const { times, isPlaying } = runClock(projectOf([overlay('o', 0, 0.5)]))
+    expect(last(times)).toBeCloseTo(0.5, 6)
+    expect(isPlaying).toBe(false)
+  })
+})

package/src/video/preview/useVideoPlayback.ts

@@ -322,18 +322,33 @@ export function useVideoPlayback(
     applyClipVolume(clip)
   }, [clips, videoTrack, activeSlot])
 
-  // maxEnd for the canvas rAF clock — the furthest overlay/caption end. Kept in
+  // maxEnd for the canvas rAF clock — the furthest visual/caption end. Kept in
   // a ref, updated by its own cheap effect, so the rAF effect below doesn't tear
   // down and rebuild on every project spread (only isPlaying/onTimeUpdate matter
   // to it). onTimeUpdate is the stable clock.set identity.
+  //
+  // Spans EVERY enabled track, track 0 INCLUDED — not `overlayTracks`
+  // (`slice(1)`). This clock only ever runs for canvas projects, where track 0
+  // holds content rather than the primary footage: the background images, and
+  // on an agent-authored project frequently the overlays themselves (an
+  // animations-workflow project is often ONE track of nothing but overlays).
+  // Reading `overlayTracks` here collapsed the ceiling to 0 for exactly those,
+  // so the very first tick clamped to 0 and immediately called
+  // `setIsPlaying(false)` — space appeared to do nothing at all.
+  // `OverlayItemsLayer` already draws track 0 in canvas mode; this keeps the
+  // clock's ceiling and what's on screen in agreement. Mirrored in the engine
+  // path's `transportEndFor` (engine/scheduler.ts) — change both together.
+  //
+  // Audio stays OUT, unchanged: the canvas/video divergence over the audio tail
+  // is documented in timeline-core's `durations.js` and is not this fix.
   const canvasMaxEndRef = useRef(0)
   useEffect(() => {
     const captionEnd = (project.captions?.segments ?? []).reduce((m: number, s) => Math.max(m, s.end), 0)
     canvasMaxEndRef.current = Math.max(
-      overlayTracks.flat().reduce((m, i) => Math.max(m, i.end), 0),
+      enabledTrackItems(project).flat().reduce((m, i) => Math.max(m, i.end ?? 0), 0),
       captionEnd,
     )
-  }, [overlayTracks, project.captions])
+  }, [project])
 
   useEffect(() => {
     if (!isCanvasProject) return

package/src/video/timeline/Timeline.tsx

@@ -18,7 +18,8 @@ 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 { removeMarkers } from './markers'
+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 +658,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
@@ -794,6 +837,11 @@ export default function Timeline({ project, clock, onProjectChange, onOverlayEdi
             updated = { ...updated, captions: normalizeCaptionLanes({ ...captionTrack, segments: kept }) }
           }
         }
+        // Markers live at project.markers, outside tracks/audio, so `deleteSelection`
+        // cannot see them — same reason captions need their own strip above. Folded
+        // into the SAME commit so a mixed clip + caption + marker delete is one
+        // undo entry.
+        updated = removeMarkers(updated, new Set(selectedIds))
         if (rippleMode) updated = collapseGaps(updated)
         // Deleting a clip out of a magnetic audio lane leaves a gap exactly
         // like a trim or a move would — close it the same way, on release.

package/src/video/timeline/__tests__/Timeline.keymap.test.tsx

@@ -360,6 +360,22 @@ describe('Timeline — T9 keymap (arrows / delete / enter / escape)', () => {
     expect(onProjectChange).not.toHaveBeenCalled()
   })
 
+  it('Delete removes a selected marker, in the same commit as everything else', () => {
+    // Markers live outside tracks/audio, so deleteSelection cannot see them —
+    // the same reason captions needed their own strip in this action.
+    const clock = createPlaybackClock(0)
+    const onProjectChange = vi.fn()
+    const project = { ...makeProject(), markers: [{ id: 'm1', t: 5, label: '1' }] }
+    const { container } = render(
+      <Timeline project={project} clock={clock} selectedIds={['m1']} onProjectChange={onProjectChange} />,
+    )
+    focusTimelineRoot(container)
+    fireEvent.keyDown(document.body, { key: 'Delete' })
+    expect(onProjectChange).toHaveBeenCalledTimes(1)
+    const updated = onProjectChange.mock.calls[0][0] as Project
+    expect(updated.markers).toBeUndefined()   // last one gone → key dropped
+  })
+
   it('exposes zoomFit through actionsRef for a host-level palette', () => {
     const clock = createPlaybackClock(1)
     const actionsRef: { current: TimelineActions | null } = { current: null }