Sync fixes: clean seeks, clock offset, end of file, 2.5 min read-ahead (proto 6)

- User seeks are intercepted at the player (SyncPlayer), previewed
  locally, sent once 300 ms after the drag ends; own echoes are matched
  by seekSeq and never re-applied; the landed check can't reapply a
  stale target. 1 s position poll removed.
- ping/pong clock offset (min-RTT ClockSync); positions use server time.
- Reports carry duration; buffer gate is min(4 s, remaining - 2 s);
  new finished transport instead of a HELD stall at the end.
- cache/readahead 150 s, 256 MiB demuxer cache, pins read back.
- Resumed reports put a stale ready member back in the set; hello.resume
  takes over the old member after an unclean drop (no ghost).
- Docs: roadmap rendering findings (HW path works; shaders verified).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

apps/desktop/test/clock_offset_test.dart

@@ -0,0 +1,52 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:sync_relay_core/core.dart';
+import 'package:sync_relay_server/server.dart';
+import 'package:watch_together/src/sync/state_diff.dart';
+import 'package:watch_together/src/sync/sync_client.dart';
+
+Future<void> _poll(FutureOr<bool> Function() cond, String what) async {
+  final end = DateTime.now().add(const Duration(seconds: 10));
+  while (DateTime.now().isBefore(end)) {
+    if (await cond()) return;
+    await Future.delayed(const Duration(milliseconds: 50));
+  }
+  fail('timed out waiting for $what');
+}
+
+void main() {
+  test('a client whose clock is 3 s off still extrapolates the server position',
+      () async {
+    final server = SyncServer(const AppConfig(port: 0, secret: '', name: 'clk'));
+    await server.start();
+    const skew = Duration(seconds: 3);
+    final client = SyncClient(clock: () => DateTime.now().toUtc().add(skew));
+    try {
+      await client.connect(
+          wsUri: Uri.parse('ws://127.0.0.1:${server.boundPort}/sync'),
+          secret: '',
+          name: 'skewed');
+      client.sendReady(true);
+      client.sendReport(position: 0, buffered: 10, eventId: 0);
+      await _poll(() => client.lastState?.transport == 'playing', 'playing');
+      for (var i = 0; i < 5; i++) {
+        client.sendPing();
+        await Future.delayed(const Duration(milliseconds: 50));
+      }
+      await _poll(() => client.clockSync.hasSample, 'a pong');
+      expect(client.clockSync.offsetMs, closeTo(-skew.inMilliseconds, 50));
+      final st = client.lastState!;
+      final truth = server.hub.engine.positionAt();
+      // The bug: extrapolating with the local clock is off by the skew.
+      final naive = serverPositionAt(st, DateTime.now().toUtc().add(skew));
+      expect(naive - truth, closeTo(3, 0.1));
+      // The fix: extrapolate on the server's clock.
+      final corrected = serverPositionAt(st, client.serverNow());
+      expect(corrected, closeTo(truth, 0.1));
+    } finally {
+      await client.dispose();
+      await server.stop();
+    }
+  });
+}

apps/desktop/test/end_of_file_e2e_test.dart

