dsh-piggy 0.25.0

package/packages/pet-core/src/core/care.js

@@ -0,0 +1,160 @@
+// @ts-check
+/**
+ * 照护动作（喂食/洗澡/玩耍）。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，不读写文件、不碰 DOM（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/core/care
+ */
+
+import { CARE_KIND, ILLNESS_ONSET, careItems } from '../data.js'
+import { ACTIONS, DIET } from './constants.js'
+import { applyEffects, remember } from './effects.js'
+import { growFromRealWork } from './growth.js'
+import { rollForOverfeeding } from './illness.js'
+import { say } from './lines.js'
+import { decay } from './settlement.js'
+import { noteToday } from './diary.js'
+
+/** Which line scene each care action makes the pig speak from. */
+const CARE_SCENE = Object.freeze({ feed: 'eat', bathe: 'bathe', play: 'play', pet: 'pet' })
+
+/** Which shelves the pig can actually use right now, for the panel's picker. */
+export function careView(state) {
+  const out = {}
+  for (const action of ['feed', 'bathe', 'play']) out[action] = careOptions(state, action)
+  return out
+}
+
+export function feed(state, event, nowMs) {
+  const diet = DIET[event]
+  if (diet === undefined) return []
+  decay(state, nowMs)
+  if (state.dead) return []
+  switch (event) {
+    case 'message': state.stats.messages += 1; break
+    case 'turn': state.stats.turns += 1; break
+    case 'tool': state.stats.tools += 1; break
+    case 'toolError': state.stats.toolErrors += 1; break
+    case 'agentError': state.stats.agentErrors += 1; break
+    default: break
+  }
+  // The box does not eat: the work still counts in the stats, nothing else.
+  if (state.hatched !== true) return []
+  applyEffects(state, diet, nowMs)
+  growFromRealWork(state, event, nowMs)
+  noteToday(state, event)
+  return []
+}
+
+// ---------------------------------------------------------------------------
+// Care actions
+// ---------------------------------------------------------------------------
+
+export function actionCooldownSeconds(state, action, nowMs) {
+  const spec = ACTIONS[action]
+  if (spec === undefined || spec.cooldownMs <= 0) return 0
+  const last = state.cooldowns?.[action] ?? 0
+  const remaining = spec.cooldownMs - (nowMs - last)
+  return remaining <= 0 ? 0 : Math.ceil(remaining / 1000)
+}
+
+export const actionReady = (state, action, nowMs) => actionCooldownSeconds(state, action, nowMs) === 0
+
+export function act(state, action, nowMs, itemKey) {
+  const spec = ACTIONS[action]
+  if (spec === undefined) return { ok: false, reason: 'unknown' }
+  if (state === null) return { ok: false, reason: 'absent' }
+  if (state.hatched !== true) return { ok: false, reason: 'box' }
+  decay(state, nowMs)
+  if (state.dead) return { ok: false, reason: 'dead' }
+  if (state.activity !== null && action !== 'pet') return { ok: false, reason: 'away' }
+
+  const wait = actionCooldownSeconds(state, action, nowMs)
+  if (wait > 0) return { ok: false, reason: 'cooldown', wait }
+
+  // Feeding, washing and playing each spend something off their own shelf —
+  // QQ Pet keeps food, sundries and medicine in separate inventory categories
+  // for exactly this reason. Petting is affection, and costs nothing.
+  const shelf = CARE_KIND[action]
+  let item = null
+  if (shelf !== undefined) {
+    item = resolveCareItem(state, shelf, itemKey)
+    if (item === null) return { ok: false, reason: 'no-item', kind: shelf }
+    if (item.default !== true) {
+      const left = (state.inventory?.[item.key] ?? 0) - 1
+      state.inventory = { ...(state.inventory ?? {}) }
+      if (left > 0) state.inventory[item.key] = left
+      else delete state.inventory[item.key]
+    }
+  }
+
+  state.cooldowns = { ...(state.cooldowns ?? {}), [action]: nowMs }
+  if (action === 'feed') { state.stats.feeds += 1; state.lastFedAt = nowMs }
+  else if (action === 'bathe') state.stats.baths += 1
+  else if (action === 'play') state.stats.plays += 1
+  else if (action === 'pet') state.stats.pets += 1
+
+  const satietyBefore = state.satiety
+  applyEffects(state, careEffects(item, spec), nowMs)
+  remember(state, item === null ? spec.verb : `${item.emoji} ${spec.label}用了「${item.label}」`, nowMs)
+  if (action === 'feed') rollForOverfeeding(state, satietyBefore, nowMs)
+  // Feeding a pig that was already stuffed gets a different complaint.
+  say(state, action === 'feed' && satietyBefore >= ILLNESS_ONSET.overfullAt ? 'overfull' : CARE_SCENE[action], nowMs)
+  noteToday(state, action)
+  return { ok: true, item: item === null ? null : item.key, spent: item !== null && item.default !== true }
+}
+
+/**
+ * The item an action will spend: the caller's pick when it is actually in the
+ * bag, otherwise the cheapest thing the pig owns. The free default toy makes
+ * `play` always available.
+ */
+export function resolveCareItem(state, kind, wanted) {
+  const usable = careItems(kind).filter(
+    item => item.default === true || (state.inventory?.[item.key] ?? 0) > 0,
+  )
+  if (usable.length === 0) return null
+  if (wanted === undefined || wanted === null || wanted === '') return usable[0]
+  return usable.find(item => item.key === wanted) ?? null
+}
+
+/**
+ * Blend an item's own effects with the action's baseline. The item decides how
+ * far its own bar moves; the action keeps whatever the item does not mention.
+ */
+export function careEffects(item, spec) {
+  if (item === null) return spec
+  return {
+    weightG: item.satiety !== undefined && spec.key === 'feed' ? spec.weightG : 0,
+    satiety: item.satiety ?? spec.satiety,
+    happiness: item.happiness ?? spec.happiness,
+    cleanliness: item.cleanliness ?? spec.cleanliness,
+  }
+}
+
+/** What each care action could be done with right now, and how many are left. */
+export function careOptions(state, action) {
+  const kind = CARE_KIND[action]
+  if (kind === undefined) return []
+  return careItems(kind)
+    .filter(item => item.default === true || (state.inventory?.[item.key] ?? 0) > 0)
+    .map(item => ({
+      key: item.key,
+      label: item.label,
+      emoji: item.emoji,
+      price: item.price,
+      default: item.default === true,
+      count: item.default === true ? null : (state.inventory?.[item.key] ?? 0),
+      satiety: item.satiety ?? 0,
+      happiness: item.happiness ?? 0,
+      cleanliness: item.cleanliness ?? 0,
+    }))
+}
+
+// ---------------------------------------------------------------------------
+// Activities: work · study · trip
+// ---------------------------------------------------------------------------
+
+export const canFeed = (state, nowMs) => actionReady(state, 'feed', nowMs)
+
+export const feedCooldownSeconds = (state, nowMs) => actionCooldownSeconds(state, 'feed', nowMs)

