@bycrux/editor 1.0.1 → 1.1.0

package/src/engine/__tests__/source-host.test.ts

@@ -18,6 +18,12 @@
  *     when `src` itself changed;
  *   - `volume`/`muted` edits on a live clip never reached the session at all
  *     (`MasterClock.setVolume` had zero call sites anywhere in the engine).
+ *
+ * SP-transitions 9b added the exclusive-server block at the foot of the file,
+ * for the same reason: `acquireServer`'s keying and its refcount hygiene are
+ * only reachable from here. `demuxCalls` is the fetch counter those tests
+ * assert on and `serverInstances` is the decoder ledger — both already hoisted
+ * above, no parallel helpers needed.
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { EditorProject as Project, VisualItem } from '../../schema'
@@ -453,3 +459,162 @@ describe('EngineSourceHost.acquirePinnedDemux — shared demux LRU', () => {
     engine.dispose()
   })
 })
+
+// ── 9b: the exclusive-server carve-out ──────────────────────────────────────
+describe('EngineSourceHost.acquireServer — a second decoder for a blending pair off ONE src', () => {
+  /**
+   * Three cuts of ONE take — what a silence-trimmed timeline is made of. `a`
+   * and `b` overlap on [3, 4) so the resolver reads them as a crossfade pair:
+   * the commonest crossfade there is, and the one the engine could not blend
+   * before 9b. `c` picks the picture up at 8 off the same take, which is what
+   * makes the demotion observable — it is the clip that inherits `b`'s decoder.
+   */
+  function sameTakeProject(): Project {
+    const cut = (id: string, start: number, end: number): VisualItem =>
+      videoItem({
+        id,
+        src: '/media/take.mov',
+        proxySrc: '/proxies/take_proxy.mp4',
+        start,
+        end,
+        inPoint: start,
+        outPoint: end,
+      })
+    return {
+      id: 'p1',
+      status: 'draft',
+      settings: { resolution: [1080, 1920], fps: 30 },
+      tracks: [{ id: 'trk-0', items: [cut('a', 0, 4), cut('b', 3, 8), cut('c', 8, 12)] }],
+    } as Project
+  }
+
+  const engineFor = (project: Project) =>
+    createEngine(project, { fileUrl: (p) => p, nowMs: () => 0 })
+
+  it('an exclusive request gets its OWN FrameServer for the same src', async () => {
+    const engine = engineFor(sameTakeProject())
+    engine.seek(3.5) // mid-overlap: `a` outgoing, `b` incoming and exclusive
+    await flush()
+
+    // Two decoders off one proxy — the carve-out. Before 9b this was one, and
+    // the blend had no second read position to ask for.
+    expect(serverInstances).toHaveLength(2)
+
+    engine.dispose()
+  })
+
+  it('non-exclusive requests on one src still SHARE a server — the invariant holds', async () => {
+    const engine = engineFor(sameTakeProject())
+    engine.seek(2.5) // `a` active, `b` prewarmed as `next`; no blend yet
+    await flush()
+
+    expect(serverInstances).toHaveLength(1)
+
+    engine.dispose()
+  })
+
+  it('the exclusive server reuses the cached demux rather than re-fetching', async () => {
+    // The whole justification for the carve-out. If this fails the carve-out is
+    // not cheap and the invariant should win instead.
+    const engine = engineFor(sameTakeProject())
+    engine.seek(2.5)
+    await flush()
+    const fetches = demuxCalls.length
+    expect(fetches).toBe(1)
+
+    engine.seek(3.5) // `b` moves onto a decoder of its own
+    await flush()
+
+    expect(serverInstances.length).toBeGreaterThan(1) // it really did spawn one
+    // LENGTH, not membership: a re-demux appends a SECOND '/proxies/take_proxy
+    // .mp4' to this array, so `toContain` would stay green through the exact
+    // regression this test exists to catch.
+    expect(demuxCalls).toHaveLength(fetches)
+
+    engine.dispose()
+  })
+
+  it('releasing the exclusive clip disposes ITS server and leaves the shared one alive', async () => {
+    // The refcount key CHANGES between calls — the release path must use the
+    // same key the acquire used, or the entry is orphaned and never disposed.
+    const project = sameTakeProject()
+    const engine = engineFor(project)
+    engine.seek(3.5)
+    await flush()
+    expect(serverInstances).toHaveLength(2)
+    const [shared, exclusive] = serverInstances
+
+    // Drop `b` outright, leaving the shared clip retained.
+    const items = project.tracks![0].items as VisualItem[]
+    engine.updateProject({ ...project, tracks: [{ id: 'trk-0', items: [items[0]] }] } as Project)
+    await flush()
+
+    // Named instances, not a count: "exactly one server was disposed" is also
+    // true when the WRONG one was, which is precisely what an inverted key does.
+    expect(exclusive.disposed).toBe(true)
+    expect(shared.disposed).toBe(false)
+
+    engine.dispose()
+  })
+
+  it('keeps the exclusive server while the outgoing clip still holds the shared key', async () => {
+    // The blend ends at 4, but `retainFor` keeps the outgoing clip as `prev`,
+    // so the shared key is still TAKEN at the moment `b` stops being exclusive.
+    // Two live servers for one src cannot be merged into one: re-filing `b`
+    // there would either overwrite `a`'s entry — orphaning a worker that is
+    // still decoding, and one nothing would ever dispose — or merge the
+    // refcounts, so the first release would tear down a server the other clip
+    // is still streaming from. `demoteServer` declines and waits instead.
+    //
+    // Both halves have to be in ONE test: the orphan an overwrite creates is
+    // invisible until `a` is released and its server fails to be disposed.
+    const engine = engineFor(sameTakeProject())
+    engine.seek(3.5)
+    await flush()
+    expect(serverInstances).toHaveLength(2)
+    const [outgoing, incoming] = serverInstances
+
+    engine.seek(4.5) // past the overlap; `b` active, `a` still retained as `prev`
+    await flush()
+    expect(serverInstances).toHaveLength(2)
+    expect(outgoing.disposed).toBe(false)
+    expect(incoming.disposed).toBe(false)
+
+    engine.seek(8.5) // `a` finally leaves the retained set
+    await flush()
+
+    // `a`'s worker was terminated under the key `a` itself held. An overwrite
+    // back at 4.5 would have left this false forever — `a`'s release would find
+    // `b`'s entry under the shared key, delete a ref that was never there, and
+    // walk away from a running decoder.
+    expect(outgoing.disposed).toBe(true)
+    expect(incoming.disposed).toBe(false)
+    // And `c` still shares the demoted server rather than spawning a third.
+    expect(serverInstances).toHaveLength(2)
+
+    engine.dispose()
+  })
+
+  it('hands the exclusive server back to the shared key once that key frees', async () => {
+    // The demotion on its own, with no contended step in between: once `a`
+    // leaves the retained set its entry is disposed and removed in the SAME
+    // `retain` — the drop loop runs before the demotion loop — so the shared
+    // key is free by the time `b` is re-filed under it, decoder untouched. `c`
+    // then finds that entry and shares it, which is the invariant restored
+    // rather than merely deferred.
+    const engine = engineFor(sameTakeProject())
+    engine.seek(3.5)
+    await flush()
+    expect(serverInstances).toHaveLength(2)
+
+    engine.seek(8.5) // `c` active, `b` is `prev`, `a` has left the retained set
+    await flush()
+
+    // Still two: `c` found `b`'s demoted server instead of spawning a third.
+    expect(serverInstances).toHaveLength(2)
+    expect(serverInstances[0].disposed).toBe(true)
+    expect(serverInstances[1].disposed).toBe(false)
+
+    engine.dispose()
+  })
+})

