Add client-side jitter buffer + steady render clock for smooth playback

index.html

@@ -352,47 +352,99 @@ async function initClient(){
   if(!state.client) state.client = await Client.connect(window.location.origin);
 }
 
-// --- Frame decode + paint ---
-// Decode each incoming JPEG and paint it to the canvas as soon as it is ready.
-// We always keep only the FRESHEST pending frame (coalesce) so a slow decode
-// can never build up a backlog / play stale buffered frames — the visible
-// output tracks the real generation rate reported by the fps counter.
-let pendingFrame = null;   // {bytes, blk, fps} newest arrived, not yet decoded
-let decoding = false;
-
-async function drainFrames(){
-  if(decoding) return;
-  decoding = true;
+// --- Frame decode + jitter buffer + steady render clock ---
+// Rendering is DECOUPLED from network arrival. WebSocket messages only decode
+// frames into a small jitter buffer; a steady render clock (requestAnimationFrame)
+// then pulls the freshest decoded frame at a smoothed target interval and paints
+// it. This absorbs network jitter and the server's block-boundary bursts so the
+// visible cadence stays even instead of "burst of N frames, then a gap".
+//
+// The buffer is intentionally shallow (JITTER_MAX): if frames arrive faster than
+// we render, older ones are dropped (coalesced) rather than queued, so we never
+// accumulate buffering delay that would later flush as a burst of stale frames.
+const JITTER_MAX = 3;              // max decoded frames held before we drop-oldest
+const JITTER_MIN = 1;              // frames to buffer before the render clock starts
+let jitterBuf = [];                // [{bitmap, blk, fps}] decoded, awaiting display
+let renderPrimed = false;          // becomes true once JITTER_MIN frames buffered
+let renderInterval = 1000 / 16;    // ms between paints; adapted to server fps (EMA)
+let lastPaint = 0;                 // performance.now() of last painted frame
+let lastArrival = 0;               // performance.now() of last WS frame (for interval est.)
+let arrivalEma = 0;                // EMA of inter-arrival gap (ms)
+
+async function ingestFrame(bytes, blk, fps){
+  // Estimate the true incoming cadence from arrival timing and adapt the render
+  // interval toward it (bounded), so the steady clock matches the real fps.
+  const now = performance.now();
+  if(lastArrival){
+    const gap = now - lastArrival;
+    arrivalEma = arrivalEma ? (0.2 * gap + 0.8 * arrivalEma) : gap;
+    const tgt = Math.min(200, Math.max(20, arrivalEma));   // clamp 5–50 fps
+    renderInterval = 0.2 * tgt + 0.8 * renderInterval;
+  }
+  lastArrival = now;
+
+  let bitmap = null;
   try{
-    while(pendingFrame){
-      const { bytes, blk, fps } = pendingFrame;
-      pendingFrame = null;               // grab the freshest, drop anything older
-      let painted = false;
-      try{
-        const bitmap = await createImageBitmap(new Blob([bytes], {type:"image/jpeg"}));
-        viewCtx.drawImage(bitmap, 0, 0, view.width, view.height);
-        if(bitmap.close) bitmap.close();
-        painted = true;
-      }catch(err){
-        // Fallback for browsers without createImageBitmap JPEG support.
-        painted = await paintViaImage(bytes);
-      }
-      if(painted){
-        if(!state.playing){ hideOverlay(); setPlaying(true); setStatus("playing","Playing"); }
-        frameValue.textContent = blk;
-        fpsValue.textContent = fps.toFixed(1);
-      }
-    }
-  }finally{
-    decoding = false;
+    bitmap = await createImageBitmap(new Blob([bytes], {type:"image/jpeg"}));
+  }catch(err){
+    // Fallback path for browsers without createImageBitmap JPEG support:
+    // paint straight to canvas (bypasses buffer but keeps the stream alive).
+    await paintViaImage(bytes, blk, fps);
+    return;
+  }
+  jitterBuf.push({ bitmap, blk, fps });
+  // Drop-oldest to keep the buffer shallow (avoid stale-frame burst on flush).
+  while(jitterBuf.length > JITTER_MAX){
+    const stale = jitterBuf.shift();
+    if(stale.bitmap && stale.bitmap.close) stale.bitmap.close();
   }
+  if(!renderPrimed && jitterBuf.length >= JITTER_MIN){
+    renderPrimed = true;
+    lastPaint = performance.now() - renderInterval;   // paint first frame promptly
+  }
+}
+
+function paintBitmap(entry){
+  viewCtx.drawImage(entry.bitmap, 0, 0, view.width, view.height);
+  if(entry.bitmap && entry.bitmap.close) entry.bitmap.close();
+  if(!state.playing){ hideOverlay(); setPlaying(true); setStatus("playing","Playing"); }
+  frameValue.textContent = entry.blk;
+  fpsValue.textContent = entry.fps.toFixed(1);
+}
+
+// Steady render clock: runs continuously via rAF while playing; pulls at most one
+// buffered frame per render-interval so display timing is even, not arrival-tied.
+function renderClock(){
+  requestAnimationFrame(renderClock);
+  if(!renderPrimed || jitterBuf.length === 0) return;
+  const now = performance.now();
+  if(now - lastPaint < renderInterval) return;   // not yet this frame's slot
+  const entry = jitterBuf.shift();               // freshest frames kept; oldest painted in order
+  lastPaint = now;
+  paintBitmap(entry);
+}
+requestAnimationFrame(renderClock);
+
+function resetJitterBuffer(){
+  for(const e of jitterBuf){ if(e.bitmap && e.bitmap.close) e.bitmap.close(); }
+  jitterBuf = [];
+  renderPrimed = false;
+  lastArrival = 0;
+  arrivalEma = 0;
 }
 
-function paintViaImage(bytes){
+function paintViaImage(bytes, blk, fps){
   return new Promise((resolve)=>{
     const url = URL.createObjectURL(new Blob([bytes], {type:"image/jpeg"}));
     const im = new Image();
-    im.onload = ()=>{ viewCtx.drawImage(im, 0, 0, view.width, view.height); URL.revokeObjectURL(url); resolve(true); };
+    im.onload = ()=>{
+      viewCtx.drawImage(im, 0, 0, view.width, view.height);
+      URL.revokeObjectURL(url);
+      if(!state.playing){ hideOverlay(); setPlaying(true); setStatus("playing","Playing"); }
+      if(typeof blk !== "undefined") frameValue.textContent = blk;
+      if(typeof fps !== "undefined") fpsValue.textContent = fps.toFixed(1);
+      resolve(true);
+    };
     im.onerror = ()=>{ URL.revokeObjectURL(url); resolve(false); };
     im.src = url;
   });
@@ -408,10 +460,9 @@ function connectWS(){
       const dv = new DataView(e.data);
       const blk = dv.getUint32(0);
       const fps = dv.getUint32(4)/10;
-      // Store the newest frame's bytes and decode/paint immediately (coalescing
-      // any frame that hasn't been painted yet), so display keeps pace with fps.
-      pendingFrame = { bytes: e.data.slice(8), blk, fps };
-      drainFrames();
+      // Decode into the jitter buffer; the steady render clock paints on its own
+      // cadence, so display timing is decoupled from network arrival jitter.
+      ingestFrame(e.data.slice(8), blk, fps);
     }else{
       try{
         const msg = JSON.parse(e.data);
@@ -498,7 +549,7 @@ async function startWorld(){
 async function stopWorld(){
   try{ if(state.client) await state.client.predict("/stop_game", { session_id: state.sessionId }); }catch{}
   if(state.ws){ try{ state.ws.send(JSON.stringify({type:"stop"})); }catch{} state.ws.close(); state.ws=null; }
-  pendingFrame = null;
+  resetJitterBuffer();
   stopCtrlLoop();
   setPlaying(false);
   state.pressed.clear(); renderKeys();