texas-poker-core 1.4.26 → 1.4.28

package/README.md

@@ -608,4 +608,12 @@ fix: 修复结算金额分配异常
 - 导出 `createStandardDeckPokes`，生成标准 52 张牌（与 `Deck` 建牌顺序一致）
 
 ## 1.4.26
-export new functiono 
+
+- 版本发布
+
+## 1.4.27
+
+reject modulo bias
+
+## 1.4.28
+贴盲与game start原子化

package/dist/Controller/index.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "StageEnum", {
   }
 });
 exports.default = void 0;
+var _Player = require("../Player");
 var _CurrentHand = require("../Hand/CurrentHand");
 var _handBettingActions = require("../Player/handBettingActions");
 var _TexasEngineContext = require("../TexasEngineContext");
@@ -22,6 +23,7 @@ function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLim
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
 function _arrayWithHoles(r) { if (Array.isArray(r)) return r; }
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t.return || t.return(); } finally { if (u) throw o; } } }; }
 function _toConsumableArray(r) { return _arrayWithoutHoles(r) || _iterableToArray(r) || _unsupportedIterableToArray(r) || _nonIterableSpread(); }
 function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
 function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
@@ -465,77 +467,19 @@ var Controller = /*#__PURE__*/function () {
      * 入池额 `min(桌大盲, 余额)`，与开局盲注路径一致；**不**调用 `completeBettingTurn`、不改变当前思考权。
      */
     function postBigBlindForJoiningPlayer(player) {
-      if (_classPrivateFieldGet(_hand, this).status !== 'in_hand') {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_NOT_IN_HAND));
-      }
-      if (_classPrivateFieldGet(_hand, this).stage !== _stage.StageEnum.PRE_FLOP) {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_NOT_PREFLOP));
-      }
-      if (_classPrivateFieldGet(_hand, this).activePlayer === player) {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_IS_ACTIVE_PLAYER));
-      }
-      if (player.getStatus() !== 'eligible') {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_PLAYER_INELIGIBLE));
-      }
-      if (player.currentStageTotalAmount !== 0) {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_ALREADY_CONTRIBUTED));
-      }
-      var requested = _classPrivateFieldGet(_dealer, this).stakes.bigBlind;
-      var balanceBefore = player.balance;
-      if (balanceBefore <= 0) {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_NO_CHIPS));
-      }
-
-      // `requested > 0`（TableStakes）且余额已正 ⇒ `#postBlind` 入池额必为正
-      var posted = _assertClassBrand(_Controller_brand, this, _postBlind).call(this, player, requested);
+      var row = _assertClassBrand(_Controller_brand, this, _applyJoiningBigBlindChips).call(this, player);
       _classPrivateFieldGet(_handEvents, this).push({
-        type: 'PostedBigBlind',
+        type: 'PostedJoiningBigBlinds',
         payload: _objectSpread(_objectSpread({}, _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)), {}, {
-          userId: player.getUserInfo().id,
-          amount: posted,
-          requested: requested
+          posts: [row]
         })
       });
-      this.recordPotUpdated();
     }
   }, {
     key: "takeActionInPreFlop",
     value: function takeActionInPreFlop() {
-      var _this2 = this;
-      _classPrivateFieldGet(_handEvents, this).push({
-        type: 'HandStarted',
-        payload: _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)
-      });
-      var takeDefaultActionPlayers = _assertClassBrand(_Controller_brand, this, _getSmallBindAndBigBind).call(this);
-      var posts = [];
-      takeDefaultActionPlayers.forEach(function (player, index) {
-        if (player) {
-          var requested = index === 0 ? _classPrivateFieldGet(_dealer, _this2).stakes.smallBlind : _classPrivateFieldGet(_dealer, _this2).stakes.bigBlind;
-          var kind = index === 0 ? 'sb' : 'bb';
-          var posted = _assertClassBrand(_Controller_brand, _this2, _postBlind).call(_this2, player, requested);
-          posts.push({
-            userId: player.getUserInfo().id,
-            amount: posted,
-            kind: kind
-          });
-          // 细粒度 PotUpdated：与自愿下注一致，每次入池一条（盲注用 skipDomainEvents，此处补发）。
-          _this2.recordPotUpdated();
-        }
-      });
-      _classPrivateFieldGet(_handEvents, this).push({
-        type: 'BlindsPosted',
-        payload: _objectSpread(_objectSpread({}, _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)), {}, {
-          posts: posts
-        })
-      });
-      var _takeDefaultActionPla = _slicedToArray(takeDefaultActionPlayers, 2),
-        bigBlind = _takeDefaultActionPla[1];
-      var activePlayer = bigBlind === null || bigBlind === void 0 ? void 0 : bigBlind.getNextPlayer();
-      if (activePlayer) {
-        this.transferControlTo(activePlayer);
-      } else {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_START_NO_ACTIVE));
-      }
+      _assertClassBrand(_Controller_brand, this, _emitHandStarted).call(this);
+      _assertClassBrand(_Controller_brand, this, _postTableBlindsAndFirstPreflopActor).call(this);
     }
   }, {
     key: "start",
@@ -545,20 +489,47 @@ var Controller = /*#__PURE__*/function () {
      * 写入 `HandStarted`、贴盲与 **`pendingFlowOps` / 跑马路状态**，再 `transferControlTo`（首人思考权先入队，待业务 flush）。
      */
     function start() {
-      if (_classPrivateFieldGet(_activeHandId, this) === null) {
-        return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_START_NO_HAND_PREP));
-      }
-      _classPrivateFieldSet(_pendingTurnEndedReason, this, null);
-      _classPrivateFieldSet(_pendingFlowOps, this, []);
-      _classPrivateFieldSet(_pausedActiveUserId, this, null);
-      _classPrivateFieldSet(_runoutMode, this, false);
-      _classPrivateFieldGet(_hand, this).status = 'in_hand';
-      _classPrivateFieldGet(_hand, this).stage = _stage.StageEnum.PRE_FLOP;
-      if (_TexasEngineContext.TexasEngineContext.simulation().resetDealerBeforeHandStart) {
-        _classPrivateFieldGet(_dealer, this).reset();
-      }
+      _assertClassBrand(_Controller_brand, this, _enterPreflopHandFrame).call(this);
       this.takeActionInPreFlop();
     }