package/src/engine/eligibility.ts

@@ -29,8 +29,9 @@
  * placeholder fallback rather than a whole-project revert) land in T6. This
  * module is the pure/async logic T6 calls into.
  */
+import { transitionPairs } from '@bycrux/timeline-core'
 import type { EditorProject as Project } from '../schema'
-import { trackItems } from '../video/timeline/timeline-model'
+import { enabledTrackItems, trackItems } from '../video/timeline/timeline-model'
 
 export interface EligibilityResult {
   eligible: boolean
@@ -138,3 +139,38 @@ export async function evaluateEngineEligibility(project: Project): Promise<Eligi
   }
   return { eligible: true }
 }
+
+/**
+ * Does this project need the engine for a reason the LEGACY `<video>` player
+ * cannot serve on its own? Additive to the checks above — this is not part of
+ * `checkProjectShapeEligibility`/`evaluateEngineEligibility`'s eligibility
+ * verdict, it answers a different question ("is legacy playback wrong here",
+ * not "can the engine run this project").
+ *
+ * Today the only such reason is a CLIP (video/image) crossfade on the
+ * PRIMARY footage track (`tracks[0]`): the resolver stamps
+ * `ResolvedItem.crossfade` for clip pairs per `transitionPairs`
+ * (`@bycrux/timeline-core`, matching `activation.js`'s `crossfadesAt`), and
+ * both render and the engine's own preview blend it — but the legacy player
+ * mounts one `<video>` element per clip with no compositing stage, so it can
+ * only hard-cut. Clip pairs on an OVERLAY track are excluded, and not just
+ * because their fade is baked `opacity` keyframe data
+ * (`computeVisualCrossfade`, which the legacy player already renders
+ * correctly via the DOM/CSS layer): `OverlayItemsLayer` blends overlay clip
+ * pairs itself in legacy mode too, so there is nothing here the legacy path
+ * cannot already serve. A track-0-only check also means `transitionPairs`
+ * naturally short-circuits (needs 2+ items) so an empty or single-clip
+ * primary track costs nothing extra.
+ *
+ * Reads via `enabledTrackItems`, not `trackItems`: a `enabled: false` track's
+ * clips are invisible to every real blend consumer (preview, render), so an
+ * overlapping pair sitting on a skipped track must not raise this banner —
+ * there is no crossfade for the legacy player to fail at rendering.
+ */
+export function engineRequiredReason(project: Project): 'clip-crossfade' | null {
+  const primary = enabledTrackItems(project)[0] ?? []
+  const clips = primary.filter((item) => item.type === 'video' || item.type === 'image')
+  if (clips.length < 2) return null
+  if (transitionPairs(clips).length > 0) return 'clip-crossfade'
+  return null
+}