@@ -0,0 +1,76 @@
+import 'dart:async';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:media_kit/media_kit.dart';
+import 'package:sync_relay_core/core.dart';
+import 'package:sync_relay_server/server.dart';
+import 'package:watch_together/src/session/session_coordinator.dart';
+
+const _mediaPath = '/home/foxyz/Videos/chiyo.mp4'; // 13.8 s
+
+Future<void> _poll(
+  FutureOr<bool> Function() cond,
+  String what, {
+  Duration timeout = const Duration(seconds: 30),
+}) async {
+  final deadline = DateTime.now().add(timeout);
+  while (DateTime.now().isBefore(deadline)) {
+    if (await cond()) return;
+    await Future.delayed(const Duration(milliseconds: 100));
+  }
+  fail('timed out waiting for $what');
+}
+
+void main() {
+  test(
+    'plays through the last 4 s to finished; seek back plays again',
+    timeout: const Timeout(Duration(minutes: 2)),
+    () async {
+      MediaKit.ensureInitialized();
+      final server = SyncServer(const AppConfig(
+          port: 0, secret: 'eof', name: 'eof', mediaPath: _mediaPath));
+      await server.start();
+      final c = SessionCoordinator();
+      try {
+        await c.connect(ConnectParams(
+            host: '127.0.0.1',
+            port: server.boundPort,
+            secret: 'eof',
+            name: 'solo'));
+        await c.playback.player.setVolume(0);
+        await _poll(() => c.serverState.peek() != null, 'server state');
+        await _poll(
+            () => (c.serverState.peek()?.media?['duration'] as num? ?? 0) > 13,
+            'server learns the duration from reports');
+        c.toggleReady();
+        await _poll(() => c.playback.player.state.playing, 'playing');
+        c.seekTo(7);
+        final transports = <String>[];
+        await _poll(() {
+          transports.add(c.serverState.peek()?.transport ?? '');
+          return c.serverState.peek()?.transport == 'finished';
+        }, 'finished at the end');
+        // ignore: avoid_print
+        print('transports: ${transports.toSet()} '
+            'end at ${c.playback.positionSecs.toStringAsFixed(2)}');
+        expect(transports, isNot(contains('held')),
+            reason: 'never held in the last seconds');
+        expect(c.serverState.peek()!.position, closeTo(13.77, 0.1));
+        await _poll(() => !c.playback.player.state.playing, 'player stopped');
+        expect(c.playback.positionSecs, greaterThan(12));
+        expect(c.starving.peek(), contains('finished'));
+
+        c.seekTo(2);
+        await _poll(
+            () =>
+                c.serverState.peek()?.transport == 'playing' &&
+                c.playback.player.state.playing &&
+                c.playback.positionSecs < 6,
+            'seek back from finished plays again');
+      } finally {
+        await c.dispose();
+        await server.stop();
+      }
+    },
+  );
+}

apps/desktop/test/readahead_e2e_test.dart

@@ -0,0 +1,70 @@
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:media_kit/media_kit.dart';
+import 'package:sync_relay_core/core.dart';
+import 'package:sync_relay_server/server.dart';
+import 'package:watch_together/src/playback/playback_controller.dart';
+
+final _tmp = Platform.environment['WT_TEST_TMP'] ?? Directory.systemTemp.path;
+
+/// 240 s at a constant 8 Mbit/s: the bitrate of a 1.4 GB / 24 min episode.
+Future<String> _media() async {
+  final path = '$_tmp/readahead_240s.mp4';
+  if (await File(path).exists()) return path;
+  final r = await Process.run('ffmpeg', [
+    '-y', '-v', 'error',
+    '-f', 'lavfi', '-i', 'testsrc2=size=640x360:rate=24',
+    '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000',
+    '-t', '240', '-c:v', 'libx264', '-preset', 'ultrafast', '-g', '48',
+    '-b:v', '8M', '-minrate', '8M', '-maxrate', '8M', '-bufsize', '4M',
+    '-x264-params', 'nal-hrd=cbr', '-pix_fmt', 'yuv420p', '-c:a', 'aac',
+    '-movflags', '+faststart', path,
+  ]);
+  if (r.exitCode != 0) fail('ffmpeg failed: ${r.stderr}');
+  return path;
+}
+
+void main() {
+  test('pins read back as set', () {
+    expect(pinMatches('150', '150.000000'), isTrue);
+    expect(pinMatches('268435456', '268435456'), isTrue);
+    expect(pinMatches('150', '10.000000'), isFalse);
+    expect(pinMatches('a=1,b=2', 'a=1,b=2'), isTrue);
+  });
+
+  test(
+    'read-ahead grows far past 10 s from the server media endpoint',
+    timeout: const Timeout(Duration(minutes: 2)),
+    () async {
+      MediaKit.ensureInitialized();
+      final media = await _media();
+      final server = SyncServer(AppConfig(
+          port: 0, secret: '', name: 'readahead', mediaPath: media));
+      await server.start();
+      final p = PlaybackController();
+      try {
+        await p.init();
+        expect(p.pinMismatches, isEmpty,
+            reason: 'every pinned mpv property took effect');
+        final token = server.session.issueToken('probe', '');
+        await p.openUrl(
+            'http://127.0.0.1:${server.boundPort}/m/default/$token/readahead.mp4');
+        var best = 0.0;
+        final end = DateTime.now().add(const Duration(seconds: 30));
+        while (DateTime.now().isBefore(end) && best < 120) {
+          await Future.delayed(const Duration(milliseconds: 500));
+          best = p.bufferedSecsAhead;
+        }
+        // ignore: avoid_print
+        print('buffered ahead: ${best.toStringAsFixed(1)} s, '
+            'served ${server.session.totalBytesServed >> 20} MiB');
+        expect(best, greaterThan(120),
+            reason: 'paused player reads ahead about two minutes');
+      } finally {
+        await p.dispose();
+        await server.stop();
+      }
+    },
+  );
+}