+
+    /**
+     * 与 {@link start} 同属一手开局原子路径：先进入翻前帧并 `HandStarted`，再对 `joiningBigBlindUserIds`
+     * 依次入账（跳过 SB/BB、环上不存在 id 忽略），其间每条入池后各一条 `PotUpdated`；
+     * 最后 **恒** 缓冲一条 {@link PostedJoiningBigBlinds}，`posts` 为本次所有入座大盲（无人须贴时为空数组）；
+     * 再贴桌盲并 `transferControlTo(BB.getNext())`。
+     * 业务应仅此入口处理「待贴入座大盲」，勿在 `start()` 后再穿插 `PostBigBlind`。
+     */
+  }, {
+    key: "startPreflopWithJoiningBigBlinds",
+    value: function startPreflopWithJoiningBigBlinds(joiningBigBlindUserIds) {
+      _assertClassBrand(_Controller_brand, this, _enterPreflopHandFrame).call(this);
+      _assertClassBrand(_Controller_brand, this, _emitHandStarted).call(this);
+      var joiningPosts = [];
+      var _iterator = _createForOfIteratorHelper(joiningBigBlindUserIds),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var userId = _step.value;
+          var pl = _classPrivateFieldGet(_dealer, this).getById(userId);
+          if (!pl) continue;
+          var role = pl.getRole();
+          if (role === _Player.RoleEnum.SB || role === _Player.RoleEnum.BB) continue;
+          joiningPosts.push(_assertClassBrand(_Controller_brand, this, _applyJoiningBigBlindChips).call(this, pl));
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      _classPrivateFieldGet(_handEvents, this).push({
+        type: 'PostedJoiningBigBlinds',
+        payload: _objectSpread(_objectSpread({}, _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)), {}, {
+          posts: joiningPosts
+        })
+      });
+      _assertClassBrand(_Controller_brand, this, _postTableBlindsAndFirstPreflopActor).call(this);
+    }
   }, {
     key: "continue",
     value: function _continue() {
@@ -690,12 +661,12 @@ function _getPokeEndIndex(stage) {
   if (stage === _stage.StageEnum.RIVER) return 5;
 }
 function _performBettingRoundStageAdvance() {
-  var _this3 = this;
+  var _this2 = this;
   if (!_assertClassBrand(_Controller_brand, this, _everyPlayerNonActionableForRound).call(this)) {
     return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_FLOW_PENDING_MISMATCH));
   }
   var index = _stage.STAGE_ORDER.findIndex(function (stage) {
-    return stage === _classPrivateFieldGet(_hand, _this3).stage;
+    return stage === _classPrivateFieldGet(_hand, _this2).stage;
   });
   if (index < 0 || index >= _stage.STAGE_ORDER.length - 1) {
     return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_FLOW_PENDING_MISMATCH));
@@ -723,9 +694,9 @@ function _performBettingRoundStageAdvance() {
  * 摊牌跑马路一步：推进 `stage` 并 `StageAdvanced(runout_reveal)`；到河牌则 settle、`HandEnded`。
  */
 function _applyOneRunoutRevealStep() {
-  var _this4 = this;
+  var _this3 = this;
   var index = _stage.STAGE_ORDER.findIndex(function (s) {
-    return s === _classPrivateFieldGet(_hand, _this4).stage;
+    return s === _classPrivateFieldGet(_hand, _this3).stage;
   });
   if (index < 0 || index >= _stage.STAGE_ORDER.length - 1) {
     return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_FLOW_PENDING_MISMATCH));
@@ -760,6 +731,78 @@ function _postBlind(player, requested) {
   });
   return posted;
 }
