@linxin666/dsh-pet 0.1.18 → 0.1.19

package/src/ledger.test.ts

@@ -5,13 +5,11 @@ import { emptyPersist } from './persist.ts'
 import { PetLedger } from './ledger.ts'
 
 describe('PetLedger', () => {
-  it('settles the economy on completed turns (work treat per 3 turns)', () => {
+  it('settles the economy on completed turns (work treat per 30 turns)', () => {
     const ledger = new PetLedger(emptyPersist())
     const n = 1_000_000
-    ledger.rewardTurn('s1', 1, n)
-    ledger.rewardTurn('s1', 2, n + 1)
-    ledger.rewardTurn('s1', 3, n + 2)
-    expect(ledger.snapshot.affinity.turns).toBe(3)
+    for (let turn = 1; turn <= 30; turn++) ledger.rewardTurn('s1', turn, n + turn)
+    expect(ledger.snapshot.affinity.turns).toBe(30)
     expect(ledger.snapshot.treats.treats).toBe(1)
     expect(ledger.takeDirty()).toBe(true)
   })
@@ -25,6 +23,19 @@ describe('PetLedger', () => {
     expect(ledger.snapshot.affinity.turns).toBe(1)
   })
 
+  it('forgetSession re-arms a session so a repeated reward can award again', () => {
+    const ledger = new PetLedger(emptyPersist())
+    const n = 1_000_000
+    ledger.rewardTurn('s1', 1, n)
+    expect(ledger.snapshot.affinity.turns).toBe(1)
+    // The disposed-session eviction drops only the per-session bookkeeping.
+    ledger.forgetSession('s1')
+    // The same turn number is now treated as fresh: a same-turn retry on a
+    // new session lifecycle re-awards rather than being deduplicated.
+    expect(ledger.rewardTurn('s1', 1, n + 1)).toBe(true)
+    expect(ledger.snapshot.affinity.turns).toBe(2)
+  })
+
   it('a read of the view does not mark dirty (no settle on read)', () => {
     const ledger = new PetLedger(emptyPersist())
     ledger.affinityView(1_000_000)
@@ -34,16 +45,36 @@ describe('PetLedger', () => {
   it('feed consumes a treat and applies the feed reward', () => {
     const ledger = new PetLedger(emptyPersist())
     const n = 1_000_000
-    ledger.rewardTurn('s1', 1, n)
-    ledger.rewardTurn('s1', 2, n + 1)
-    ledger.rewardTurn('s1', 3, n + 2)
+    for (let turn = 1; turn <= 30; turn++) ledger.rewardTurn('s1', turn, n + turn)
     expect(ledger.snapshot.treats.treats).toBe(1)
-    const res = ledger.interact('feed', n + 10)
+    const res = ledger.interact('feed', n + 40)
     expect(res.delta).toBe(defaultAffinityConfig.feedReward)
     expect(ledger.snapshot.treats.treats).toBe(0)
     expect(ledger.snapshot.affinity.feeds).toBe(1)
   })
 
+  it('cycles per-pet custom remarks per slot and falls back to built-ins', () => {
+    const ledger = new PetLedger(emptyPersist(), {
+      remarks: { pet: ['第一句', '第二句'] },
+    })
+    const n = 1_000_000
+    expect(ledger.interact('pet', n).reaction).toBe('第一句')
+    // Per-slot counters: the cooldown refusal still opens with the built-in
+    // legacy line, not the custom pool above.
+    expect(ledger.interact('pet', n + 1).reaction).toBe('摸过头啦，让鲸鱼娘歇口气～')
+    // Feeding falls back to the built-in pool when the pet declares none.
+    expect(ledger.interact('feed', n + 2).reaction).toBe('没有小鱼干了，多陪我工作一会儿吧～')
+  })
+
+  it('swaps remark pools when the selected pet changes', () => {
+    const ledger = new PetLedger(emptyPersist(), { remarks: { pet: ['旧宠物台词'] } })
+    expect(ledger.interact('pet', 1_000_000).reaction).toBe('旧宠物台词')
+    ledger.setRemarks({ pet: ['新宠物台词'] })
+    expect(ledger.interact('pet', 1_011_000).reaction).toBe('新宠物台词')
+    ledger.setRemarks(undefined)
+    expect(ledger.interact('pet', 1_022_000).reaction).toBe('咕噜咕噜～被摸摸好舒服！')
+  })
+
   it('refuses a feed on an empty stock without burning anything', () => {
     const ledger = new PetLedger(emptyPersist())
     const res = ledger.interact('feed', 1_000_000)

package/src/ledger.ts

@@ -22,12 +22,15 @@ import {
   settleTreatGrants,
   type TreatConfig,
 } from './treats.ts'
+import { RemarkPicker, type PetRemarks } from './remarks.ts'
 import type { PetDisplayConfig, PetPersist } from './persist.ts'
 
 /** Tuning overrides for the affinity economy. */
 export interface LedgerConfig {
   affinity?: Partial<AffinityConfig>
   treats?: Partial<TreatConfig>
+  /** Per-pet remark pools for the selected pet (custom slots override built-ins). */
+  remarks?: PetRemarks
 }
 
 /** Result of one ledger interaction (the shape the pet RPC returns). */
@@ -48,6 +51,8 @@ export interface LedgerInteractionResult {
 export class PetLedger {
   private readonly affinityConfig: AffinityConfig
   private readonly treatConfig: TreatConfig
+  /** Round-robin reaction picker; rebuilt when the selected pet changes. */
+  private picker: RemarkPicker
   private current: PetPersist
   /** Completed turns already rewarded, per session (turn numbers are per-session). */
   private rewardedTurns = new Map<string, number>()
@@ -57,6 +62,7 @@ export class PetLedger {
   constructor(persist: PetPersist, config: LedgerConfig = {}) {
     this.affinityConfig = { ...defaultAffinityConfig, ...(config.affinity ?? {}) }
     this.treatConfig = { ...defaultTreatConfig, ...(config.treats ?? {}) }
+    this.picker = new RemarkPicker(config.remarks)
     this.current = persist
   }
 
@@ -82,6 +88,14 @@ export class PetLedger {
     return was
   }
 
+  /**
+   * Drop a session's rewarded-turn bookkeeping once that session is disposed,
+   * so the per-session map does not grow without bound.
+   */
+  forgetSession(sessionId: string): void {
+    this.rewardedTurns.delete(sessionId)
+  }
+
   /** Replace the display block (clamping stays a caller concern). */
   setDisplay(display: PetDisplayConfig): void {
     this.current = { ...this.current, display }
@@ -101,10 +115,18 @@ export class PetLedger {
     this.dirty = true
   }
 
+  /**
+   * Swap the reaction pools to another pet's custom remarks (called on pet
+   * selection). Slots the pet does not declare fall back to built-ins.
+   */
+  setRemarks(remarks?: PetRemarks): void {
+    this.picker = new RemarkPicker(remarks)
+  }
+
   /**
    * Settle the treat economy (work + time output since the last settlement).
    * A zero-gain first settlement still starts the time clock (anchor write),
-   * which is how the 30-minute time output can ever accrue. Returns true when
+   * which is how the time output can ever accrue. Returns true when
    * the in-memory ledger changed and should be persisted.
    */
   settleTreats(nowMs: number): boolean {
@@ -161,14 +183,17 @@ export class PetLedger {
   interact(kind: PetInteraction, nowMs: number): LedgerInteractionResult {
     if (kind === 'feed') this.settleTreats(nowMs)
     const outcome = applyInteraction(this.current.affinity, kind, nowMs, this.affinityConfig)
+    // Reactions come from the picker pools (custom per-pet slots override
+    // the built-in library per slot); outcome.reaction stays the fallback
+    // copy for direct applyInteraction callers.
     if (kind === 'feed' && !outcome.accepted) {
-      return { reaction: outcome.reaction, delta: 0, affinity: this.affinityView(nowMs) }
+      return { reaction: this.picker.pick('feedCooldown'), delta: 0, affinity: this.affinityView(nowMs) }
     }
     if (kind === 'feed') {
       const consume = consumeTreat(this.current.treats)
       if (!consume.ok) {
         return {
-          reaction: '没有小鱼干了，多陪我工作一会儿吧～',
+          reaction: this.picker.pick('noTreats'),
           delta: 0,
           affinity: this.affinityView(nowMs),
         }
@@ -180,7 +205,11 @@ export class PetLedger {
       this.current = { ...this.current, affinity: outcome.affinity }
       this.dirty = true
     }
-    return { reaction: outcome.reaction, delta: outcome.delta, affinity: this.affinityView(nowMs) }
+    return {
+      reaction: this.picker.pick(outcome.accepted ? kind : 'petCooldown'),
+      delta: outcome.delta,
+      affinity: this.affinityView(nowMs),
+    }
   }
 
   /** Current affinity view for the RPC snapshot. */

package/src/persist.test.ts

@@ -108,7 +108,7 @@ describe('loadPetPersist', () => {
       writeFileSync(join(dir, 'pet.json'), JSON.stringify({
         name: '   ',
         names: { bad: '  ' },
-        affinity: { points: 9999, lastPetAt: -5, lastFeedAt: 'x', pets: -1, feeds: 1.5, turns: 0 },
+        affinity: { points: AFFINITY_MAX + 5000, lastPetAt: -5, lastFeedAt: 'x', pets: -1, feeds: 1.5, turns: 0 },
         treats: { treats: 150, lastTreatGrantAt: -1, turnsAtLastTreatGrant: 0 },
         display: { visible: 'yes', size: -10, right: 1e12, bottom: 20 },
       }), 'utf8')

package/src/registry.test.ts

@@ -70,6 +70,33 @@ describe('resolvePetManifest', () => {
     expect(resolvePetManifest({ id: 'ok', displayName: 'x', spritesheetPath: '/absolute.webp' }, '/tmp', { warnings })).toBeUndefined()
     expect(warnings.length).toBe(3)
   })
+
+  it('normalizes a manifest remarks block into per-pet pools', () => {
+    const entry = resolvePetManifest({
+      id: 'otter',
+      displayName: '水獭',
+      spritesheetPath: 'spritesheet.webp',
+      remarks: {
+        pet: '摸摸水獭的头',
+        feed: ['小鱼干真香', ' 再来一条 '],
+      },
+    }, join(tmpdir(), 'otter'))
+    expect(entry!.remarks).toEqual({ pet: ['摸摸水獭的头'], feed: ['小鱼干真香', '再来一条'] })
+  })
+
+  it('warns on malformed remarks slots but keeps the pet', () => {
+    const warnings: string[] = []
+    const entry = resolvePetManifest({
+      id: 'fox',
+      displayName: '狐狸',
+      spritesheetPath: 'spritesheet.webp',
+      remarks: { unknownSlot: ['x'], pet: [1, null] },
+    }, join(tmpdir(), 'fox'), { warnings })
+    expect(entry).toBeDefined()
+    expect(entry!.remarks).toBeUndefined()
+    expect(warnings.some(message => message.includes('unknown remarks slot'))).toBe(true)
+    expect(warnings.some(message => message.includes('no usable lines'))).toBe(true)
+  })
 })
 
 describe('loadPetRegistry', () => {

package/src/registry.ts

@@ -22,6 +22,7 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { PetAnimation } from './state.ts'
+import { normalizePetRemarks, type PetRemarks, type PetRemarksManifest } from './remarks.ts'
 
 /** Fixed row order of the 9-state animation contract. */
 export const PET_ROW_ORDER: readonly PetAnimation[] = [
@@ -134,6 +135,13 @@ export interface PetManifest {
   frames?: number[]
   /** Optional per-track rhythm overrides; omitted tracks use the defaults. */
   tracks?: Partial<Record<PetAnimation, PetTrackOverride>>
+  /**
+   * Optional witty-remark overrides the pet speaks on interactions
+   * (community contributions use this to give their pet its own voice).
+   * Each slot accepts one line or a pool of lines; a slot replaces the
+   * built-in default pool for that slot only.
+   */
+  remarks?: PetRemarksManifest
 }
 
 /** Per-track rhythm overrides a manifest may carry. */
@@ -171,6 +179,8 @@ export interface PetEntry extends PetDefinition {
   dir: string
   /** Atlas path relative to 'dir' (declared by the manifest). */
   spritesheetPath: string
+  /** Normalized per-pet remark pools (manifest 'remarks'), when declared. */
+  remarks?: PetRemarks
 }
 
 /** Registry load result: resolved entries plus load warnings. */
@@ -250,6 +260,7 @@ export function resolvePetManifest(
     const value = Array.isArray(source.frames) ? source.frames[index] : undefined
     return finiteInt(value, fallback, columns)
   })
+  const remarks = normalizePetRemarks(source.remarks, message => warn('manifest ' + id + ': ' + message))
   const trackOverrides = (typeof source.tracks === 'object' && source.tracks !== null ? source.tracks : {}) as Partial<Record<PetAnimation, PetTrackOverride>>
   const tracks = {} as Record<PetAnimation, PetTrackDef>
   for (const [row, animation] of PET_ROW_ORDER.entries()) {
@@ -289,6 +300,7 @@ export function resolvePetManifest(
     manifestUrl: assetUrl(assetPrefix, id, 'pet.json'),
     dir,
     spritesheetPath: spritesheetPath.join('/'),
+    ...(remarks === undefined ? {} : { remarks }),
   }
 }
 

package/src/remarks.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import {
+  BUILTIN_REMARKS,
+  REMARK_KINDS,
+  REMARK_LINE_MAX,
+  REMARK_LINES_MAX,
+  RemarkPicker,
+  builtinRemark,
+  normalizePetRemarks,
+} from './remarks.ts'
+
+describe('BUILTIN_REMARKS', () => {
+  it('carries a generous pool for every slot, with the legacy line first', () => {
+    for (const kind of REMARK_KINDS) {
+      const pool = BUILTIN_REMARKS[kind]
+      expect(pool.length).toBeGreaterThanOrEqual(8)
+      expect(pool.every(line => line.trim() !== '')).toBe(true)
+    }
+    // The legacy first lines keep the plugin's original wording so existing
+    // installs and tests never see a different opening reaction.
+    expect(BUILTIN_REMARKS.pet[0]).toBe('咕噜咕噜～被摸摸好舒服！')
+    expect(BUILTIN_REMARKS.petCooldown[0]).toBe('摸过头啦，让鲸鱼娘歇口气～')
+    expect(BUILTIN_REMARKS.feed[0]).toBe('呜哇！小鱼干好好吃！')
+    expect(BUILTIN_REMARKS.feedCooldown[0]).toBe('吃饱啦，晚点再喂～')
+    expect(BUILTIN_REMARKS.noTreats[0]).toBe('没有小鱼干了，多陪我工作一会儿吧～')
+    // Repo-wide ban on emoji characters: the pools must stay plain text.
+    const emoji = /[\u{1F000}-\u{1FFFF}\u{2600}-\u{27BF}\u{FE0F}]/u
+    for (const kind of REMARK_KINDS) {
+      for (const line of BUILTIN_REMARKS[kind]) expect(line).not.toMatch(emoji)
+    }
+  })
+})
+
+describe('RemarkPicker', () => {
+  it('picks the built-in pool round-robin, per slot, deterministically', () => {
+    const picker = new RemarkPicker()
+    const first = picker.pick('pet')
+    const second = picker.pick('pet')
+    expect(first).toBe(BUILTIN_REMARKS.pet[0])
+    expect(second).toBe(BUILTIN_REMARKS.pet[1])
+    // Per-slot counters: the feed slot still opens with its own first line.
+    expect(picker.pick('feed')).toBe(BUILTIN_REMARKS.feed[0])
+  })
+
+  it('cycles back to the start after exhausting a pool', () => {
+    const picker = new RemarkPicker({ pet: ['A', 'B'] })
+    expect(picker.pick('pet')).toBe('A')
+    expect(picker.pick('pet')).toBe('B')
+    expect(picker.pick('pet')).toBe('A')
+  })
+
+  it('lets a custom slot override only its own pool', () => {
+    const picker = new RemarkPicker({ pet: ['专属摸头台词'] })
+    expect(picker.pick('pet')).toBe('专属摸头台词')
+    expect(picker.pick('feed')).toBe(BUILTIN_REMARKS.feed[0])
+  })
+})
+
+describe('normalizePetRemarks', () => {
+  it('accepts single lines and line pools and trims them', () => {
+    const remarks = normalizePetRemarks({
+      pet: '  单句台词  ',
+      feed: ['第一句', ' 第二句 ', 42],
+      petCooldown: [],
+    })
+    expect(remarks).toEqual({ pet: ['单句台词'], feed: ['第一句', '第二句'] })
+  })
+
+  it('rejects non-object blocks and unknown slots with warnings', () => {
+    const warnings: string[] = []
+    expect(normalizePetRemarks('nope', message => warnings.push(message))).toBeUndefined()
+    expect(normalizePetRemarks({ wat: ['x'] }, message => warnings.push(message))).toBeUndefined()
+    expect(normalizePetRemarks({ pet: [1, null] }, message => warnings.push(message))).toBeUndefined()
+    expect(warnings.length).toBe(3)
+  })
+
+  it('caps pool size and line length at the contract bounds', () => {
+    const lines = Array.from({ length: REMARK_LINES_MAX + 10 }, (_, i) => 'line-' + i)
+    const remarks = normalizePetRemarks({ pet: lines, feed: 'x'.repeat(REMARK_LINE_MAX + 50) })
+    expect(remarks?.pet?.length).toBe(REMARK_LINES_MAX)
+    expect(remarks?.feed?.[0]?.length).toBe(REMARK_LINE_MAX)
+  })
+})
+
+describe('builtinRemark', () => {
+  it('returns the legacy first line of every slot', () => {
+    expect(builtinRemark('noTreats')).toBe('没有小鱼干了，多陪我工作一会儿吧～')
+  })
+})

package/src/remarks.ts

@@ -0,0 +1,177 @@
+/**
+ * Pet remark (reaction copy) library — pure. Reaction bubbles the pet speaks
+ * on interaction events come from two layers:
+ *  - the built-in default library below (a generous pool per event kind);
+ *  - per-pet custom lines declared in a manifest's 'remarks' block, which
+ *    community pet contributions (PRs) use to give their pet its own voice.
+ * A custom slot replaces the built-in pool for that slot only; the other
+ * slots keep the built-in lines. Picks cycle round-robin within a pool so
+ * repeated interactions stay varied while tests stay deterministic (no
+ * randomness, no clock).
+ * @module @linxin666/dsh-pet/remarks
+ */
+
+/** Interaction events a reaction line can accompany. */
+export type RemarkKind = 'pet' | 'petCooldown' | 'feed' | 'feedCooldown' | 'noTreats'
+
+/** Every remark slot, in a stable order. */
+export const REMARK_KINDS: readonly RemarkKind[] = [
+  'pet',
+  'petCooldown',
+  'feed',
+  'feedCooldown',
+  'noTreats',
+]
+
+/** Per-pet remark overrides (normalized shape; each slot is a line pool). */
+export type PetRemarks = Partial<Record<RemarkKind, string[]>>
+
+/** Raw manifest shape: each slot accepts one line or a pool of lines. */
+export type PetRemarksManifest = Partial<Record<RemarkKind, string | string[]>>
+
+/** Longest accepted reaction line (characters, trimmed before slicing). */
+export const REMARK_LINE_MAX = 120
+/** Longest accepted pool per slot. */
+export const REMARK_LINES_MAX = 64
+
+/**
+ * Built-in default remark library. Every pool is plain zh copy in the
+ * whale-girl voice; the first line of each pool is the legacy reaction the
+ * plugin has always spoken, so existing installs and tests keep their
+ * wording while the pool adds variety. No emoji characters anywhere (the
+ * repo bans them); ～ is the whale-girl's signature.
+ */
+export const BUILTIN_REMARKS: Readonly<Record<RemarkKind, readonly string[]>> = {
+  pet: [
+    '咕噜咕噜～被摸摸好舒服！',
+    '再摸摸这里，痒痒的～',
+    '头顶温度刚刚好，安心～',
+    '被摸到耳朵啦，扑通扑通！',
+    '你的手掌好温暖，舍不得你走～',
+    '呼噜呼噜～就靠在这里不走了！',
+    '今天的摸头也收货成功！',
+    '蹭蹭你的手心，这是回礼～',
+    '多摸摸我，亲密度会涨哦！',
+    '闭眼享受中，请勿打扰～',
+  ],
+  petCooldown: [
+    '摸过头啦，让鲸鱼娘歇口气～',
+    '羽毛都快被摸秃啦，缓一缓～',
+    '呼……先让我喘口气嘛！',
+    '再摸就要睡着了哦～',
+    '稍微休息一下，待会儿再摸～',
+    '头顶要冒烟啦，停一停！',
+    '我知道你喜欢我，但也要节制呀～',
+    '歇一歇，摸摸的手感会更好哦～',
+    '咕……等我回个蓝～',
+    '让我先消化一下刚才的爱！',
+  ],
+  feed: [
+    '呜哇！小鱼干好好吃！',
+    '咔嚓咔嚓，美味到尾巴打结～',
+    '这条小鱼干是刚晒好的，好香！',
+    '谢谢你，胃里暖暖的～',
+    '囤粮 +1，今天也有好好被爱！',
+    '好吃到想转圈圈～',
+    '小鱼干最好吃了，再来亿条！',
+    '饱餐一顿，马上满血复活～',
+    '这个味道，是幸福的味道！',
+    '吃完了还不忘舔舔爪子～',
+  ],
+  feedCooldown: [
+    '吃饱啦，晚点再喂～',
+    '肚子圆滚滚的，装不下啦～',
+    '再喂就要变成球啦！',
+    '让我慢慢消化这份心意～',
+    '小鱼干的香气还没散呢～',
+    '呼……满足得动不了了～',
+    '先散步一圈再吃下一顿！',
+    '肚皮已经鼓鼓的啦～',
+    '好吃是好吃，可也得节制呀～',
+    '等我饿了会告诉你哦～',
+  ],
+  noTreats: [
+    '没有小鱼干了，多陪我工作一会儿吧～',
+    '粮仓空空，陪我完成几轮任务就会有小鱼干啦～',
+    '小鱼干在路上啦，先一起加油工作！',
+    '嘴巴寂寞了……快去完成一轮任务！',
+    '陪我多工作一会儿，鱼干自动到账～',
+    '现在喂我也只会饿着肚子说谢谢哦～',
+    '粮仓见底啦，用几轮任务换一条鱼干吧～',
+    '饿着肚子等你完成下一轮任务～',
+    '小鱼干藏在你的工作里，去找找看！',
+    '先工作后干饭，我们的约定哦～',
+  ],
+}
+
+/** The legacy first line of one kind (direct callers' fallback copy). */
+export function builtinRemark(kind: RemarkKind): string {
+  return BUILTIN_REMARKS[kind][0]!
+}
+
+/**
+ * Normalize a manifest 'remarks' block into per-kind line pools. Unknown
+ * slots and non-string entries are skipped with a warning; empty pools are
+ * dropped so the built-in library takes the slot. Returns undefined when no
+ * usable slot remains.
+ */
+export function normalizePetRemarks(
+  raw: unknown,
+  onWarning: (message: string) => void = () => {},
+): PetRemarks | undefined {
+  if (raw === undefined) return undefined
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    onWarning('remarks must be an object with pet/petCooldown/feed/feedCooldown/noTreats slots')
+    return undefined
+  }
+  const remarks: PetRemarks = {}
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!REMARK_KINDS.includes(key as RemarkKind)) {
+      onWarning('unknown remarks slot ' + JSON.stringify(key))
+      continue
+    }
+    const lines = (Array.isArray(value) ? value : [value])
+      .filter((line): line is string => typeof line === 'string')
+      .map(line => line.trim())
+      .filter(line => line !== '')
+      .slice(0, REMARK_LINES_MAX)
+      .map(line => line.slice(0, REMARK_LINE_MAX))
+    if (lines.length === 0) {
+      onWarning('remarks slot ' + key + ' carries no usable lines')
+      continue
+    }
+    remarks[key as RemarkKind] = lines
+  }
+  return Object.keys(remarks).length === 0 ? undefined : remarks
+}
+
+/**
+ * Round-robin reaction picker over the effective pools (per-pet custom lines
+ * override the built-in pool per slot). Counters are per slot, so each slot
+ * cycles its own list independently and picks stay deterministic for tests.
+ */
+export class RemarkPicker {
+  private readonly counters = new Map<RemarkKind, number>()
+  private readonly pools: Record<RemarkKind, readonly string[]>
+
+  constructor(overrides?: PetRemarks) {
+    this.pools = {} as Record<RemarkKind, readonly string[]>
+    for (const kind of REMARK_KINDS) {
+      const custom = overrides?.[kind]
+      this.pools[kind] = custom !== undefined && custom.length > 0 ? custom : BUILTIN_REMARKS[kind]
+    }
+  }
+
+  /** The effective pool for one slot (custom override or built-in). */
+  pool(kind: RemarkKind): readonly string[] {
+    return this.pools[kind]
+  }
+
+  /** The next line for one slot (round-robin within its pool). */
+  pick(kind: RemarkKind): string {
+    const pool = this.pools[kind]
+    const index = (this.counters.get(kind) ?? 0) % pool.length
+    this.counters.set(kind, index + 1)
+    return pool[index]!
+  }
+}