apps/desktop/test/seek_drag_e2e_test.dart

@@ -0,0 +1,164 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:media_kit/media_kit.dart';
+import 'package:sync_relay_core/core.dart';
+import 'package:sync_relay_server/server.dart';
+import 'package:watch_together/src/session/session_coordinator.dart';
+import 'package:watch_together/src/sync/state_diff.dart';
+
+final _tmp = Platform.environment['WT_TEST_TMP'] ?? Directory.systemTemp.path;
+
+/// 120 s, keyframe every second (seeks land fast). Needs an audio track:
+/// without a video output attached (headless) mpv refuses a video-only file.
+Future<String> _media() async {
+  final path = '$_tmp/seek_drag_120s.mp4';
+  if (await File(path).exists()) return path;
+  final r = await Process.run('ffmpeg', [
+    '-y', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=320x240:rate=24',
+    '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000',
+    '-t', '120', '-c:v', 'libx264', '-preset', 'ultrafast', '-g', '24',
+    '-pix_fmt', 'yuv420p', '-c:a', 'aac', '-movflags', '+faststart', path,
+  ]);
+  if (r.exitCode != 0) fail('ffmpeg failed: ${r.stderr}');
+  return path;
+}
+
+Future<void> _poll(
+  FutureOr<bool> Function() cond,
+  String what, {
+  Duration timeout = const Duration(seconds: 30),
+}) async {
+  final deadline = DateTime.now().add(timeout);
+  while (DateTime.now().isBefore(deadline)) {
+    if (await cond()) return;
+    await Future.delayed(const Duration(milliseconds: 100));
+  }
+  fail('timed out waiting for $what');
+}
+
+void main() {
+  test(
+    'seek bar drag: one seek to the release point, no yank back',
+    timeout: const Timeout(Duration(minutes: 3)),
+    () async {
+      MediaKit.ensureInitialized();
+      final media = await _media();
+      final server = SyncServer(AppConfig(
+          port: 0, secret: 'drag', name: 'drag', mediaPath: media));
+      await server.start();
+      final c = SessionCoordinator();
+      try {
+        await c.connect(ConnectParams(
+            host: '127.0.0.1',
+            port: server.boundPort,
+            secret: 'drag',
+            name: 'solo'));
+        await c.playback.player.setVolume(0);
+        await _poll(() => c.serverState.peek() != null, 'server state');
+        c.toggleReady();
+        await _poll(
+            () => c.playback.player.state.playing && c.playback.positionSecs > 1,
+            'solo playback');
+
+        // What media_kit's MaterialDesktopSeekBar does: player.seek on every
+        // pointer move (here 2.5 s of dragging from 20 s to 80 s), then once
+        // more on release.
+        final positions = <double>[];
+        final sampler = Timer.periodic(const Duration(milliseconds: 100),
+            (_) => positions.add(c.playback.positionSecs));
+        const moves = 130; // ~4 s of dragging
+        for (var i = 0; i <= moves; i++) {
+          final at = 20 + 60 * i / moves;
+          unawaited(c.playback.player.seek(Duration(milliseconds: (at * 1000).round())));
+          await Future.delayed(const Duration(milliseconds: 30));
+        }
+        await c.playback.player.seek(const Duration(seconds: 80));
+        final releasedAt = positions.length;
+        await Future.delayed(const Duration(seconds: 5));
+        sampler.cancel();
+
+        final seeks = c.feedLog.peek().where((f) => f.action == 'seek').length;
+        final r = c.serverState.peek()!;
+        final serverPos = serverPositionAt(r, DateTime.now().toUtc());
+        final during = positions.sublist(0, releasedAt);
+        final after = positions.sublist(releasedAt);
+        // ignore: avoid_print
+        print('seek feeds=$seeks server=${serverPos.toStringAsFixed(2)} '
+            'local=${c.playback.positionSecs.toStringAsFixed(2)} '
+            'during=${during.map((p) => p.toStringAsFixed(1)).join(' ')} '
+            'after release=${after.map((p) => p.toStringAsFixed(1)).join(' ')}');
+        for (var i = 1; i < during.length; i++) {
+          expect(during[i], greaterThan(during[i - 1] - 2),
+              reason: 'drag never yanked backwards (sample $i)');
+        }
+        expect(seeks, 1, reason: 'one seek per drag, sent on release');
+        expect(serverPos, inInclusiveRange(80, 87),
+            reason: 'server follows the release point');
+        expect((c.playback.positionSecs - serverPos).abs(), lessThan(1.0));
+        for (final p in after) {
+          expect(p, greaterThanOrEqualTo(79), reason: 'no yank back after release');
+        }
+      } finally {
+        await c.dispose();
+        await server.stop();
+      }
+    },
+  );
+
+  test(
+    'drag on one client: the other follows with exactly one seek',
+    timeout: const Timeout(Duration(minutes: 3)),
+    () async {
+      MediaKit.ensureInitialized();
+      final media = await _media();
+      final server = SyncServer(AppConfig(
+          port: 0, secret: 'drag2', name: 'drag2', mediaPath: media));
+      await server.start();
+      final a = SessionCoordinator();
+      final b = SessionCoordinator();
+      try {
+        for (final (c, name) in [(a, 'a'), (b, 'b')]) {
+          await c.connect(ConnectParams(
+              host: '127.0.0.1',
+              port: server.boundPort,
+              secret: 'drag2',
+              name: name));
+          await c.playback.player.setVolume(0);
+        }
+        await _poll(() => a.serverState.peek()?.members.length == 2, 'both in');
+        a.toggleReady();
+        b.toggleReady();
+        await _poll(
+            () => a.playback.player.state.playing && b.playback.player.state.playing,
+            'both playing');
+        final bSamples = <double>[];
+        final sampler = Timer.periodic(const Duration(milliseconds: 100),
+            (_) => bSamples.add(b.playback.positionSecs));
+        for (var i = 0; i <= 100; i++) {
+          unawaited(a.playback.player
+              .seek(Duration(milliseconds: (30000 + 400 * i))));
+          await Future.delayed(const Duration(milliseconds: 30));
+        }
+        await a.playback.player.seek(const Duration(seconds: 70));
+        await Future.delayed(const Duration(seconds: 4));
+        sampler.cancel();
+        final seeks = b.feedLog.peek().where((f) => f.action == 'seek').length;
+        // ignore: avoid_print
+        print('b saw $seeks seek(s); a=${a.playback.positionSecs.toStringAsFixed(2)} '
+            'b=${b.playback.positionSecs.toStringAsFixed(2)}');
+        expect(seeks, 1);
+        expect(b.playback.positionSecs, greaterThan(70));
+        expect((a.playback.positionSecs - b.playback.positionSecs).abs(),
+            lessThan(1.0));
+        expect(bSamples.where((p) => p > 31 && p < 69), isEmpty,
+            reason: 'b never jumps to mid-drag positions');
+      } finally {
+        await a.dispose();
+        await b.dispose();
+        await server.stop();
+      }
+    },
+  );
+}