+/**
+ * 入座大盲入账与池快照；供单条指令与批量开局共用（领域事件由调用方缓冲 `PostedJoiningBigBlinds`）。
+ */
+function _applyJoiningBigBlindChips(player) {
+  if (_classPrivateFieldGet(_hand, this).status !== 'in_hand') {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_NOT_IN_HAND));
+  }
+  if (_classPrivateFieldGet(_hand, this).stage !== _stage.StageEnum.PRE_FLOP) {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_NOT_PREFLOP));
+  }
+  if (_classPrivateFieldGet(_hand, this).activePlayer === player) {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_IS_ACTIVE_PLAYER));
+  }
+  if (player.getStatus() !== 'eligible') {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_PLAYER_INELIGIBLE));
+  }
+  if (player.currentStageTotalAmount !== 0) {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_ALREADY_CONTRIBUTED));
+  }
+  var requested = _classPrivateFieldGet(_dealer, this).stakes.bigBlind;
+  var balanceBefore = player.balance;
+  if (balanceBefore <= 0) {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_POST_BB_NO_CHIPS));
+  }
+  var posted = _assertClassBrand(_Controller_brand, this, _postBlind).call(this, player, requested);
+  player.grantJoiningBlindOption();
+  this.recordPotUpdated();
+  return {
+    userId: player.getUserInfo().id,
+    amount: posted,
+    requested: requested
+  };
+}
+function _emitHandStarted() {
+  _classPrivateFieldGet(_handEvents, this).push({
+    type: 'HandStarted',
+    payload: _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)
+  });
+}
+/** 桌 SB/BB、`BlindsPosted`，再 `transferControlTo(BB.getNext())`（翻前首动）；不含 `HandStarted`。 */
+function _postTableBlindsAndFirstPreflopActor() {
+  var _this4 = this;
+  var takeDefaultActionPlayers = _assertClassBrand(_Controller_brand, this, _getSmallBindAndBigBind).call(this);
+  var posts = [];
+  takeDefaultActionPlayers.forEach(function (player, index) {
+    if (player) {
+      var requested = index === 0 ? _classPrivateFieldGet(_dealer, _this4).stakes.smallBlind : _classPrivateFieldGet(_dealer, _this4).stakes.bigBlind;
+      var kind = index === 0 ? 'sb' : 'bb';
+      var posted = _assertClassBrand(_Controller_brand, _this4, _postBlind).call(_this4, player, requested);
+      posts.push({
+        userId: player.getUserInfo().id,
+        amount: posted,
+        kind: kind
+      });
+      _this4.recordPotUpdated();
+    }
+  });
+  _classPrivateFieldGet(_handEvents, this).push({
+    type: 'BlindsPosted',
+    payload: _objectSpread(_objectSpread({}, _assertClassBrand(_Controller_brand, this, _eventMeta).call(this)), {}, {
+      posts: posts
+    })
+  });
+  var _takeDefaultActionPla = _slicedToArray(takeDefaultActionPlayers, 2),
+    bigBlind = _takeDefaultActionPla[1];
+  var activePlayer = bigBlind === null || bigBlind === void 0 ? void 0 : bigBlind.getNextPlayer();
+  if (activePlayer) {
+    this.transferControlTo(activePlayer);
+  } else {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_START_NO_ACTIVE));
+  }
+}
 function _getSmallBindAndBigBind() {
   var _classPrivateFieldGet6;
   var smallBind = _classPrivateFieldGet(_dealer, this).count === 2 ? _classPrivateFieldGet(_dealer, this).button : (_classPrivateFieldGet6 = _classPrivateFieldGet(_dealer, this).button) === null || _classPrivateFieldGet6 === void 0 ? void 0 : _classPrivateFieldGet6.getNextPlayer();
@@ -769,6 +812,21 @@ function _getSmallBindAndBigBind() {
   })) return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_SB_BB_MISSING));
   return result;
 }
+/** 进入翻前会话帧（`in_hand` / `PRE_FLOP`、清队列）；须已有 `handId`；**不写**领域事件。 */
+function _enterPreflopHandFrame() {
+  if (_classPrivateFieldGet(_activeHandId, this) === null) {
+    return this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.CTRL_START_NO_HAND_PREP));
+  }
+  _classPrivateFieldSet(_pendingTurnEndedReason, this, null);
+  _classPrivateFieldSet(_pendingFlowOps, this, []);
+  _classPrivateFieldSet(_pausedActiveUserId, this, null);
+  _classPrivateFieldSet(_runoutMode, this, false);
+  _classPrivateFieldGet(_hand, this).status = 'in_hand';
+  _classPrivateFieldGet(_hand, this).stage = _stage.StageEnum.PRE_FLOP;
+  if (_TexasEngineContext.TexasEngineContext.simulation().resetDealerBeforeHandStart) {
+    _classPrivateFieldGet(_dealer, this).reset();
+  }
+}
 function _settle() {
   var commonPokes = this.getRevealedPokes();
   _classPrivateFieldGet(_hand, this).settlement.settleFromCommonBoard(_classPrivateFieldGet(_dealer, this).players, _classPrivateFieldGet(_dealer, this).getPlayersStillInGame(), commonPokes);

package/dist/Deck/index.js

@@ -23,6 +23,39 @@ function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("C
 function _classPrivateFieldGet(s, a) { return s.get(_assertClassBrand(s, a)); }
 function _classPrivateFieldSet(s, a, r) { return s.set(_assertClassBrand(s, a), r), r; }
 function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); }
