dsh-blackjack 0.1.4 → 0.2.0

package/dist/i18n/en.js

@@ -0,0 +1,170 @@
+const n = (v) => v.toLocaleString('en-US');
+export const en = {
+    freeStakeLine: (bet) => `This hand is free: win and you take ${n(bet)} CHIP; lose and you are out nothing.`,
+    raiseStakeLine: (bet) => `${n(bet)} CHIP is committed from your balance for this hand.`,
+    freeWin: (payout) => `You won ${n(payout)} CHIP.`,
+    freeLose: () => 'This hand did not win. A free hand costs you nothing.',
+    freePush: () => 'A tie. Nothing gained, nothing lost.',
+    raiseWin: (payout, bet) => `You won — ${n(payout)} CHIP back (${n(bet)} committed).`,
+    raiseLose: (bet) => `This hand lost; the ${n(bet)} CHIP you committed is gone.`,
+    raisePush: (bet) => `A tie. Your ${n(bet)} CHIP comes back.`,
+    handLabel: () => 'Your hand: ',
+    splitHandLabel: (handIndex) => `Hand ${handIndex}: `,
+    dealerLabel: () => 'Dealer: ',
+    totalInParens: (total, isSoft) => ` (${isSoft ? 'soft ' : ''}${total})`,
+    doubled: () => ' [doubled]',
+    actionsPrefix: () => 'Available: ',
+    actionLabels: {
+        hit: '/bj-hit hit',
+        stand: '/bj-stand stand',
+        double: '/bj-double double down',
+        split: '/bj-split split',
+        insure: '/bj-insure buy insurance',
+        decline: '/bj-decline decline insurance',
+    },
+    actionsSeparator: () => ' ',
+    balanceLine: (chips, exchangedChips) => `Balance: ${n(chips)} CHIP  Exchanged so far: ${n(exchangedChips)} CHIP`,
+    freeHandsLine: (freeHandsRemaining, seasonId) => `Free hands left today: ${freeHandsRemaining}  Season: ${seasonId}`,
+    thresholdLine: (exchangeThresholdChips) => `Exchange threshold: ${n(exchangeThresholdChips)} CHIP (once reached, use /blackjack exchange)`,
+    pointsLine: (points) => `Points: ${n(points)}`,
+    poolEmptyNotice: () => "Note: this season's pool is spent; wins now grant points instead.",
+    pointsGrantedNotice: (points) => `This season's pool is spent, so you were granted ${n(points)} points instead.`,
+    chipValidityNotice: () => '(At season end, CHIP below the exchange threshold converts to points and is reclaimed; CHIP past the threshold carries over.)',
+    // 第四条跟着中文一起改（运营者单独批准，见 messages.ts 里 consentText 的
+    // 文档）：披露的不再只有赛季末回收，还有赛季中途的长期不活跃回收——服务端
+    // 的 recycleInactive 每天跑，把游戏余额和已兑换额度一起清零。
+    // 一个字都不许比中文多：不报天数（`inactive_recycle_days` 是可调配置，
+    // render.test.ts 里那条 `\b\d+\s*(day|week|month)\b` 反向断言就是为这个
+    // 存在的），也不把「有效期」说成一句"在赛季内有效"的保证——早先一版写作
+    // `Rewards are valid for the season`，把中文的**限制**说成了**承诺**，被打回过。
+    consentText: () => [
+        '[Please read before first use]',
+        "· This is a third-party mini-game published by a community developer; it is not affiliated with any model vendor and does not represent any vendor's position.",
+        '· Taking part is free: you get a limited number of free hands each day, losing costs you nothing, and your own API key and balance are unaffected.',
+        '· CHIP you win can only be exchanged, within this plugin, for model API quota to spend: it cannot be withdrawn, cannot be transferred to anyone else, and cannot be moved into any vendor account.',
+        '· Rewards carry a season-limited validity period; whatever is left unused is reclaimed under the rules after the season ends, or after a long stretch of inactivity.',
+        '',
+        'Once you have read and agree to the above, run /blackjack agree confirm to start.',
+    ].join('\n'),
+    agreeHint: () => 'Please read the notice and run /blackjack agree before using this.',
+    noRoundHint: () => 'No hand is in progress right now — run /blackjack deal to start one.',
+    commandUsage: () => 'agree | deal [amount] | exchange [amount] | reset',
+    actionDescriptions: {
+        hit: 'Blackjack: draw one card from the shoe',
+        stand: 'Blackjack: stand, ending your turn and moving to settlement',
+        double: 'Blackjack: double down — double your committed CHIP and draw exactly one more card',
+        split: 'Blackjack: split a pair of equal-rank cards into two hands',
+        insure: 'Blackjack: buy insurance when the dealer shows an Ace',
+        decline: 'Blackjack: decline insurance',
+    },
+    blackjackCommandDescription: () => 'Blackjack table (needs an open conversation): status, deal, exchange quota, reset',
+    genericFailure: () => "That didn't go through — please try again in a moment.",
+    serviceUnreachable: () => "Can't reach the table service right now — please try again shortly.",
+    dailyFreeHandsExhausted: () => "You're out of free hands for today — come back tomorrow.",
+    belowExchangeThreshold: (thresholdChips) => `Your balance hasn't reached the exchange threshold yet (needs ${n(thresholdChips)} CHIP).`,
+    insufficientBalance: () => "Your balance isn't enough to complete this action.",
+    roundAlreadyInProgress: () => 'A hand is already in progress.',
+    // Not "run /blackjack exchange again" — that's the very command that
+    // produced this code, and running it again just lands on the "give me an
+    // amount" prompt, not an actual way out. See this method's doc in
+    // messages.ts: no server code path can reach this state today.
+    githubBindingRequired: () => "This wallet's GitHub link looks inconsistent, so a direct exchange isn't possible right now. Please try again later; if it keeps happening, contact the operator.",
+    seasonCapReached: (capChips, exchangedThisSeasonChips) => `This would go over this season's exchange cap (cap ${n(capChips)} CHIP, already exchanged ${n(exchangedThisSeasonChips)} CHIP this season).`,
+    exchangeUnavailable: () => "Exchanging isn't available right now (an operator deployment setting is missing) — the table itself is unaffected, please try again later.",
+    betAmountAboveLimit: (maxChips) => `That amount is over the limit — the most you can raise is ${n(maxChips)} CHIP.`,
+    illegalAction: () => "That move isn't available anymore — the hand's state may have changed. Run /blackjack to see the current state.",
+    registerRateLimited: () => 'Too many registrations from this network right now — please try again later.',
+    // Both commands, not one: `reset` alone never gets a new token, and `agree`
+    // alone is short-circuited by `identity.accept()`'s `if (existing) return
+    // existing`, handing back the very credential the server rejected. See this
+    // method's doc in messages.ts — the path was checked against the code.
+    unknownPlayerToken: () => "The table service no longer recognizes the credential stored on this machine (the server was reset, or serverUrl now points at a different deployment). Run /blackjack reset confirm to clear it, then /blackjack agree to start over.",
+    agreeWelcome: () => [
+        'You have confirmed the notice — welcome to the table.',
+        "Run /blackjack deal to start today's free hand, or /blackjack deal <amount> to raise from your balance.",
+    ].join('\n'),
+    invalidBetAmount: () => 'The amount must be a positive integer.',
+    pairingInstructions: (url, minutes) => [
+        'Linking a GitHub account is required for your first exchange — this is a one-time step.',
+        '',
+        'Open this link in your browser:',
+        url,
+        '',
+        'After opening it, click "Continue with GitHub" to authorize, then enter the amount to exchange on the same page and submit.',
+        `The link stays valid for about ${minutes} ${minutes === 1 ? 'minute' : 'minutes'}; if it expires, just run /blackjack exchange again for a new one.`,
+        'Once linked, use /blackjack exchange <amount> directly from now on — no more browser trips needed.',
+    ].join('\n'),
+    exchangeAmountPrompt: (githubLogin, chips, exchangeThresholdChips) => [
+        `GitHub account linked: ${githubLogin}`,
+        `Current balance: ${n(chips)} CHIP  Exchange threshold: ${n(exchangeThresholdChips)} CHIP`,
+        'Use /blackjack exchange <amount> to specify how much CHIP to exchange.',
+    ].join('\n'),
+    invalidExchangeAmount: () => 'The exchange amount must be a positive integer.',
+    exchangeSuccess: (chips, exchangedChips) => [
+        `You exchanged ${n(chips)} CHIP.`,
+        `Total exchanged so far: ${n(exchangedChips)} CHIP`,
+        "This quota automatically takes over the one request that fails once your own model quota runs out; it isn't touched otherwise, and there's nothing you need to do.",
+    ].join('\n'),
+    // 新写的英文，不是中文的直译：三件事一件不能多、一件不能少——只能在插件内
+    // 消费/不可提现/不可转让、不因赛季结束清零、N 天无游戏无消费触发回收进奖池。
+    // 参见 messages.ts 里这条方法的文档：Task 3 曾经因为英文比中文说得更肯定
+    // 被打回，这里对着中文原句逐条核对过一遍。
+    // The `true` branch drops the middle clause and nothing else — it does NOT
+    // claim the opposite. The server only says "this expires at season end"; it
+    // says nothing about when, or at what rate, and inventing those details
+    // would be the same false promise 「有效期至本赛季末」 was, in reverse.
+    exchangedQuotaNote: (inactiveRecycleDays, expiresAtSeasonEnd) => expiresAtSeasonEnd
+        ? `Exchanged quota is spendable only inside this plugin — it can't be withdrawn or transferred. An account with ${inactiveRecycleDays} consecutive days of no play and no spending has its balance recycled into the pool.`
+        : `Exchanged quota is spendable only inside this plugin — it can't be withdrawn or transferred. It doesn't expire at the end of a season; but an account with ${inactiveRecycleDays} consecutive days of no play and no spending has its balance recycled into the pool.`,
+    resetConfirmPrompt: () => 'This clears the table credential saved on this machine (server-side records are unaffected; pairing again will recover it). Confirm with /blackjack reset confirm',
+    resetDone: () => 'Local credential cleared. Run /blackjack agree to start over.',
+    unknownSubcommand: (sub, usage) => `Unknown subcommand "${sub}". Available: ${usage}`,
+    poolSwitchNotice: () => 'Switched to the pool balance to continue this request.',
+    noCredentialHint: () => "The fallback route only takes over once your own model quota is exhausted; right now no API key is configured, so your exchanged quota can't be used yet.",
+    hiddenCardLabel: () => 'Hidden card',
+    tableHandLabel: () => 'Your hand',
+    tableSplitHandLabel: (handIndex) => `Hand ${handIndex}`,
+    tableDealerLabel: () => 'Dealer',
+    tableActionLabels: {
+        hit: 'Hit',
+        stand: 'Stand',
+        double: 'Double down',
+        split: 'Split',
+        insure: 'Buy insurance',
+        decline: 'Decline insurance',
+    },
+    // 分隔符用 ' · '，不是双 ASCII 空格：中文那边用的 U+3000（全角空格）在 CSS
+    // 里天生不可折叠，视觉上就是宽间隔；英文这边如果用两个普通空格，落进
+    // Table.tsx 那个没有 white-space 覆盖的 <div>（默认 `normal`）时，连续空白
+    // 会被 HTML 渲染折叠成一个，四段字段就会挤成一整行看不出分段。已经在这个
+    // 文件里的 `insufficientBalanceSuffix`/`freeHandsRemainingToday` 等地方用过
+    // 同一个可见分隔符，这里跟着统一，而不是再造一个会被折叠的写法。
+    tableBalanceHeader: (chips, freeHandsRemaining) => `Balance: ${n(chips)} CHIP · Free hands left today: ${freeHandsRemaining}`,
+    tablePointsSuffix: (points) => ` · Points: ${n(points)}`,
+    tableExchangedSuffix: (exchangedChips) => ` · Exchanged so far: ${n(exchangedChips)} CHIP`,
+    tableExchangeThresholdReached: (exchangeThresholdChips) => `You've reached the exchange threshold (${n(exchangeThresholdChips)} CHIP) — use /blackjack exchange to turn CHIP into model quota`,
+    tableExchangeThresholdShort: (shortChips, exchangeThresholdChips) => `${n(shortChips)} CHIP short of the exchange threshold (${n(exchangeThresholdChips)}) — once you cross it, use /blackjack exchange to turn CHIP into model quota`,
+    tableExchangedQuotaNote: (exchangedChips) => `The ${n(exchangedChips)} CHIP you've exchanged automatically takes over the one request that fails once your own model quota runs out; it isn't touched otherwise.`,
+    tablePoolEmptyNotice: () => "(This season's pool is spent — wins now grant points instead)",
+    actionShortfallHint: (costChips) => `${n(costChips)} more CHIP needed — balance too low`,
+    tableCostSuffix: (costChips) => ` (${n(costChips)})`,
+    betAmountMissing: () => 'Enter an amount.',
+    betAmountExceedsCap: (maxChips) => `The cap for a single hand is ${n(maxChips)} CHIP.`,
+    betAmountExceedsBalance: () => "Your balance isn't enough for this amount.",
+    customBetToggle: () => 'Custom amount',
+    customBetSubmit: () => 'Start',
+    customBetRange: (maxChips) => `1 to ${n(maxChips)} CHIP`,
+    noActiveRoundNotice: () => 'No hand is in progress right now.',
+    freeHandsGroupTitle: () => 'Free hands',
+    freeHandsRemainingToday: (freeHandsRemaining) => ` · ${freeHandsRemaining} left today`,
+    freeHandsExhaustedToday: () => ' · used up for today — come back tomorrow',
+    freeHandExplainer: (baseChips, naturalBlackjackPayoutChips) => `No CHIP required. Win and you take ${n(baseChips)} CHIP; a natural blackjack in the first two cards (an Ace with a 10/J/Q/K) pays ${n(naturalBlackjackPayoutChips)}. Lose or tie and you are out nothing.`,
+    startFreeHandButton: () => 'Start a free hand',
+    raiseGroupTitle: () => 'Raise from your balance',
+    insufficientBalanceSuffix: () => ' · balance too low',
+    raiseExplainer: () => 'The CHIP you raise comes from your balance: win and it doubles, lose and it is gone.',
+    rematchFreeLabel: () => 'Play again (free)',
+    dealButtonFreeHandsSuffix: (freeHandsRemaining) => ` — ${freeHandsRemaining} left`,
+    dismissButton: () => 'Dismiss',
+    actionFailedNotice: () => "That didn't go through — you've been refreshed to the latest state.",
+};