apps/desktop/test/session_logic_test.dart

@@ -1,19 +1,6 @@
 import 'package:flutter_test/flutter_test.dart';
-import 'package:sync_relay_core/core.dart';
 import 'package:watch_together/src/session/idle.dart';
 import 'package:watch_together/src/session/session_coordinator.dart';
-import 'package:watch_together/src/sync/state_diff.dart';
-
-MemberView _self({bool ready = true, bool inSet = true, bool stale = false}) =>
-    MemberView(
-      id: 'm1',
-      name: 'me',
-      avatar: '',
-      ready: ready,
-      inSet: inSet,
-      buffered: 5,
-      stale: stale,
-    );
 
 void main() {
   group('IdleTracker', () {
@@ -104,17 +91,4 @@ void main() {
       expect(n.contains('SECRET'), isFalse);
     });
   });
-
-  group('shouldReassertReady', () {
-    test('ready, fresh, out of set (after stale sweep) -> reassert', () {
-      expect(shouldReassertReady(_self(inSet: false)), isTrue);
-    });
-    test('normal states -> no', () {
-      expect(shouldReassertReady(null), isFalse);
-      expect(shouldReassertReady(_self()), isFalse);
-      expect(shouldReassertReady(_self(ready: false, inSet: false)), isFalse);
-      expect(shouldReassertReady(_self(ready: false)), isFalse);
-      expect(shouldReassertReady(_self(inSet: false, stale: true)), isFalse);
-    });
-  });
 }

apps/desktop/test/state_diff_test.dart

@@ -156,4 +156,39 @@ void main() {
       expect(localPlayAllowed(state, ''), isFalse);
     });
   });