+var TWO_POW_32 = 0x100000000;
+
+/**
+ * 均匀整数 `j` 满足 `0 <= j < n`（用于 Fisher–Yates 时 `n = maxInclusive + 1`）。
+ * - **生产 / RN**：`crypto.getRandomValues` + 拒绝采样，避免 `uint32 % n` 的 modulo bias；比 `Math.random` 更不可预测。
+ * - **Jest**：`NODE_ENV === 'test'` 时只用 `Math.random`，以便 `jest.spyOn(Math, 'random')` 固定发牌序（golden / imperative 对拍）。
+ *
+ * 更稳妥的架构化做法是构造 `Deck` 时注入 `() => number` 或 `randomInt(max)`；当前以零配置为先。
+ */
+function randomIntBelow(n) {
+  if (n <= 0) {
+    throw new Error("Deck shuffle: invalid range n=".concat(n));
+  }
+  var inJestTest = typeof process !== 'undefined' && process.env.NODE_ENV === 'test';
+  if (!inJestTest) {
+    var c = globalThis.crypto;
+    if (c !== null && c !== void 0 && c.getRandomValues) {
+      var limit = TWO_POW_32 - TWO_POW_32 % n;
+      var buf = new Uint32Array(1);
+      var v;
+      do {
+        c.getRandomValues(buf);
+        v = buf[0];
+      } while (v >= limit);
+      return v % n;
+    }
+  }
+  return Math.floor(Math.random() * n);
+}
+function randomIntInclusive(maxInclusive) {
+  return randomIntBelow(maxInclusive + 1);
+}
+
 /**
  * 52 张牌堆：生成、洗牌、按德州规则发手牌与公牌（含烧牌）。
  * 发牌结果由调用方写入 {@link DealtBoard}，本类不缓存手牌/公牌。
@@ -85,9 +118,10 @@ var Deck = /*#__PURE__*/function () {
 function _createDeck() {
   _classPrivateFieldSet(_deck, this, (0, _standardDeck.createStandardDeckPokes)());
 }
+/** Fisher–Yates；索引用 `crypto.getRandomValues`（若可用），否则回退 `Math.random`。 */
 function _shuffle() {
   for (var i = _classPrivateFieldGet(_deck, this).length - 1; i > 0; i--) {
-    var j = Math.floor(Math.random() * (i + 1));
+    var j = randomIntInclusive(i);
     var _ref = [_classPrivateFieldGet(_deck, this)[j], _classPrivateFieldGet(_deck, this)[i]];
     _classPrivateFieldGet(_deck, this)[i] = _ref[0];
     _classPrivateFieldGet(_deck, this)[j] = _ref[1];

package/dist/Player/allowedActions.js

@@ -51,7 +51,7 @@ function resolveAllowedActions(ctx) {
   };
   var last = (_ctx$dealerActionHist = ctx.dealerActionHistory[ctx.dealerActionHistory.length - 1]) !== null && _ctx$dealerActionHist !== void 0 ? _ctx$dealerActionHist : null;
   var result = _helper(last);
-  if (ctx.isBigBlindPreFlopOption && result.includes(_constant.ActionTypeEnum.CALL)) {
+  if ((ctx.isBigBlindPreFlopOption || ctx.isJoiningBlindPreFlopOption) && result.includes(_constant.ActionTypeEnum.CALL) && ctx.selfCurrentStageTotal >= ctx.maxOthersStageBet) {
     return [_constant.ActionTypeEnum.CHECK, _constant.ActionTypeEnum.RAISE, _constant.ActionTypeEnum.FOLD, _constant.ActionTypeEnum.ALL_IN];
   }
   return result;

package/dist/Player/index.js

@@ -63,6 +63,7 @@ var _handSession = /*#__PURE__*/new WeakMap();
 var _balance = /*#__PURE__*/new WeakMap();
 var _status = /*#__PURE__*/new WeakMap();
 var _action = /*#__PURE__*/new WeakMap();
+var _hasJoiningBlindOption = /*#__PURE__*/new WeakMap();
 var _stakes = /*#__PURE__*/new WeakMap();
 var _currentStageTotalAmount = /*#__PURE__*/new WeakMap();
 var _totalBetAmount = /*#__PURE__*/new WeakMap();
@@ -100,6 +101,7 @@ var Player = exports.Player = /*#__PURE__*/function () {
      *   业务「多调一次 flush」通常队头已非 `turn_handoff`，靠队列即可挡，不依赖本标记。
      */
     _classPrivateFieldInitSpec(this, _action, void 0);
+    _classPrivateFieldInitSpec(this, _hasJoiningBlindOption, false);
     _classPrivateFieldInitSpec(this, _stakes, void 0);
     /**
      * 当前阶段的下注总额, 全押筹码不够时可以小于此金额
@@ -199,7 +201,8 @@ var Player = exports.Player = /*#__PURE__*/function () {
         selfCurrentStageTotal: _classPrivateFieldGet(_currentStageTotalAmount, this),
         dealerActionHistory: _classPrivateFieldGet(_dealerRing, this).actionHistory,
         maxOthersStageBet: this.getMaxOthersStageBet(),
-        isBigBlindPreFlopOption: _assertClassBrand(_Player_brand, this, _isBigBlindOptionInPreFlop).call(this)
+        isBigBlindPreFlopOption: _assertClassBrand(_Player_brand, this, _isBigBlindOptionInPreFlop).call(this),
+        isJoiningBlindPreFlopOption: _assertClassBrand(_Player_brand, this, _isJoiningBlindOptionInPreFlop).call(this)
       };
     }
 
@@ -320,6 +323,7 @@ var Player = exports.Player = /*#__PURE__*/function () {
   }, {
     key: "notifyActionCommitted",
     value: function notifyActionCommitted(options) {
+      _classPrivateFieldSet(_hasJoiningBlindOption, this, false);
       _classPrivateFieldGet(_handSession, this).recordPlayerAction(this, {
         emitPot: options.emitPot
       });
@@ -403,8 +407,8 @@ var Player = exports.Player = /*#__PURE__*/function () {
       if (_classPrivateFieldGet(_status, this) === 'allIn' || _classPrivateFieldGet(_status, this) === 'out') return false;
       if (!_classPrivateFieldGet(_action, this)) return true;
 
-      // 翻牌前大盲具有最后行动权: 仅下过盲注视为未行动, 须给一次选择机会
-      if (_assertClassBrand(_Player_brand, this, _isBigBlindOptionInPreFlop).call(this) && _classPrivateFieldGet(_action, this).type === _constant.ActionTypeEnum.BET) return true;
+      // 翻牌前盲注选项：大盲或入座贴盲玩家仅下过盲注视为未行动，须给一次选择机会
+      if ((_assertClassBrand(_Player_brand, this, _isBigBlindOptionInPreFlop).call(this) || _assertClassBrand(_Player_brand, this, _isJoiningBlindOptionInPreFlop).call(this)) && _classPrivateFieldGet(_action, this).type === _constant.ActionTypeEnum.BET) return true;
 
       // 当前的下注金额已经等于最大下注额
       return _classPrivateFieldGet(_currentStageTotalAmount, this) !== this.getMaxBetAmountAtCurrentStage();
@@ -418,6 +422,7 @@ var Player = exports.Player = /*#__PURE__*/function () {
     key: "resetAction",
     value: function resetAction() {
       _classPrivateFieldSet(_action, this, undefined);
+      _classPrivateFieldSet(_hasJoiningBlindOption, this, false);
     }
   }, {
     key: "getAllowedActions",
@@ -640,6 +645,13 @@ var Player = exports.Player = /*#__PURE__*/function () {
       _classPrivateFieldGet(_handSession, this).recordTurnOffered(this);
       this.continue();
     }
+
+    /** 贴入座大盲后保留一次翻前主动选择权（直到该玩家提交一次自愿行动）。 */
+  }, {
+    key: "grantJoiningBlindOption",
+    value: function grantJoiningBlindOption() {
+      _classPrivateFieldSet(_hasJoiningBlindOption, this, true);
+    }
   }]);
 }();
 /**
@@ -649,6 +661,12 @@ var Player = exports.Player = /*#__PURE__*/function () {
 function _isBigBlindOptionInPreFlop() {
   return _classPrivateFieldGet(_handSession, this).stage === _stage.StageEnum.PRE_FLOP && _classPrivateFieldGet(_role, this) === _constant.RoleEnum.BB && _classPrivateFieldGet(_currentStageTotalAmount, this) >= this.getMaxBetAmountAtCurrentStage();
 }
+/**
+ * 翻牌前入座贴盲选项：已贴到当前最高注且尚未消耗该次行动机会时，可选择过牌/加注/弃牌/全下。
+ */
+function _isJoiningBlindOptionInPreFlop() {
+  return _classPrivateFieldGet(_handSession, this).stage === _stage.StageEnum.PRE_FLOP && _classPrivateFieldGet(_hasJoiningBlindOption, this) && _classPrivateFieldGet(_currentStageTotalAmount, this) >= this.getMaxBetAmountAtCurrentStage();
+}
 function _getAllowedActions() {
   return (0, _allowedActions.resolveAllowedActions)(this.getAllowedActionsContext());
 }

package/dist/Texas/index.js

@@ -1,5 +1,6 @@
 "use strict";
 
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
@@ -28,7 +29,6 @@ var _tableCommandParse = require("../domain/tableCommandParse");
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(e) { return e ? t : r; })(e); }
 function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != _typeof(e) && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
@@ -39,9 +39,12 @@ function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length)
 function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
 function _defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, _toPropertyKey(o.key), o); } }
 function _createClass(e, r, t) { return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
+function _classPrivateMethodInitSpec(e, a) { _checkPrivateRedeclaration(e, a), a.add(e); }
+function _checkPrivateRedeclaration(e, t) { if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object"); }
 function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _assertClassBrand(e, t, n) { if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n; throw new TypeError("Private element is not present on this object"); }
 /** 当前引擎角色表最多支持 10 人桌；更大人数需扩展 playerRoleSetMap */
 var SUPPORTED_MAX_TABLE_PLAYERS = 10;
 /**
@@ -50,6 +53,7 @@ var SUPPORTED_MAX_TABLE_PLAYERS = 10;
  * {@link TexasDomainEvent}，与文档中 `apply → events[]` 形态对齐；仍可用 {@link drainDomainEvents} 取出
  * 未经上述 API 消费的缓冲（少见）。进街/交权节奏由 {@link getPendingFlowOps} + `flush*` / `apply*` 驱动。
  */
+var _Texas_brand = /*#__PURE__*/new WeakSet();
 var Texas = /*#__PURE__*/function () {
   function Texas(_ref) {
     var user = _ref.user,
@@ -57,6 +61,8 @@ var Texas = /*#__PURE__*/function () {
       maximumCountOfPlayers = _ref.maximumCountOfPlayers,
       initialChips = _ref.initialChips;
     _classCallCheck(this, Texas);
+    /** `start` / `startPreflopWithJoiningBigBlinds` 共用的开局前置校验。 */
+    _classPrivateMethodInitSpec(this, _Texas_brand);
     _defineProperty(this, "pool", void 0);
     _defineProperty(this, "room", void 0);
     _defineProperty(this, "dealer", void 0);
@@ -232,23 +238,32 @@ var Texas = /*#__PURE__*/function () {
     value: function removePlayerByIdAsSystem(userId) {
       this.room.removeByIdForce(userId);
     }
-
+  }, {
+    key: "start",
+    value:
     /**
      * 开始本手：`HandStarted` / 盲注等事件进入缓冲，且队列入队首人 `turn_handoff`。
      * 须随后 drain 并消费队列，首条 `TurnOffered` 才会出现。
      */
-  }, {
-    key: "start",
-    value: function start() {
-      if (this.room.getPlayersBySeatStatus('on-set').length < 2) this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.SESSION_START_MIN_SEATED, {
-        min: 2
-      }));
-      if (this.room.status === 'seats_open') this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.SESSION_START_SEATS_OPEN));
-      if (this.controller.status !== 'idle') this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.SESSION_START_NOT_IDLE));
+    function start() {
+      _assertClassBrand(_Texas_brand, this, _assertCanStartHand).call(this);
       this.controller.start();
       return this.drainDomainEvents();
     }
 
+    /**
+     * 开始本手（含「入座大盲」）：与 {@link start} 相同前置条件；由 Core 原子完成
+     * `HandStarted` → 对 `joiningBigBlindUserIds` 贴入座大盲（跳过 SB/BB、未知 id 忽略）→ **恒** 一条 `PostedJoiningBigBlinds`（`posts` 汇总，无人须贴时为空数组）→ 桌盲 → `transferControlTo(BB.getNext())`。
+     * 业务应消费本批领域事件并驱动 `pendingFlowOps`；勿再于 `start()` 后自行 `dispatchCommand(PostBigBlind)`。
+     */
+  }, {
+    key: "startPreflopWithJoiningBigBlinds",
+    value: function startPreflopWithJoiningBigBlinds(joiningBigBlindUserIds) {
+      _assertClassBrand(_Texas_brand, this, _assertCanStartHand).call(this);
+      this.controller.startPreflopWithJoiningBigBlinds(joiningBigBlindUserIds);
+      return this.drainDomainEvents();
+    }
+
     /** 强制结束本手到 `between_hands`；状态校验由 {@link Controller.end} 负责（非 `in_hand` 时 `CTRL_END_NOT_IN_HAND`）。 */
   }, {
     key: "end",
@@ -450,4 +465,11 @@ var Texas = /*#__PURE__*/function () {
     }
   }]);
 }();
