@linxin666/dsh-pet 0.2.3 → 0.2.4

package/src/voice-pack.test.ts

@@ -0,0 +1,216 @@
+/**
+ * Voice-pack unit tests (pet-center M4, issue #677): normalization rules
+ * (structure fail-closed per file, content warn-and-drop per slot), the
+ * per-kind placeholder whitelists, and the layer merge precedence
+ * (later layers win per slot).
+ */
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  mergeVoicePacks,
+  normalizePanel,
+  normalizePool,
+  normalizeVoicePack,
+  normalizeWhisperRules,
+  PANEL_ACTIONS,
+  PANEL_LABEL_KEYS,
+  PANEL_STAT_KEYS,
+  VOICE_LINE_MAX,
+  VOICE_PACK_KEYS,
+  VOICE_PACK_V1,
+  WHISPER_KEYS,
+} from './voice-pack.ts'
+import { STATUS_SCENES, TOOL_CATEGORIES } from './chatter.ts'
+import { petPackageRoot } from './registry.ts'
+
+function collectWarnings(pack: unknown): { pack: ReturnType<typeof normalizeVoicePack>; warnings: string[] } {
+  const warnings: string[] = []
+  const result = normalizeVoicePack(pack, message => warnings.push(message))
+  return { pack: result, warnings }
+}
+
+describe('normalizeVoicePack structure', () => {
+  it('accepts a minimal pack and drops it when nothing usable remains', () => {
+    expect(normalizeVoicePack({})).toBeUndefined()
+    expect(normalizeVoicePack({ status: { done: ['收工'] } })).toBeDefined()
+  })
+
+  it('rejects a non-object root with a warning (fail-closed per file)', () => {
+    const { pack, warnings } = collectWarnings(['not', 'an', 'object'])
+    expect(pack).toBeUndefined()
+    expect(warnings[0]).toContain('must be a JSON object')
+  })
+
+  it('warns on unknown top-level fields and unknown voicePackVersion', () => {
+    const { pack, warnings } = collectWarnings({
+      voicePackVersion: 99,
+      mystery: true,
+      status: { done: ['收工'] },
+    })
+    expect(pack).toBeDefined()
+    expect(warnings.join('\n')).toContain('mystery')
+    expect(warnings.join('\n')).toContain('voicePackVersion')
+  })
+})
+
+describe('normalizePool', () => {
+  it('accepts a single string and arrays, dropping non-string entries', () => {
+    const warnings: string[] = []
+    expect(normalizePool('一行', 'status', m => warnings.push(m))).toEqual(['一行'])
+    expect(normalizePool(['一', 7, '二'], 'status', m => warnings.push(m))).toEqual(['一', '二'])
+    expect(warnings.join('\n')).toContain('non-string')
+  })
+
+  it('caps pool length and truncates long lines', () => {
+    const lines = Array.from({ length: 80 }, (_, i) => '行' + i)
+    const warnings: string[] = []
+    const pool = normalizePool(lines, 'status', m => warnings.push(m))
+    expect(pool).toHaveLength(64)
+    expect(warnings.join('\n')).toContain('extra lines')
+    expect(normalizePool(['x'.repeat(500)], 'status')?.[0]).toHaveLength(VOICE_LINE_MAX)
+  })
+
+  it('drops lines carrying placeholders the pool kind does not allow', () => {
+    const warnings: string[] = []
+    const pool = normalizePool(['好的 {tool}', '干净的'], 'status', m => warnings.push(m))
+    expect(pool).toEqual(['干净的'])
+    expect(warnings.join('\n')).toContain('unsupported placeholder')
+  })
+
+  it('keeps allowed placeholders per kind', () => {
+    expect(normalizePool(['跑 {hint}', '用 {tool}'], 'tools')![0]).toBe('跑 {hint}')
+    expect(normalizePool(['还有 {n} 个'], 'toolRemaining')![0]).toBe('还有 {n} 个')
+    expect(normalizePool(['好感 {rank}'], 'stat')![0]).toBe('好感 {rank}')
+  })
+
+  it('preserves an explicit empty array (mute semantics) but not absent', () => {
+    expect(normalizePool([], 'whisperGeneric')).toEqual([])
+    expect(normalizePool(undefined, 'whisperGeneric')).toBeUndefined()
+  })
+})
+
+describe('normalizeWhisperRules', () => {
+  it('lowercases and trims keywords, drops unusable rules', () => {
+    const warnings: string[] = []
+    const rules = normalizeWhisperRules([
+      { keywords: ['  测试通过  ', 7], pool: ['全绿'] },
+      { keywords: [], pool: ['没有关键词'] },
+      { keywords: ['有词'], pool: [] },
+    ], m => warnings.push(m))
+    expect(rules).toEqual([{ keywords: ['测试通过'], pool: ['全绿'] }])
+    expect(warnings.length).toBeGreaterThan(0)
+  })
+
+  it('caps the rule count and keyword count', () => {
+    const many = Array.from({ length: 40 }, (_, i) => ({ keywords: ['k' + i], pool: ['p'] }))
+    expect(normalizeWhisperRules(many)).toHaveLength(32)
+    expect(normalizeWhisperRules([{ keywords: Array.from({ length: 20 }, (_, i) => 'k' + i), pool: ['p'] }])![0]!.keywords).toHaveLength(16)
+  })
+
+  it('returns an explicit empty array (disables the keyword channel)', () => {
+    expect(normalizeWhisperRules([])).toEqual([])
+  })
+})
+
+describe('normalizePanel', () => {
+  it('normalizes labels, stats and the action subset', () => {
+    const panel = normalizePanel({
+      labels: { feed: '投喂', confirm: '好的', bogus: 'x' },
+      stats: { rank: '好感 {rank}', points: '{points} 分' },
+      actions: ['hide', 'feed', 'hide', 'bogus'],
+    })
+    expect(panel?.labels).toEqual({ feed: '投喂', confirm: '好的' })
+    expect(panel?.stats).toEqual({ rank: '好感 {rank}', points: '{points} 分' })
+    expect(panel?.actions).toEqual(['feed', 'hide'])
+  })
+
+  it('rejects non-string labels and labels carrying placeholders', () => {
+    const warnings: string[] = []
+    const panel = normalizePanel({ labels: { feed: 3, rename: '改名 {tool}' } }, m => warnings.push(m))
+    expect(panel?.labels).toBeUndefined()
+    expect(warnings.length).toBe(2)
+  })
+
+  it('keeps an explicit empty action list (hides every action)', () => {
+    expect(normalizePanel({ actions: [] })?.actions).toEqual([])
+  })
+})
+
+describe('mergeVoicePacks', () => {
+  it('merges per-key with later layers winning', () => {
+    const global = normalizeVoicePack({
+      status: { done: ['全局收工'], thinking: ['全局思考'] },
+      panel: { labels: { feed: '全局投喂' } },
+    })
+    const pet = normalizeVoicePack({
+      status: { done: ['宠物收工'] },
+      panel: { labels: { feed: '宠物投喂', hide: '宠物藏' } },
+    })
+    const merged = mergeVoicePacks(global, pet)
+    expect(merged?.overrides.status?.done).toEqual(['宠物收工'])
+    expect(merged?.overrides.status?.thinking).toEqual(['全局思考'])
+    expect(merged?.panel?.labels).toEqual({ feed: '宠物投喂', hide: '宠物藏' })
+  })
+
+  it('lets the pet pack replace whisper sections while the global stays', () => {
+    const global = normalizeVoicePack({ whispers: { generic: ['全局碎碎念'] } })
+    const pet = normalizeVoicePack({ whispers: { rules: [{ keywords: ['测试'], pool: ['宠物全绿'] }] } })
+    const merged = mergeVoicePacks(global, pet)
+    expect(merged?.overrides.whispers?.generic).toEqual(['全局碎碎念'])
+    expect(merged?.overrides.whispers?.rules).toEqual([{ keywords: ['测试'], pool: ['宠物全绿'] }])
+  })
+
+  it('returns undefined when every layer is empty', () => {
+    expect(mergeVoicePacks(undefined, undefined)).toBeUndefined()
+  })
+})
+
+describe('normalizeVoicePack schema twin', () => {
+  it('accepts the $schema field without a warning', () => {
+    const { pack, warnings } = collectWarnings({
+      $schema: 'http://json-schema.org/draft-07/schema#',
+      status: { done: ['收工'] },
+    })
+    expect(pack).toBeDefined()
+    expect(warnings).toEqual([])
+  })
+
+  it('drops the tail when the length cap cuts a placeholder token in half', () => {
+    const line = 'x'.repeat(155) + '{tool}'
+    const { pack, warnings } = collectWarnings({ tools: { shell: [line] } })
+    expect(pack?.overrides.tools?.shell).toEqual(['x'.repeat(155)])
+    expect(warnings.some(w => w.includes('unterminated placeholder'))).toBe(true)
+  })
+})
+
+describe('voice-pack schema file drift lock', () => {
+  const schema = JSON.parse(readFileSync(
+    join(petPackageRoot(import.meta.url), 'contracts', 'voice-pack-v1.schema.json'),
+    'utf8',
+  )) as {
+    properties: Record<string, { const?: number; properties?: Record<string, unknown>; items?: { enum?: string[] } }>
+  }
+
+  it('locks the schema top-level fields to the validator allow-list', () => {
+    expect(new Set(Object.keys(schema.properties))).toEqual(VOICE_PACK_KEYS)
+  })
+
+  it('locks the scene, tool, whisper and panel key sets', () => {
+    const props = schema.properties
+    expect(new Set(Object.keys(props.status?.properties ?? {}))).toEqual(new Set(STATUS_SCENES))
+    expect(new Set(Object.keys(props.tools?.properties ?? {}))).toEqual(new Set(TOOL_CATEGORIES))
+    expect(new Set(Object.keys(props.whispers?.properties ?? {}))).toEqual(WHISPER_KEYS)
+    const panel = props.panel?.properties ?? {}
+    const labels = (panel.labels as { properties?: Record<string, unknown> } | undefined)?.properties ?? {}
+    const stats = (panel.stats as { properties?: Record<string, unknown> } | undefined)?.properties ?? {}
+    expect(new Set(Object.keys(labels))).toEqual(new Set(PANEL_LABEL_KEYS))
+    expect(new Set(Object.keys(stats))).toEqual(new Set(PANEL_STAT_KEYS))
+    const actions = (panel.actions as { items?: { enum?: string[] } } | undefined)
+    expect(actions?.items?.enum).toEqual([...PANEL_ACTIONS])
+  })
+
+  it('keeps the schema version const in sync', () => {
+    expect(schema.properties.voicePackVersion?.const).toBe(VOICE_PACK_V1)
+  })
+})