+
+  group('finished', () {
+    test('stops in place: pause, no seek to the end, no drift seeks', () {
+      final diff = StateDiff();
+      final t = DateTime.now().toUtc();
+      diff.diff(_state(eventId: 1, transport: 'playing', position: 100), 100, t);
+      final end = _state(eventId: 2, transport: 'finished', position: 120);
+      final actions = diff.diff(end, 119.4, t);
+      expect(actions.whereType<SeekAction>(), isEmpty);
+      expect(actions.whereType<TransportAction>().single.playing, isFalse);
+      // Far off and later: still nothing.
+      expect(diff.diff(end, 50, t.add(const Duration(seconds: 10))), isEmpty);
+    });
+
+    test('late joiner lands just before the end, paused', () {
+      final diff = StateDiff();
+      final actions = diff.diff(
+          _state(eventId: 5, transport: 'finished', position: 120), 0,
+          DateTime.now().toUtc());
+      expect(actions.whereType<SeekAction>().single.position, 119);
+      expect(actions.whereType<TransportAction>().single.playing, isFalse);
+    });
+  });
+
+  test('serverPositionAt extrapolates on the server clock', () {
+    final st = StateBroadcast(
+      eventId: 1,
+      transport: 'playing',
+      position: 10,
+      serverTime: DateTime.utc(2026, 1, 1, 12),
+      mediaId: 1,
+      members: const [],
+    );
+    expect(serverPositionAt(st, DateTime.utc(2026, 1, 1, 12, 0, 2, 500)), 12.5);
+  });
 }

apps/desktop/test/user_seek_test.dart

@@ -0,0 +1,68 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:sync_relay_core/core.dart';
+import 'package:watch_together/src/sync/user_seek.dart';
+
+StateBroadcast _state({int eventId = 1, String? seekBy, int? seekSeq}) =>
+    StateBroadcast(
+      eventId: eventId,
+      transport: 'playing',
+      position: 0,
+      serverTime: DateTime.utc(2026),
+      mediaId: 1,
+      members: const [],
+      seekBy: seekBy,
+      seekSeq: seekSeq,
+    );
+
+void main() {
+  final t0 = DateTime.utc(2026, 1, 1);
+  DateTime at(int ms) => t0.add(Duration(milliseconds: ms));
+
+  test('a drag is one seek, sent after the user stops', () {
+    final g = UserSeekGate(debounce: const Duration(milliseconds: 300));
+    for (var i = 0; i < 100; i++) {
+      g.request(20.0 + i, at(i * 30));
+      expect(g.takeSettled(at(i * 30 + 10)), isNull, reason: 'still dragging');
+      expect(g.holdsPlayer(at(i * 30 + 10)), isTrue);
+    }
+    final sent = g.takeSettled(at(99 * 30 + 300));
+    expect(sent!.position, 119.0);
+    expect(sent.seq, 1);
+    expect(g.takeSettled(at(99 * 30 + 600)), isNull, reason: 'sent once');
+  });
+
+  test('holds until the echo of the last seek, then releases', () {
+    final g = UserSeekGate(debounce: const Duration(milliseconds: 300));
+    g.request(50, at(0));
+    final first = g.takeSettled(at(300))!;
+    g.request(60, at(400));
+    final second = g.takeSettled(at(700))!;
+    expect(second.seq, first.seq + 1);
+    // Echo of the older seek: ours, but the hold stays.
+    final old = _state(eventId: 2, seekBy: 'm1', seekSeq: first.seq);
+    expect(g.isOwnEcho(old, 'm1'), isTrue);
+    g.observe(old, 'm1');
+    expect(g.holdsPlayer(at(800)), isTrue);
+    g.observe(_state(eventId: 3, seekBy: 'm1', seekSeq: second.seq), 'm1');
+    expect(g.holdsPlayer(at(900)), isFalse);
+    expect(g.target, isNull);
+  });
+
+  test('someone else\'s seek is not ours', () {
+    final g = UserSeekGate();
+    g.request(5, at(0));
+    g.takeSettled(at(1000));
+    expect(g.isOwnEcho(_state(seekBy: 'm2', seekSeq: 1), 'm1'), isFalse);
+    expect(g.isOwnEcho(_state(), 'm1'), isFalse);
+  });
+
+  test('a lost echo stops holding the player after the timeout', () {
+    final g = UserSeekGate(
+        debounce: const Duration(milliseconds: 300),
+        echoTimeout: const Duration(seconds: 3));
+    g.request(5, at(0));
+    g.takeSettled(at(300));
+    expect(g.holdsPlayer(at(3000)), isTrue);
+    expect(g.holdsPlayer(at(3400)), isFalse);
+  });
+}