+function _assertCanStartHand() {
+  if (this.room.getPlayersBySeatStatus('on-set').length < 2) this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.SESSION_START_MIN_SEATED, {
+    min: 2
+  }));
+  if (this.room.status === 'seats_open') this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.SESSION_START_SEATS_OPEN));
+  if (this.controller.status !== 'idle') this.fail(new _TexasError.default(_TexasError.TexasCoreErrorCode.SESSION_START_NOT_IDLE));
+}
 var _default = exports.default = Texas;

package/dist/TexasEngineContext.js

@@ -18,7 +18,7 @@ function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e
  * 应用启动时 `configure`，单元测试可 `reset` 或按需 `configure`。
  */
 
-/** 与旧 PROJECT_ENV=dev 等行为对齐的可选仿真开关 */
+/** 进程级可选仿真开关（由 `Texas.configureEngine` / `TexasEngineContext.configure` 注入） */
 
 var DEFAULT_GLOBAL = {};
 var TexasEngineContext = exports.TexasEngineContext = /*#__PURE__*/function () {

package/dist/engine/domainEventReadModel.js

@@ -384,7 +384,7 @@ function reduceTurnEndedTrailFromDomainEvents(events) {
   return rows;
 }
 
-/** 本批中**最后一条** `PostedBigBlind`（中途入座大盲）。 */
+/** 本批中**最后一条** `PostedJoiningBigBlinds` 且 `posts` 非空时，取其 `posts` 末项（`PostBigBlind` 为单元素；批量开局为多行汇总）。`posts` 为空的事件跳过。 */
 
 function reduceLastPostedBigBlindFromDomainEvents(events) {
   var last = null;
@@ -393,11 +393,14 @@ function reduceLastPostedBigBlindFromDomainEvents(events) {
   try {
     for (_iterator13.s(); !(_step13 = _iterator13.n()).done;) {
       var e = _step13.value;
-      if (e.type === 'PostedBigBlind') {
-        var p = e.payload;
+      if (e.type === 'PostedJoiningBigBlinds') {
+        var posts = e.payload.posts;
+        if (posts.length === 0) continue;
+        var p = posts[posts.length - 1];
+        var meta = e.payload;
         last = {
-          handId: p.handId,
-          seq: p.seq,
+          handId: meta.handId,
+          seq: meta.seq,
           userId: p.userId,
           amount: p.amount,
           requested: p.requested

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "texas-poker-core",
-  "version": "1.4.26",
+  "version": "1.4.28",
   "description": "德州扑克核心功能",
   "main": "dist/index.js",
   "types": "types/index.d.ts",
   "scripts": {
-    "test": "cross-env PROJECT_ENV=prd jest",
+    "test": "jest",
     "prettier": "prettier --write \"**/*.{js,ts}\"",
     "prepare": "husky",
     "commitlint": "commitlint --edit",
@@ -14,15 +14,15 @@
     "prepublishOnly": "tsc --noEmit && pnpm run test",
     "build:types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true})\" && npx tsc && npx tsc-alias",
     "build:core": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && babel src --out-dir dist --extensions \".ts\"",
-    "build": "cross-env PROJECT_ENV=prd pnpm run build:types && pnpm run build:core",
+    "build": "pnpm run build:types && pnpm run build:core",
     "push-origin": "ts-node ./publish",
     "push-local": "bash scripts/push-local.sh",
-    "integration-test": "cross-env PROJECT_ENV=dev ts-node -r tsconfig-paths/register  ./src/integration_test.ts",
-    "simulatore": "cross-env PROJECT_ENV=prd ts-node -r tsconfig-paths/register  ./src/simulator_game_run.ts",
-    "replay:composite": "cross-env PROJECT_ENV=prd ts-node -r tsconfig-paths/register ./src/replay/replayCompositeCli.ts",
-    "replay:validate": "cross-env PROJECT_ENV=prd ts-node -r tsconfig-paths/register ./src/replay/replayValidateCli.ts",
-    "replay:verify": "cross-env PROJECT_ENV=prd ts-node -r tsconfig-paths/register ./src/replay/replayVerifyCli.ts",
-    "replay:canonical": "cross-env PROJECT_ENV=prd ts-node -r tsconfig-paths/register ./src/replay/replayCanonicalCli.ts"
+    "integration-test": "ts-node -r tsconfig-paths/register ./src/integration_test.ts",
+    "simulatore": "ts-node -r tsconfig-paths/register ./src/simulator_game_run.ts",
+    "replay:composite": "ts-node -r tsconfig-paths/register ./src/replay/replayCompositeCli.ts",
+    "replay:validate": "ts-node -r tsconfig-paths/register ./src/replay/replayValidateCli.ts",
+    "replay:verify": "ts-node -r tsconfig-paths/register ./src/replay/replayVerifyCli.ts",
+    "replay:canonical": "ts-node -r tsconfig-paths/register ./src/replay/replayCanonicalCli.ts"
   },
   "files": [
     "dist/**/*",
@@ -50,7 +50,6 @@
     "@types/ramda": "^0.30.2",
     "babel-plugin-module-resolver": "^5.0.2",
     "commitlint": "^19.7.1",
-    "cross-env": "^7.0.3",
     "eslint": "^9.21.0",
     "globals": "^16.0.0",
     "husky": "^9.1.7",

package/types/Controller/index.d.ts

@@ -10,8 +10,8 @@ import type { HandDomainEvent, TurnEndedReason } from '../domain/handDomainEvent
 import type { GameComponent, HandLifecycle, TexasErrorCallback } from '../gameContracts';
 import Pool from '../Pool';
 import Dealer from '../Dealer';
-import { Player } from '../Player';
 import { Poke } from '../Deck/constant';
+import { Player } from '../Player';
 import { StageEnum, type Stage } from './stage';
 export { StageEnum, type Stage } from './stage';
 export type { HandLifecycle };
@@ -121,12 +121,20 @@ declare class Controller implements GameComponent, PlayerHandSession<Player> {
      * 入池额 `min(桌大盲, 余额)`，与开局盲注路径一致；**不**调用 `completeBettingTurn`、不改变当前思考权。
      */
     postBigBlindForJoiningPlayer(player: Player): void;
-    takeActionInPreFlop(): undefined;
+    takeActionInPreFlop(): void;
     /**
      * 进入本手街道阶段：须在 {@link prepareHandTape} 之后调用；不清空已缓冲的 `RolesAssigned` / `HoleCardsDealt`。
      * 写入 `HandStarted`、贴盲与 **`pendingFlowOps` / 跑马路状态**，再 `transferControlTo`（首人思考权先入队，待业务 flush）。
      */
-    start(): undefined;
+    start(): void;
+    /**
+     * 与 {@link start} 同属一手开局原子路径：先进入翻前帧并 `HandStarted`，再对 `joiningBigBlindUserIds`
+     * 依次入账（跳过 SB/BB、环上不存在 id 忽略），其间每条入池后各一条 `PotUpdated`；
+     * 最后 **恒** 缓冲一条 {@link PostedJoiningBigBlinds}，`posts` 为本次所有入座大盲（无人须贴时为空数组）；
+     * 再贴桌盲并 `transferControlTo(BB.getNext())`。
+     * 业务应仅此入口处理「待贴入座大盲」，勿在 `start()` 后再穿插 `PostBigBlind`。
+     */
+    startPreflopWithJoiningBigBlinds(joiningBigBlindUserIds: ReadonlyArray<number>): void;
     continue(): undefined;
     settleRankingsThroughStage(throughStage: Stage): void;
     end(): undefined;

package/types/Player/allowedActions.d.ts

@@ -17,6 +17,7 @@ export type AllowedActionsContext = {
     }[];
     maxOthersStageBet: number;
     isBigBlindPreFlopOption: boolean;
+    isJoiningBlindPreFlopOption: boolean;
 };
 export declare function resolveAllowedActions(ctx: AllowedActionsContext): ActionTypeEnum[];
 /**

package/types/Player/index.d.ts

@@ -165,6 +165,8 @@ export declare class Player implements GameComponent {
         max: number;
     };
     getControl(): void;
+    /** 贴入座大盲后保留一次翻前主动选择权（直到该玩家提交一次自愿行动）。 */
+    grantJoiningBlindOption(): void;
 }
 /**
  * 仍可参与本街思考权轮转（未弃牌、未进入全下终态）。

package/types/Texas/index.d.ts

@@ -24,6 +24,7 @@ export { parseTableCommandFromJson, parseTableCommandFromUnknown } from '../doma
  * 未经上述 API 消费的缓冲（少见）。进街/交权节奏由 {@link getPendingFlowOps} + `flush*` / `apply*` 驱动。
  */
 declare class Texas {
+    #private;
     pool: Pool;
     room: Room;
     dealer: Dealer;
@@ -73,6 +74,12 @@ declare class Texas {
      * 须随后 drain 并消费队列，首条 `TurnOffered` 才会出现。
      */
     start(): TexasDomainEvent[];
+    /**
+     * 开始本手（含「入座大盲」）：与 {@link start} 相同前置条件；由 Core 原子完成
+     * `HandStarted` → 对 `joiningBigBlindUserIds` 贴入座大盲（跳过 SB/BB、未知 id 忽略）→ **恒** 一条 `PostedJoiningBigBlinds`（`posts` 汇总，无人须贴时为空数组）→ 桌盲 → `transferControlTo(BB.getNext())`。
+     * 业务应消费本批领域事件并驱动 `pendingFlowOps`；勿再于 `start()` 后自行 `dispatchCommand(PostBigBlind)`。
+     */
+    startPreflopWithJoiningBigBlinds(joiningBigBlindUserIds: readonly number[]): TexasDomainEvent[];
     /** 强制结束本手到 `between_hands`；状态校验由 {@link Controller.end} 负责（非 `in_hand` 时 `CTRL_END_NOT_IN_HAND`）。 */
     end(): TexasDomainEvent[];
     /** 中央池分配给赢家并缓冲 `PotAwarded`（通常在解释 `HandEnded` 时调用）。 */

package/types/TexasEngineContext.d.ts

@@ -2,7 +2,7 @@
  * 进程级引擎配置：仿真开关等（**不含**库内 trace；观测由业务对领域事件 / 指令自行记录）。
  * 应用启动时 `configure`，单元测试可 `reset` 或按需 `configure`。
  */
-/** 与旧 PROJECT_ENV=dev 等行为对齐的可选仿真开关 */
+/** 进程级可选仿真开关（由 `Texas.configureEngine` / `TexasEngineContext.configure` 注入） */
 export type TexasSimulationFlags = {
     /** balance setter 不生效 */
     ignoreBalanceSetter?: boolean;

package/types/domain/handDomainEvents.d.ts

@@ -22,7 +22,7 @@ export type HandEventMeta = {
  *
  * **顺序约定（终极目标 / 回放友好）**
  * - 自愿下注：`PlayerActed` 与同一次入池后的 **`PotUpdated` 紧邻**，且 **`PlayerActed` 在前**（见 `Controller.recordPlayerAction`）。
- * - 盲注：每次 `#postBlind` 入池后各一条 **`PotUpdated`**（细粒度），再以 **`BlindsPosted`** 汇总；不发 `PlayerActed`。
+ * - 盲注：每次 `#postBlind` 入池后各一条 **`PotUpdated`**（细粒度）。**入座大盲**：该批每位玩家的 `PotUpdated` **之后** 紧跟 **`PostedJoiningBigBlinds`**（`Texas#startPreflopWithJoiningBigBlinds` **恒** 一条、`posts` 汇总当次入账，无人须贴时 `posts` 为 `[]`；`PostBigBlind` 指令则每次一条且 `posts.length === 1`）。**桌 SB/BB**：各自 `PotUpdated` 之后 **`BlindsPosted`** 汇总；不发 `PlayerActed`。
  * - `seq` 在 {@link HandEventMeta} 中本手单调递增，与 `handId` 联用做幂等与重放键。
  */
 export type HandDomainEvent = {
@@ -53,14 +53,21 @@ export type HandDomainEvent = {
             kind: 'sb' | 'bb';
         }>;
     };
-} | {
-    type: 'PostedBigBlind';
+}
+/**
+ * 中途入座大盲汇总（与桌盲 {@link BlindsPosted} 区分：`requested` 为桌级大盲规定额，`amount` 为实际入池）。
+ *
+ * - {@link Texas#startPreflopWithJoiningBigBlinds}：每名待贴玩家先入账并各发 **`PotUpdated`**，再 **恒** 本条，`posts` 为当次全部行（经 SB/BB/未知 id 跳过后无人须贴则为 `[]`）。
+ * - `dispatchCommand({ type: 'PostBigBlind' })`：先 **`PotUpdated`**，再本条，`posts` 恒为单元素。
+ */
+ | {
+    type: 'PostedJoiningBigBlinds';
     payload: HandEventMeta & {
-        userId: number;
-        /** 实际入池（短码时为 `min(requested, balance)`） */
-        amount: number;
-        /** 桌级大盲规定额 */
-        requested: number;
+        posts: Array<{
+            userId: number;
+            amount: number;
+            requested: number;
+        }>;
     };
 } | {
     type: 'PlayerActed';

package/types/domain/tableCommand.d.ts

@@ -46,10 +46,15 @@ export type TableCommand = {
     playerId: number;
 }
 /**
- * 中途入座：在翻牌前、非当前思考方、且本街尚未入池时，按桌级大盲强制贴盲（`min(BB, 余额)`），
+ * 中途入座：在翻牌前、且本街尚未入池时，按桌级大盲强制贴盲（`min(BB, 余额)`），
  * 不交权、不触发自愿行动校验；金额由 core 从 `Dealer.stakes.bigBlind` 推导，不由业务传参。
+ *
+ * 默认仍拒绝 **当前 `activePlayer`**（防滥用自愿行动绕过）。业务在「一手开局后批量贴入座大盲」时，
+ * 若某待贴玩家恰为翻前首动位（`BB.getNext()`），须传 **`allowWhenCurrentActor: true`**（仅服务端对可信入座队列使用）。
  */
  | {
     type: 'PostBigBlind';
     playerId: number;
+    /** 为 true 时允许当前思考方贴入座大盲（须仍满足 `currentStageTotalAmount === 0` 等其余校验） */
+    allowWhenCurrentActor?: boolean;
 };

package/types/engine/domainEventReadModel.d.ts

@@ -102,7 +102,7 @@ export type TurnEndedEntry = Readonly<{
     reason: TurnEndedReason;
 }>;
 export declare function reduceTurnEndedTrailFromDomainEvents(events: readonly TexasDomainEvent[]): readonly TurnEndedEntry[];
-/** 本批中**最后一条** `PostedBigBlind`（中途入座大盲）。 */
+/** 本批中**最后一条** `PostedJoiningBigBlinds` 且 `posts` 非空时，取其 `posts` 末项（`PostBigBlind` 为单元素；批量开局为多行汇总）。`posts` 为空的事件跳过。 */
 export type PostedBigBlindReadModel = Readonly<{
     handId: string;
     seq: number;