package/src/voice-pack.ts

@@ -0,0 +1,413 @@
+/**
+ * Voice-pack normalization and merge (pet-center M4, issue #677).
+ *
+ * A voice pack is the optional 'voice.json' inside a pet directory, or the
+ * global '$DSH_HOME/pets/.voice.json' override file — pure JSON content that
+ * layers pet copy over the built-in pools. Two halves:
+ *
+ *  - 'overrides': the chatter pools (status / tools / toolRemaining /
+ *    whispers) handed to the chatter engines through a VoicePoolsProvider;
+ *  - 'panel': the hover-panel chrome (button labels, stat formats, action
+ *    subset) served to the browser half through PetDefinition.panel.
+ *
+ * Discipline split matches the registry: STRUCTURE is fail-closed per file
+ * (a non-object root drops the whole pack with a warning), CONTENT is
+ * warn-and-drop per slot — one bad line never breaks a pet. The JSON Schema
+ * twin lives at contracts/voice-pack-v1.schema.json for documentation and
+ * external tooling; this hand-rolled normalizer is authoritative (the
+ * repository ships no schema-validator runtime).
+ *
+ * Placeholder policy (each pool kind whitelists its own tokens):
+ *  - status / whisper pools / panel labels: no placeholders allowed — a line
+ *    carrying any '{...}' token is dropped with a warning;
+ *  - tools: {tool} and {hint}; toolRemaining: {n}; panel stats:
+ *    {rank} / {n} / {points}.
+ *
+ * This file is imported directly by scripts/dsh-pet under node's strip-only
+ * TypeScript mode: keep it erasable-syntax-only.
+ * @module @linxin666/dsh-pet/voice-pack
+ */
+
+import {
+  STATUS_SCENES,
+  TOOL_CATEGORIES,
+  type VoicePackOverrides,
+  type WhisperRule,
+} from './chatter.ts'
+
+/** Schema version this module normalizes (optional field; missing = 1). */
+export const VOICE_PACK_V1 = 1 as const
+
+/** Hover-panel action buttons a pack can show or hide (canonical order). */
+export const PANEL_ACTIONS = ['feed', 'rename', 'hide'] as const
+export type PanelAction = (typeof PANEL_ACTIONS)[number]
+
+/** Panel label slots (unset slots keep the client's i18n dictionary copy). */
+export const PANEL_LABEL_KEYS = ['feed', 'rename', 'hide', 'confirm'] as const
+export type PanelLabelKey = (typeof PANEL_LABEL_KEYS)[number]
+
+/** Panel stat slots ({rank}/{n}/{points} interpolate the live values). */
+export const PANEL_STAT_KEYS = ['rank', 'treats', 'points'] as const
+export type PanelStatKey = (typeof PANEL_STAT_KEYS)[number]
+
+/** Hover-panel chrome overrides served to the browser half. */
+export interface PetPanelView {
+  /** Button / input labels; unset slots keep the i18n dictionary copy. */
+  labels?: Partial<Record<PanelLabelKey, string>>
+  /** Stat line formats; unset slots keep the i18n dictionary copy. */
+  stats?: Partial<Record<PanelStatKey, string>>
+  /** Actions to render in canonical order; absent = all three; [] = none. */
+  actions?: PanelAction[]
+}
+
+/** One normalized voice pack (a pet's voice.json or the global override). */
+export interface VoicePack {
+  /** Chatter pool overrides (draw-time merged with the built-in pools). */
+  overrides: VoicePackOverrides
+  /** Hover-panel chrome, when the pack declares any. */
+  panel?: PetPanelView
+}
+
+/** Hard caps shared by every pool slot (mirrors the remarks discipline). */
+export const VOICE_POOL_LINES_MAX = 64
+export const VOICE_LINE_MAX = 160
+export const VOICE_KEYWORDS_PER_RULE_MAX = 16
+export const VOICE_KEYWORD_MAX = 40
+export const VOICE_RULES_MAX = 32
+export const VOICE_LABEL_MAX = 40
+export const VOICE_STAT_MAX = 80
+
+/** Any '{token}' placeholder (no nesting, no newlines). */
+const PLACEHOLDER_PATTERN = /{[^{}]*}/g
+
+/** Allowed placeholder tokens per pool kind (absent kind = none allowed). */
+const PLACEHOLDER_WHITELIST: Partial<Record<PoolKind, readonly string[]>> = {
+  tools: ['{tool}', '{hint}'],
+  toolRemaining: ['{n}'],
+  stat: ['{rank}', '{n}', '{points}'],
+}
+
+type PoolKind = 'status' | 'tools' | 'toolRemaining' | 'whisperGeneric' | 'whisperRule' | 'label' | 'stat'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Trim, length-cap and placeholder-check one copy line; undefined to drop. */
+function normalizeLine(raw: string, kind: PoolKind, onWarning: (message: string) => void): string | undefined {
+  const trimmed = raw.trim()
+  if (trimmed === '') return undefined
+  let capped = trimmed.length > VOICE_LINE_MAX ? trimmed.slice(0, VOICE_LINE_MAX) : trimmed
+  // The length cap may cut a placeholder token in half, leaving a dangling
+  // '{' that would render literally; drop the tail from the unmatched brace.
+  const dangling = capped.lastIndexOf('{')
+  if (dangling !== -1 && capped.indexOf('}', dangling) === -1) {
+    onWarning('line cut at an unterminated placeholder; tail dropped: ' + capped.slice(0, 40) + '...')
+    capped = capped.slice(0, dangling)
+  }
+  if (capped === '') return undefined
+  const allowed = PLACEHOLDER_WHITELIST[kind]
+  const tokens = capped.match(PLACEHOLDER_PATTERN) ?? []
+  for (const token of tokens) {
+    if (allowed?.includes(token) === true) continue
+    const preview = capped.length > 40 ? capped.slice(0, 40) + '...' : capped
+    onWarning('line dropped (unsupported placeholder ' + token + '): ' + preview)
+    return undefined
+  }
+  return capped
+}
+
+/**
+ * Normalize one pool slot. Accepts a single line or an array; non-string
+ * entries warn and drop, empty lines drop silently, lines over the length
+ * cap truncate, illegal placeholders drop the line, and pools over the line
+ * cap keep their first lines. An explicit empty pool normalizes to [] (the
+ * whisper channels read that as mute) while an absent slot normalizes to
+ * undefined (the slot keeps the built-in pool).
+ */
+export function normalizePool(
+  raw: unknown,
+  kind: PoolKind,
+  onWarning: (message: string) => void = () => {},
+): string[] | undefined {
+  if (raw === undefined) return undefined
+  const entries = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw : undefined
+  if (entries === undefined) {
+    onWarning('pool must be a string or an array of strings')
+    return undefined
+  }
+  if (entries.length > VOICE_POOL_LINES_MAX) {
+    onWarning('pool has more than ' + VOICE_POOL_LINES_MAX + ' lines; extra lines are ignored')
+  }
+  const pool: string[] = []
+  for (const entry of entries.slice(0, VOICE_POOL_LINES_MAX)) {
+    if (typeof entry !== 'string') {
+      onWarning('non-string pool entry dropped')
+      continue
+    }
+    const line = normalizeLine(entry, kind, onWarning)
+    if (line !== undefined) pool.push(line)
+  }
+  return pool
+}
+
+/** Normalize the ordered keyword-rule list ([] disables the keyword channel). */
+export function normalizeWhisperRules(
+  raw: unknown,
+  onWarning: (message: string) => void = () => {},
+): WhisperRule[] | undefined {
+  if (raw === undefined) return undefined
+  if (!Array.isArray(raw)) {
+    onWarning('whispers.rules must be an array')
+    return undefined
+  }
+  if (raw.length > VOICE_RULES_MAX) {
+    onWarning('whispers.rules has more than ' + VOICE_RULES_MAX + ' rules; extra rules are ignored')
+  }
+  const rules: WhisperRule[] = []
+  for (const item of raw.slice(0, VOICE_RULES_MAX)) {
+    if (!isRecord(item)) {
+      onWarning('whisper rule must be an object')
+      continue
+    }
+    for (const key of Object.keys(item)) {
+      if (key !== 'keywords' && key !== 'pool') onWarning('unknown whisper rule field ' + key + ' ignored')
+    }
+    const keywordsRaw: unknown = item.keywords
+    const keywords: string[] = []
+    if (Array.isArray(keywordsRaw)) {
+      for (const entry of keywordsRaw.slice(0, VOICE_KEYWORDS_PER_RULE_MAX)) {
+        if (typeof entry !== 'string') {
+          onWarning('non-string keyword dropped')
+          continue
+        }
+        const trimmed = entry.trim().toLowerCase().slice(0, VOICE_KEYWORD_MAX)
+        if (trimmed !== '') keywords.push(trimmed)
+      }
+      if (keywordsRaw.length > VOICE_KEYWORDS_PER_RULE_MAX) {
+        onWarning('rule has more than ' + VOICE_KEYWORDS_PER_RULE_MAX + ' keywords; extra keywords are ignored')
+      }
+    }
+    const pool = normalizePool(item.pool, 'whisperRule', onWarning)
+    if (keywords.length === 0 || pool === undefined || pool.length === 0) {
+      onWarning('whisper rule dropped (needs keywords and a non-empty pool)')
+      continue
+    }
+    rules.push({ keywords, pool })
+  }
+  return rules
+}
+
+/** Normalize the panel block (labels / stats / actions; warn-and-drop). */
+export function normalizePanel(
+  raw: unknown,
+  onWarning: (message: string) => void = () => {},
+): PetPanelView | undefined {
+  if (!isRecord(raw)) {
+    onWarning('panel must be an object')
+    return undefined
+  }
+  const panel: PetPanelView = {}
+  const labelsRaw = raw.labels
+  if (labelsRaw !== undefined) {
+    if (!isRecord(labelsRaw)) {
+      onWarning('panel.labels must be an object')
+    } else {
+      const labels: Record<string, string> = {}
+      for (const key of PANEL_LABEL_KEYS) {
+        const value = labelsRaw[key]
+        if (value === undefined) continue
+        if (typeof value !== 'string') {
+          onWarning('panel.labels.' + key + ' must be a string')
+          continue
+        }
+        const line = normalizeLine(value, 'label', onWarning)
+        if (line !== undefined) labels[key] = line.slice(0, VOICE_LABEL_MAX)
+      }
+      if (Object.keys(labels).length > 0) panel.labels = labels
+    }
+  }
+  const statsRaw = raw.stats
+  if (statsRaw !== undefined) {
+    if (!isRecord(statsRaw)) {
+      onWarning('panel.stats must be an object')
+    } else {
+      const stats: Record<string, string> = {}
+      for (const key of PANEL_STAT_KEYS) {
+        const value = statsRaw[key]
+        if (value === undefined) continue
+        if (typeof value !== 'string') {
+          onWarning('panel.stats.' + key + ' must be a string')
+          continue
+        }
+        const line = normalizeLine(value, 'stat', onWarning)
+        if (line !== undefined) stats[key] = line.slice(0, VOICE_STAT_MAX)
+      }
+      if (Object.keys(stats).length > 0) panel.stats = stats
+    }
+  }
+  const actionsRaw = raw.actions
+  if (actionsRaw !== undefined) {
+    if (!Array.isArray(actionsRaw)) {
+      onWarning('panel.actions must be an array')
+    } else {
+      const seen = new Set<PanelAction>()
+      for (const entry of actionsRaw) {
+        if (typeof entry !== 'string' || !(PANEL_ACTIONS as readonly string[]).includes(entry)) {
+          onWarning('unknown panel action dropped: ' + String(entry))
+          continue
+        }
+        seen.add(entry as PanelAction)
+      }
+      // Canonical order, deduplicated; an explicit empty array hides all.
+      panel.actions = PANEL_ACTIONS.filter(action => seen.has(action))
+    }
+  }
+  if (panel.labels === undefined && panel.stats === undefined && panel.actions === undefined) return undefined
+  return panel
+}
+
+/** Voice-pack top-level fields ('$schema' mirrors the schema twin; drift-locked in tests). */
+export const VOICE_PACK_KEYS = new Set(['$schema', 'voicePackVersion', 'status', 'tools', 'toolRemaining', 'whispers', 'panel'])
+
+/** Allowed whisper-section fields (drift-locked in tests). */
+export const WHISPER_KEYS = new Set(['generic', 'rules'])
+
+/**
+ * Normalize one raw voice.json document into a VoicePack, or undefined when
+ * the file cannot serve as a pack at all (non-object root — structure is
+ * fail-closed per file). Every slot issue is a warning, never a throw.
+ */
+export function normalizeVoicePack(
+  raw: unknown,
+  onWarning: (message: string) => void = () => {},
+): VoicePack | undefined {
+  if (raw === undefined) return undefined
+  if (!isRecord(raw)) {
+    onWarning('voice.json must be a JSON object; the file is ignored')
+    return undefined
+  }
+  for (const key of Object.keys(raw)) {
+    if (!VOICE_PACK_KEYS.has(key)) onWarning('unknown top-level field ' + key + ' ignored')
+  }
+  const version = raw.voicePackVersion
+  if (version !== undefined && (typeof version !== 'number' || version !== VOICE_PACK_V1)) {
+    onWarning('voicePackVersion ' + String(version) + ' is not supported; reading as v1 best-effort')
+  }
+  const overrides: VoicePackOverrides = {}
+  const statusRaw = raw.status
+  if (statusRaw !== undefined) {
+    if (!isRecord(statusRaw)) {
+      onWarning('status must be an object')
+    } else {
+      for (const key of Object.keys(statusRaw)) {
+        if (!(STATUS_SCENES as readonly string[]).includes(key)) {
+          onWarning('unknown status scene ' + key + ' ignored')
+          continue
+        }
+        const pool = normalizePool(statusRaw[key], 'status', onWarning)
+        if (pool !== undefined && pool.length > 0) {
+          overrides.status = { ...overrides.status, [key]: pool }
+        }
+      }
+    }
+  }
+  const toolsRaw = raw.tools
+  if (toolsRaw !== undefined) {
+    if (!isRecord(toolsRaw)) {
+      onWarning('tools must be an object')
+    } else {
+      for (const key of Object.keys(toolsRaw)) {
+        if (!(TOOL_CATEGORIES as readonly string[]).includes(key)) {
+          onWarning('unknown tool family ' + key + ' ignored')
+          continue
+        }
+        const pool = normalizePool(toolsRaw[key], 'tools', onWarning)
+        if (pool !== undefined && pool.length > 0) {
+          overrides.tools = { ...overrides.tools, [key]: pool }
+        }
+      }
+    }
+  }
+  const remainingRaw = raw.toolRemaining
+  if (remainingRaw !== undefined) {
+    const pool = normalizePool(remainingRaw, 'toolRemaining', onWarning)
+    if (pool !== undefined && pool.length > 0) overrides.toolRemaining = pool
+  }
+  const whispersRaw = raw.whispers
+  if (whispersRaw !== undefined) {
+    if (!isRecord(whispersRaw)) {
+      onWarning('whispers must be an object')
+    } else {
+      for (const key of Object.keys(whispersRaw)) {
+        if (!WHISPER_KEYS.has(key)) onWarning('unknown whispers field ' + key + ' ignored')
+      }
+      const generic = normalizePool(whispersRaw.generic, 'whisperGeneric', onWarning)
+      const rules = normalizeWhisperRules(whispersRaw.rules, onWarning)
+      if (generic !== undefined || rules !== undefined) {
+        overrides.whispers = {
+          ...(generic === undefined ? {} : { generic }),
+          ...(rules === undefined ? {} : { rules }),
+        }
+      }
+    }
+  }
+  const panel = raw.panel === undefined ? undefined : normalizePanel(raw.panel, onWarning)
+  if (
+    overrides.status === undefined && overrides.tools === undefined
+    && overrides.toolRemaining === undefined && overrides.whispers === undefined
+    && panel === undefined
+  ) {
+    return undefined
+  }
+  return {
+    overrides,
+    ...(panel === undefined ? {} : { panel }),
+  }
+}
+
+/**
+ * Merge voice-pack layers into one pack; later layers win per slot. The
+ * built-in pools are NOT a layer here — the chatter engines fall back to
+ * them per key at draw time. Merge order for a selected pet:
+ * mergeVoicePacks(registry.globalVoice, entry.voice).
+ */
+export function mergeVoicePacks(...layers: (VoicePack | undefined)[]): VoicePack | undefined {
+  const overrides: VoicePackOverrides = {}
+  const labels: NonNullable<PetPanelView['labels']> = {}
+  const stats: NonNullable<PetPanelView['stats']> = {}
+  let actions: PanelAction[] | undefined
+  let panelSeen = false
+  let any = false
+  for (const layer of layers) {
+    if (layer === undefined) continue
+    any = true
+    if (layer.overrides.status !== undefined) {
+      overrides.status = { ...overrides.status, ...layer.overrides.status }
+    }
+    if (layer.overrides.tools !== undefined) {
+      overrides.tools = { ...overrides.tools, ...layer.overrides.tools }
+    }
+    if (layer.overrides.toolRemaining !== undefined) overrides.toolRemaining = layer.overrides.toolRemaining
+    if (layer.overrides.whispers !== undefined) {
+      overrides.whispers = { ...overrides.whispers, ...layer.overrides.whispers }
+    }
+    if (layer.panel !== undefined) {
+      panelSeen = true
+      if (layer.panel.labels !== undefined) Object.assign(labels, layer.panel.labels)
+      if (layer.panel.stats !== undefined) Object.assign(stats, layer.panel.stats)
+      if (layer.panel.actions !== undefined) actions = layer.panel.actions
+    }
+  }
+  if (!any) return undefined
+  const panel: PetPanelView = {
+    ...(Object.keys(labels).length > 0 ? { labels } : {}),
+    ...(Object.keys(stats).length > 0 ? { stats } : {}),
+    ...(actions === undefined ? {} : { actions }),
+  }
+  const panelEmpty = panel.labels === undefined && panel.stats === undefined && panel.actions === undefined
+  return {
+    overrides,
+    ...(panelSeen && !panelEmpty ? { panel } : {}),
+  }
+}