refactor: all screens refactor

2026-07-08 20:12:04 +03:30
parent 2496580e86
commit adc2d1fc47
16 changed files with 3546 additions and 3351 deletions
@@ -0,0 +1,57 @@
+import 'package:flutter/foundation.dart';
+
+/// دروازه‌ی انیمیشنِ صحنه: نگه‌دارِ سه فازِ «مشغولِ انیمیشن» که در آن‌ها بازیِ کارت
+/// قفل است و کارت‌ها/پشت‌کارت‌ها ممکن است پنهان شوند — اینترو («جستجوی حریف»)،
+/// بُر زدن، و پخشِ بقیه‌ی کارت‌ها. یک [animating] هم برای HUD/دیالوگِ حکم می‌دهد.
+class AnimGate {
+  bool _intro = true;
+  bool _pendingShuffle = false; // بُرِ دستِ اول که تا پایانِ اینترو معوق مانده
+  bool _shuffling = false;
+  bool _dealing = false;
+
+  /// آیا انیمیشنی در جریان است (صفحه از این برای پنهان‌کردنِ دیالوگِ حکم استفاده می‌کند).
+  final ValueNotifier<bool> animating = ValueNotifier(true);
+
+  bool get introActive => _intro;
+  bool get shuffling => _shuffling;
+  bool get dealing => _dealing;
+
+  /// در جریانِ هر انیمیشنِ قفل‌کننده (بازیِ کارت ممنوع، صدا خاموش).
+  bool get busy => _intro || _shuffling || _dealing;
+
+  /// در اینترو یا بُر زدن — کارت‌های دست/پشت‌کارت‌ها پنهان‌اند (انیمیشن خودش پخش می‌کند).
+  bool get cardsHidden => _intro || _shuffling;
+
+  void _refresh() => animating.value = busy;
+
+  void markPendingShuffle() => _pendingShuffle = true;
+
+  /// پایانِ اینترو؛ true اگر بُرِ معوقِ دستِ اول باید اکنون اجرا شود.
+  bool endIntro() {
+    _intro = false;
+    final run = _pendingShuffle;
+    _pendingShuffle = false;
+    _refresh();
+    return run;
+  }
+
+  void beginShuffle() {
+    _shuffling = true;
+    _refresh();
+  }
+
+  void endShuffle() {
+    _shuffling = false;
+    _refresh();
+  }
+
+  void beginDeal() {
+    _dealing = true;
+    _refresh();
+  }
+
+  void endDeal() {
+    _dealing = false;
+    _refresh();
+  }
+}
@@ -0,0 +1,45 @@
+import '../../../domain/entities/game_entities.dart';
+
+/// وضعیتِ افکتِ «بریدن با حکم»: بالاترین حکمِ دستِ جاری، کمبوِ روبُریدن‌های سریع،
+/// و «مکثِ آتش» (فریزِ کوتاهِ صحنه پس از آتشِ کمبو). فقط وضعیت و تصمیم را نگه
+/// می‌دارد؛ افزودنِ کامپوننت‌های افکت و بافرِ وضعیت بر عهده‌ی خودِ صحنه است.
+class CutFx {
+  static const double comboWindowSec = 6.0; // پنجره‌ی شمارشِ بریدنِ پیاپی
+  static const double holdSec = 1.0; // مدتِ مکثِ آتش
+
+  int _bestTrumpRank = 0; // بالاترین حکمِ بازی‌شده در دستِ جاری
+  int combo = 0; // شمارِ بریدنِ پیاپیِ سریع (برای شدتِ آتش)
+  double _lastCutAt = -999;
+
+  bool holding = false; // آیا در «مکثِ آتش» هستیم
+  double _holdUntil = 0;
+  GameState? pending; // آخرین وضعیتِ بافرشده در حینِ مکث
+
+  /// دستِ جدید (زمین خالی/تک‌کارت) ⇒ بالاترین حکم ریست می‌شود.
+  void resetTrick() => _bestTrumpRank = 0;
+
+  /// ثبتِ یک بریدن؛ true اگر این حکم «دست را می‌بَرد» (اولین بریدن یا روبُریدنِ
+  /// بالاتر) — در این صورت کمبو هم به‌روزرسانی می‌شود. حکمِ بازنده false می‌دهد.
+  bool registerWinningCut(int rank, double now) {
+    if (rank <= _bestTrumpRank) return false;
+    _bestTrumpRank = rank;
+    combo = (now - _lastCutAt < comboWindowSec) ? combo + 1 : 1;
+    _lastCutAt = now;
+    return true;
+  }
+
+  /// شروعِ مکثِ آتش (پس از آتشِ کمبو).
+  void startHold(double now) {
+    holding = true;
+    _holdUntil = now + holdSec;
+  }
+
+  /// آیا مکث به پایان رسیده و باید وضعیتِ بافرشده اعمال شود.
+  bool holdExpired(double now) => holding && now >= _holdUntil;
+
+  /// لغوِ مکث و پاک‌کردنِ بافر (هنگام خروج از میز).
+  void clearHold() {
+    holding = false;
+    pending = null;
+  }
+}
@@ -12,10 +12,13 @@ import '../../../../../core/settings/app_settings.dart';
 import '../../../../../core/theme/app_theme.dart';
 import '../../../domain/entities/game_entities.dart';
 import '../../bloc/game_bloc.dart';
