@meframe/core 0.1.6 → 0.1.8

package/dist/controllers/PlaybackController.js

@@ -1,42 +1,44 @@
+import { PlaybackActionType, PlaybackState, PlaybackCommandType } from "./types.js";
 import { MeframeEvent } from "../event/events.js";
 import { WaiterReplacedError } from "../utils/errors.js";
 import { VideoComposer } from "../stages/compose/VideoComposer.js";
 import { isVideoClip } from "../model/types.js";
+import { PlaybackStateMachine } from "./PlaybackStateMachine.js";
 class PlaybackController {
   orchestrator;
   eventBus;
   canvas;
   videoComposer = null;
-  // Playback state
+  // Playback time (external)
   currentTimeUs = 0;
-  state = "idle";
   playbackRate = 1;
   volume = 1;
   loop = false;
-  // Animation loop
+  // Time base
   rafId = null;
   startTimeUs = 0;
-  // Playback start position in AudioContext timeline (microseconds)
-  // Frame tracking
+  // AudioContext timeline origin (microseconds)
+  // Frame stats
   frameCount = 0;
   lastFrameTime = 0;
   fps = 0;
+  // Audio
   audioContext;
   audioSession;
-  // Seek tracking
-  currentSeekId = 0;
-  wasPlayingBeforeSeek = false;
+  lastAudioScheduleTime = 0;
+  AUDIO_SCHEDULE_INTERVAL = 1e5;
+  // 100ms
+  // State machine
+  fsm = new PlaybackStateMachine();
   // Unified window management for both video and audio
   windowEnd = 0;
   WINDOW_DURATION = 3e6;
   // 3s decode window
+  AUDIO_READY_PROBE_WINDOW = 5e5;
+  // 500ms: gate buffering only for near-future audio
   PREHEAT_DISTANCE = 1e6;
   // 1s preheat trigger distance
   preheatInProgress = false;
-  // Audio scheduling throttle to reduce CPU overhead
-  lastAudioScheduleTime = 0;
-  AUDIO_SCHEDULE_INTERVAL = 1e5;
-  // 100ms (~3 frames at 30fps)
   constructor(orchestrator, eventBus, options) {
     this.orchestrator = orchestrator;
     this.audioSession = orchestrator.audioSession;
@@ -62,162 +64,62 @@ class PlaybackController {
     if (options.loop !== void 0) {
       this.loop = options.loop;
     }
+    this.setupEventListeners();
     if (options.autoStart) {
       this.play();
     }
-    this.setupEventListeners();
   }
   async renderCover() {
-    await this.renderCurrentFrame(0);
+    await this.renderCurrentFrame(0, { mode: "blocking" });
   }
-  // Playback control
+  // ========= Public API =========
   play() {
-    if (this.state === "playing") return;
-    this.lastAudioScheduleTime = 0;
-    this.wasPlayingBeforeSeek = true;
-    this.startPlayback();
-  }
-  async startPlayback() {
-    const wasIdle = this.state === "idle";
-    const seekId = this.currentSeekId;
-    this.state = "playing";
-    try {
-      await this.renderCurrentFrame(this.currentTimeUs);
-      if (seekId !== this.currentSeekId || this.state !== "playing") {
-        return;
-      }
-      this.initWindow(this.currentTimeUs);
-      await this.audioSession.startPlayback(this.currentTimeUs, this.audioContext);
-      this.startTimeUs = this.audioContext.currentTime * 1e6 - this.currentTimeUs / this.playbackRate;
-      this.playbackLoop();
-      this.eventBus.emit(MeframeEvent.PlaybackPlay);
-    } catch (error) {
-      console.error("[PlaybackController] Failed to start playback:", error);
-      this.state = wasIdle ? "idle" : "paused";
-      this.eventBus.emit(MeframeEvent.PlaybackError, error);
-    }
+    this.dispatch({ type: PlaybackActionType.Play });
   }
   pause() {
-    this.state = "paused";
-    this.wasPlayingBeforeSeek = false;
-    if (this.rafId !== null) {
-      cancelAnimationFrame(this.rafId);
-      this.rafId = null;
-    }
-    this.audioSession.stopPlayback();
-    this.currentSeekId++;
-    this.eventBus.emit(MeframeEvent.PlaybackPause);
+    this.dispatch({ type: PlaybackActionType.Pause });
   }
   stop() {
-    this.pause();
-    this.currentTimeUs = 0;
-    this.state = "idle";
-    this.wasPlayingBeforeSeek = false;
-    this.frameCount = 0;
-    this.lastFrameTime = 0;
-    this.lastAudioScheduleTime = 0;
-    const ctx = this.canvas.getContext("2d");
-    if (ctx && "clearRect" in ctx) {
-      ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
-    }
-    this.audioSession.reset();
-    this.audioSession.resetPlaybackStates();
-    this.eventBus.emit(MeframeEvent.PlaybackStop);
+    this.dispatch({ type: PlaybackActionType.Stop });
   }
   async seek(timeUs) {
-    const previousState = this.state;
-    this.orchestrator.cancelActiveDecoding();
-    if (this.rafId !== null) {
-      cancelAnimationFrame(this.rafId);
-      this.rafId = null;
-    }
-    this.audioSession.stopPlayback();
-    this.lastAudioScheduleTime = 0;
-    const clamped = this.clampTime(timeUs);
-    this.currentTimeUs = clamped;
-    this.currentSeekId++;
-    this.state = "seeking";
-    const seekId = this.currentSeekId;
-    try {
-      const keyframeTimeUs = await this.orchestrator.tryRenderKeyframe(clamped);
-      if (keyframeTimeUs !== null) {
-        const renderState = await this.orchestrator.getRenderState(clamped, {
-          immediate: true,
-          relativeTimeUs: keyframeTimeUs
-        });
-        if (renderState && this.videoComposer) {
-          await this.videoComposer.composeFrame({
-            timeUs: clamped,
-            layers: renderState.layers,
-            transition: renderState.transition
-          });
-        }
-      }
-      if (seekId !== this.currentSeekId) {
-        return;
-      }
-      await this.audioSession.ensureAudioForTime(clamped, { immediate: false });
-      await this.orchestrator.getFrame(clamped, {
-        immediate: false,
-        preheat: true
-      });
-      this.initWindow(clamped);
-      if (seekId !== this.currentSeekId) {
-        return;
-      }
-      await this.renderCurrentFrame(clamped);
-      if (seekId !== this.currentSeekId) {
-        return;
-      }
-      this.eventBus.emit(MeframeEvent.PlaybackSeek, { timeUs: this.currentTimeUs });
-      if (this.wasPlayingBeforeSeek) {
-        await this.startPlayback();
-      } else {
-        this.state = previousState === "idle" ? "idle" : "paused";
-      }
-    } catch (error) {
-      if (seekId !== this.currentSeekId) {
-        return;
-      }
-      console.error("[PlaybackController] Seek error:", error);
-      this.eventBus.emit(MeframeEvent.PlaybackError, error);
-      this.state = previousState === "idle" ? "idle" : "paused";
-    }
+    const { done } = this.dispatch({
+      type: PlaybackActionType.Seek,
+      timeUs,
+      durationUs: this.duration
+    });
+    await done;
   }
-  // Playback properties
   setRate(rate) {
     const currentTimeUs = this.currentTimeUs;
     this.playbackRate = rate;
     this.startTimeUs = this.audioContext.currentTime * 1e6 - currentTimeUs / rate;
-    this.eventBus.emit(MeframeEvent.PlaybackRateChange, { rate });
     this.audioSession.setPlaybackRate(this.playbackRate);
+    this.eventBus.emit(MeframeEvent.PlaybackRateChange, { rate });
   }
   setVolume(volume) {
     this.volume = Math.max(0, Math.min(1, volume));
-    this.eventBus.emit(MeframeEvent.PlaybackVolumeChange, { volume: this.volume });
     this.audioSession.setVolume(this.volume);
+    this.eventBus.emit(MeframeEvent.PlaybackVolumeChange, { volume: this.volume });
   }
   setMute(muted) {
     if (muted) {
       this.audioSession.stopPlayback();
-    } else if (this.state === "playing") {
-      this.audioSession.startPlayback(this.currentTimeUs, this.audioContext);
+      return;
+    }
+    if (this.fsm.snapshot.state === PlaybackState.Playing) {
+      void this.audioSession.startPlayback(this.currentTimeUs, this.audioContext);
     }
   }
   setLoop(loop) {
     this.loop = loop;
   }
   get duration() {
-    const modelDuration = this.orchestrator.compositionModel?.durationUs;
-    if (modelDuration !== void 0) {
-      return modelDuration;
-    }
-    return 0;
+    return this.orchestrator.compositionModel?.durationUs ?? 0;
   }
   get isPlaying() {
-    return this.state === "playing";
+    return this.fsm.snapshot.state === PlaybackState.Playing;
   }
-  // Resume is just an alias for play
   resume() {
     this.play();
   }
@@ -227,82 +129,296 @@ class PlaybackController {
   off(event, handler) {
     this.eventBus.off(event, handler);
   }
-  // Private methods
-  playbackLoop() {
-    if (this.state !== "playing") {
-      if (this.rafId !== null) {
-        cancelAnimationFrame(this.rafId);
-        this.rafId = null;
+  // ========= State machine wiring =========
+  dispatch(action) {
+    const { token, commands } = this.fsm.dispatch(action, { currentTimeUs: this.currentTimeUs });
+    const done = this.executeCommands(commands, token);
+    return { token, done };
+  }
+  executeCommands(commands, token) {
+    const maybe = this.executeSeq(commands, token, 0);
+    return maybe ?? Promise.resolve();
+  }
+  executeSeq(commands, token, startIndex) {
+    for (let i = startIndex; i < commands.length; i++) {
+      if (!this.isCurrentToken(token)) return;
+      const maybe = this.executeCommand(commands[i], token);
+      if (maybe) {
+        return maybe.then(() => {
+          if (!this.isCurrentToken(token)) return;
+          const cont = this.executeSeq(commands, token, i + 1);
+          return cont ?? Promise.resolve();
+        });
       }
-      return;
     }
-    this.rafId = requestAnimationFrame(async () => {
-      if (this.state !== "playing") {
+  }
+  executePar(commands, token) {
+    const promises = [];
+    for (const c of commands) {
+      if (!this.isCurrentToken(token)) return;
+      const maybe = this.executeCommand(c, token);
+      if (maybe) promises.push(maybe);
+    }
+    if (promises.length === 0) return;
+    return Promise.all(promises).then(() => void 0);
+  }
+  executeCommand(command, token) {
+    if (!this.isCurrentToken(token)) return;
+    switch (command.type) {
+      case PlaybackCommandType.Seq:
+        return this.executeSeq(command.commands, token, 0);
+      case PlaybackCommandType.Par:
+        return this.executePar(command.commands, token);
+      case PlaybackCommandType.Try: {
+        const handleError = (error) => {
+          if (!this.isCurrentToken(token)) return;
+          if (command.ignoreWaiterReplacedError && error instanceof WaiterReplacedError) return;
+          if (command.logPrefix) console.error(command.logPrefix, error);
+          const onErrorDone = command.onError ? this.dispatch(command.onError).done : void 0;
+          const normalizeError = (e) => {
+            if (e instanceof Error) return e;
+            return new Error(typeof e === "string" ? e : JSON.stringify(e));
+          };
+          const emit = () => {
+            if (command.emitPlaybackError) {
+              const err = normalizeError(error);
+              this.eventBus.emit(MeframeEvent.PlaybackError, err);
+              this.eventBus.emit(MeframeEvent.Error, {
+                source: "playback",
+                error: err,
+                context: {
+                  command: command.logPrefix,
+                  onError: command.onError?.type
+                },
+                recoverable: false
+              });
+            }
+          };
+          if (onErrorDone) {
+            return onErrorDone.then(() => {
+              emit();
+            });
+          }
+          emit();
+        };
+        try {
+          const maybe = this.executeCommand(command.command, token);
+          if (maybe) {
+            return maybe.catch(handleError);
+          }
+          return;
+        } catch (error) {
+          return handleError(error) ?? Promise.resolve();
+        }
+      }
+      case PlaybackCommandType.Dispatch:
+        return this.dispatch(command.action).done;
+      case PlaybackCommandType.SetTime: {
+        this.currentTimeUs = command.timeUs;
+        return;
+      }
+      case PlaybackCommandType.SetFrozenTime:
+      case PlaybackCommandType.SetWantsPlay:
+      case PlaybackCommandType.SetState: {
+        return;
+      }
+      case PlaybackCommandType.CancelRaf: {
+        this.cancelRaf();
+        return;
+      }
+      case PlaybackCommandType.StopAudio: {
+        this.audioSession.stopPlayback();
+        return;
+      }
+      case PlaybackCommandType.ResetAudioPlaybackStates: {
+        this.audioSession.resetPlaybackStates();
         return;
       }
-      this.updateTime();
-      if (this.state !== "playing") {
+      case PlaybackCommandType.ResetAudioSession: {
+        this.audioSession.reset();
         return;
       }
-      if (this.currentTimeUs - this.lastAudioScheduleTime >= this.AUDIO_SCHEDULE_INTERVAL) {
-        await this.audioSession.scheduleAudio(this.currentTimeUs, this.audioContext);
-        this.lastAudioScheduleTime = this.currentTimeUs;
+      case PlaybackCommandType.ClearCanvas: {
+        this.clearCanvas();
+        return;
       }
-      await this.renderCurrentFrame(this.currentTimeUs);
-      if (this.state !== "playing") {
+      case PlaybackCommandType.SetLastAudioScheduleTime: {
+        this.lastAudioScheduleTime = command.timeUs;
         return;
       }
-      const now = performance.now();
-      if (this.lastFrameTime > 0) {
-        const deltaTime = now - this.lastFrameTime;
-        const instantFps = 1e3 / deltaTime;
-        this.fps = this.fps > 0 ? this.fps * 0.9 + instantFps * 0.1 : instantFps;
+      case PlaybackCommandType.SetStartTimeBase: {
+        this.startTimeUs = command.startTimeUs;
+        return;
       }
-      this.lastFrameTime = now;
-      this.frameCount++;
-      this.orchestrator.cacheManager.setWindow(this.currentTimeUs);
-      this.playbackLoop();
+      case PlaybackCommandType.SyncTimeBaseToAudioClock: {
+        this.startTimeUs = this.audioContext.currentTime * 1e6 - command.timeUs / this.playbackRate;
+        return;
+      }
+      case PlaybackCommandType.InitWindow: {
+        this.initWindow(command.timeUs);
+        return;
+      }
+      case PlaybackCommandType.SetCacheWindow: {
+        this.orchestrator.cacheManager.setWindow(command.timeUs);
+        return;
+      }
+      case PlaybackCommandType.Emit: {
+        if (command.payload === void 0) {
+          this.eventBus.emit(command.event);
+        } else {
+          this.eventBus.emit(command.event, command.payload);
+        }
+        return;
+      }
+      case PlaybackCommandType.RenderFrame: {
+        return this.renderCurrentFrame(command.timeUs, {
+          mode: command.mode,
+          relativeTimeUs: command.relativeTimeUs
+        });
+      }
+      case PlaybackCommandType.MaybeRenderKeyframePreview: {
+        return this.orchestrator.tryRenderKeyframe(command.timeUs).then((keyframeTimeUs) => {
+          if (!this.isCurrentToken(token)) return;
+          if (keyframeTimeUs === null) return;
+          return this.orchestrator.getRenderState(command.timeUs, {
+            mode: "probe",
+            relativeTimeUs: keyframeTimeUs
+          }).then((keyframeRenderState) => {
+            if (!this.isCurrentToken(token)) return;
+            if (!keyframeRenderState) return;
+            return this.compose(command.timeUs, keyframeRenderState);
+          });
+        });
+      }
+      case PlaybackCommandType.EnsureAudio: {
+        return this.audioSession.ensureAudioForTime(command.timeUs, {
+          mode: command.mode
+        });
+      }
+      case PlaybackCommandType.GetFrame: {
+        return this.orchestrator.getFrame(command.timeUs, {
+          mode: command.mode,
+          preheat: command.preheat
+        }).then((frame) => {
+          if (!frame && command.mode === "blocking") {
+            throw new Error(
+              `[PlaybackController] GetFrame miss in blocking mode at ${command.timeUs}`
+            );
+          }
+        });
+      }
+      case PlaybackCommandType.StartAudioPlayback: {
+        return this.audioSession.startPlayback(command.timeUs, this.audioContext);
+      }
+      case PlaybackCommandType.ProbeStartReady: {
+        const audioWindowEnd = Math.min(
+          this.duration,
+          command.timeUs + this.AUDIO_READY_PROBE_WINDOW
+        );
+        const audioReady = this.audioSession.isAudioResourceWindowReady(
+          command.timeUs,
+          audioWindowEnd
+        );
+        const videoReady = this.isVideoResourceReadyAtTime(command.timeUs);
+        if (audioReady && videoReady) return;
+        if (!audioReady) {
+          void this.audioSession.ensureAudioForTime(command.timeUs, { mode: "probe" });
+        }
+        if (!videoReady) {
+          void this.orchestrator.getFrame(command.timeUs, { mode: "probe" });
+        }
+        this.dispatch({
+          type: PlaybackActionType.EnterBuffering,
+          timeUs: command.timeUs,
+          bumpToken: true,
+          reason: "startup"
+        });
+        return;
+      }
+      case PlaybackCommandType.StartRafLoop: {
+        this.startPlaybackLoop(token);
+        return;
+      }
+    }
+  }
+  cancelRaf() {
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+  }
+  isCurrentToken(token) {
+    return token === this.fsm.snapshot.token;
+  }
+  startPlaybackLoop(token) {
+    this.rafId = requestAnimationFrame(() => {
+      void this.onRafTick(token);
     });
   }
-  updateTime() {
-    const elapsedUs = (this.audioContext.currentTime * 1e6 - this.startTimeUs) * this.playbackRate;
-    this.currentTimeUs = elapsedUs;
-    if (this.currentTimeUs >= this.duration) {
-      if (this.loop) {
-        this.currentTimeUs = 0;
-        this.startTimeUs = this.audioContext.currentTime * 1e6;
-        this.audioSession.resetPlaybackStates();
-        this.lastAudioScheduleTime = 0;
-        this.initWindow(0);
-      } else {
-        this.pause();
-        this.currentTimeUs = 0;
-        this.state = "ended";
-        this.eventBus.emit(MeframeEvent.PlaybackEnded, { timeUs: this.duration });
-      }
+  async onRafTick(token) {
+    if (!this.isCurrentToken(token) || this.fsm.snapshot.state !== PlaybackState.Playing) {
+      return;
+    }
+    const candidateTimeUs = (this.audioContext.currentTime * 1e6 - this.startTimeUs) * this.playbackRate;
+    this.dispatch({
+      type: PlaybackActionType.ClockTick,
+      candidateTimeUs,
+      durationUs: this.duration,
+      loop: this.loop,
+      audioNowUs: this.audioContext.currentTime * 1e6
+    });
+    if (!this.isCurrentToken(token) || this.fsm.snapshot.state !== PlaybackState.Playing) {
+      return;
+    }
+    const audioWindowEnd = Math.min(
+      this.duration,
+      this.currentTimeUs + this.AUDIO_READY_PROBE_WINDOW
+    );
+    if (!this.audioSession.isAudioResourceWindowReady(this.currentTimeUs, audioWindowEnd)) {
+      void this.audioSession.ensureAudioForTime(this.currentTimeUs, { mode: "probe" });
+      this.dispatch({ type: PlaybackActionType.EnterBuffering, timeUs: this.currentTimeUs });
+      return;
+    }
+    if (this.currentTimeUs - this.lastAudioScheduleTime >= this.AUDIO_SCHEDULE_INTERVAL) {
+      await this.audioSession.scheduleAudio(this.currentTimeUs, this.audioContext);
+      if (!this.isCurrentToken(token) || this.fsm.snapshot.state !== PlaybackState.Playing) return;
+      this.lastAudioScheduleTime = this.currentTimeUs;
+    }
+    const renderState = await this.orchestrator.getRenderState(this.currentTimeUs, {
+      mode: "probe"
+    });
+    if (!this.isCurrentToken(token) || this.fsm.snapshot.state !== PlaybackState.Playing) {
+      return;
+    }
+    if (!renderState) {
+      this.dispatch({ type: PlaybackActionType.EnterBuffering, timeUs: this.currentTimeUs });
+      return;
     }
-    this.eventBus.emit(MeframeEvent.PlaybackTimeUpdate, { timeUs: this.currentTimeUs });
+    await this.compose(this.currentTimeUs, renderState);
+    if (!this.isCurrentToken(token) || this.fsm.snapshot.state !== PlaybackState.Playing) return;
+    this.updateFps();
+    this.frameCount++;
+    this.orchestrator.cacheManager.setWindow(this.currentTimeUs);
     this.checkAndPreheatWindow();
+    if (!this.isCurrentToken(token) || this.fsm.snapshot.state !== PlaybackState.Playing) return;
+    this.startPlaybackLoop(token);
+  }
+  updateFps() {
+    const now = performance.now();
+    if (this.lastFrameTime > 0) {
+      const deltaTime = now - this.lastFrameTime;
+      const instantFps = 1e3 / deltaTime;
+      this.fps = this.fps > 0 ? this.fps * 0.9 + instantFps * 0.1 : instantFps;
+    }
+    this.lastFrameTime = now;
   }
-  /**
-   * Initialize window at given time (called on play/seek)
-   * Sets unified window for both video and audio
-   */
   initWindow(timeUs) {
     this.windowEnd = timeUs + this.WINDOW_DURATION;
     this.preheatInProgress = false;
     this.orchestrator.cacheManager.setWindow(timeUs);
   }
-  /**
-   * Check if approaching window end and trigger preheat for next window
-   *
-   * Strategy: Unified sliding window for both video and audio
-   * - Current window: [windowStart, windowEnd] (3s duration)
-   * - When playback reaches windowEnd - 1s, preheat next window
-   * - Next window: [windowEnd, windowEnd + 3s]
-   */
   checkAndPreheatWindow() {
-    if (this.preheatInProgress || this.state !== "playing") {
+    if (this.preheatInProgress || this.fsm.snapshot.state !== PlaybackState.Playing) {
       return;
     }
     const distanceToWindowEnd = this.windowEnd - this.currentTimeUs;
@@ -311,15 +427,11 @@ class PlaybackController {
       return;
     }
     if (distanceToWindowEnd > 0 && distanceToWindowEnd <= this.PREHEAT_DISTANCE) {
-      this.preheatNextWindow();
+      void this.preheatNextWindow();
     }
   }
-  /**
-   * Preheat next window by decoding from current playback time
-   * Supports cross-clip window preheating for seamless playback
-   * Preheats both video and audio in parallel
-   */
   async preheatNextWindow() {
+    if (this.preheatInProgress) return;
     this.preheatInProgress = true;
     try {
       const windowStart = this.currentTimeUs;
@@ -335,7 +447,7 @@ class PlaybackController {
           this.orchestrator.preheatClipWindow(clip.id, clipWindowStart, clipWindowEnd, windowStart)
         );
       }
-      preheatPromises.push(this.audioSession.ensureAudioForTime(windowStart, { immediate: false }));
+      preheatPromises.push(this.audioSession.ensureAudioForTime(windowStart, { mode: "blocking" }));
       await Promise.all(preheatPromises);
       this.windowEnd = windowEnd;
     } catch (error) {
@@ -344,70 +456,38 @@ class PlaybackController {
       this.preheatInProgress = false;
     }
   }
-  async renderCurrentFrame(timeUs) {
+  async renderCurrentFrame(timeUs, options) {
     if (!this.videoComposer) {
       console.error("[PlaybackController] VideoComposer not initialized");
       return;
     }
-    try {
-      const renderState = await this.orchestrator.getRenderState(timeUs, {
-        immediate: this.state === "playing"
-      });
-      if (!renderState) {
-        if (this.state === "playing") {
-          await this.handlePlaybackBuffering(timeUs);
-        }
-        return;
+    const renderState = await this.orchestrator.getRenderState(timeUs, {
+      mode: options.mode,
+      relativeTimeUs: options.relativeTimeUs
+    });
+    if (!renderState) {
+      if (options.mode === "blocking") {
+        throw new Error(`[PlaybackController] RenderFrame miss in blocking mode at ${timeUs}`);
       }
-      await this.videoComposer.composeFrame({
-        timeUs,
-        layers: renderState.layers,
-        transition: renderState.transition
-      });
-    } catch (error) {
-      console.error("Render error:", error);
-      this.eventBus.emit(MeframeEvent.PlaybackError, error);
-    }
-  }
-  async handlePlaybackBuffering(timeUs) {
-    if (this.state !== "playing") {
       return;
     }
-    const seekId = this.currentSeekId;
-    this.state = "buffering";
-    this.eventBus.emit(MeframeEvent.PlaybackBuffering);
-    this.audioSession.stopPlayback();
-    try {
-      this.orchestrator.cacheManager.setWindow(timeUs);
-      await this.orchestrator.getFrame(timeUs, { immediate: false });
-      await this.audioSession.ensureAudioForTime(timeUs, { immediate: false });
-      if (seekId !== this.currentSeekId || this.state !== "buffering") {
-        return;
-      }
-      this.state = "playing";
-      this.startTimeUs = this.audioContext.currentTime * 1e6 - timeUs / this.playbackRate;
-      this.lastAudioScheduleTime = 0;
-      await this.audioSession.startPlayback(timeUs, this.audioContext);
-      this.eventBus.emit(MeframeEvent.PlaybackPlay);
-      if (!this.rafId) {
-        this.playbackLoop();
-      }
-    } catch (error) {
-      if (error instanceof WaiterReplacedError) {
-        return;
-      }
-      if (seekId !== this.currentSeekId) {
-        return;
-      }
-      console.error("[PlaybackController] Buffering error:", error);
-      this.state = "paused";
-      this.eventBus.emit(MeframeEvent.PlaybackError, error);
-    }
+    await this.compose(timeUs, renderState);
   }
-  clampTime(timeUs) {
-    return Math.max(0, Math.min(timeUs, this.duration));
+  async compose(timeUs, renderState) {
+    if (!this.videoComposer) return;
+    await this.videoComposer.composeFrame({
+      timeUs,
+      layers: renderState.layers,
+      transition: renderState.transition
+    });
   }
-  // Cleanup
+  clearCanvas() {
+    const ctx = this.canvas.getContext("2d");
+    if (ctx && "clearRect" in ctx) {
+      ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+  }
+  // ========= Cleanup / event handlers =========
   dispose() {
     this.stop();
     this.eventBus.off(MeframeEvent.CacheCover, this.onCacheCover);
@@ -418,8 +498,8 @@ class PlaybackController {
     }
   }
   onCacheCover = () => {
-    if (this.state === "idle" && this.currentTimeUs === 0) {
-      this.renderCurrentFrame(0);
+    if (this.fsm.snapshot.state === PlaybackState.Idle && this.currentTimeUs === 0) {
+      void this.renderCurrentFrame(0, { mode: "blocking" });
     }
   };
   onModelSet = () => {
@@ -431,13 +511,23 @@ class PlaybackController {
       fps: model.fps || 30,
       backgroundColor: model.renderConfig?.backgroundColor || "#000"
     });
-    this.audioSession.ensureAudioForTime(this.currentTimeUs, { immediate: false });
-    this.renderCurrentFrame(this.currentTimeUs);
+    void this.audioSession.ensureAudioForTime(this.currentTimeUs, { mode: "blocking" });
+    void this.renderCurrentFrame(this.currentTimeUs, { mode: "blocking" });
   };
   setupEventListeners() {
     this.eventBus.on(MeframeEvent.CacheCover, this.onCacheCover);
     this.eventBus.on(MeframeEvent.ModelSet, this.onModelSet);
   }
+  isVideoResourceReadyAtTime(timeUs) {
+    const model = this.orchestrator.compositionModel;
+    if (!model) return true;
+    const clip = model.getClipsAtTime(timeUs, model.mainTrackId)[0];
+    if (!clip || !("resourceId" in clip) || typeof clip.resourceId !== "string")
+      return true;
+    const resourceId = clip.resourceId;
+    const resource = model.getResource(resourceId);
+    return resource?.state === "ready";
+  }
 }
 export {
   PlaybackController