package/packages/pet-core/src/core/clock.js

@@ -0,0 +1,122 @@
+// @ts-check
+/**
+ * 时间、年龄、等级派生。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，不读写文件、不碰 DOM（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/core/clock
+ */
+
+import { DAYS_PER_MONTH, DAY_STARTS_AT_HOUR, GRAVE, GROWTH_PER_HOUR, LEVEL_TITLES, LIFE_STAGES, MAX_LEVEL, SOUL_AFTER_DAYS, xpForLevel } from '../data.js'
+import { DAY_MS } from './constants.js'
+
+/**
+ * The pig's age in days.
+ *
+ * This is accumulated *pig time*, not wall clock: `decay()` adds elapsed real
+ * time times the time scale. Storing it this way means changing the scale only
+ * affects the future — the pig does not suddenly jump from a piglet to elderly
+ * because you raised the multiplier.
+ */
+export function ageDays(state, nowMs) {
+  if (state === null) return 0
+  if (typeof state.ageMs === 'number' && Number.isFinite(state.ageMs)) {
+    return Math.max(0, state.ageMs / DAY_MS)
+  }
+  // Saves from before pig time existed only have a birthday.
+  if (typeof state.bornAt !== 'number') return 0
+  return Math.max(0, (nowMs - state.bornAt) / DAY_MS)
+}
+
+/** The pig's age in whole months, for display. */
+export const ageMonths = (state, nowMs) => ageDays(state, nowMs) / DAYS_PER_MONTH
+
+/**
+ * Which stage the pig is at right now: a box, a pig of some size, or a grave.
+ * The body follows the level, not the calendar (B2).
+ */
+export function lifeStageFor(state, nowMs) {
+  if (state === null) return LIFE_STAGES[0]
+  if (state.dead === true) return GRAVE
+  if (state.hatched !== true) return LIFE_STAGES[0]
+  const level = levelFor(state.xp)
+  let stage = LIFE_STAGES[1]
+  for (const candidate of LIFE_STAGES) {
+    if (candidate.box === true) continue
+    if (level >= (candidate.fromLevel ?? 0)) stage = candidate
+  }
+  return stage
+}
+
+/** The next rung, or null once the pig is fully grown. */
+export function nextLifeStage(state, nowMs) {
+  if (state === null || state.dead === true || state.hatched !== true) return null
+  const level = levelFor(state.xp)
+  return LIFE_STAGES.find(stage => stage.box !== true && (stage.fromLevel ?? 0) > level) ?? null
+}
+
+/**
+ * Roughly how many days until the next rung, at full care and the base rate.
+ * An estimate for the panel, not a promise: care and activities move it.
+ */
+export function daysToNextStage(state, nowMs) {
+  const next = nextLifeStage(state, nowMs)
+  if (next === null) return null
+  const remaining = Math.max(0, xpForLevel(next.fromLevel ?? 0) - (Number.isFinite(state.xp) ? state.xp : 0))
+  return remaining / GROWTH_PER_HOUR / 24
+}
+
+/**
+ * The day an instant belongs to, as 'YYYY-MM-DD' in local time. A day starts
+ * at DAY_STARTS_AT_HOUR (06:00), so staying up past midnight still counts as
+ * the evening before. Daily caps, sign-in and the diary all key off this.
+ * @param {number} nowMs
+ */
+export function dayKeyFor(nowMs) {
+  const shifted = new Date(nowMs - DAY_STARTS_AT_HOUR * 3_600_000)
+  const month = String(shifted.getMonth() + 1).padStart(2, '0')
+  const day = String(shifted.getDate()).padStart(2, '0')
+  return `${shifted.getFullYear()}-${month}-${day}`
+}
+
+// ---------------------------------------------------------------------------
+// Level
+// ---------------------------------------------------------------------------
+
+/** The pig's level for a growth total, 1..MAX_LEVEL. */
+export function levelFor(xp) {
+  const value = Number.isFinite(xp) ? Math.max(0, xp) : 0
+  let level = 1
+  while (level < MAX_LEVEL && value >= xpForLevel(level + 1)) level += 1
+  return level
+}
+
+/** The title earned at this level. */
+export function levelTitle(level) {
+  let found = LEVEL_TITLES[0]
+  for (const entry of LEVEL_TITLES) if (level >= entry.level) found = entry
+  return found
+}
+
+/** How far into the current level, 0-100, plus the numbers behind it. */
+export function levelProgress(xp) {
+  const value = Number.isFinite(xp) ? Math.max(0, xp) : 0
+  const level = levelFor(value)
+  const floor = xpForLevel(level)
+  const maxed = level >= MAX_LEVEL
+  const ceiling = maxed ? floor : xpForLevel(level + 1)
+  const span = Math.max(1, ceiling - floor)
+  return {
+    level,
+    xp: value,
+    floor,
+    ceiling,
+    maxed,
+    toNext: maxed ? 0 : Math.max(0, ceiling - value),
+    percent: maxed ? 100 : Math.max(0, Math.min(100, Math.round(((value - floor) / span) * 100))),
+    title: levelTitle(level),
+  }
+}
+
+/** Has the grave been left alone long enough for the soul to settle on it? */
+export const hasSoul = (state, nowMs) =>
+  state !== null && state.dead === true && (nowMs - (state.diedAt ?? nowMs)) / DAY_MS >= SOUL_AFTER_DAYS