package/src/engine/index.ts

@@ -31,6 +31,14 @@
  *     stream from one server at once — the scheduler stops the outgoing
  *     session before starting the incoming one — and when the last clip
  *     referencing a src is dropped, the worker really is terminated.
+ *
+ *     ONE carve-out, and it does not overturn the reasoning above: the two
+ *     sides of a crossfade cut from a single take need two read positions at
+ *     the same instant, which one server cannot serve, so the incoming side
+ *     asks for its own (`SourceRequest.exclusiveServer`) for the length of the
+ *     blend. What the rule actually saves is the DEMUX, and that survives — the
+ *     cache below is keyed by `src` independently of the server map, so the
+ *     second decoder costs one worker and not one byte of extra fetch.
  *   - **`MasterClock` — one per CLIP**, because it is anchored to that clip's
  *     `start`/`inPoint`/`volume`/`muted` and T4 is explicit that a live clock is
  *     never reconfigured.
@@ -52,6 +60,7 @@ import type { FileUrlResolver } from './media-loader'
 import {
   createScheduler,
   type ClipSource,
+  type DrawPlan,
   type EngineStatus,
   type Painter,
   type Scheduler,
@@ -249,23 +258,43 @@ export function createCanvasPainter(canvas: HTMLCanvasElement): Painter {
     ctx.fillStyle = '#000'
     ctx.fillRect(0, 0, canvas.width, canvas.height)
   }
+  const draw = (frame: VideoFrame, plan: DrawPlan) => {
+    if (!ctx) return
+    if (plan.sw <= 0 || plan.sh <= 0 || plan.dw <= 0 || plan.dh <= 0) return
+    ctx.drawImage(
+      frame,
+      plan.sx,
+      plan.sy,
+      plan.sw,
+      plan.sh,
+      plan.dx,
+      plan.dy,
+      plan.dw,
+      plan.dh,
+    )
+  }
   return {
     size: () => ({ width: canvas.width, height: canvas.height }),
     paint(frame, plan) {
       if (!ctx) return
       fill()
-      if (plan.sw <= 0 || plan.sh <= 0 || plan.dw <= 0 || plan.dh <= 0) return
-      ctx.drawImage(
-        frame,
-        plan.sx,
-        plan.sy,
-        plan.sw,
-        plan.sh,
-        plan.dx,
-        plan.dy,
-        plan.dw,
-        plan.dh,
-      )
+      draw(frame, plan)
+    },
+    paintBlend(from, to, p, fromPlan, toPlan) {
+      if (!ctx) return
+      fill()
+      draw(from, fromPlan)
+      // Source-over at alpha p composites `p*to + (1-p)*from` onto the outgoing
+      // picture already on the canvas — the lerp `encode-segment.js` emits as
+      // `blend=all_expr='A+(B-A)*p'`. Restored in `finally` because the context
+      // is long-lived: a leaked alpha would ghost every later paint, including
+      // the black fill.
+      try {
+        ctx.globalAlpha = p
+        draw(to, toPlan)
+      } finally {
+        ctx.globalAlpha = 1
+      }
     },
     clear: fill,
   }
@@ -311,6 +340,23 @@ interface Session {
    * not.
    */
   speed: number
+  /**
+   * `!!request.exclusiveServer` as of the last (re)build — see
+   * {@link serverKeyFor}. Stamped alongside the fields above so `retain`'s drop
+   * test can see it change, but it is NOT one of them: a clip that stops being
+   * the incoming side of a blend keeps the session and the decoder it already
+   * has. See `retain`.
+   */
+  exclusive: boolean
+  /**
+   * The `servers` key this session actually holds a ref under, set when
+   * `acquireServer` returns. Stored rather than re-derived at release time:
+   * the REQUEST's exclusivity can change between two `retain` calls while the
+   * acquired entry cannot, and a release keyed off the current request would
+   * leave the acquired entry orphaned in the map with its worker running for
+   * the rest of the session's life. Undefined until the server is acquired.
+   */
+  serverKey?: string
   /** Rebuild attempts already spent on this clip — see {@link MAX_SESSION_RETRIES}. */
   retries: number
   /**
@@ -320,8 +366,25 @@ interface Session {
   retryAfterMs: number
 }
 
+/**
+ * The `servers` key for one clip's decode session.
+ *
+ * `src` for the ordinary case — that IS the one-server-per-src rule this file's
+ * header states. An exclusive request gets an entry of its own instead, so the
+ * two sides of a crossfade cut from a single take have two read positions; see
+ * `SourceRequest.exclusiveServer` for why that carve-out is cheap.
+ */
+const serverKeyFor = (src: string, clipId: string, exclusive: boolean): string =>
+  exclusive ? `${src}#${clipId}` : src
+
 interface ServerEntry {
   server: FrameServer
+  /**
+   * The src this server decodes. Not derivable from the map key, which carries
+   * a clip id too on an exclusive entry — and `evictDemux` has to know whether
+   * ANY live session is reading a src before it drops that src's demux.
+   */
+  src: string
   refs: Set<string>
 }
 
@@ -373,9 +436,27 @@ class EngineSourceHost implements SourceHost {
         want.item.start !== session.start ||
         sourceWindow(want.item, 'preview').inPoint !== session.inPoint ||
         !!want.item.muted !== session.muted ||
-        (want.item.speed ?? 1) !== session.speed
+        (want.item.speed ?? 1) !== session.speed ||
+        // A clip that BECOMES the incoming side of a blend has to move onto a
+        // decoder of its own, and a live session cannot change servers. It is
+        // usually already built by then — the scheduler prewarms it as `next`
+        // before the overlap starts — so without this the blend would find both
+        // sides on one server and decline. Deliberately one-directional: see
+        // the demotion loop below for why the reverse is NOT a respawn.
+        (!!want.exclusiveServer && !session.exclusive)
       if (changed) this.dropSession(clipId)
     }
+    // The other edge of `exclusiveServer`: a clip that STOPS being the incoming
+    // side of a blend, which happens the instant the outgoing clip ends. By
+    // then it is the ACTIVE clip — the transport is running on its master clock
+    // — so a respawn here would tear down that clock and terminate its decoder
+    // mid-playback at the end of every crossfade, an artefact worse than the
+    // hard cut 9b removed. The session keeps the decoder it already has; all
+    // that changes is the key it is filed under.
+    for (const request of requests) {
+      const session = this.sessions.get(request.clipId)
+      if (session?.exclusive && !request.exclusiveServer) this.demoteServer(session)
+    }
     // A clip's volume can change without a rebuild: push it straight to the
     // live clock (`MasterClock.setVolume`) rather than tearing the session
     // down. Only sessions that survived the drop loop above and already have a
@@ -468,6 +549,7 @@ class EngineSourceHost implements SourceHost {
       muted: !!request.item.muted,
       volume: request.item.volume ?? 1,
       speed: request.item.speed ?? 1,
+      exclusive: !!request.exclusiveServer,
       retries,
       retryAfterMs: 0,
     }
@@ -483,7 +565,7 @@ class EngineSourceHost implements SourceHost {
     try {
       const demuxed = await this.acquireDemux(session.src)
       if (session.cancelled) return
-      const server = this.acquireServer(session.src, demuxed, session.clipId)
+      const server = this.acquireServer(session, demuxed, !!request.exclusiveServer)
       acquired = true
 
       const window = sourceWindow(request.item, 'preview')
@@ -523,7 +605,7 @@ class EngineSourceHost implements SourceHost {
       })
       if (session.cancelled) {
         clock.dispose()
-        this.releaseServer(session.src, session.clipId)
+        this.releaseServer(session)
         return
       }
       session.source = {
@@ -535,7 +617,7 @@ class EngineSourceHost implements SourceHost {
       }
       session.status = 'ready'
     } catch (err) {
-      if (acquired) this.releaseServer(session.src, session.clipId)
+      if (acquired) this.releaseServer(session)
       if (session.cancelled) return
       const message = err instanceof Error ? err.message : String(err)
       this.markFailed(session, message)
@@ -563,7 +645,7 @@ class EngineSourceHost implements SourceHost {
     this.sessions.delete(clipId)
     session.cancelled = true
     session.source?.clock.dispose()
-    if (session.source) this.releaseServer(session.src, clipId)
+    if (session.source) this.releaseServer(session)
     else this.abandonDemux(session.src)
   }
 
@@ -586,7 +668,7 @@ class EngineSourceHost implements SourceHost {
       session.source?.clock.dispose()
       if (session.source) {
         session.source = undefined
-        this.releaseServer(src, session.clipId)
+        this.releaseServer(session)
       }
       this.scheduler?.sourceChanged(session.clipId)
     }
@@ -594,32 +676,68 @@ class EngineSourceHost implements SourceHost {
 
   // ── per-src resources ─────────────────────────────────────────────────────
 
-  private acquireServer(src: string, source: DemuxedSource, clipId: string): FrameServer {
-    let entry = this.servers.get(src)
+  private acquireServer(session: Session, source: DemuxedSource, exclusive: boolean): FrameServer {
+    const src = session.src
+    const key = serverKeyFor(src, session.clipId, exclusive)
+    let entry = this.servers.get(key)
     if (!entry) {
       entry = {
         server: createFrameServer({
           source,
           hardwareAcceleration: this.deps.hardwareAcceleration,
           decodeAheadFrames: this.deps.decodeAheadFrames,
+          // Reported against the RAW src, never the key: a decode error is a
+          // property of the file, so every session reading it has to hear
+          // about it — including the one on the other side of a blend.
           onError: (message) => this.onDecodeError(src, message),
         }),
+        src,
         refs: new Set(),
       }
-      this.servers.set(src, entry)
+      this.servers.set(key, entry)
     }
-    entry.refs.add(clipId)
+    entry.refs.add(session.clipId)
+    // Stamped here rather than by the caller so the key a session releases is
+    // by construction the key it acquired, whatever the request said later.
+    session.serverKey = key
+    session.exclusive = exclusive
     return entry.server
   }
 
-  /** Last clip off this src leaves ⇒ the worker is terminated. The spike's `load` rule. */
-  private releaseServer(src: string, clipId: string): void {
-    const entry = this.servers.get(src)
+  /** Last clip off this server leaves ⇒ the worker is terminated. The spike's `load` rule. */
+  private releaseServer(session: Session): void {
+    const key = session.serverKey
+    if (key === undefined) return
+    session.serverKey = undefined
+    const entry = this.servers.get(key)
     if (!entry) return
-    entry.refs.delete(clipId)
+    entry.refs.delete(session.clipId)
     if (entry.refs.size > 0) return
     entry.server.dispose()
-    this.servers.delete(src)
+    this.servers.delete(key)
+  }
+
+  /**
+   * File a no-longer-exclusive session's server back under the shared key,
+   * without disturbing the decoder itself — see the demotion loop in `retain`
+   * for why this is not a respawn.
+   *
+   * Only possible while the shared key is free: two live servers for one src
+   * cannot be merged into one. When it is taken (the outgoing clip of the
+   * crossfade is usually still retained as `prev`, holding exactly that key)
+   * the exclusive entry simply stays where it is and is terminated with the
+   * clip, which is bounded by the retained set and costs one worker — never a
+   * leak, because the session still holds the key it acquired.
+   */
+  private demoteServer(session: Session): void {
+    const key = session.serverKey
+    if (key === undefined || key === session.src) return
+    const entry = this.servers.get(key)
+    if (!entry || this.servers.has(session.src)) return
+    this.servers.delete(key)
+    this.servers.set(session.src, entry)
+    session.serverKey = session.src
+    session.exclusive = false
   }
 
   private async acquireDemux(src: string): Promise<DemuxedSource> {
@@ -706,8 +824,11 @@ class EngineSourceHost implements SourceHost {
     while (this.demuxCache.size > DEMUX_CACHE_MAX) {
       let victim: string | null = null
       for (const src of this.demuxCache.keys()) {
-        // Never evict a source a live decode session is reading from.
-        if (this.servers.has(src)) continue
+        // Never evict a source a live decode session is reading from. Asked of
+        // the ENTRIES, not the keys: an exclusive server is filed under a key
+        // that carries a clip id, and evicting the demux out from under one is
+        // exactly the re-fetch the carve-out promises not to cause.
+        if (this.hasServerFor(src)) continue
         // Or one an outside consumer (the drag-scrub source) is holding.
         if (this.demuxPins.has(src)) continue
         victim = src
@@ -718,6 +839,14 @@ class EngineSourceHost implements SourceHost {
     }
   }
 
+  /** Any live decode session reading this src — under the shared key or an exclusive one. */
+  private hasServerFor(src: string): boolean {
+    for (const [, entry] of this.servers) {
+      if (entry.src === src) return true
+    }
+    return false
+  }
+
   /**
    * Shared with the drag-scrub audio source. `acquireDemux` already coalesces
    * concurrent builds and populates the LRU; this wraps it in a per-src pin
@@ -878,12 +1007,19 @@ export function createEngine(project: Project, deps: EngineDeps): Engine {
       sizeCanvas()
       const painter = createCanvasPainter(next)
       // Wrapped only to feed `stats().fps` — every other call is `painter`'s own.
+      // A blend is ONE painted frame however many sources it composites, so it
+      // records exactly like a plain paint; leaving it out would read as a
+      // frame rate collapse for the length of every crossfade.
       scheduler.attach({
         ...painter,
         paint: (frame, plan) => {
           recordPaint()
           painter.paint(frame, plan)
         },
+        paintBlend: (from, to, p, fromPlan, toPlan) => {
+          recordPaint()
+          painter.paintBlend(from, to, p, fromPlan, toPlan)
+        },
       })
     },
     play() {