package/dist/i18n/index.d.ts

@@ -0,0 +1,4 @@
+import type { LocaleId, Messages } from './messages.js';
+export { LOCALES } from './messages.js';
+export type { LocaleId, Messages } from './messages.js';
+export declare function resolveMessages(locale: LocaleId): Messages;

package/dist/i18n/index.js

@@ -0,0 +1,6 @@
+import { zh } from './zh.js';
+import { en } from './en.js';
+export { LOCALES } from './messages.js';
+export function resolveMessages(locale) {
+    return locale === 'zh' ? zh : en;
+}

package/dist/i18n/messages.d.ts

@@ -0,0 +1,412 @@
+/**
+ * 面向玩家的全部文案，按 locale 分成两份实现。
+ *
+ * 为什么是"接口 + 两个实现"而不是 t(key) 查表：`satisfies Messages` 让漏翻一条
+ * 直接编译失败，根本发不出去；查表方案漏翻通常只是静默回退或输出 key。这个项目
+ * 已经因为"同一句话在两处不同步"吃过两次亏，多语言会把这个风险乘以二。
+ *
+ * 为什么每条是函数而不是模板串：中文没有复数、英文有（1 hand / 2 hands），语序
+ * 也不同。函数让两种语言各自把话说顺。
+ */
+export declare const LOCALES: readonly ["zh", "en"];
+export type LocaleId = (typeof LOCALES)[number];
+/**
+ * 英文文案的红线，对标 render.ts 的 `BANNED`。
+ *
+ * 曾经写作 `/gambl|casino|\bwager\b|\bbet\b|real money/i`，只挡五个字面 token，
+ * 比中文那条松得多，而且松在两个地方：
+ *
+ * 一是词形。`\bbet\b` 的词边界在 bet 之后就断了，bets / betting / bettor 全部
+ * 漏网——而这三个正是英文里真正会写出来的形态，光秃秃的 "bet" 反而少见。
+ *
+ * 二是概念。中文的 `赢钱` 禁的是"把赢来的东西说成钱"这件事本身，英文这边却
+ * 只禁 real money，cash out / winnings / payout / jackpot 一律放行。这个项目的
+ * 全部合规站位就建立在"赢来的 CHIP 不是钱、不可提现"上，用 payout 或 winnings
+ * 描述结算，等于在文案层面把这条站位拆掉。
+ *
+ * 收紧的时机是现在而不是以后：后面还有五个任务要写新的英文文案，每一条都按
+ * 这条正则验收。先把线划到位，比等文案写完再回头重审所有文案便宜得多。
+ *
+ * 词边界要当心：`bett?` 单独用会误伤 better/betterment，所以后缀写成显式的
+ * `(?:s|ing|or|ors)?` 再收一个 `\b`。i18n.test.ts 里有一张"必须拦下"和一张
+ * "不许误伤"的清单钉住这两侧。
+ */
+export declare const BANNED_EN: RegExp;
+export interface Messages {
+    /** 免费局进行中：不出 CHIP，赢了拿多少。 */
+    freeStakeLine(betChips: number): string;
+    /** 加注局进行中：已从余额里出多少。 */
+    raiseStakeLine(betChips: number): string;
+    freeWin(payoutChips: number): string;
+    freeLose(): string;
+    freePush(): string;
+    raiseWin(payoutChips: number, betChips: number): string;
+    raiseLose(betChips: number): string;
+    raisePush(betChips: number): string;
+    /**
+     * 手牌标签及其后缀标点全部在这里——不是"你的牌"四个字单独一条，是因为
+     * 冒号、括号这类标点在两种语言里长得不一样（全角冒号 vs ASCII 冒号），把它们
+     * 留在 render.ts 拼接会让 render.ts 里又出现语言相关的字符。函数返回的是可以
+     * 直接和牌面字符串拼接的完整前缀。
+     */
+    handLabel(): string;
+    /** 分牌后第 N 手的标签，同样带上后缀标点。 */
+    splitHandLabel(handIndex: number): string;
+    dealerLabel(): string;
+    /**
+     * 点数展示：`（软18）`/`（18）` 这个带括号的整体，`isSoft` 决定是否插入"软"。
+     *
+     * 曾经叫 `soft()`，两次不同任务的 review 各自独立提过一次：那个名字读起来像
+     * "返回软点数"，可它真正的产物是"括号里的点数"，`isSoft` 只是其中一个开关。
+     * 三个生产调用点里有两个（`render.ts` 与 `Table.tsx` 的庄家那一行）传的是
+     * `false`，也就是说这个方法最常见的用法恰恰和它的旧名字相反。
+     */
+    totalInParens(total: number, isSoft: boolean): string;
+    /** 双倍标记，含前导空格；未双倍时调用方直接用空字符串，不调用这个方法。 */
+    doubled(): string;
+    /** "可选：" 前缀，后面接 actionLabels 拼出来的动作列表。 */
+    actionsPrefix(): string;
+    /** 六个动作按钮的完整文案（含斜杠指令），键与 view.actions 里的动作名一致。 */
+    actionLabels: Record<'hit' | 'stand' | 'double' | 'split' | 'insure' | 'decline', string>;
+    /**
+     * 拼接 actionLabels 之间的分隔符。中文原本用全角空格（U+3000）分隔——这也是
+     * 玩家看到的输出的一部分，不是纯排版细节，所以必须由 locale 决定，不能在
+     * render.ts 里写死一个两边共用的字符（写死 ASCII 空格会悄悄改掉中文原有输出；
+     * 写死全角空格则会让英文动作列表看起来断裂）。
+     */
+    actionsSeparator(): string;
+    balanceLine(chips: number, exchangedChips: number): string;
+    freeHandsLine(freeHandsRemaining: number, seasonId: string): string;
+    thresholdLine(exchangeThresholdChips: number): string;
+    pointsLine(points: number): string;
+    poolEmptyNotice(): string;
+    /** 奖池已发完，改发积分时的提示，需要报出实际发放的积分数。 */
+    pointsGrantedNotice(points: number): string;
+    /** 赛季结束时未达兑换门槛的 CHIP 会被折算回收的提醒。 */
+    chipValidityNotice(): string;
+    /**
+     * 首次使用须知的全文（含标题行、四条正文、空行、末尾的下一步指引），玩家要
+     * 对着它点同意。
+     *
+     * 为什么整段是一个方法而不是拆成七条：这七行是一份声明，不是七句可以各自
+     * 增删的界面文案。拆开之后，任何一次"只改其中一行"的改动都不会强迫改动者
+     * 重读上下文，而这段话的分寸恰恰在于几条之间的相互限定（比如"只能在插件内
+     * 兑换"和后面三条禁止是一体的）。整段搬运也让中英两版能一行对一行地比对。
+     *
+     * 措辞上的红线：英文版不许比中文版更具体，也不许更含糊。「按规则回收」是
+     * 刻意留的模糊——回收细则还会变，写死天数就是又一次假承诺（这个项目已经
+     * 因为把话说得比代码更精确而翻过两次车）。三条禁止（不可提现／不可转让／
+     * 不可转入厂商账户）和"无关联 + 不代表其立场"这两组，任何一版都必须齐全。
+     *
+     * **第四条为什么在 i18n 分支里被改写过一次**（这是本分支唯一一处经运营者
+     * 单独批准、跳出"中文只搬运不改写"那条规则的合规文案改动）：原句只说
+     * 「赛季结束后未使用的部分按规则回收」，只披露了赛季末这一个触发条件。可
+     * 服务端 `jobs.ts` 的 `recycleInactive` 每天 00:15 由 cron 跑一次，把
+     * `inactive_recycle_days`（当前配置 7 天）内既无游戏、也无消费的账户交给
+     * `ledger.ts` 的 `recycleAll`——**游戏余额和已兑换额度一起清零**，而且完全
+     * 不等赛季结束，赛季中途就会发生。也就是说"赢了 CHIP、停手一周、回来余额
+     * 归零"这条最常见的真实路径，在玩家点"同意"的那一刻一个字都没被告知，而
+     * 这段话正是这个项目全部合规站位的承重墙。现在两个触发条件都写进去了。
+     *
+     * 改写之后仍然不写天数：`inactive_recycle_days` 是运营者随时可调的配置，
+     * 把 7 写进须知，运营者下次调参就把这句话变成假的——这正是上一段那两次
+     * 翻车的同一个形状。`render.test.ts` 里英文那侧有一条反向断言
+     * （`\b\d+\s*(day|week|month)\b` 不许出现）专门守着这一点，中文那侧则
+     * 正面钉住「按规则」这个刻意的模糊还在。两侧同时钉住了新加的这半句本身，
+     * 免得它哪天被"顺一顺措辞"顺没了。
+     */
+    consentText(): string;
+    /** 还没同意须知时，任何需要凭证的命令都用这句拒绝并指路。 */
+    agreeHint(): string;
+    /** 没有进行中的牌局时，动作命令（bj-hit 等）用这句指路去 deal。 */
+    noRoundHint(): string;
+    /** `/blackjack` 命令的用法提示，同时用在 command 注册的 `input.hint` 和"未知子命令"的错误里。 */
+    commandUsage(): string;
+    /** 六个 bj-* 命令注册时各自的 description，键与 ACTIONS 里的 action 名一致。 */
+    actionDescriptions: Record<'hit' | 'stand' | 'double' | 'split' | 'insure' | 'decline', string>;
+    /**
+     * `/blackjack` 命令本身的 description。
+     *
+     * **「需要先有会话」必须放在最前面，别挪到后面去。** 宿主在启动页
+     * （Into the Unknown）会渲染命令补全，补全里显示的就是这句——但在那一屏
+     * 执行命令只会静默失败：命令真的跑了，一行都不渲染，用户看到的是"插件坏了"。
+     * 补全是启动页上唯一由我们提供内容的地方（其余挂点要么是替换式的、要么在
+     * 那一屏根本不渲染，2026-08-22 实测），所以这句话是我们能在失败现场说的
+     * 唯一一句。而补全的描述列**会截断**，放后面等于没写。
+     */
+    blackjackCommandDescription(): string;
+    /**
+     * 兜底失败文案：`ApiError` 的 `code` 不在已知映射表里时用这句——可能来自
+     * 一个比这版插件更新的服务端（加了新 code 没同步），也可能是插件这边漏映射
+     * 了。不管哪种，绝不能把服务端的英文诊断散文（`ApiError.message`）直接
+     * 甩给玩家：那正是 Task 7 要修的缺陷本身（把 message 错当 code 匹配）。
+     */
+    genericFailure(): string;
+    /** 网络层失败（status 0 或 5xx）：牌桌服务本身连不上。 */
+    serviceUnreachable(): string;
+    /** code `no-free-hands-left`：今日免费手已用完。 */
+    dailyFreeHandsExhausted(): string;
+    /**
+     * code `below-exchange-threshold`（原名 `below-threshold`——review 指出
+     * "below WHICH threshold"是个契约名不该留给读者猜的问题，改了名）：余额
+     * 没到兑换门槛。`thresholdChips` 来自服务端 `error.thresholdChips`——一个
+     * code 配一个数字，能让玩家知道具体还差多少，比一句不带数字的通用拒绝更
+     * 有用。**`thresholdChips` 缺失（跨版本的服务端没带这个字段）时不要编一个
+     * 数字出来**：`mapError` 在这种情况下改叫 `genericFailure()`，不会用 0 之
+     * 类的假数字调用这个方法——见 `commands.ts` 里 `numberDetail` 的文档。
+     */
+    belowExchangeThreshold(thresholdChips: number): string;
+    /** code `insufficient-balance`：余额不足以完成这个动作（开局加注、双倍/分牌/保险、或兑换超额）。 */
+    insufficientBalance(): string;
+    /**
+     * code `active-round-exists`：已经有一局在进行中。单独一行文本——`mapError`
+     * 的恢复分支里会把它和 `renderRound(round, m)` 拼在一起展示，所以这句话
+     * 本身不能带牌局细节。
+     */
+    roundAlreadyInProgress(): string;
+    /**
+     * code `github-binding-required`：直接兑换（`POST /api/exchange`）要求已绑定
+     * GitHub 身份（服务端读的是 `players.github_id`）。正常操作下这条在
+     * `doExchange` 里走不到——未绑定的玩家会先被 `me.githubLogin === null`
+     * （`players.github_login`）分流去配对流程，根本不会调用这个端点。
+     *
+     * **不要建议玩家重新执行 `/blackjack exchange`。** review 抓到过一版文案
+     * 这么写，但唯一能拿到这个 code 的路径就是先跑了
+     * `/blackjack exchange <数量>`——重新执行只会命中 `exchangeAmountPrompt`
+     * （因为 `me.githubLogin` 非空，插件不会再走配对分支），是一个循环建议，
+     * 不是真的恢复路径。核实过 `github_id`/`github_login` 在服务端只有一处
+     * 写入（`pairing.ts` 的 OAuth 回调，两个字段总是同一条 UPDATE 一起写），
+     * 也没有任何清除 `github_id` 单独留下 `github_login` 的代码路径——也就是说
+     * 触发这个 code 需要的"`github_login` 非空但 `github_id` 为空"这种状态，
+     * 在当前代码库里根本走不到，这是纯粹面向未来（服务端换了实现、数据被手动
+     * 改过）的防御性分支，不该假装有一个真实存在的恢复步骤。措辞因此只说"绑定
+     * 状态不一致、稍后再试、持续出现请联系运营者"，不指一条不存在的路。
+     */
+    githubBindingRequired(): string;
+    /**
+     * code `would-exceed-season-cap`（原名 `season-cap-reached`——review 指出
+     * 触发条件是 `exchangedThisSeasonChips + chips > capChips`，也就是"这一笔
+     * 会让累计超过上限"，不是"已经到达上限"；旧名字暗示的是后者，跟这里的
+     * 中英文案一直在说的「会超过」/"would go over"对不上，改了名让 code 配得上
+     * 自己的文案）。`capChips`/`exchangedThisSeasonChips` 来自服务端，报出
+     * "上限是多少、已经用掉多少"，比一句"兑换失败"有用得多。
+     */
+    seasonCapReached(capChips: number, exchangedThisSeasonChips: number): string;
+    /**
+     * code `exchange-unavailable`：运营者部署缺配置（`PUBLIC_URL`/
+     * `GITHUB_CLIENT_ID`/`GITHUB_CLIENT_SECRET` 之一），兑换整个功能暂时用不了。
+     * 故意不说"连不上牌桌服务"（`serviceUnreachable`）——牌局本身其实是好的，
+     * 只是兑换这一项不可用，说成"整个服务连不上"会让玩家误以为要重开插件。
+     *
+     * 这个方法曾经是死代码：`mapError` 里 `status>=500` 的短路判断写在 code
+     * 匹配之前，而这个 code 走的是 503，于是这句文案永远渲染不到，玩家看到的
+     * 一直是 `serviceUnreachable()` 那句——恰恰是上一段说"故意不要"的那句话
+     * （review 抓到）。`mapError` 现在把 code 匹配挪到了 5xx 短路之前，见
+     * `commands.ts` 的注释。
+     */
+    exchangeUnavailable(): string;
+    /**
+     * code `bet-amount-too-high`：加注数额超过服务端配置的上限。`maxChips` 来自
+     * 服务端 `error.maxChips`——这个数字之前只活在英文诊断散文里
+     * （"betChips must be an integer in [1, N]"），Task 7 把它拆成了字段。
+     *
+     * 这个 code 曾经叫 `invalid-bet-amount`，同一个 code 还盖着"不是正整数"
+     * 这另一种情况——但这句文案只讲得通"超过上限"。review 指出这只在插件自己
+     * 从不发送非法格式的前提下才是真话（`doDeal` 确实做了整数校验），而那个
+     * 前提活在另一个包里；服务端因此把两种情况拆成了两个 code：
+     * `invalid-bet-amount` 现在专指"不是正整数"（映射到 `genericFailure`——
+     * 插件自己触发不了这种请求），`bet-amount-too-high` 专指"超过上限"（这个
+     * 才是玩家真的会撞到的：加注数额没错格式，只是太大）。
+     */
+    betAmountAboveLimit(maxChips: number): string;
+    /**
+     * code `illegal-action`：这个动作在当前这手牌上不可用了。真实可达：玩家在
+     * 图形牌桌和命令行之间切换时，命令行的 `doAction` 只按 `ACTIONS` 里的固定
+     * 六个动作直接发送，不会先问一遍服务端"现在能做什么"——如果这手牌的状态
+     * 已经在别处推进过（比如刚在牌桌上点了停牌），这条命令仍会把已经不可用的
+     * 动作发过去。
+     */
+    illegalAction(): string;
+    /**
+     * code `register-rate-limited`：`/blackjack agree confirm` 触发的注册被服务端
+     * 的注册限流拒绝（`register_max_per_hour`/`register_max_per_ip_per_hour`，
+     * 防的是脚本批量注册领免费手掏空奖池）。真实玩家撞上的多半是共享出口 IP
+     * （公司网络、校园网），不是自己做错了什么，所以措辞不能听起来像指责。
+     */
+    registerRateLimited(): string;
+    /**
+     * code `unknown-player-token`：服务端不认识本机保存的那枚玩家令牌
+     * （`packages/server/src/auth.ts` 的 401）。
+     *
+     * 这条曾经是整个服务端唯一一处站在错误码体系之外的玩家可见错误：服务端发的是
+     * 裸 `{ error: 'unauthorized' }`，`mapError` 认不出，落进 `default` → 5xx/其它
+     * 状态都不匹配 → `genericFailure()`，玩家看到"操作没有成功，请稍后再试"。
+     * 而这句话在这个场景里是**一条死路**——令牌不会自己变回被认识的样子，玩家
+     * 每重试一次就再撞一次同一堵墙。
+     *
+     * 真实来路有两条，都不是玩家做错了什么：服务端换过库（Railway 换卷、重新
+     * 部署到空数据库），或者玩家把 `serverUrl` 改指到了另一个部署（README 明确
+     * 鼓励自建奖池）。
+     *
+     * 恢复路径是在代码里核对过的，不是照文档抄的：本机令牌就是同意记录
+     * （`identity.ts` 的注释），而 `identity.accept()` 一上来就 `if (existing)
+     * return existing`——不先清掉那枚坏令牌，`agree confirm` 只会把同一枚令牌
+     * 原样还回来。所以必须两步：`/blackjack reset confirm` 走 `identity.clear()`
+     * 抹掉凭证，再 `/blackjack agree` 重新走一遍须知（它自己会指向
+     * `agree confirm`，那一步才 `api.register()` 换一枚新令牌）。措辞里两条命令
+     * 都要点名，只说 `reset` 或只说 `agree` 都走不通。
+     */
+    unknownPlayerToken(): string;
+    /** agree confirm 成功后的欢迎语，含下一步指引（deal / deal <注额>）。 */
+    agreeWelcome(): string;
+    /**
+     * 注额不是正整数时的拒绝文案，命令行（`commands.ts` 的 `doDeal`）与图形牌桌
+     * （`client/Table.tsx` 的 `betError`）共用这一条。
+     *
+     * 牌桌那边原本另有一条 `betAmountRequired()`——两条的英文渲染出来一模一样
+     * （"The amount must be a positive integer."），中文却是两种说法。收口 review
+     * 指出这有两个问题：玩家从输出上根本分不清哪句归哪个界面，而改了其中一条的
+     * 人不会知道还有另一条要跟着改——正是这个项目吃过两次亏的那个形状。这里选择
+     * 合并成一条而不是把两版中文对齐：对齐中文只是让两份字面量恰好相等，下一次
+     * 编辑照样会把它们分开；合并才真正让"一句话只有一处"。
+     *
+     * 合并的代价是牌桌上的中文由「注额要填正整数。」变成了这一句（同一件事的
+     * 另一种说法，措辞变更已在收口报告里单独声明）。这不属于牌桌文案必须单开一
+     * 条的那类情形——见下面 `table*` 命名规则那段：牌桌单开方法是为了标点和拼接
+     * 位置不同，而这两条都是独立成句、标点相同，没有非分开不可的理由。
+     */
+    invalidBetAmount(): string;
+    /**
+     * 首次兑换（未绑定 GitHub）时的配对指引全文：怎么打开链接、点什么按钮、
+     * 链接多久过期。含 `url` 是因为链接本身嵌在指引的中段，不是拼接在末尾。
+     */
+    pairingInstructions(url: string, minutes: number): string;
+    /** 已绑定但没给兑换数量时：回显已绑定账号、当前余额与门槛，并要求补上数量。 */
+    exchangeAmountPrompt(githubLogin: string, chips: number, exchangeThresholdChips: number): string;
+    /** `exchange` 的数量不是正整数时的拒绝文案。 */
+    invalidExchangeAmount(): string;
+    /**
+     * 兑换成功后的说明（不含已兑换额度的有效性说明——那一句由 `exchangedQuotaNote`
+     * 单独负责，commands.ts 按 `result.quota` 是否存在决定要不要拼接在后面）。
+     */
+    exchangeSuccess(chips: number, exchangedChips: number): string;
+    /**
+     * 已兑换额度的有效性说明，接住 `POST /api/exchange` 返回的
+     * `quota.inactiveRecycleDays`。Task 6 之前这句话由服务端的
+     * `exchangedQuotaNote()`（`packages/server/src/routes/account.ts`）直接吐出
+     * 现成中文；服务端不知道调用者用什么语言，让它也维护一份译文，等于把"同一句
+     * 话在两处不同步"的老问题复制到语言维度——这个项目已经因为这个吃过两次亏。
+     * 现在服务端只吐事实（`quota`），措辞统一搬到这里。
+     *
+     * **按事实描述，一个字都不能比代码兑现的多**：这份额度不会因赛季结束而
+     * 清零——服务端的 `seasonSettle` 从头到尾不触碰 `exchanged_micro`。真正会
+     * 收走它的只有不活跃回收（`recycleAll` 同时清空游戏余额与已兑换额度）。早期
+     * 这里（当时还在服务端）写的是"有效期至本赛季末"，那是一句代码不兑现的
+     * 承诺，而玩家恰恰在兑换成功那一刻看到它。中文版这次是原句搬运，不重写。
+     *
+     * `inactiveRecycleDays` 必须原样使用服务端传来的数字，不能在插件这边写死——
+     * 写死的话运营者调了 `inactive_recycle_days` 之后文案就又和行为对不上了。
+     *
+     * `expiresAtSeasonEnd` 同理，而且更要紧：它一路从服务端
+     * （`routes/account.ts` 的 `quota.expiresAtSeasonEnd`）经 `api.ts` 传到这里，
+     * 之前**没有任何人读它**，而上面那句「它不会因赛季结束而清零」是无条件说
+     * 出口的。也就是说服务端哪天真的改成"赛季末回收已兑换额度"、老老实实把
+     * 这个字段发成 `true`，插件照样把那句话说给玩家听——这正是
+     * 「有效期至本赛季末」当年翻车的同一个形状（文案比代码更肯定），只是方向
+     * 反了过来。收口 review 要求这个事实必须真的驱动措辞。
+     *
+     * 为什么是给这条方法加一个参数，而不是新开一条方法：措辞归措辞、判断归
+     * 判断，"这一句要不要说"是两种语言各自的语序问题（中文靠「但」承接，英文
+     * 靠分号），留在 `commands.ts` 里拼接就等于又把语言相关的判断挪出 i18n。
+     * 加参数还有一个编译期好处：签名一改，`zh.ts`/`en.ts` 两边都必须重新处理
+     * 这个分支，`satisfies Messages` 不给静默漏掉的机会。
+     *
+     * `true` 分支**只是把那半句拿掉，不反过来断言"会在赛季末清零"**：服务端
+     * 只告诉我们"会过期"，没告诉我们什么时候、按什么比例、折不折算积分。把
+     * 一个没有细节的过期承诺写进兑换成功页，就是再造一次假承诺。
+     */
+    exchangedQuotaNote(inactiveRecycleDays: number, expiresAtSeasonEnd: boolean): string;
+    /** `reset` 不带 confirm 时的二次确认提示。 */
+    resetConfirmPrompt(): string;
+    /** `reset confirm` 完成后的提示。 */
+    resetDone(): string;
+    /** `/blackjack` 收到无法识别的子命令时的错误文案，`usage` 由调用方传入 `commandUsage()` 的结果。 */
+    unknownSubcommand(sub: string, usage: string): string;
+    /**
+     * 续命成功切换到奖池路由时的提示。当前版本里它只写进 `ctx.logger.info`，
+     * 玩家看不到——见 router.ts 里 `registerRouter` 的已知限制说明——但文案仍然
+     * 要走 locale，为将来真的有通知位那天做准备。
+     */
+    poolSwitchNotice(): string;
+    /** 没配 key 时的说明：续命只在自己额度耗尽时接管，配置缺失时用不上已兑换额度。 */
+    noCredentialHint(): string;
+    /** 暗牌（庄家扣着的那张）的 `aria-label`。 */
+    hiddenCardLabel(): string;
+    /** 牌桌上"你的牌"标签，不带冒号——点数是紧跟在后面的括号，不是直接接牌面。 */
+    tableHandLabel(): string;
+    /** 牌桌上分牌后第 N 手的标签，同样不带冒号。 */
+    tableSplitHandLabel(handIndex: number): string;
+    /** 牌桌上"庄家"标签，不带冒号。 */
+    tableDealerLabel(): string;
+    /** 六个动作按钮在牌桌上的纯文案（不含 render.ts 那份的 `/bj-xxx` 斜杠指令前缀）。 */
+    tableActionLabels: Record<'hit' | 'stand' | 'double' | 'split' | 'insure' | 'decline', string>;
+    /** 余额条第一行：余额与今日剩余免费手，牌桌专用的组合（不含赛季号）。 */
+    tableBalanceHeader(chips: number, freeHandsRemaining: number): string;
+    /** 余额条里追加的积分片段，仅当积分 > 0 时拼接，含前导分隔符。 */
+    tablePointsSuffix(points: number): string;
+    /** 余额条里追加的已兑换额度片段，仅当已兑换 > 0 时拼接，含前导分隔符。 */
+    tableExchangedSuffix(exchangedChips: number): string;
+    /** 已达兑换门槛时的提示，指路 /blackjack exchange。 */
+    tableExchangeThresholdReached(exchangeThresholdChips: number): string;
+    /** 未达兑换门槛时的提示，报出还差多少。 */
+    tableExchangeThresholdShort(shortChips: number, exchangeThresholdChips: number): string;
+    /** 已有兑换额度时，说明这份额度什么时候会被用到。 */
+    tableExchangedQuotaNote(exchangedChips: number): string;
+    /** 奖池已发完的简短提示（牌桌上的版本，比 poolEmptyNotice 短，套在括号里）。 */
+    tablePoolEmptyNotice(): string;
+    /** 余额不够触发某个动作（双倍/分牌/保险）时，按钮 title 里说明还差多少。 */
+    actionShortfallHint(costChips: number): string;
+    /** 动作按钮标签后面追加的费用后缀，如"（10,000）"。 */
+    tableCostSuffix(costChips: number): string;
+    /** 自定义注额：留空提交时的提示。 */
+    betAmountMissing(): string;
+    /** 自定义注额：超过服务端上限时的提示（`betError` 用）。 */
+    betAmountExceedsCap(maxChips: number): string;
+    /** 自定义注额：超过余额时的提示（`betError` 用）。 */
+    betAmountExceedsBalance(): string;
+    /** "自定义注额"这个词本身：展开按钮的文案，也是输入框的 aria-label。 */
+    customBetToggle(): string;
+    /** 自定义注额输入框旁的提交按钮。 */
+    customBetSubmit(): string;
+    /** 自定义注额输入框旁的可填范围提示。 */
+    customBetRange(maxChips: number): string;
+    /** 空闲态："当前没有进行中的牌局。" */
+    noActiveRoundNotice(): string;
+    /** 免费手分组标题（不含今日状态后缀）。 */
+    freeHandsGroupTitle(): string;
+    /** 免费手分组标题的后缀：今日还剩几手，含前导分隔符。 */
+    freeHandsRemainingToday(freeHandsRemaining: number): string;
+    /** 免费手分组标题的后缀：今日已用完，含前导分隔符。 */
+    freeHandsExhaustedToday(): string;
+    /**
+     * 免费手玩法说明：不出 CHIP、赢了拿多少、天生 21 点拿多少、输了或平局不损失。
+     * 天生 21 点的赔付额由调用方算好传入（base * 1.5 取整），这里只负责措辞。
+     */
+    freeHandExplainer(baseChips: number, naturalBlackjackPayoutChips: number): string;
+    /** 开始免费一局的按钮文案。 */
+    startFreeHandButton(): string;
+    /** 加注分组标题（不含余额不足后缀）。 */
+    raiseGroupTitle(): string;
+    /** 余额不足时追加在分组标题后的后缀，含前导分隔符。 */
+    insufficientBalanceSuffix(): string;
+    /** 加注玩法说明：钱从余额出、赢了翻倍、输了收不回。 */
+    raiseExplainer(): string;
+    /** 结算后"再来一局"按钮的免费局标签（后面会紧跟 `dealButtonFreeHandsSuffix`）。 */
+    rematchFreeLabel(): string;
+    /** "再来一局"按钮上追加的剩余免费手数量。 */
+    dealButtonFreeHandsSuffix(freeHandsRemaining: number): string;
+    /** 结算后"收起"按钮的文案。 */
+    dismissButton(): string;
+    /** 动作/发牌请求失败后的兜底提示（container 组件用，绝不回显服务端原始错误）。 */
+    actionFailedNotice(): string;
+}