package/packages/pet-core/src/core/constants.js

@@ -0,0 +1,109 @@
+// @ts-check
+/**
+ * 领域常量与动作表。
+ *
+ * 纯函数领域逻辑：时间由 nowMs 传入，不读写文件、不碰 DOM（见 docs/CONVENTIONS.md）。
+ * @module dsh-piggy/core/constants
+ */
+
+/** Bumped when the saved shape changes in a way migrate() must handle. */
+export const STATE_VERSION = 12
+
+export const BIRTH_WEIGHT_G = 1200
+
+export const HATCH_WEIGHT_G = 160
+
+export const MEMORY_LIMIT = 8
+
+export const PENDING_LIMIT = 6
+
+/** Growth ladder, ascending by xp. */
+/**
+ * Growth ladder, ascending by xp.
+ *
+ * Tuned so that ordinary passive work alone takes roughly: 7 minutes to 小猪崽,
+ * 40 minutes to 圆滚猪, an afternoon to 大猪猪, a few days to 猪皇, a week or so
+ * to 猪王, and the best part of a month of real use to 野猪王. Sending the pig
+ * out to work or study is worth several hours of watching you type, so playing
+ * the game is the fast lane.
+ */
+
+/**
+ * Passive diet — what the pig gets for watching you actually work. Growth from
+ * real work is separate and capped per day (data/growth.js DSH_GROWTH).
+ *
+ * These numbers are deliberately small. A single tool call used to be worth 3,
+ * and a heavy agent session fires hundreds of them an hour: one afternoon of
+ * ordinary use was 2232 XP, 94% of the whole pig, and it hit 「猪皇」 without the
+ * player ever sending it to work or school. Passive work is now a trickle; the
+ * activities are where the growth is.
+ */
+export const DIET = Object.freeze({
+  message: { satiety: 1, happiness: 1, weightG: 6 },
+  turn: { satiety: 2, happiness: 1, weightG: 14 },
+  tool: { satiety: 2, happiness: 0, weightG: 9 },
+  toolError: { satiety: 0, happiness: 1, weightG: 2 },
+  agentError: { satiety: 0, happiness: 0, weightG: 2 },
+})
+
+export const ACTIONS = Object.freeze({
+  feed: {
+    key: 'feed', label: '喂食', emoji: '🍎', verb: '吃了一口 🍎',
+    // No blanket cleanliness hit: eating an apple does not make you dirty. Only
+    // the foods that are actually messy declare a penalty of their own.
+    // No cooldown (owner, 2026-10-01): every bite already costs a food item,
+    // and feeding a full pig risks a stomach ache (B3) — that is the brake.
+    cooldownMs: 0, satiety: 22, happiness: 6, cleanliness: 0, weightG: 90,
+  },
+  bathe: {
+    key: 'bathe', label: '洗澡', emoji: '🛁', verb: '洗了个澡 🛁',
+    cooldownMs: 90_000, satiety: -2, happiness: 8, cleanliness: 50, weightG: 0,
+  },
+  play: {
+    key: 'play', label: '玩耍', emoji: '🎾', verb: '玩了一会儿 🎾',
+    cooldownMs: 45_000, satiety: -5, happiness: 16, cleanliness: -4, weightG: 4,
+  },
+  pet: {
+    key: 'pet', label: '摸摸', emoji: '❤️', verb: '被摸了摸头 ❤️',
+    cooldownMs: 0, satiety: 0, happiness: 10, cleanliness: 0, weightG: 0,
+  },
+})
+
+export const ACTION_ORDER = Object.freeze(['feed', 'bathe', 'play', 'pet'])
+
+// Tuned against the activity lengths, not against minutes. A four-hour shift
+// now costs roughly one meal and one bath, which is recoverable; the old rates
+// were written when a shift was ten minutes and emptied every bar twice over.
+export const SATIETY_DECAY_PER_MIN = 0.08
+
+export const HAPPINESS_DECAY_PER_MIN = 0.06
+
+export const CLEANLINESS_DECAY_PER_MIN = 0.07
+
+export const AWAY_DECAY_MULTIPLIER = 1.4
+
+/** No single trip may push a bar below this — see the drain() comment in decay. */
+export const AWAY_FLOOR = 15
+
+export const DAY_MS = 86_400_000
+
+/**
+ * The longest single step decay() takes. Long absences are walked in steps of
+ * this size so thresholds are crossed when they really were; five minutes keeps
+ * a month offline under ten thousand cheap steps.
+ */
+export const SETTLE_STEP_MS = 5 * 60_000
+
+/**
+ * Health at or below which the pig is too weak to leave the house. The scale is
+ * 5 = full, and the four illness stages set it to 4/3/2/1, so 1 is the last
+ * stage before it dies.
+ */
+export const TOO_WEAK_HEALTH = 1
+
+export const AWAY_MOODS = Object.freeze({
+  work: { key: 'working', emoji: '💼', label: '在打工' },
+  study: { key: 'studying', emoji: '📚', label: '在上课' },
+  trip: { key: 'traveling', emoji: '🧳', label: '在旅行' },
+  interest: { key: 'studying', emoji: '💻', label: '在兴趣课' },
+})

