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>

packages/server/lib/src/server_hub.dart

@@ -23,6 +23,15 @@ class ServerHub {
 
   bool isHostKey(String key) => hostKey.isNotEmpty && key == hostKey;
 
+  /// The member a reconnecting client may take over with its old token:
+  /// still known and not kicked.
+  EngineMember? resumable(String token) {
+    if (token.isEmpty) return null;
+    final viewer = session.tokens[token];
+    if (viewer == null || viewer.kicked) return null;
+    return engine.members[token];
+  }
+
   Session get session => sessions.getOrCreate('default', expectedSecret);
 
   void broadcastState() {
@@ -90,6 +99,13 @@ class ServerHub {
     broadcastFeed();
   }
 
+  /// Like [forgetSocket], but only while [ws] is still the member's socket:
+  /// after a resume the old socket's close must not remove the member.
+  void forgetSocketOf(String token, RelicWebSocket ws) {
+    if (!identical(sockets[token], ws)) return;
+    forgetSocket(token);
+  }
+
   void forgetSocket(String token) {
     engine.applyLeave(token);
     final viewer = session.tokens[token];
@@ -175,7 +191,7 @@ void mountSyncRoute(
             case 'seek':
               if (token == null) return;
               final intent = SeekIntent.fromJson(decoded);
-              hub.engine.applySeek(token, intent.position);
+              hub.engine.applySeek(token, intent.position, seq: intent.seq);
               hub.changed();
             case 'swap':
               if (token == null) return;
@@ -219,8 +235,15 @@ void mountSyncRoute(
               if (token == null) return;
               final report = ReportMessage.fromJson(decoded);
               hub.engine.applyReport(
-                  token, report.position, report.buffered, report.eventId);
-              hub.broadcastState();
+                  token, report.position, report.buffered, report.eventId,
+                  duration: report.duration, mediaId: report.mediaId);
+              hub.changed();
+            case 'ping':
+              final ping = PingMessage.fromJson(decoded);
+              ws.trySendText(jsonEncode(PongMessage(
+                      clientMs: ping.clientMs,
+                      serverMs: hub.engine.now.millisecondsSinceEpoch)
+                  .toJson()));
             case 'chat':
               final chat = ChatMessage.fromJson(decoded);
               hub.broadcastChat(viewer?.name ?? '?', chat.text);
@@ -258,13 +281,13 @@ void mountSyncRoute(
           }
         },
         onError: (_) {
-          if (token != null) hub.forgetSocket(token);
+          if (token != null) hub.forgetSocketOf(token, ws);
         },
         onDone: () {
           if (!firstText.isCompleted) {
             firstText.completeError(StateError('closed before hello'));
           } else if (token != null) {
-            hub.forgetSocket(token);
+            hub.forgetSocketOf(token, ws);
           }
         },
       );
@@ -300,23 +323,36 @@ void mountSyncRoute(
         await close();
         return;
       }
-      try {
-        token = session.issueToken(hello.user.name, hello.user.avatar);
-      } catch (e) {
-        _hubLog.warning('reject ${hello.user.name}: $e');
-        wsErr(ws, 'rejected: $e');
-        await close();
-        return;
+      final resumed = hub.resumable(hello.resume);
+      String memberId;
+      if (resumed != null) {
+        // Unclean drop the server has not noticed yet: take the member over
+        // (same token, id, ready flag) and drop the dead socket quietly.
+        token = hello.resume;
+        memberId = resumed.id;
+        final old = hub.sockets.remove(token);
+        if (old != null) unawaited(old.tryClose());
+        hub.engine.applyResume(token);
+        _hubLog.info('resume ${hello.user.name} ($memberId)');
+      } else {
+        try {
+          token = session.issueToken(hello.user.name, hello.user.avatar);
+        } catch (e) {
+          _hubLog.warning('reject ${hello.user.name}: $e');
+          wsErr(ws, 'rejected: $e');
+          await close();
+          return;
+        }
+        memberId = hub.engine.applyJoin(token, hello.user.name, hello.user.avatar);
       }
       session.tokens[token]!.isHost = hub.isHostKey(hello.hostKey);
-      final memberId = hub.engine.applyJoin(token, hello.user.name, hello.user.avatar);
       final activeToken = token;
       hub.sockets[activeToken] = ws;
       session.tokens[activeToken]!.onKick = (reason) async {
         ws.trySendText(jsonEncode(KickedMessage(reason: reason).toJson()));
         await Future.delayed(const Duration(milliseconds: 200));
         await ws.tryClose();
-        hub.forgetSocket(activeToken);
+        hub.forgetSocketOf(activeToken, ws);
       };
       final media = session.media;
       final welcome = WelcomeMessage(

packages/server/lib/src/sync_server.dart

@@ -101,7 +101,7 @@ class SyncServer {
     );
     _startedAt = DateTime.now();
     _heartbeat = Timer.periodic(const Duration(seconds: 1), (_) {
-      hub.engine.sweepStale();
+      hub.engine.tick();
       hub.sweepClosedSockets();
       hub.dropSilentSockets();
       hub.broadcastState();

packages/server/test/session_test.dart

@@ -80,8 +80,8 @@ void main() {
   });
 
   group('core welcome + proto', () {
-    test('proto 5: state broadcast + hello hostKey', () {
-      expect(RelayConstants.protoVersion, 5);
+    test('proto 6: state broadcast + hello hostKey', () {
+      expect(RelayConstants.protoVersion, 6);
     });
 
     test('welcome round-trips with token + member id', () {

packages/server/test/sync_wave_test.dart

@@ -0,0 +1,171 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:sync_relay_core/core.dart';
+import 'package:sync_relay_server/server.dart';
+import 'package:test/test.dart';
+
+/// TCP relay that can go silent without closing: the server sees a socket
+/// that is open but never talks again (an unclean drop it cannot detect).
+class _FreezableProxy {
+  final ServerSocket _listener;
+  final List<Socket> _open = [];
+  bool frozen = false;
+  _FreezableProxy._(this._listener);
+
+  int get port => _listener.port;
+
+  static Future<_FreezableProxy> start(int target) async {
+    final l = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
+    final p = _FreezableProxy._(l);
+    l.listen((client) async {
+      final upstream = await Socket.connect(InternetAddress.loopbackIPv4, target);
+      p._open..add(client)..add(upstream);
+      client.listen((d) {
+        if (!p.frozen) upstream.add(d);
+      }, onError: (_) {}, onDone: () {});
+      upstream.listen((d) {
+        if (!p.frozen) client.add(d);
+      }, onError: (_) {}, onDone: () {});
+    });
+    return p;
+  }
+
+  Future<void> close() async {
+    for (final s in _open) {
+      s.destroy();
+    }
+    await _listener.close();
+  }
+}
+
+class _Client {
+  final WebSocket ws;
+  final frames = <Map<String, Object?>>[];
+  final _welcome = Completer<Map<String, Object?>>();
+  _Client(this.ws) {
+    ws.listen((m) {
+      final d = Map<String, Object?>.from(jsonDecode('$m') as Map);
+      frames.add(d);
+      if (d['t'] == 'welcome' && !_welcome.isCompleted) _welcome.complete(d);
+    }, onError: (_) {}, onDone: () {});
+  }
+
+  StateBroadcast? get lastState {
+    for (final f in frames.reversed) {
+      if (f['t'] == 'state') return StateBroadcast.fromJson(f);
+    }
+    return null;
+  }
+
+  void send(Map<String, Object?> j) => ws.add(jsonEncode(j));
+
+  static Future<(_Client, WelcomeMessage)> join(int port, String name,
+      {String resume = ''}) async {
+    final ws = await WebSocket.connect('ws://127.0.0.1:$port/sync');
+    final c = _Client(ws);
+    c.send(HelloMessage(
+      proto: RelayConstants.protoVersion,
+      secret: 'w',
+      user: HelloUser(name: name),
+      media: const HelloMedia(name: '', size: 0, duration: 0),
+      resume: resume,
+    ).toJson());
+    final w = await c._welcome.future.timeout(const Duration(seconds: 5));
+    return (c, WelcomeMessage.fromJson(w));
+  }
+}
+
+Future<void> _until(FutureOr<bool> Function() cond, String what,
+    {Duration timeout = const Duration(seconds: 10)}) async {
+  final end = DateTime.now().add(timeout);
+  while (DateTime.now().isBefore(end)) {
+    if (await cond()) return;
+    await Future.delayed(const Duration(milliseconds: 50));
+  }
+  fail('timed out waiting for $what');
+}
+
+void main() {
+  late SyncServer server;
+  setUp(() async {
+    server = SyncServer(const AppConfig(port: 0, secret: 'w', name: 'wave'));
+    await server.start();
+  });
+  tearDown(() => server.stop());
+
+  test('reconnect after an unclean drop takes over the old member, no ghost',
+      () async {
+    final proxy = await _FreezableProxy.start(server.boundPort);
+    final other = (await _Client.join(server.boundPort, 'other')).$1;
+    final (first, welcome) = await _Client.join(proxy.port, 'alice');
+    first.send(const ReadyIntent(ready: true).toJson());
+    await _until(() => server.hub.engine.members[welcome.token]?.ready == true,
+        'ready');
+    proxy.frozen = true; // unclean drop: the server's socket stays open
+
+    final (second, again) =
+        await _Client.join(server.boundPort, 'alice', resume: welcome.token);
+    expect(again.memberId, welcome.memberId);
+    expect(again.token, welcome.token,
+        reason: 'same token keeps the media URL valid');
+    expect(server.hub.engine.members.length, 2,
+        reason: 'alice once (taken over) plus other, no ghost');
+    expect(server.hub.engine.members[welcome.token]!.ready, isTrue,
+        reason: 'ready survives the takeover');
+    // The frozen old socket closing later must not remove the new one.
+    await proxy.close();
+    await Future.delayed(const Duration(seconds: 2));
+    expect(server.hub.engine.members.containsKey(welcome.token), isTrue);
+    expect(server.hub.sockets.containsKey(welcome.token), isTrue);
+    second.send(const ChatMessage(text: 'still here').toJson());
+    await _until(
+        () => other.frames.any((f) => f['t'] == 'chat' && f['text'] == 'still here'),
+        'chat from the resumed member');
+    await other.ws.close();
+    await second.ws.close();
+  });
+
+  test('unknown or kicked resume token joins as a new member', () async {
+    final (a, wa) = await _Client.join(server.boundPort, 'a', resume: 'nope');
+    expect(wa.token, isNot('nope'));
+    final (b, wb) = await _Client.join(server.boundPort, 'b');
+    await server.hub.kickById(wb.memberId, 'bye');
+    final (c, wc) = await _Client.join(server.boundPort, 'b', resume: wb.token);
+    expect(wc.token, isNot(wb.token));
+    expect(wc.memberId, isNot(wb.memberId));
+    await a.ws.close();
+    await b.ws.close();
+    await c.ws.close();
+  });
+
+  test('ping gets a pong with the client stamp and the server clock', () async {
+    final (c, _) = await _Client.join(server.boundPort, 'p');
+    final before = DateTime.now().millisecondsSinceEpoch;
+    c.send(const PingMessage(clientMs: 1234).toJson());
+    await _until(() => c.frames.any((f) => f['t'] == 'pong'), 'pong');
+    final pong = PongMessage.fromJson(c.frames.firstWhere((f) => f['t'] == 'pong'));
+    expect(pong.clientMs, 1234);
+    expect(pong.serverMs, greaterThanOrEqualTo(before));
+    await c.ws.close();
+  });
+
+  test('seek echo carries seekBy/seekSeq; report teaches the duration',
+      () async {
+    final (c, w) = await _Client.join(server.boundPort, 's');
+    c.send(const SeekIntent(position: 12, seq: 3).toJson());
+    await _until(() => c.lastState?.seekSeq == 3, 'seek echo');
+    expect(c.lastState!.seekBy, w.memberId);
+    server.hub.engine.media = const HelloMedia(name: 'f', size: 1, duration: 0);
+    c.send(ReportMessage(
+            position: 12,
+            buffered: 5,
+            eventId: c.lastState!.eventId,
+            duration: 1440,
+            mediaId: c.lastState!.mediaId)
+        .toJson());
+    await _until(() => c.lastState?.media?['duration'] == 1440, 'duration');
+    await c.ws.close();
+  });
+}