package/dist/i18n/messages.js

@@ -0,0 +1,33 @@
+/**
+ * 面向玩家的全部文案，按 locale 分成两份实现。
+ *
+ * 为什么是"接口 + 两个实现"而不是 t(key) 查表：`satisfies Messages` 让漏翻一条
+ * 直接编译失败，根本发不出去；查表方案漏翻通常只是静默回退或输出 key。这个项目
+ * 已经因为"同一句话在两处不同步"吃过两次亏，多语言会把这个风险乘以二。
+ *
+ * 为什么每条是函数而不是模板串：中文没有复数、英文有（1 hand / 2 hands），语序
+ * 也不同。函数让两种语言各自把话说顺。
+ */
+export const LOCALES = ['zh', 'en'];
+/**
+ * 英文文案的红线，对标 render.ts 的 `BANNED`。
+ *
+ * 曾经写作 `/gambl|casino|\bwager\b|\bbet\b|real money/i`，只挡五个字面 token，
+ * 比中文那条松得多，而且松在两个地方：
+ *
+ * 一是词形。`\bbet\b` 的词边界在 bet 之后就断了，bets / betting / bettor 全部
+ * 漏网——而这三个正是英文里真正会写出来的形态，光秃秃的 "bet" 反而少见。
+ *
+ * 二是概念。中文的 `赢钱` 禁的是"把赢来的东西说成钱"这件事本身，英文这边却
+ * 只禁 real money，cash out / winnings / payout / jackpot 一律放行。这个项目的
+ * 全部合规站位就建立在"赢来的 CHIP 不是钱、不可提现"上，用 payout 或 winnings
+ * 描述结算，等于在文案层面把这条站位拆掉。
+ *
+ * 收紧的时机是现在而不是以后：后面还有五个任务要写新的英文文案，每一条都按
+ * 这条正则验收。先把线划到位，比等文案写完再回头重审所有文案便宜得多。
+ *
+ * 词边界要当心：`bett?` 单独用会误伤 better/betterment，所以后缀写成显式的
+ * `(?:s|ing|or|ors)?` 再收一个 `\b`。i18n.test.ts 里有一张"必须拦下"和一张
+ * "不许误伤"的清单钉住这两侧。
+ */
+export const BANNED_EN = /gambl|casino|\bwager(?:s|ing|ed)?\b|\bbett?(?:s|ing|or|ors)?\b|real money|\bcash(?:ing|es|ed)?[\s-]?out|winnings|payout|jackpot/i;