package/packages/pet-core/src/core/daily.js

@@ -0,0 +1,204 @@
+// @ts-check
+/**
+ * 日常：签到 12 天、在线礼包、宠物日记。
+ *
+ * 纯领域逻辑：时间由 nowMs 传入，随机走 `core/random.js`，不读文件、不碰 DOM。
+ * 一天的边界是早上 06:00 —— `dayKeyFor()` 就在 clock.js，这里只是转出去，
+ * 免得「一天从几点算起」有两份实现（见 docs/CONVENTIONS.md）。
+ *
+ * @module dsh-piggy/core/daily
+ */
+import { GIFT_TABLE, ONLINE_GIFT, SIGN_IN_CYCLE, SIGN_IN_REWARDS, SHOP, itemByKey } from '../data.js'
+import { dayKeyFor } from './clock.js'
+import { rollerFor } from './random.js'
+import { announce } from './effects.js'
+import { say } from './lines.js'
+
+export { dayKeyFor }
+
+/** 一份全新的日常状态：今天没签、没在线、没礼包。 */
+export function emptyDaily() {
+  return {
+    signIn: { lastDay: null, index: 0, total: 0 },
+    online: { day: null, onlineMs: 0, given: 0, unclaimed: 0 },
+  }
+}
+
+/**
+ * 补默认值。新字段不加 upgrades 级、不动 STATE_VERSION（那归 Claude）：
+ * 缺什么补什么，坏值当没有（参考 core/lines.js 的 ensureDialogue）。
+ * @param {object} state
+ */
+export function ensureDaily(state) {
+  const raw = state.daily
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    state.daily = emptyDaily()
+    return state.daily
+  }
+  const signIn = raw.signIn !== null && typeof raw.signIn === 'object' && !Array.isArray(raw.signIn) ? raw.signIn : {}
+  const online = raw.online !== null && typeof raw.online === 'object' && !Array.isArray(raw.online) ? raw.online : {}
+  const index = Number.isInteger(signIn.index) && signIn.index >= 0 ? signIn.index % SIGN_IN_CYCLE : 0
+  state.daily = {
+    signIn: {
+      lastDay: typeof signIn.lastDay === 'string' && signIn.lastDay !== '' ? signIn.lastDay : null,
+      index,
+      total: Number.isInteger(signIn.total) && signIn.total >= 0 ? signIn.total : 0,
+    },
+    online: {
+      day: typeof online.day === 'string' && online.day !== '' ? online.day : null,
+      onlineMs: Number.isFinite(online.onlineMs) && online.onlineMs > 0 ? online.onlineMs : 0,
+      given: Number.isInteger(online.given) && online.given >= 0 ? online.given : 0,
+      unclaimed: Number.isInteger(online.unclaimed) && online.unclaimed >= 0 ? online.unclaimed : 0,
+    },
+  }
+  return state.daily
+}
+
+/**
+ * 把一份奖励记到账上。
+ * @param {object} state
+ * @param {{coins: number, items: ReadonlyArray<{key: string, count: number}>}} reward
+ * @returns {string} 领到了什么（给公告用）
+ */
+export function grantReward(state, reward) {
+  const parts = []
+  if (reward.coins > 0) {
+    state.coins += reward.coins
+    parts.push(`🪙 ${reward.coins}`)
+  }
+  for (const entry of reward.items) {
+    state.inventory = { ...(state.inventory ?? {}) }
+    state.inventory[entry.key] = (state.inventory[entry.key] ?? 0) + entry.count
+    const item = itemByKey(entry.key)
+    // A key the shelf does not know yet (B3's medicine) still lands in the bag.
+    parts.push(`${item === null ? '🎁' : item.emoji} ${item === null ? entry.key : item.label} ×${entry.count}`)
+  }
+  return parts.join(' + ')
+}
+
+/** 今天这一签领了没。 */
+export function canSignIn(state, nowMs) {
+  return ensureDaily(state).signIn.lastDay !== dayKeyFor(nowMs)
+}
+
+/**
+ * 签到：发当天的礼包、推进一轮，写回今天是哪一天。
+ *
+ * 断签不清零（下次接着领下一天），12 天领完从头来；死了也能签 —— 墓碑也攒还魂丹。
+ * @returns {{ ok: boolean, reason?: string, day?: number, reward?: string }}
+ */
+export function signIn(state, nowMs) {
+  const daily = ensureDaily(state)
+  const today = dayKeyFor(nowMs)
+  if (daily.signIn.lastDay === today) return { ok: false, reason: 'signed' }
+  const index = daily.signIn.index % SIGN_IN_CYCLE
+  const text = grantReward(state, SIGN_IN_REWARDS[index])
+  daily.signIn.lastDay = today
+  daily.signIn.index = (index + 1) % SIGN_IN_CYCLE
+  daily.signIn.total += 1
+  announce(state, 'gift', `签到第 ${index + 1} 天：${text}`, nowMs)
+  say(state, 'signIn', nowMs)
+  return { ok: true, day: index + 1, reward: text }
+}
+
+/**
+ * 记一段在线时长。
+ *
+ * 纯函数：`lastPollMs` 是上一次轮询的时刻，由宿主（store）传进来。
+ * **只算真实毫秒**，跟调试页的时间倍率无关；两次轮询间隔超过 30 秒就当作
+ * 「人不在」，中间那段不算。跨天（06:00）时清零当日进度，但**没领的礼包留着**。
+ */
+export function recordOnline(state, lastPollMs, nowMs) {
+  const daily = ensureDaily(state)
+  const today = dayKeyFor(nowMs)
+  if (daily.online.day !== today) {
+    daily.online.day = today
+    daily.online.onlineMs = 0
+    daily.online.given = 0
+    // unclaimed 不清：攒着的礼包换天还在，用户回来能一起领。
+  }
+  const gap = nowMs - lastPollMs
+  if (lastPollMs > 0 && gap > 0 && gap <= ONLINE_GIFT.pollGapMaxMs) daily.online.onlineMs += gap
+  // 每满一小时一个。到了当天的上限（或攒满 3 个）就只消耗时长，不再给。
+  while (daily.online.onlineMs >= ONLINE_GIFT.perGiftMs) {
+    daily.online.onlineMs -= ONLINE_GIFT.perGiftMs
+    if (daily.online.given < ONLINE_GIFT.perDay && daily.online.unclaimed < ONLINE_GIFT.unclaimedMax) {
+      daily.online.given += 1
+      daily.online.unclaimed += 1
+    }
+  }
+  return daily.online
+}
+
+/**
+ * 抽一个礼包内容（纯函数，随机来自 state.seed）。
+ * @returns {{coins: number, items: ReadonlyArray<{key: string, count: number}>}}
+ */
+export function pickGift(state, next) {
+  return resolveGiftBucket(GIFT_TABLE[giftBucketIndex(next())], next)
+}
+
+/**
+ * Which row of `GIFT_TABLE` a `[0, 1)` roll lands on（抽出来是为了能测分布）。
+ * @param {number} roll
+ * @returns {number} GIFT_TABLE 的下标
+ */
+export function giftBucketIndex(roll) {
+  let accumulated = 0
+  for (let index = 0; index < GIFT_TABLE.length; index += 1) {
+    accumulated += GIFT_TABLE[index].chance
+    if (roll < accumulated) return index
+  }
+  // Floating point can leave the sum a hair under 1: fall back to the common case.
+  return 0
+}
+
+/** @param {object} bucket @param {() => number} next */
+function resolveGiftBucket(bucket, next) {
+  if (bucket.coins !== undefined) {
+    const [low, high] = bucket.coins
+    return { coins: low + Math.floor(next() * (high - low + 1)), items: [] }
+  }
+  if (bucket.keys !== undefined && bucket.keys.length > 0) {
+    const key = bucket.keys[Math.min(bucket.keys.length - 1, Math.floor(next() * bucket.keys.length))]
+    return { coins: 0, items: [{ key, count: 1 }] }
+  }
+  const kinds = bucket.kinds ?? (bucket.kind === undefined ? [] : [bucket.kind])
+  const pool = SHOP.filter(item => kinds.includes(item.kind)
+    && (bucket.maxPrice === undefined || item.price <= bucket.maxPrice))
+  if (pool.length === 0) return { coins: 30, items: [] }
+  const item = pool[Math.min(pool.length - 1, Math.floor(next() * pool.length))]
+  return { coins: 0, items: [{ key: item.key, count: 1 }] }
+}
+
+/** 现在有没有没领的礼包。 */
+export function giftsWaiting(state) {
+  return ensureDaily(state).online.unclaimed
+}
+
+/**
+ * 开一个在线礼包：抽一项、发到账上、公告 + 说一句。
+ * @returns {{ ok: boolean, reason?: string, reward?: string }}
+ */
+export function openGift(state, nowMs) {
+  const daily = ensureDaily(state)
+  if (daily.online.unclaimed <= 0) return { ok: false, reason: 'empty' }
+  daily.online.unclaimed -= 1
+  const text = grantReward(state, pickGift(state, rollerFor(state)))
+  announce(state, 'gift', `在线礼包：${text}`, nowMs)
+  say(state, 'gift', nowMs)
+  return { ok: true, reward: text }
+}
+
+/** 面板需要的那几个数。 */
+export function dailyView(state, nowMs) {
+  const daily = ensureDaily(state)
+  return {
+    canSignIn: daily.signIn.lastDay !== dayKeyFor(nowMs),
+    signInDay: (daily.signIn.index % SIGN_IN_CYCLE) + 1,
+    signInTotal: daily.signIn.total,
+    cycle: SIGN_IN_CYCLE,
+    unclaimed: daily.online.unclaimed,
+    onlineMinutes: Math.floor(daily.online.onlineMs / 60000),
+  }
+}