From 0f84428fd8a5770a685b4be5c9f2a2fb8d0a7a2f Mon Sep 17 00:00:00 2001
From: Claude Agent <noreply@anthropic.com>
Date: Mon, 20 Apr 2026 22:37:13 +0000
Subject: [PATCH 1/4] fix(viewer): eliminate dual-decoder race and seek-flood
 jerkiness

- Share a single HTMLVideoElement decoder for both playback and filmstrip
  thumb capture. Drop the hidden extractor <video>, its canvas/ctx, and
  the onseeked-based busy flag. Thumb drain is now a serialized Promise
  chain with a generation counter so new-video loads abort old chains.
- Add _seekToFrame helper that resolves on seeked + requestVideoFrameCallback
  (with a timeout/safety fallback). Used by _stepFrame, _jumpToFrame,
  slider input, scrub-play, and thumb capture.
- Replace fixed-interval _scrubPlayTick with an async while-loop that
  awaits each seek, then throttles to 1/fps only if the decoder is faster
  than real-time. scrubPlayToggle guards against double-start.
- Render via a requestAnimationFrame batcher driven by 'seeked'; timeupdate
  is now loop-wrap only. Avoids duplicate _updateFivePanel calls per step.
- Detect real fps: rVFC median-delta probe first, then GET /api/video/fps
  (new ffprobe-backed Flask route), then fall back to 30. _initFrameScrubber
  no longer hardcodes 30.
- Round _jumpToFrame argument defensively.

ffprobe is optional on the host: the route returns 404 on absence and the
frontend falls back cleanly.
---
 src/telescope_routes.py |  75 ++++++++++
 static/telescope.js     | 316 ++++++++++++++++++++++++++--------------
 2 files changed, 278 insertions(+), 113 deletions(-)

diff --git a/src/telescope_routes.py b/src/telescope_routes.py
index 957f900..e2072a2 100644
--- a/src/telescope_routes.py
+++ b/src/telescope_routes.py
@@ -2708,6 +2708,74 @@ def isolate_transit_route():
         return handle_error(exc)
 
 