+import 'anim_gate.dart';
 import 'card_codes.dart';
 import 'card_component.dart';
+import 'cut_fx.dart';
 import 'shuffle_animation.dart';
 import 'table_pieces.dart';
+import 'turn_heartbeat.dart';

 /// صحنه‌ی میز حکم با انیمیشن. شما همیشه پایین میز (rel=0) هستید.
 /// کامپوننت‌های دست و trick ماندگارند و با افکت حرکت جابه‌جا می‌شوند.
@@ -49,37 +52,21 @@ class HokmGame extends FlameGame {
  double _t = 0;
  List<String> _prevTrick = const [];
  bool _highlightedTrick = false; // آیا کارتِ برنده‌ی دستِ کامل هایلایت شده (یک‌بار)
-  int _bestTrumpRank = 0; // بالاترین رتبه‌ی حکمِ بازی‌شده در دستِ جاری (برای افکتِ بریدن)
-  int _cutCombo = 0; // شمارِ بریدنِ پیاپیِ سریع (روبُریدن‌ها) برای افکتِ آتش
-  double _lastCutAt = -999; // زمانِ آخرین بریدن (برای پنجره‌ی کمبو)
-  // «مکثِ آتش»: پس از افکتِ آتشِ کمبو، صحنه کوتاه فریز می‌شود تا لحظه دیده شود؛
-  // وضعیت‌های ورودی بافر می‌شوند و پس از مکث اعمال می‌گردند (کاربر و بات فرقی ندارند).
-  bool _cutHold = false;
-  double _cutHoldUntil = 0;
-  GameState? _pendingState;
-  static const double _cutHoldSec = 1.0;
+  // افکتِ بریدن با حکم: کمبوِ روبُریدن + آتش + «مکثِ آتش» (منطق در CutFx جدا شده).
+  final CutFx _cut = CutFx();
  int _prevHandSize = 0; // برای تشخیصِ پخشِ کارت (دستِ جدید) جهت صدای بُر زدن
  String _prevHandSig = ''; // امضای دست؛ برای تشخیصِ بُرِ مجدد (تغییرِ ۵ کارت در فازِ حکم)
  bool _silent = false; // هنگام خروج از میز، دیگر صدایی پخش نشود
-  bool _introActive = true; // تا پایانِ نمایشِ «جستجوی حریف»
-  bool _pendingShuffle =
-      false; // بُرِ دستِ اول که تا پایانِ اینترو به تعویق افتاده
-  bool _shuffling = false; // در حالِ بُر زدن/پخشِ ۵ کارت (بازیِ کارت ممنوع)
-  bool _dealing = false; // در حالِ پخشِ بقیه‌ی کارت‌ها پس از حکم (بازی ممنوع)
  String? _prevTrump; // برای تشخیصِ لحظه‌ی انتخابِ حکم

-  /// آیا انیمیشنی در حال اجراست (اینترو/بُر زدن/پخشِ کارت). صفحه از این برای
-  /// پنهان‌کردنِ دیالوگِ انتخابِ حکم تا پایانِ پخشِ کارت‌ها استفاده می‌کند.
-  final ValueNotifier<bool> animating = ValueNotifier(true);
-  void _refreshAnimating() =>
-      animating.value = _introActive || _shuffling || _dealing;
+  // دروازه‌ی انیمیشن (اینترو/بُر/پخش) — منطق در AnimGate جدا شده است.
+  final AnimGate _anim = AnimGate();

-  // مدیریتِ ضربانِ قلب (فقط نوبتِ خودِ کاربر؛ مستقل از بازساختِ صحنه).
-  double _turnElapsed = 0;
-  bool _beatPlayed = false; // اولین ضربان در پنجره‌ی پایانیِ نوبت پخش شد
-  double _hbAccum = 0; // انباشتِ زمان برای تکرارِ منظمِ ضربان تا پایانِ نوبت
-  bool _wasMyTurn = false;
-  String _turnSig = ''; // امضای نوبت (نوبت|تعدادِ کارتِ زمین|فاز) — هم‌گام با HUD
+  /// آیا انیمیشنی در حال اجراست؛ صفحه از این برای پنهان‌کردنِ دیالوگِ حکم استفاده می‌کند.
+  ValueNotifier<bool> get animating => _anim.animating;
+
+  // ضربانِ قلبِ نوبتِ کاربر (منطق در TurnHeartbeat جدا شده است).
+  final TurnHeartbeat _heart = TurnHeartbeat();

  /// فرشِ انتخابی؛ 'classic' یعنی سطحِ میزِ ترسیمی. فرشِ تصویری به‌عنوانِ سطحِ
  /// میز (بریده در شکلِ میز) روی زمینِ لاجوردی کشیده می‌شود.
@@ -100,8 +87,8 @@ class HokmGame extends FlameGame {
      if (ui.state == null) return;
      final s = ui.state!;
      // در حینِ «مکثِ آتش»، آخرین وضعیت را بافر کن و بعد از مکث اعمالش کن.
-      if (_cutHold) {
-        _pendingState = s;
+      if (_cut.holding) {
+        _cut.pending = s;
        return;
      }
      _applyState(s);
@@ -124,8 +111,8 @@ class HokmGame extends FlameGame {
    // دستِ اول تا پایانِ نمایشِ «جستجوی حریف» به تعویق می‌افتد تا انیمیشن
    // زیرِ اوورلی پنهان نشود و صدا با تصویر هماهنگ باشد.
    if (_prevHandSize == 0 && s.yourHand.isNotEmpty && !_silent) {
-      if (_introActive) {
-        _pendingShuffle = true;
+      if (_anim.introActive) {
+        _anim.markPendingShuffle();
      } else {
        _shuffleNow();
      }
@@ -133,7 +120,7 @@ class HokmGame extends FlameGame {
    // بُرِ مجدد: هنوز در فازِ حکم هستیم اما ۵ کارتِ حاکم عوض شده ⇒ انیمیشنِ بُر دوباره.
    final sig = (s.yourHand.toList()..sort()).join(',');
    if (!_silent &&
-        !_introActive &&
+        !_anim.introActive &&
        s.phase == 'choose_trump' &&
        s.trump == null &&
        _prevHandSize > 0 &&
@@ -174,13 +161,13 @@ class HokmGame extends FlameGame {
  void _checkTrickSounds(GameState s) {
    final now = s.trick.map((t) => t.card).toList();
    // در زمانِ اینترو/بُر زدن/پخش، کارتی روی میز نشان داده نمی‌شود ⇒ صدا هم نه.
-    if (_silent || _introActive || _shuffling || _dealing) {
+    if (_silent || _anim.busy) {
      _prevTrick = now;
      return;
    }
    final addedOne =
        now.length == _prevTrick.length + 1 && _isPrefix(_prevTrick, now);
-    if (now.length <= 1) _bestTrumpRank = 0; // دستِ جدید ⇒ ریستِ بالاترین حکم
+    if (now.length <= 1) _cut.resetTrick(); // دستِ جدید ⇒ ریستِ بالاترین حکم
    if (addedOne) {
      final card = s.trick.last;
      // بریدن: خالِ راهبر حکم نیست و کارتِ بازی‌شده حکم است.
@@ -189,25 +176,20 @@ class HokmGame extends FlameGame {
          s.leadSuit != s.trump &&
          suitName(card.card) == s.trump;
      final rank = isTrump ? rankValue(card.card) : 0;
-      // افکتِ بریدن فقط وقتی حکمِ بازی‌شده «دست را می‌برد» (بالاترین حکم تا کنون):
-      // یعنی اولین بریدن یا روبریدنِ بالاتر. حکمِ پایین‌تر (بازنده) فقط صدای گذاشتن.
-      if (isTrump && rank > _bestTrumpRank) {
-        _bestTrumpRank = rank;
+      // افکتِ بریدن فقط وقتی حکمِ بازی‌شده «دست را می‌برد» (اولین بریدن یا روبُریدنِ
+      // بالاتر). حکمِ پایین‌تر (بازنده) فقط صدای گذاشتن.
+      if (isTrump && _cut.registerWinningCut(rank, _t)) {
        _shake = 1.0;
        add(Lightning());
-        // کمبوِ بریدن: روبُریدن‌های سریعِ پیاپی (پنجره‌ی ~۶ ثانیه) را می‌شمارد.
-        _cutCombo = (_t - _lastCutAt < 6.0) ? _cutCombo + 1 : 1;
-        _lastCutAt = _t;
        if (!AppSettings.I.lowGraphics.value) {
          add(CutBurst()); // فلاش + شوک‌ویو + جرقه (کم‌مصرف: خاموش)
          // سه بریدنِ پیاپی یا بیشتر ⇒ افکتِ آتش (هرچه کمبو بیشتر، شعله بلندتر).
-          if (_cutCombo >= 3) {
+          if (_cut.combo >= 3) {
            _shake = 1.4; // تکانِ قوی‌تر برای اوجِ کمبو
-            add(FireBurst(intensity: _cutCombo));
+            add(FireBurst(intensity: _cut.combo));
            // مکثِ کوتاه پس از آتش تا لحظه دیده شود؛ کارتِ بعدی (کاربر یا بات)
            // تا پایانِ مکث اعمال نمی‌شود.
-            _cutHold = true;
-            _cutHoldUntil = _t + _cutHoldSec;
+            _cut.startHold(_t);
          }
        }
        AppSounds.cut(); // بریدن با حکم (شمشیر)
@@ -224,20 +206,14 @@ class HokmGame extends FlameGame {
  /// قطعِ صداهای بازی هنگام خروج از میز (جلوگیری از پخشِ صدای کارت پس از ترک).
  void silence() {
    _silent = true;
-    _cutHold = false; // مکثِ آتش را لغو کن تا وضعیتِ بافرشده اعمال/رها نشود
-    _pendingState = null;
+    _cut.clearHold(); // مکثِ آتش را لغو کن تا وضعیتِ بافرشده اعمال/رها نشود
    AppSounds.stopHeartBeat();
  }

  /// پایانِ نمایشِ «جستجوی حریف»؛ اگر بُرِ دستِ اول به تعویق افتاده بود، اکنون
  /// (که اوورلی کنار رفته) با صدا و تصویرِ هماهنگ اجرا می‌شود.
  void endIntro() {
-    _introActive = false;
-    if (_pendingShuffle && !_silent) {
-      _pendingShuffle = false;
-      _shuffleNow();
-    }
-    _refreshAnimating();
+    if (_anim.endIntro() && !_silent) _shuffleNow();
  }

  /// اجرای هم‌زمانِ انیمیشن و صدای بُر زدن (صدا با پایانِ انیمیشن قطع می‌شود).
@@ -246,11 +222,9 @@ class HokmGame extends FlameGame {
    if (_silent) return;
    AppSounds.shuffle(cutoffMs: ShuffleAnimation.totalMs);
    add(ShuffleAnimation(size));
-    _shuffling = true;
-    _refreshAnimating();
+    _anim.beginShuffle();
    Future.delayed(const Duration(milliseconds: ShuffleAnimation.totalMs), () {
-      _shuffling = false;
-      _refreshAnimating();
+      _anim.endShuffle();
      if (_s != null && !_silent) _relayout(); // فعال‌سازیِ دوباره‌ی کارت‌ها
    });
  }
@@ -260,11 +234,9 @@ class HokmGame extends FlameGame {
    if (_silent) return;
    AppSounds.shuffle(cutoffMs: ShuffleAnimation.dealMs);
    add(ShuffleAnimation(size, dealOnly: true));
-    _dealing = true;
-    _refreshAnimating();
+    _anim.beginDeal();
    Future.delayed(const Duration(milliseconds: ShuffleAnimation.dealMs), () {
-      _dealing = false;
-      _refreshAnimating();
+      _anim.endDeal();
      if (_s != null && !_silent) _relayout();
    });
  }
@@ -310,10 +282,10 @@ class HokmGame extends FlameGame {
    super.update(dt);
    _t += dt;
    // پایانِ «مکثِ آتش»: آخرین وضعیتِ بافرشده را اعمال کن (یا صحنه را تازه کن).
-    if (_cutHold && _t >= _cutHoldUntil) {
-      _cutHold = false;
-      final p = _pendingState;
-      _pendingState = null;
+    if (_cut.holdExpired(_t)) {
+      _cut.holding = false;
+      final p = _cut.pending;
+      _cut.pending = null;
      if (!_silent) {
        if (p != null) {
          _applyState(p);
@@ -323,70 +295,8 @@ class HokmGame extends FlameGame {
      }
    }
    if (_shake > 0) _shake = math.max(0, _shake - dt * 2.2);
-    _updateHeartBeat(dt);
-  }
-
-  // ضربانِ قلب فقط در ثانیه‌های پایانیِ نوبتِ خودِ کاربر؛ هنگامِ پایانِ نوبت
-  // (بازی‌شدنِ کارت توسط کاربر یا سیستم) بلافاصله قطع می‌شود.
-  //
-  // زمان‌سنجِ نوبت باید دقیقاً هم‌زمان با «حلقه‌ی زمانِ نوبت» در HUD شروع شود؛
-  // آن حلقه با تغییرِ امضای نوبت (نوبت|تعدادِ کارتِ زمین|فاز) ریست می‌شود و به
-  // انیمیشنِ بُر/پخش کاری ندارد. پس اینجا هم شمارش را به همان امضا می‌بندیم و
-  // فقط «پخشِ صدا» را در حینِ انیمیشن/اینترو خاموش می‌کنیم تا صدا و تصویر یکی شوند.
-  void _updateHeartBeat(double dt) {
-    final s = _s;
-    final isMyTurn = s != null &&
-        ((s.phase == 'playing' && s.turn == s.yourSeat) ||
-            (s.phase == 'choose_trump' && s.hakem == s.yourSeat));
-
-    if (!isMyTurn || _silent) {
-      if (_wasMyTurn) {
-        AppSounds.stopHeartBeat(); // نوبت تمام شد ⇒ توقفِ فوریِ صدا
-        _wasMyTurn = false;
-      }
-      _turnSig = s == null ? '' : '${s.turn}|${s.trick.length}|${s.phase}';
-      return;
-    }
-
-    // امضای نوبت — همانی که حلقه‌ی HUD استفاده می‌کند.
-    final sig = '${s.turn}|${s.trick.length}|${s.phase}';
-    if (!_wasMyTurn || sig != _turnSig) {
-      // شروعِ نوبتِ من (یا نوبتِ جدید) ⇒ شمارش از صفر، هم‌زمان با حلقه‌ی HUD.
-      _wasMyTurn = true;
-      _turnSig = sig;
-      _turnElapsed = 0;
-      _beatPlayed = false;
-      _hbAccum = 0;
-      // صدای «نوبتِ شما» فقط هنگامِ بازیِ کارت و بیرون از انیمیشن‌ها.
-      if (s.phase == 'playing' && !_introActive && !_shuffling && !_dealing) {
-        AppSounds.turn();
-      }
-    }
-    _turnElapsed += dt;
-
-    // در حینِ اینترو/بُر/پخش صدایی پخش نمی‌کنیم (اما شمارش ادامه دارد تا با
-    // حلقه‌ی HUD هم‌گام بماند). این انیمیشن‌ها در ابتدای نوبت‌اند و با پنجره‌ی
-    // پایانیِ ضربان هم‌پوشانی ندارند.
-    if (_introActive || _shuffling || _dealing) return;
-
-    final dur = (s.turnTimeoutMs > 0 ? s.turnTimeoutMs / 1000.0 : 30.0);
-    final remaining = dur - _turnElapsed;
-    final warn = math.min(7.0, dur * 0.4);
-    // در پنجره‌ی پایانیِ نوبت، ضربان را با فاصله‌ی منظم تکرار کن تا تا لحظه‌ی
-    // آخر شنیده شود (نه فقط یک ضربانِ زودهنگام که در سکوتِ پایانی گم می‌شود).
-    if (remaining > 0 && remaining <= warn) {
-      if (!_beatPlayed) {
-        _beatPlayed = true;
-        _hbAccum = 0;
-        AppSounds.heartBeat();
-      } else {
-        _hbAccum += dt;
-        if (_hbAccum >= 0.95) {
-          _hbAccum = 0;
-          AppSounds.heartBeat();
-        }
-      }
-    }
+    _heart.update(dt, _s,
+        silent: _silent, busy: _anim.busy);
  }

  @override
@@ -423,7 +333,7 @@ class HokmGame extends FlameGame {
  bool _legal(String code) {
    final s = _s!;
    // هنگامِ اینترو/بُر زدن/پخشِ کارت‌ها یا مکثِ آتش، بازیِ کارت مجاز نیست.
-    if (_introActive || _shuffling || _dealing || _cutHold) return false;
+    if (_anim.busy || _cut.holding) return false;
    if (s.phase != 'playing' || s.trickDone || !s.isMyTurn) return false;
    final lead = s.leadSuit;
    if (lead == null || lead.isEmpty) return true;
@@ -458,7 +368,7 @@ class HokmGame extends FlameGame {
  void _layoutHand(GameState s) {
    // در زمانِ اینترو/بُر زدنِ ابتدای هَند، کارت‌های دست پنهان‌اند و پس از پایانِ
    // بُر زدن «پخش» می‌شوند (می‌آیند). در زمانِ پخشِ بقیه‌ی کارت‌ها مخفی نمی‌شوند.
-    if (_introActive || _shuffling) {
+    if (_anim.cardsHidden) {
      for (final c in _hand.values.toList()) {
        c.removeFromParent();
      }
@@ -532,7 +442,7 @@ class HokmGame extends FlameGame {
  void _layoutTrick(GameState s) {
    // در زمانِ اینترو/بُر زدن/پخش، کارت‌های روی میز پنهان می‌مانند تا با انیمیشن
    // تداخل نکنند (پس از پایانِ انیمیشن دوباره چیده می‌شوند).
-    if (_introActive || _shuffling || _dealing) {
+    if (_anim.busy) {
      for (final c in _trick.values.toList()) {
        c.removeFromParent();
      }
@@ -681,7 +591,7 @@ class HokmGame extends FlameGame {

    // پشتِ کارتِ حریفان در زمانِ بُر زدنِ ابتدای هَند پنهان است (انیمیشنِ بُر
    // خودش کارت‌ها را پخش می‌کند)؛ پس از آن نمایش داده می‌شود.
-    final hideBacks = _introActive || _shuffling;
+    final hideBacks = _anim.cardsHidden;
    for (var seat = 0; seat < 4 && !hideBacks; seat++) {
      if (seat == s.yourSeat) continue;
      final count = seat < s.handCounts.length ? s.handCounts[seat] : 0;
@@ -0,0 +1,76 @@
+import 'dart:math' as math;
+
+import '../../../../../core/service/app_sounds.dart';
+import '../../../domain/entities/game_entities.dart';
+
+/// ضربانِ قلبِ نوبتِ کاربر: در ثانیه‌های پایانیِ نوبتِ خودِ کاربر صدای ضربان پخش
+/// می‌کند و با پایانِ نوبت بلافاصله قطع می‌شود. مستقل از چیدمانِ صحنه است.
+///
+/// زمان‌سنجِ نوبت دقیقاً هم‌زمان با «حلقه‌ی زمانِ نوبت» در HUD شروع می‌شود؛ آن حلقه
+/// با تغییرِ امضای نوبت (نوبت|تعدادِ کارتِ زمین|فاز) ریست می‌شود و به انیمیشنِ بُر/
+/// پخش کاری ندارد. اینجا هم شمارش به همان امضا بسته می‌شود و فقط «پخشِ صدا» در حینِ
+/// انیمیشن/اینترو خاموش است تا صدا و تصویر یکی شوند.
+class TurnHeartbeat {
+  double _elapsed = 0;
+  bool _beatPlayed = false;
+  double _accum = 0;
+  bool _wasMyTurn = false;
+  String _sig = '';
+
+  /// هر فریم صدا زده می‌شود. [busy] یعنی اینترو/بُر زدن/پخشِ کارت در جریان است
+  /// (شمارش ادامه دارد اما صدایی پخش نمی‌شود).
+  void update(
+    double dt,
+    GameState? s, {
+    required bool silent,
+    required bool busy,
+  }) {
+    final isMyTurn = s != null &&
+        ((s.phase == 'playing' && s.turn == s.yourSeat) ||
+            (s.phase == 'choose_trump' && s.hakem == s.yourSeat));
+
+    if (!isMyTurn || silent) {
+      if (_wasMyTurn) {
+        AppSounds.stopHeartBeat(); // نوبت تمام شد ⇒ توقفِ فوریِ صدا
+        _wasMyTurn = false;
+      }
+      _sig = s == null ? '' : '${s.turn}|${s.trick.length}|${s.phase}';
+      return;
+    }
+
+    final sig = '${s.turn}|${s.trick.length}|${s.phase}';
+    if (!_wasMyTurn || sig != _sig) {
+      // شروعِ نوبتِ من (یا نوبتِ جدید) ⇒ شمارش از صفر، هم‌زمان با حلقه‌ی HUD.
+      _wasMyTurn = true;
+      _sig = sig;
+      _elapsed = 0;
+      _beatPlayed = false;
+      _accum = 0;
+      if (s.phase == 'playing' && !busy) AppSounds.turn();
+    }
+    _elapsed += dt;
+
+    if (busy) return;
+
+    final dur = (s.turnTimeoutMs > 0 ? s.turnTimeoutMs / 1000.0 : 30.0);
+    final remaining = dur - _elapsed;
+    final warn = math.min(7.0, dur * 0.4);
+    // در پنجره‌ی پایانیِ نوبت، ضربان با فاصله‌ی منظم تکرار می‌شود تا تا لحظه‌ی آخر
+    // شنیده شود (نه فقط یک ضربانِ زودهنگام که در سکوتِ پایانی گم می‌شود).
+    if (remaining > 0 && remaining <= warn) {
+      if (!_beatPlayed) {
+        _beatPlayed = true;
+        _accum = 0;
+        AppSounds.heartBeat();
+      } else {
+        _accum += dt;
+        if (_accum >= 0.95) {
+          _accum = 0;
+          AppSounds.heartBeat();
+        }
+      }
+    }
+  }
+
+  void stop() => AppSounds.stopHeartBeat();
+}