Protocol 13: Up next preloads, so switching to it is instant

Every app gets the first Up next item ready itself (own Jellyfin plan,
direct links, guests via /j when state.relayNext says the server's
login can pass it on) and opens it in a hidden, muted, paused second
player; the swap promotes that player instead of opening cold, so its
buffer counts at once. Reports go out on open and when the buffer
reaches the gate's need. SwitchTrace times each phase. Measured in the
e2e harness: 1.5-3 s before, 35-103 ms with a preload. Relayed items
still open cold for everyone but their source (ROADMAP).

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

packages/core/lib/src/constants.dart

@@ -1,5 +1,5 @@
 abstract class RelayConstants {
-  static const int protoVersion = 12;
+  static const int protoVersion = 13;
 
   // Relay (`/r/...`): a member's bytes through the server's buffer.
   static const int relaySliceBytes = 1 << 20;

packages/core/lib/src/protocol.dart

@@ -711,6 +711,10 @@ class StateBroadcast {
   /// The server can relay the current Jellyfin media (`/j/...`) for viewers
   /// without their own access to it.
   final bool relay;
+  /// The server can relay Up next's first item the same way (it is a
+  /// Jellyfin ref on the server's login), so viewers without access get
+  /// it ready before it goes up.
+  final bool relayNext;
   /// Up next, in order (see `QueueItem`); empty when nothing is queued.
   final List<QueueItem> queue;
   /// The queued item someone asked to play now, waiting for the member
@@ -727,6 +731,7 @@ class StateBroadcast {
     this.seekBy,
     this.seekSeq,
     this.relay = false,
+    this.relayNext = false,
     this.queue = const [],
     this.queuePlay,
   });
@@ -743,6 +748,7 @@ class StateBroadcast {
         if (seekBy != null) 'seekBy': seekBy,
         if (seekSeq != null) 'seekSeq': seekSeq,
         if (relay) 'relay': true,
+        if (relayNext) 'relayNext': true,
         if (queue.isNotEmpty) 'queue': [for (final q in queue) q.toJson()],
         if (queuePlay != null) 'queuePlay': queuePlay,
       };
@@ -767,6 +773,7 @@ class StateBroadcast {
       seekBy: json['seekBy'] as String?,
       seekSeq: json['seekSeq'] == null ? null : finiteInt(json['seekSeq'], 'seekSeq'),
       relay: (json['relay'] as bool?) ?? false,
+      relayNext: json['relayNext'] == true,
       queue: json['queue'] is List
           ? (json['queue'] as List).map(QueueItem.fromJson).whereType<QueueItem>().toList()
           : const [],

packages/core/lib/src/sync_engine.dart

@@ -535,7 +535,7 @@ class SyncEngine {
 
   /// [relay]: whether the server can relay the current Jellyfin media; the
   /// engine does not know the server's credential.
-  StateBroadcast broadcast({bool relay = false}) {
+  StateBroadcast broadcast({bool relay = false, bool relayNext = false}) {
     final bySeek = _seekEventId == eventId;
     return StateBroadcast(
       eventId: eventId,
@@ -554,6 +554,7 @@ class SyncEngine {
       seekBy: bySeek ? _seekBy : null,
       seekSeq: bySeek ? _seekSeq : null,
       relay: relay,
+      relayNext: relayNext,
       queue: queue.items,
       queuePlay: queue.play,
     );

packages/core/test/jellyfin_ref_test.dart

@@ -66,13 +66,16 @@ void main() {
           MemberView(id: 'm2', name: 'b', ready: false, inSet: false, buffered: 0, stale: false),
         ],
         relay: true,
+        relayNext: true,
       );
       final json = wire(state.toJson());
       expect(json['relay'], true);
+      expect(json['relayNext'], true);
       expect((json['members'] as List)[0], containsPair('jf', {'abc123': false}));
       expect((json['members'] as List)[1], isNot(contains('jf')));
       final back = StateBroadcast.fromJson(json);
       expect(back.relay, isTrue);
+      expect(back.relayNext, isTrue);
       expect(back.members[0].jf, {'abc123': false});
       expect(back.members[1].jf, isEmpty);
       expect(HelloMedia.fromJson(back.media!).jellyfin, ref);
@@ -80,7 +83,9 @@ void main() {
       final plain = StateBroadcast(
           eventId: 1, transport: 'held', position: 0, serverTime: DateTime.utc(2026), mediaId: 1, members: const []);
       expect(plain.toJson().containsKey('relay'), isFalse);
+      expect(plain.toJson().containsKey('relayNext'), isFalse);
       expect(StateBroadcast.fromJson(wire(plain.toJson())).relay, isFalse);
+      expect(StateBroadcast.fromJson(wire(plain.toJson())).relayNext, isFalse);
     });
 
     test('welcome relayUrl round-trips, omitted when null', () {