@@ -134,3 +134,82 @@ describe("TransportClock eliminates pause/play drift (issue #668)", () => {
     // No two clocks can diverge because there is only one.
   });
 });
+
+describe("TransportClock end-of-playback (loop semantics)", () => {
+  it("reachedEnd returns true at duration boundary", () => {
+    let ms = 0;
+    const clock = new TransportClock({ nowMs: () => ms, duration: 5 });
+    clock.play();
+    ms += 5000;
+    expect(clock.reachedEnd()).toBe(true);
+    expect(clock.now()).toBe(5);
+  });
+
+  it("clock auto-caps at duration and refuses to advance past it", () => {
+    let ms = 0;
+    const clock = new TransportClock({ nowMs: () => ms, duration: 3 });
+    clock.play();
+    ms += 10000;
+    expect(clock.now()).toBe(3);
+    expect(clock.reachedEnd()).toBe(true);
+  });
+
+  it("seek to 0 after reaching end allows replay", () => {
+    let ms = 0;
+    const clock = new TransportClock({ nowMs: () => ms, duration: 5 });
+    clock.play();
+    ms += 5000;
+    expect(clock.reachedEnd()).toBe(true);
+    clock.pause();
+    clock.seek(0);
+    expect(clock.now()).toBe(0);
+    expect(clock.reachedEnd()).toBe(false);
+    expect(clock.play()).toBe(true);
+    ms += 2000;
+    expect(clock.now()).toBe(2);
+  });
+
+  it("pause + seek to end + play is rejected (no infinite loop)", () => {
+    let ms = 0;
+    const clock = new TransportClock({ nowMs: () => ms, duration: 5 });
+    clock.seek(5);
+    expect(clock.play()).toBe(false);
+    expect(clock.isPlaying()).toBe(false);
+  });
+});
+
+describe("TransportClock + simulated timeline wiring", () => {
+  it("clock drives timeline seek on each tick", () => {
+    let ms = 0;
+    const clock = new TransportClock({ nowMs: () => ms, duration: 10 });
+    const seekLog: number[] = [];
+    const mockSeek = (t: number) => seekLog.push(t);
+
+    clock.play();
+    for (let i = 0; i < 5; i++) {
+      ms += 16;
+      mockSeek(clock.now());
+    }
+
+    expect(seekLog.length).toBe(5);
+    expect(seekLog[0]).toBeCloseTo(0.016, 5);
+    expect(seekLog[4]).toBeCloseTo(0.08, 5);
+    for (let i = 1; i < seekLog.length; i++) {
+      expect(seekLog[i]).toBeGreaterThan(seekLog[i - 1]);
+    }
+  });
+
+  it("forceSync threshold: drift above 20ms is correctable", () => {
+    let ms = 0;
+    const clock = new TransportClock({ nowMs: () => ms, duration: 10 });
+    clock.play();
+    ms += 2000;
+
+    const clockTime = clock.now();
+    const simulatedAudioTime = clockTime - 0.025;
+    const drift = Math.abs(clockTime - simulatedAudioTime);
+
+    expect(drift).toBeGreaterThan(0.02);
+    expect(drift).toBeLessThan(0.04);
+  });
+});
@@ -1695,6 +1695,11 @@ export function initSandboxRuntimeModular(): void {
       state.currentTime = t;
       seekTimelineAndAdapters(t);
 
+      // Looping is handled at the player layer (<hyperframes-player>),
+      // not the runtime. The clock pauses at duration; GSAP's repeat:-1
+      // is bypassed because we drive tl.totalTime(t) directly. The
+      // parent observes isPlaying=false at end and re-issues seek(0)+play()
+      // if its loop attribute is set.
       if (clock.isPlaying() && clock.reachedEnd()) {
         clock.pause();
         state.isPlaying = false;
@@ -1822,18 +1827,27 @@ export function initSandboxRuntimeModular(): void {
     state.capturedTimeline.pause();
   }
 
-  // Sync the __player API compat object with the overridden player methods.
-  // createPlayerApiCompat captures function references at construction time,
-  // so we must patch them after the transport overrides are installed.
+  // Re-delegate __player methods through the live `player` object so
+  // transport clock overrides are visible to iframe consumers reading
+  // window.__player. Uses property delegation so future methods added
+  // to createPlayerApiCompat are forwarded automatically.
   const playerApi = window.__player;
   if (playerApi) {
-    playerApi.play = player.play;
-    playerApi.pause = player.pause;
-    playerApi.seek = player.seek;
-    playerApi.renderSeek = player.renderSeek;
-    playerApi.getTime = player.getTime;
-    playerApi.getDuration = player.getDuration;
-    playerApi.isPlaying = player.isPlaying;
+    const delegated = [
+      "play",
+      "pause",
+      "seek",
+      "renderSeek",
+      "getTime",
+      "getDuration",
+      "isPlaying",
+    ] as const;
+    for (const key of delegated) {
+      Object.defineProperty(playerApi, key, {
+        get: () => player[key],
+        configurable: true,
+      });
+    }
   }
 
   // Start the rAF tick loop
 
@@ -168,8 +168,24 @@ export function syncRuntimeMedia(params: {
         // ignore unsupported playbackRate
         swallow("runtime.media.site1", err);
       }
-      // Drift correction. Forcing `el.currentTime = relTime` every frame
-      // causes an audible seek+rebuffer hiccup (readyState drops briefly).
+      // Drift correction — three tiers:
+      //
+      // 1. Hard sync (0.5s): first tick, timeline jumps (scrub), catastrophic
+      //    drift (>3s). Unconditional seek — accepts brief rebuffer cost.
+      //    Forcing el.currentTime every frame causes audible seek hiccups
+      //    (readyState drops briefly), so we only hard-seek when necessary.
+      //
+      // 2. Strict sync (40ms, 2 consecutive samples): catches accumulated
+      //    drift from pause/play toggling or browser media pipeline latency.
+      //    Offset-stabilization guard (4ms/tick) prevents false corrections
+      //    during initial buffering where offset grows naturally.
+      //
+      // 3. Force sync (20ms): on play/pause/seek/rate transitions, correct
+      //    any drift >20ms immediately via the forceSync one-shot flag.
+      //
+      // The first tick a clip is active has no previous offset to compare —
+      // treated as hard resync so sub-compositions with non-zero mediaStart
+      // land on the right frame.
       const STRICT_DRIFT_THRESHOLD = 0.04;
       const STRICT_REQUIRED_SAMPLES = 2;
 
@@ -182,6 +198,10 @@ export function syncRuntimeMedia(params: {
       const offsetJumped = !firstTickOfClip && Math.abs(offset - prevOffset!) > 0.5;
       const catastrophicDrift = drift > 3;
       const hardSync = drift > 0.5 && (firstTickOfClip || offsetJumped || catastrophicDrift);
+      // Only apply strict sync when offset has stabilized (not growing).
+      // During initial buffering, offset grows ~16ms/tick as the timeline
+      // advances while media stays at 0. Accumulated drift from pause/play
+      // toggling shows up as a stable, non-zero offset (delta near 0).
       const offsetStabilized = prevOffset !== undefined && Math.abs(offset - prevOffset) < 0.004;
       let strictSync = false;
       if (!hardSync && !firstTickOfClip && offsetStabilized && drift > STRICT_DRIFT_THRESHOLD) {