+def video_fps_route():
+    """GET /api/video/fps?path=captures/...
+
+    Probe an MP4's video-stream fps via ffprobe. Returns {"fps": <float>} on
+    success, or 404 {"error": "..."} on any failure (missing file, ffprobe
+    absent, parse error). The frontend falls back to 30 fps on non-200.
+    """
+    rel_path = request.args.get("path", "")
+    if not rel_path:
+        return jsonify({"error": "Missing path"}), 400
+
+    captures_abs = os.path.abspath("static/captures")
+    abs_path = os.path.abspath(os.path.join("static", rel_path))
+    if not abs_path.startswith(captures_abs):
+        return jsonify({"error": "Invalid file path"}), 403
+    if not os.path.exists(abs_path):
+        return jsonify({"error": "File not found"}), 404
+    if not abs_path.lower().endswith(".mp4"):
+        return jsonify({"error": "Only MP4 files supported"}), 400
+
+    ffprobe = os.getenv("FFPROBE_PATH", "") or "ffprobe"
+    # Derive ffprobe from ffmpeg path when FFMPEG is an absolute path and
+    # ffprobe sits next to it (common for bundled builds).
+    if FFMPEG and os.path.isabs(FFMPEG):
+        candidate = os.path.join(os.path.dirname(FFMPEG), "ffprobe")
+        if os.path.isfile(candidate):
+            ffprobe = candidate
+
+    try:
+        r = subprocess.run(
+            [
+                ffprobe,
+                "-v",
+                "error",
+                "-select_streams",
+                "v:0",
+                "-show_entries",
+                "stream=r_frame_rate",
+                "-of",
+                "csv=p=0",
+                abs_path,
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=3,
+        )
+        if r.returncode != 0:
+            return jsonify({"error": "ffprobe failed"}), 404
+        raw = r.stdout.decode("utf-8", errors="replace").strip()
+        if not raw:
+            return jsonify({"error": "empty ffprobe output"}), 404
+        if "/" in raw:
+            num, den = raw.split("/", 1)
+            fps = float(num) / float(den) if float(den) != 0 else 0.0
+        else:
+            fps = float(raw)
+        if fps <= 0 or fps > 1000:
+            return jsonify({"error": "implausible fps"}), 404
+        return jsonify({"fps": fps}), 200
+    except FileNotFoundError:
+        return jsonify({"error": "ffprobe not installed"}), 404
+    except subprocess.TimeoutExpired:
+        return jsonify({"error": "ffprobe timeout"}), 404
+    except Exception as exc:
+        logger.warning(f"[Telescope] video fps probe error: {exc}")
+        return jsonify({"error": str(exc)}), 404
+
+
 def composite_from_frames_route():
     """POST /telescope/files/composite-from-frames
 
@@ -4079,6 +4147,13 @@ def register_routes(app):
         methods=["POST"],
     )
 
+    app.add_url_rule(
+        "/api/video/fps",
+        "api_video_fps",
+        video_fps_route,
+        methods=["GET"],
+    )
+
     app.add_url_rule(
         "/telescope/composite",
         "telescope_composite_viewer",
diff --git a/static/telescope.js b/static/telescope.js
index 58332f8..b97b37b 100644
--- a/static/telescope.js
+++ b/static/telescope.js
@@ -3912,22 +3912,29 @@ function viewFile(path, name, opts) {
         const slider = document.getElementById('frameScrubSlider');
         slider.addEventListener('input', () => {
             const f = parseInt(slider.value, 10);
-            _currentFrame = f;
-            vid.currentTime = f / _videoFps;
+            _seekToFrame(vid, f);
         });
 
+        const _scheduleViewerRender = () => {
+            if (_renderPending) return;
+            _renderPending = true;
+            requestAnimationFrame(() => {
+                _renderPending = false;
+                const v = document.getElementById('hiddenVid');
+                if (!v) return;
+                _updateScrubPosition(v);
+                _updateFivePanel();
+            });
+        };
         const updateAfterSeek = () => {
             _currentFrame = Math.round(vid.currentTime * _videoFps);
-            _updateScrubPosition(vid);
-            _updateFivePanel();
+            _scheduleViewerRender();
         };
+        // timeupdate only handles loop wrap-around; render is driven by seeked.
         vid.addEventListener('timeupdate', () => {
             if (_loopSegment && _loopSegment.start != null && vid.currentTime >= _loopSegment.end) {
                 vid.currentTime = _loopSegment.start;
             }
-            _currentFrame = Math.round(vid.currentTime * _videoFps);
-            _updateScrubPosition(vid);
-            _updateFivePanel();
         });
         vid.addEventListener('seeked', updateAfterSeek);
         const _isDetClip = /\/det_[^/]+\.mp4$/i.test(path);
@@ -3951,10 +3958,16 @@ function viewFile(path, name, opts) {
                 _runIsolateTransit(apiPath, null);
             });
         };
-        vid.addEventListener('loadedmetadata', () => { _initFrameScrubber(vid); updateAfterSeek(); _maybeAutoIsolate(); });
+        const _initAfterMeta = async () => {
+            _videoFps = await _probeVideoFps(vid, path);
+            _initFrameScrubber(vid);
+            updateAfterSeek();
+            _extractFrameThumbs(vid);
+            _maybeAutoIsolate();
+        };
+        vid.addEventListener('loadedmetadata', _initAfterMeta, { once: true });
         vid.addEventListener('loadeddata', () => { updateAfterSeek(); });
-        if (vid.readyState >= 1) { _initFrameScrubber(vid); updateAfterSeek(); }
-        _extractFrameThumbs(vid);
+        if (vid.readyState >= 1) { _initAfterMeta(); }
     } else {
         const isDiff = name.includes('_diff');
         const isFrame = name.includes('_frame');
@@ -4046,14 +4059,11 @@ function closeFileViewer() {
     _frameThumbs = {};
     _thumbExtractionQueue = [];
     _thumbExtractionPending = new Set();
-    _thumbExtractionBusy = false;
-    _thumbExtractorCanvas = null;
-    _thumbExtractorCtx = null;
+    _thumbCanvas = null;
+    _thumbCtx = null;
+    _thumbGeneration++;
+    _thumbChain = Promise.resolve();
     _currentFrame = 0;
-    if (_thumbExtractorVid) {
-        try { document.body.removeChild(_thumbExtractorVid); } catch (e) {}
-        _thumbExtractorVid = null;
-    }
 
     if (viewer._filesModalWasOpen) {
         const filesModal = document.getElementById('filesModal');
@@ -4171,28 +4181,22 @@ function frameStepStop() {
     if (_frameStepTimer) { clearTimeout(_frameStepTimer); _frameStepTimer = null; }
 }
 
-// Scrubber playback (frame-by-frame at ~_videoFps using rAF)
-var _scrubPlayRAF = null;
+// Scrubber playback — serialized on seek completion, not a fixed interval.
 var _scrubPlayDir = 0;
-var _scrubPlayLastT = null;
+var _scrubPlayRunning = false;
 
 function scrubPlayToggle(dir) {
     if (_scrubPlayDir === dir) {
-        // Already playing this direction — stop
         _scrubPlayStop();
         return;
     }
-    _scrubPlayStop();
     _scrubPlayDir = dir;
-    _scrubPlayLastT = null;
-    _scrubPlayRAF = requestAnimationFrame(_scrubPlayTick);
     _scrubPlayUpdateBtns();
+    if (!_scrubPlayRunning) _scrubPlayLoop();
 }
 
 function _scrubPlayStop() {
-    if (_scrubPlayRAF) { cancelAnimationFrame(_scrubPlayRAF); _scrubPlayRAF = null; }
     _scrubPlayDir = 0;
-    _scrubPlayLastT = null;
     _scrubPlayUpdateBtns();
 }
 
@@ -4203,20 +4207,30 @@ function _scrubPlayUpdateBtns() {
     if (fwd) fwd.style.background = _scrubPlayDir ===  1 ? '#0a4' : '';
 }
 
-function _scrubPlayTick(ts) {
-    if (_scrubPlayDir === 0) return;
-    const interval = 1000 / (_videoFps || 30);
-    if (_scrubPlayLastT === null) _scrubPlayLastT = ts;
-    if (ts - _scrubPlayLastT >= interval) {
-        _scrubPlayLastT = ts;
-        const next = _currentFrame + _scrubPlayDir;
-        if (next < 0 || next >= _frameTotalCount) {
-            _scrubPlayStop();
-            return;
+async function _scrubPlayLoop() {
+    if (_scrubPlayRunning) return;
+    _scrubPlayRunning = true;
+    try {
+        while (_scrubPlayDir !== 0) {
+            const vid = document.getElementById('hiddenVid');
+            if (!vid || !vid.duration) break;
+            vid.pause();
+            const next = _currentFrame + _scrubPlayDir;
+            if (next < 0 || next >= _frameTotalCount) {
+                _scrubPlayStop();
+                break;
+            }
+            const tStart = performance.now();
+            await _seekToFrame(vid, next);
+            const target = 1000 / (_videoFps || 30);
+            const elapsed = performance.now() - tStart;
+            if (elapsed < target) {
+                await new Promise(r => setTimeout(r, target - elapsed));
+            }
         }
-        _stepFrame(_scrubPlayDir);
+    } finally {
+        _scrubPlayRunning = false;
     }
-    _scrubPlayRAF = requestAnimationFrame(_scrubPlayTick);
 }
 
 // ---------------------------------------------------------------------------
@@ -4224,19 +4238,105 @@ function _scrubPlayTick(ts) {
 // ---------------------------------------------------------------------------
 
 var _currentFrame = 0;
+var _renderPending = false;
+
+/** Seek `vid` to the given frame and resolve once the post-seek frame is
+ *  actually decoded (requestVideoFrameCallback) or seeked has fired +
+ *  a best-effort settle in the fallback path. */
+function _seekToFrame(vid, frame) {
+    if (!vid) return Promise.resolve();
+    const fps = _videoFps || 30;
+    const clamped = Math.max(0, Math.min((_frameTotalCount || 1) - 1, Math.round(frame)));
+    _currentFrame = clamped;
+    const useRVFC = typeof vid.requestVideoFrameCallback === 'function';
+    return new Promise(resolve => {
+        let done = false;
+        const finish = () => { if (!done) { done = true; resolve(); } };
+        const onSeeked = () => {
+            vid.removeEventListener('seeked', onSeeked);
+            if (useRVFC) {
+                try { vid.requestVideoFrameCallback(() => finish()); return; } catch (e) {}
+            }
+            // Fallback: allow one browser tick for the frame to present.
+            setTimeout(finish, 16);
+        };
+        vid.addEventListener('seeked', onSeeked, { once: true });
+        try {
+            vid.currentTime = clamped / fps;
+        } catch (e) {
+            vid.removeEventListener('seeked', onSeeked);
+            finish();
+        }
+        // Safety net: never hang forever.
+        setTimeout(finish, 1500);
+    });
+}
 
 function _stepFrame(dir) {
     const vid = document.getElementById('hiddenVid');
     if (!vid || !vid.duration) return;
     vid.pause();
-    const newFrame = Math.max(0, Math.min(_frameTotalCount - 1, _currentFrame + dir));
-    _currentFrame = newFrame;
-    vid.currentTime = newFrame / _videoFps;
+    _seekToFrame(vid, _currentFrame + dir);
+}
+
+/** Probe the video's real fps. Prefer requestVideoFrameCallback sampling
+ *  (fast, client-only); fall back to the ffprobe-backed server route; fall
+ *  back to 30. Resolves to a positive number. */
+async function _probeVideoFps(vid, path) {
+    try {
+        if (typeof vid.requestVideoFrameCallback === 'function') {
+            const deltas = [];
+            const wasMuted = vid.muted;
+            vid.muted = true;
+            await new Promise(res => {
+                let last = null;
+                let count = 0;
+                const cb = (_now, meta) => {
+                    if (last !== null) {
+                        const d = meta.mediaTime - last;
+                        if (d > 0 && d < 1) deltas.push(d);
+                    }
+                    last = meta.mediaTime;
+                    count++;
+                    if (count < 12 && deltas.length < 10) {
+                        try { vid.requestVideoFrameCallback(cb); } catch (e) { res(); }
+                    } else {
+                        res();
+                    }
+                };
+                try { vid.requestVideoFrameCallback(cb); } catch (e) { res(); }
+                vid.play().catch(() => {});
+                setTimeout(res, 1200);
+            });
+            try { vid.pause(); } catch (e) {}
+            vid.muted = wasMuted;
+            try { vid.currentTime = 0; } catch (e) {}
+            if (deltas.length >= 3) {
+                deltas.sort((a, b) => a - b);
+                const median = deltas[Math.floor(deltas.length / 2)];
+                if (median > 0) {
+                    const fps = 1 / median;
+                    if (fps > 5 && fps < 480) return Math.round(fps * 1000) / 1000;
+                }
+            }
+        }
+    } catch (e) { /* fall through */ }
+    // Server fallback
+    try {
+        const apiPath = (path || '').replace(/^\/static\//, '');
+        if (apiPath) {
+            const r = await fetch('/api/video/fps?path=' + encodeURIComponent(apiPath));
+            if (r.ok) {
+                const j = await r.json();
+                if (j && typeof j.fps === 'number' && j.fps > 0) return j.fps;
+            }
+        }
+    } catch (e) { /* fall through */ }
+    return 30;
 }
 
 function _initFrameScrubber(vid) {
     if (!vid || !vid.duration) return;
-    _videoFps = 30;
     _frameTotalCount = Math.round(vid.duration * _videoFps);
     const slider = document.getElementById('frameScrubSlider');
     if (slider) {
@@ -4270,95 +4370,84 @@ function _updateScrubPosition(vid) {
 
 var _frameThumbs = {};      // frame index -> data URL
 var _frameTotalCount = 0;
-var _thumbExtractorVid = null;
-var _thumbExtractorCanvas = null;
-var _thumbExtractorCtx = null;
-var _thumbExtractionBusy = false;
+var _thumbCanvas = null;
+var _thumbCtx = null;
 var _thumbExtractionQueue = [];
 var _thumbExtractionPending = new Set();
+var _thumbChain = Promise.resolve();
+var _thumbGeneration = 0;
 var _lastThumbQueueMs = 0;
 const THUMB_QUEUE_THROTTLE_MS = 120;
 
-/** Prepare a hidden extractor video for lightweight on-demand frame thumbnails. */
+/** Install a shared offscreen canvas sized from mainVid. Thumb extraction
+ *  reuses mainVid's own decoder — no second <video>, no decoder race. */
 function _extractFrameThumbs(mainVid) {
-    if (_thumbExtractorVid) {
-        try { document.body.removeChild(_thumbExtractorVid); } catch (e) {}
-        _thumbExtractorVid = null;
-    }
     _frameThumbs = {};
     _thumbExtractionQueue = [];
     _thumbExtractionPending = new Set();
-    _thumbExtractionBusy = false;
-    _thumbExtractorCanvas = null;
-    _thumbExtractorCtx = null;
-
-    const extVid = document.createElement('video');
-    extVid.src = mainVid.src;
-    extVid.muted = true;
-    extVid.preload = 'metadata';
-    extVid.style.cssText = 'position:absolute;left:-9999px;width:1px;height:1px;';
-    document.body.appendChild(extVid);
-    _thumbExtractorVid = extVid;
-
-    extVid.addEventListener('loadedmetadata', () => {
-        if (extVid !== _thumbExtractorVid) return;
-
-        const vw = extVid.videoWidth || 640;
-        const vh = extVid.videoHeight || 480;
-        const thumbW = Math.min(vw, 400);
-        const thumbH = Math.max(1, Math.round(thumbW * (vh / vw)));
-        _thumbExtractorCanvas = document.createElement('canvas');
-        _thumbExtractorCanvas.width = thumbW;
-        _thumbExtractorCanvas.height = thumbH;
-        _thumbExtractorCtx = _thumbExtractorCanvas.getContext('2d');
-        _queueFivePanelThumbs(_currentFrame);
-    }, { once: true });
+    _thumbGeneration++;
+    _thumbChain = Promise.resolve();
+
+    const vw = mainVid.videoWidth || 640;
+    const vh = mainVid.videoHeight || 480;
+    const thumbW = Math.min(vw, 400);
+    const thumbH = Math.max(1, Math.round(thumbW * (vh / vw)));
+    _thumbCanvas = document.createElement('canvas');
+    _thumbCanvas.width = thumbW;
+    _thumbCanvas.height = thumbH;
+    _thumbCtx = _thumbCanvas.getContext('2d');
+
+    _queueFivePanelThumbs(_currentFrame);
 }
 
 function _queueFrameThumb(frameIdx) {
-    if (!_thumbExtractorVid || !_thumbExtractorCtx || !_thumbExtractorCanvas) return;
+    if (!_thumbCtx || !_thumbCanvas) return;
     if (frameIdx < 0 || frameIdx >= _frameTotalCount) return;
     if (_frameThumbs[frameIdx] || _thumbExtractionPending.has(frameIdx)) return;
     _thumbExtractionPending.add(frameIdx);
     _thumbExtractionQueue.push(frameIdx);
 }
 
-function _drainThumbQueue() {
-    if (_thumbExtractionBusy) return;
-    if (!_thumbExtractorVid || !_thumbExtractorCtx || !_thumbExtractorCanvas) return;
-    const frameIdx = _thumbExtractionQueue.shift();
-    if (frameIdx === undefined) return;
-
-    _thumbExtractionBusy = true;
-    const extVid = _thumbExtractorVid;
-    const fps = _videoFps || 30;
+function _captureCurrentAsThumb(vid, frameIdx) {
+    try {
+        _thumbCtx.drawImage(vid, 0, 0, _thumbCanvas.width, _thumbCanvas.height);
+        _frameThumbs[frameIdx] = _thumbCanvas.toDataURL('image/jpeg', 0.85);
+    } catch (e) { /* ignore per-frame failures */ }
+    _thumbExtractionPending.delete(frameIdx);
+}
 
-    extVid.onseeked = () => {
-        if (extVid !== _thumbExtractorVid) {
-            _thumbExtractionPending.delete(frameIdx);
-            _thumbExtractionBusy = false;
-            requestAnimationFrame(_drainThumbQueue);
-            return;
+function _drainThumbQueue() {
+    if (!_thumbCtx || !_thumbCanvas) return;
+    if (_thumbExtractionQueue.length === 0) return;
+    if (_scrubPlayDir !== 0) return; // don't fight the play loop
+    const gen = _thumbGeneration;
+    _thumbChain = _thumbChain.then(async () => {
+        if (gen !== _thumbGeneration) return;
+        const vid = document.getElementById('hiddenVid');
+        if (!vid || !vid.duration) { _thumbExtractionQueue = []; return; }
+        const homeFrame = _currentFrame;
+        let movedPlayhead = false;
+        while (_thumbExtractionQueue.length > 0 && gen === _thumbGeneration && _scrubPlayDir === 0) {
+            const frameIdx = _thumbExtractionQueue.shift();
+            if (frameIdx === undefined) break;
+            if (_frameThumbs[frameIdx]) { _thumbExtractionPending.delete(frameIdx); continue; }
+            const curFrame = Math.round(vid.currentTime * (_videoFps || 30));
+            if (curFrame === frameIdx) {
+                _captureCurrentAsThumb(vid, frameIdx);
+            } else {
+                vid.pause();
+                await _seekToFrame(vid, frameIdx);
+                if (gen !== _thumbGeneration) return;
+                movedPlayhead = true;
+                _captureCurrentAsThumb(vid, frameIdx);
+            }
+            _updateFivePanel();
         }
-        try {
-            _thumbExtractorCtx.drawImage(extVid, 0, 0, _thumbExtractorCanvas.width, _thumbExtractorCanvas.height);
-            _frameThumbs[frameIdx] = _thumbExtractorCanvas.toDataURL('image/jpeg', 0.85);
-        } catch (e) {
-            // Ignore per-frame extraction failures and continue.
+        // Restore user's playhead if we moved it for thumb capture.
+        if (movedPlayhead && gen === _thumbGeneration && _scrubPlayDir === 0) {
+            await _seekToFrame(vid, homeFrame);
         }
-        _thumbExtractionPending.delete(frameIdx);
-        _thumbExtractionBusy = false;
-        _updateFivePanel();
-        requestAnimationFrame(_drainThumbQueue);
-    };
-
-    try {
-        extVid.currentTime = frameIdx / fps;
-    } catch (e) {
-        _thumbExtractionPending.delete(frameIdx);
-        _thumbExtractionBusy = false;
-        requestAnimationFrame(_drainThumbQueue);
-    }
+    }).catch(() => {});
 }
 
 function _queueFivePanelThumbs(centerFrame) {
@@ -4401,10 +4490,11 @@ function _updateFivePanel() {
 
 function _jumpToFrame(f) {
     const vid = document.getElementById('hiddenVid');
-    if (!vid || f < 0 || f >= _frameTotalCount) return;
+    const frame = Math.round(f);
+    if (!vid || frame < 0 || frame >= _frameTotalCount) return;
     vid.pause();
-    _currentFrame = f;
-    vid.currentTime = f / _videoFps;
+    _scrubPlayStop();
+    _seekToFrame(vid, frame);
 }
 
 function toggleMarkFrame() {

From 8d4f9d400ed65d60e21458225d8f0f2abcb0d43d Mon Sep 17 00:00:00 2001
From: Claude Agent <noreply@anthropic.com>
Date: Mon, 20 Apr 2026 23:29:00 +0000
Subject: [PATCH 2/4] fix(viewer): populate filmstrip thumbs during playback
 and on load

- Opportunistic thumb capture on every _seekToFrame completion
- Drain queue during playback (in-place capture only, no extra seeks)
- Await initial seek(0) before extracting thumbs; wait for videoWidth>0
- Prime the pump: capture frame 0 synchronously on load
- Guard 5-panel render against premature canvas access
- _VIDDBG flag for silent debug logging
---
 static/telescope.js | 107 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 96 insertions(+), 11 deletions(-)

diff --git a/static/telescope.js b/static/telescope.js
index b97b37b..4316aec 100644
--- a/static/telescope.js
+++ b/static/telescope.js
@@ -3961,8 +3961,14 @@ function viewFile(path, name, opts) {
         const _initAfterMeta = async () => {
             _videoFps = await _probeVideoFps(vid, path);
             _initFrameScrubber(vid);
-            updateAfterSeek();
+            // Ensure the playhead is settled at frame 0 and a real frame is
+            // decoded before we size the thumb canvas / draw anything.
+            await _seekToFrame(vid, 0);
             _extractFrameThumbs(vid);
+            // Prime the pump: guarantee the centre panel has content.
+            _captureLandedThumb(vid, 0);
+            _updateFivePanel();
+            updateAfterSeek();
             _maybeAutoIsolate();
         };
         vid.addEventListener('loadedmetadata', _initAfterMeta, { once: true });
@@ -4239,19 +4245,52 @@ async function _scrubPlayLoop() {
 
 var _currentFrame = 0;
 var _renderPending = false;
+var _fivePanelRetryScheduled = false;
+
+// Viewer debug logging. Leave false in production; flip to true when
+// diagnosing filmstrip / playback regressions.
+const _VIDDBG = false;
+function _vdbg(...args) { if (_VIDDBG) try { console.log('[vid]', ...args); } catch (e) {} }
+
+/** Capture whatever the decoder is currently showing into the shared
+ *  offscreen canvas, stored against `frameIdx`. No-op if already captured
+ *  or if the canvas isn't ready. Safe to call from any seek/play code path. */
+function _captureLandedThumb(vid, frameIdx) {
+    if (!_thumbCtx || !_thumbCanvas || !vid) return;
+    if (frameIdx < 0 || frameIdx >= _frameTotalCount) return;
+    if (_frameThumbs[frameIdx]) return;
+    try {
+        _thumbCtx.drawImage(vid, 0, 0, _thumbCanvas.width, _thumbCanvas.height);
+        const url = _thumbCanvas.toDataURL('image/jpeg', 0.85);
+        _frameThumbs[frameIdx] = url;
+        _thumbExtractionPending.delete(frameIdx);
+        _vdbg('captured', frameIdx, 'len=', url.length);
+    } catch (e) {
+        _vdbg('capture failed', frameIdx, e && e.message);
+    }
+}
 
 /** Seek `vid` to the given frame and resolve once the post-seek frame is
  *  actually decoded (requestVideoFrameCallback) or seeked has fired +
- *  a best-effort settle in the fallback path. */
+ *  a best-effort settle in the fallback path. Opportunistically captures
+ *  the landed frame into the thumb cache so playback/stepping also
+ *  populates the filmstrip. */
 function _seekToFrame(vid, frame) {
     if (!vid) return Promise.resolve();
     const fps = _videoFps || 30;
     const clamped = Math.max(0, Math.min((_frameTotalCount || 1) - 1, Math.round(frame)));
     _currentFrame = clamped;
     const useRVFC = typeof vid.requestVideoFrameCallback === 'function';
+    _vdbg('seek start', clamped);
     return new Promise(resolve => {
         let done = false;
-        const finish = () => { if (!done) { done = true; resolve(); } };
+        const finish = () => {
+            if (done) return;
+            done = true;
+            _captureLandedThumb(vid, clamped);
+            _vdbg('seek settle', clamped);
+            resolve();
+        };
         const onSeeked = () => {
             vid.removeEventListener('seeked', onSeeked);
             if (useRVFC) {
@@ -4316,7 +4355,11 @@ async function _probeVideoFps(vid, path) {
                 const median = deltas[Math.floor(deltas.length / 2)];
                 if (median > 0) {
                     const fps = 1 / median;
-                    if (fps > 5 && fps < 480) return Math.round(fps * 1000) / 1000;
+                    if (fps > 5 && fps < 480) {
+                        const rounded = Math.round(fps * 1000) / 1000;
+                        _vdbg('probe rVFC fps=', rounded);
+                        return rounded;
+                    }
                 }
             }
         }
@@ -4328,10 +4371,14 @@ async function _probeVideoFps(vid, path) {
             const r = await fetch('/api/video/fps?path=' + encodeURIComponent(apiPath));
             if (r.ok) {
                 const j = await r.json();
-                if (j && typeof j.fps === 'number' && j.fps > 0) return j.fps;
+                if (j && typeof j.fps === 'number' && j.fps > 0) {
+                    _vdbg('probe server fps=', j.fps);
+                    return j.fps;
+                }
             }
         }
     } catch (e) { /* fall through */ }
+    _vdbg('probe fallback fps=30');
     return 30;
 }
 
@@ -4381,21 +4428,34 @@ const THUMB_QUEUE_THROTTLE_MS = 120;
 
 /** Install a shared offscreen canvas sized from mainVid. Thumb extraction
  *  reuses mainVid's own decoder — no second <video>, no decoder race. */
-function _extractFrameThumbs(mainVid) {
+async function _extractFrameThumbs(mainVid) {
     _frameThumbs = {};
     _thumbExtractionQueue = [];
     _thumbExtractionPending = new Set();
     _thumbGeneration++;
     _thumbChain = Promise.resolve();
 
-    const vw = mainVid.videoWidth || 640;
-    const vh = mainVid.videoHeight || 480;
+    // On large (4K) sources videoWidth can still be 0 right after the probe's
+    // play/pause dance. Poll briefly before sizing the canvas.
+    let tries = 0;
+    while (!(mainVid.videoWidth > 0) && tries < 20) {
+        await new Promise(r => setTimeout(r, 50));
+        tries++;
+    }
+    if (!(mainVid.videoWidth > 0)) {
+        _vdbg('extract bail: videoWidth still 0');
+        return;
+    }
+
+    const vw = mainVid.videoWidth;
+    const vh = mainVid.videoHeight || Math.round(vw * 9 / 16);
     const thumbW = Math.min(vw, 400);
     const thumbH = Math.max(1, Math.round(thumbW * (vh / vw)));
     _thumbCanvas = document.createElement('canvas');
     _thumbCanvas.width = thumbW;
     _thumbCanvas.height = thumbH;
     _thumbCtx = _thumbCanvas.getContext('2d');
+    _vdbg('canvas', thumbW, 'x', thumbH);
 
     _queueFivePanelThumbs(_currentFrame);
 }
@@ -4419,7 +4479,6 @@ function _captureCurrentAsThumb(vid, frameIdx) {
 function _drainThumbQueue() {
     if (!_thumbCtx || !_thumbCanvas) return;
     if (_thumbExtractionQueue.length === 0) return;
-    if (_scrubPlayDir !== 0) return; // don't fight the play loop
     const gen = _thumbGeneration;
     _thumbChain = _thumbChain.then(async () => {
         if (gen !== _thumbGeneration) return;
@@ -4427,11 +4486,25 @@ function _drainThumbQueue() {
         if (!vid || !vid.duration) { _thumbExtractionQueue = []; return; }
         const homeFrame = _currentFrame;
         let movedPlayhead = false;
-        while (_thumbExtractionQueue.length > 0 && gen === _thumbGeneration && _scrubPlayDir === 0) {
+        while (_thumbExtractionQueue.length > 0 && gen === _thumbGeneration) {
             const frameIdx = _thumbExtractionQueue.shift();
             if (frameIdx === undefined) break;
             if (_frameThumbs[frameIdx]) { _thumbExtractionPending.delete(frameIdx); continue; }
             const curFrame = Math.round(vid.currentTime * (_videoFps || 30));
+            if (_scrubPlayDir !== 0) {
+                // Playing: only capture frames we're already sitting on.
+                // Anything else goes back on the queue for the play loop /
+                // _seekToFrame's opportunistic capture to pick up later.
+                if (curFrame === frameIdx) {
+                    _captureCurrentAsThumb(vid, frameIdx);
+                    _updateFivePanel();
+                } else {
+                    _thumbExtractionQueue.push(frameIdx);
+                    break;
+                }
+                continue;
+            }
+            // Paused: may seek to reach the frame.
             if (curFrame === frameIdx) {
                 _captureCurrentAsThumb(vid, frameIdx);
             } else {
@@ -4464,7 +4537,19 @@ function _updateFivePanel() {
     if (!panel) return;
     const total = _frameTotalCount || 1;
     const cur = _currentFrame;
-    _queueFivePanelThumbs(cur);
+    // If the thumb canvas isn't ready yet, draw placeholders and schedule
+    // a single retry once the canvas finishes setup.
+    if (!_thumbCanvas || !_thumbCtx) {
+        if (!_fivePanelRetryScheduled) {
+            _fivePanelRetryScheduled = true;
+            requestAnimationFrame(() => {
+                _fivePanelRetryScheduled = false;
+                _updateFivePanel();
+            });
+        }
+    } else {
+        _queueFivePanelThumbs(cur);
+    }
 
     const offsets = [-2, -1, 0, 1, 2];
     let html = '';

From 0f90278b5596a91838b286f09c8373276fdb2211 Mon Sep 17 00:00:00 2001
From: Claude Agent <noreply@anthropic.com>
Date: Tue, 21 Apr 2026 13:48:55 +0000
Subject: [PATCH 3/4] fix(viewer): re-render 5-panel after late thumb capture

- Capture happens after seeked event; previous render sees empty thumb
- Schedule a second render from capture paths when frame is in visible window
- Reject suspiciously small captures (decoder not ready) and re-queue
- Consolidate on single _scheduleFivePanelRender helper
---
 static/telescope.js | 77 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 60 insertions(+), 17 deletions(-)

diff --git a/static/telescope.js b/static/telescope.js
index 4316aec..8077029 100644
--- a/static/telescope.js
+++ b/static/telescope.js
@@ -3915,20 +3915,9 @@ function viewFile(path, name, opts) {
             _seekToFrame(vid, f);
         });
 
-        const _scheduleViewerRender = () => {
-            if (_renderPending) return;
-            _renderPending = true;
-            requestAnimationFrame(() => {
-                _renderPending = false;
-                const v = document.getElementById('hiddenVid');
-                if (!v) return;
-                _updateScrubPosition(v);
-                _updateFivePanel();
-            });
-        };
         const updateAfterSeek = () => {
             _currentFrame = Math.round(vid.currentTime * _videoFps);
-            _scheduleViewerRender();
+            _scheduleFivePanelRender();
         };
         // timeupdate only handles loop wrap-around; render is driven by seeked.
         vid.addEventListener('timeupdate', () => {
@@ -4252,9 +4241,31 @@ var _fivePanelRetryScheduled = false;
 const _VIDDBG = false;
 function _vdbg(...args) { if (_VIDDBG) try { console.log('[vid]', ...args); } catch (e) {} }
 
+// Minimum byte length for a data-URL to be considered a real (non-blank)
+// JPEG capture. Mostly-flat frames from a not-ready decoder compress to a
+// few hundred bytes; real 400x225 frames are tens of KB.
+const _MIN_THUMB_BYTES = 500;
+
+/** Schedule a single rAF-batched render of the scrub position + filmstrip.
+ *  Multiple calls within one animation frame collapse to one paint. */
+function _scheduleFivePanelRender() {
+    if (_renderPending) return;
+    _renderPending = true;
+    requestAnimationFrame(() => {
+        _renderPending = false;
+        const v = document.getElementById('hiddenVid');
+        if (!v) return;
+        _updateScrubPosition(v);
+        _updateFivePanel();
+    });
+}
+
 /** Capture whatever the decoder is currently showing into the shared
  *  offscreen canvas, stored against `frameIdx`. No-op if already captured
- *  or if the canvas isn't ready. Safe to call from any seek/play code path. */
+ *  or if the canvas isn't ready. Safe to call from any seek/play code path.
+ *  Schedules a 5-panel re-render when the captured frame is within the
+ *  visible window — essential because the capture happens AFTER the
+ *  'seeked' event's render, so that render had no thumb to show. */
 function _captureLandedThumb(vid, frameIdx) {
     if (!_thumbCtx || !_thumbCanvas || !vid) return;
     if (frameIdx < 0 || frameIdx >= _frameTotalCount) return;
@@ -4262,9 +4273,21 @@ function _captureLandedThumb(vid, frameIdx) {
     try {
         _thumbCtx.drawImage(vid, 0, 0, _thumbCanvas.width, _thumbCanvas.height);
         const url = _thumbCanvas.toDataURL('image/jpeg', 0.85);
+        if (url.length < _MIN_THUMB_BYTES) {
+            // Decoder likely wasn't ready — don't cache a blank. Re-queue so
+            // the drainer can retry once the frame has actually landed.
+            _vdbg('blank capture rejected', frameIdx, 'len=', url.length);
+            _thumbExtractionPending.delete(frameIdx);
+            _queueFrameThumb(frameIdx);
+            return;
+        }
         _frameThumbs[frameIdx] = url;
         _thumbExtractionPending.delete(frameIdx);
         _vdbg('captured', frameIdx, 'len=', url.length);
+        if (Math.abs(frameIdx - _currentFrame) <= 2) {
+            _vdbg('late render scheduled', frameIdx);
+            _scheduleFivePanelRender();
+        }
     } catch (e) {
         _vdbg('capture failed', frameIdx, e && e.message);
     }
@@ -4294,9 +4317,17 @@ function _seekToFrame(vid, frame) {
         const onSeeked = () => {
             vid.removeEventListener('seeked', onSeeked);
             if (useRVFC) {
-                try { vid.requestVideoFrameCallback(() => finish()); return; } catch (e) {}
+                try {
+                    vid.requestVideoFrameCallback(() => finish());
+                    // Belt-and-braces: if rVFC hasn't fired in 250ms, try
+                    // drawing anyway — the decoder almost certainly has the
+                    // frame by then. The outer 1500ms safety timeout still
+                    // applies as the absolute last resort.
+                    setTimeout(finish, 250);
+                    return;
+                } catch (e) {}
             }
-            // Fallback: allow one browser tick for the frame to present.
+            // No rVFC: allow one browser tick for the frame to present.
             setTimeout(finish, 16);
         };
         vid.addEventListener('seeked', onSeeked, { once: true });
@@ -4471,8 +4502,20 @@ function _queueFrameThumb(frameIdx) {
 function _captureCurrentAsThumb(vid, frameIdx) {
     try {
         _thumbCtx.drawImage(vid, 0, 0, _thumbCanvas.width, _thumbCanvas.height);
-        _frameThumbs[frameIdx] = _thumbCanvas.toDataURL('image/jpeg', 0.85);
-    } catch (e) { /* ignore per-frame failures */ }
+        const url = _thumbCanvas.toDataURL('image/jpeg', 0.85);
+        if (url.length < _MIN_THUMB_BYTES) {
+            _vdbg('blank capture rejected', frameIdx, 'len=', url.length);
+            _thumbExtractionPending.delete(frameIdx);
+            _queueFrameThumb(frameIdx);
+            return;
+        }
+        _frameThumbs[frameIdx] = url;
+        _vdbg('captured', frameIdx, 'len=', url.length);
+        if (Math.abs(frameIdx - _currentFrame) <= 2) {
+            _vdbg('late render scheduled', frameIdx);
+            _scheduleFivePanelRender();
+        }
+    } catch (e) { _vdbg('capture failed', frameIdx, e && e.message); }
     _thumbExtractionPending.delete(frameIdx);
 }
 

From 7f742fbed7e839f586c9599a34e4e56d22a5efb6 Mon Sep 17 00:00:00 2001
From: Claude Agent <noreply@anthropic.com>
Date: Tue, 21 Apr 2026 14:14:32 +0000
Subject: [PATCH 4/4] fix(viewer): prevent step-by-2 and use native playback
 for smooth forward play

- Guard _currentFrame against overwrite during programmatic seeks (fixes step-by-2)
- Forward play now uses native <video>.play() + requestVideoFrameCallback (smooth at native fps)
- Reverse play keeps step-based loop (seek-serialized)
- Center panel no longer blanks on first pass (capture fires on every rVFC tick)
---
 static/telescope.js | 115 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 100 insertions(+), 15 deletions(-)

diff --git a/static/telescope.js b/static/telescope.js
index 8077029..ba68daf 100644
--- a/static/telescope.js
+++ b/static/telescope.js
@@ -3915,8 +3915,16 @@ function viewFile(path, name, opts) {
             _seekToFrame(vid, f);
         });
 
+        // Do NOT overwrite _currentFrame from vid.currentTime here when a
+        // programmatic seek is in flight: floating-point rounding can push
+        // the value to frame+1, which then made the play-loop advance by two.
+        // Only trust vid.currentTime when the delta is large — i.e. something
+        // external (scrubber drag past target, loop-wrap) moved the playhead.
         const updateAfterSeek = () => {
-            _currentFrame = Math.round(vid.currentTime * _videoFps);
+            const fromVid = Math.round(vid.currentTime * _videoFps);
+            if (!_programmaticSeekInProgress && Math.abs(fromVid - _currentFrame) > 1) {
+                _currentFrame = fromVid;
+            }
             _scheduleFivePanelRender();
         };
         // timeupdate only handles loop wrap-around; render is driven by seeked.
@@ -4176,7 +4184,9 @@ function frameStepStop() {
     if (_frameStepTimer) { clearTimeout(_frameStepTimer); _frameStepTimer = null; }
 }
 
-// Scrubber playback — serialized on seek completion, not a fixed interval.
+// Scrubber playback. Forward uses native <video>.play() + rVFC so we get
+// smooth decode-native framerate. Reverse uses a step-based loop (no browser
+// supports negative playbackRate on arbitrary codecs).
 var _scrubPlayDir = 0;
 var _scrubPlayRunning = false;
 
@@ -4185,14 +4195,30 @@ function scrubPlayToggle(dir) {
         _scrubPlayStop();
         return;
     }
+    // Stop any prior direction cleanly before switching.
+    if (_scrubPlayDir !== 0) _scrubPlayStop();
     _scrubPlayDir = dir;
     _scrubPlayUpdateBtns();
-    if (!_scrubPlayRunning) _scrubPlayLoop();
+    if (dir === 1) {
+        _nativePlayForward();
+    } else if (dir === -1) {
+        if (!_scrubPlayRunning) _reversePlayLoop();
+    }
 }
 
 function _scrubPlayStop() {
     _scrubPlayDir = 0;
+    const vid = document.getElementById('hiddenVid');
+    if (vid && !vid.paused) {
+        try { vid.pause(); } catch (e) {}
+    }
+    if (typeof _scrubPlayCleanup === 'function') {
+        try { _scrubPlayCleanup(); } catch (e) {}
+    }
+    _scrubPlayCleanup = null;
+    _scrubPlayRunning = false;
     _scrubPlayUpdateBtns();
+    _vdbg('native play stopped');
 }
 
 function _scrubPlayUpdateBtns() {
@@ -4202,26 +4228,78 @@ function _scrubPlayUpdateBtns() {
     if (fwd) fwd.style.background = _scrubPlayDir ===  1 ? '#0a4' : '';
 }
 
-async function _scrubPlayLoop() {
+// Native forward playback. Let the <video> element decode at its natural
+// rate; rVFC fires once per presented frame and drives the filmstrip.
+function _nativePlayForward() {
+    const vid = document.getElementById('hiddenVid');
+    if (!vid || !vid.duration) return;
+    _scrubPlayRunning = true;
+    const useRVFC = typeof vid.requestVideoFrameCallback === 'function';
+    let rvfcHandle = null;
+    let rvfcCount = 0;
+    let tuId = null;
+    const onFrame = (_now, meta) => {
+        if (_scrubPlayDir !== 1) return;
+        const mt = (meta && typeof meta.mediaTime === 'number')
+            ? meta.mediaTime : vid.currentTime;
+        const f = Math.round(mt * (_videoFps || 30));
+        if (f !== _currentFrame) {
+            _currentFrame = f;
+            _captureLandedThumb(vid, f);
+            _scheduleFivePanelRender();
+            if (rvfcCount < 3) { _vdbg('rVFC frame', f); rvfcCount++; }
+        }
+        rvfcHandle = vid.requestVideoFrameCallback(onFrame);
+    };
+    const onTimeUpdate = () => {
+        if (_scrubPlayDir !== 1) return;
+        const f = Math.round(vid.currentTime * (_videoFps || 30));
+        if (f !== _currentFrame) {
+            _currentFrame = f;
+            _captureLandedThumb(vid, f);
+            _scheduleFivePanelRender();
+        }
+    };
+    const onEnded = () => {
+        if (_loopSegment) return; // loop handler owns wrap
+        _scrubPlayStop();
+    };
+    _scrubPlayCleanup = () => {
+        if (useRVFC && rvfcHandle != null && typeof vid.cancelVideoFrameCallback === 'function') {
+            try { vid.cancelVideoFrameCallback(rvfcHandle); } catch (e) {}
+        }
+        if (tuId != null) vid.removeEventListener('timeupdate', onTimeUpdate);
+        vid.removeEventListener('ended', onEnded);
+    };
+    vid.addEventListener('ended', onEnded);
+    if (useRVFC) {
+        rvfcHandle = vid.requestVideoFrameCallback(onFrame);
+    } else {
+        tuId = 1;
+        vid.addEventListener('timeupdate', onTimeUpdate);
+    }
+    _vdbg('native play started');
+    const p = vid.play();
+    if (p && typeof p.catch === 'function') p.catch(() => _scrubPlayStop());
+}
+
+// Reverse step-play. Seeks one frame at a time. Prefetches N-1 thumb so
+// the filmstrip doesn't lag the cursor.
+async function _reversePlayLoop() {
     if (_scrubPlayRunning) return;
     _scrubPlayRunning = true;
     try {
-        while (_scrubPlayDir !== 0) {
+        while (_scrubPlayDir === -1) {
             const vid = document.getElementById('hiddenVid');
             if (!vid || !vid.duration) break;
-            vid.pause();
-            const next = _currentFrame + _scrubPlayDir;
-            if (next < 0 || next >= _frameTotalCount) {
+            if (!vid.paused) { try { vid.pause(); } catch (e) {} }
+            const next = _currentFrame - 1;
+            if (next < 0) {
                 _scrubPlayStop();
                 break;
             }
-            const tStart = performance.now();
+            _queueFrameThumb(next - 1);
             await _seekToFrame(vid, next);
-            const target = 1000 / (_videoFps || 30);
-            const elapsed = performance.now() - tStart;
-            if (elapsed < target) {
-                await new Promise(r => setTimeout(r, target - elapsed));
-            }
         }
     } finally {
         _scrubPlayRunning = false;
@@ -4235,6 +4313,8 @@ async function _scrubPlayLoop() {
 var _currentFrame = 0;
 var _renderPending = false;
 var _fivePanelRetryScheduled = false;
+var _programmaticSeekInProgress = false;
+var _scrubPlayCleanup = null;
 
 // Viewer debug logging. Leave false in production; flip to true when
 // diagnosing filmstrip / playback regressions.
@@ -4303,6 +4383,7 @@ function _seekToFrame(vid, frame) {
     const fps = _videoFps || 30;
     const clamped = Math.max(0, Math.min((_frameTotalCount || 1) - 1, Math.round(frame)));
     _currentFrame = clamped;
+    _programmaticSeekInProgress = true;
     const useRVFC = typeof vid.requestVideoFrameCallback === 'function';
     _vdbg('seek start', clamped);
     return new Promise(resolve => {
@@ -4311,6 +4392,7 @@ function _seekToFrame(vid, frame) {
             if (done) return;
             done = true;
             _captureLandedThumb(vid, clamped);
+            _programmaticSeekInProgress = false;
             _vdbg('seek settle', clamped);
             resolve();
         };
@@ -4590,7 +4672,10 @@ function _updateFivePanel() {
                 _updateFivePanel();
             });
         }
-    } else {
+    } else if (_scrubPlayDir !== 1) {
+        // Skip bulk queueing during native forward play: rVFC captures the
+        // landed frame on every tick, so the center populates organically
+        // and we avoid contending with the decoder.
         _queueFivePanelThumbs(cur);
     }