@linxin666/dsh-pet 0.2.3 → 0.2.5

package/src/registry.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path'
 import {
   DEFAULT_FRAME_COUNTS,
   DEFAULT_PET_CELL,
+  PET_SCAN_JSON_CAP,
   codexPetsDir,
   loadPetRegistry,
   petAtlasFile,
@@ -465,3 +466,278 @@ describe('loadPetRegistry pet-center v2 (issue #623)', () => {
     }
   })
 })
+
+describe('voice packs (pet-center M4, issue #677)', () => {
+  function writeVoice(dir: string, name: string, pack: unknown): void {
+    mkdirSync(join(dir, name), { recursive: true })
+    writeFileSync(join(dir, name, 'pet.json'), JSON.stringify({ id: name, displayName: name, spritesheetPath: 'spritesheet.webp' }), 'utf8')
+    writeFileSync(join(dir, name, 'spritesheet.webp'), 'webp', 'utf8')
+    writeFileSync(join(dir, name, 'voice.json'), JSON.stringify(pack), 'utf8')
+  }
+
+  it('loads a pet voice.json and serves its panel slice to the browser view', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      writeVoice(petsDir, 'talker', {
+        status: { done: ['自定义完工'] },
+        panel: { labels: { feed: '投喂' }, stats: { rank: '好感 {rank}' }, actions: ['feed'] },
+      })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      const entry = registry.byId('talker')!
+      expect(entry.voice?.overrides.status?.done).toEqual(['自定义完工'])
+      const view = petEntryView(entry)
+      expect(view.panel).toEqual({
+        labels: { feed: '投喂' },
+        stats: { rank: '好感 {rank}' },
+        actions: ['feed'],
+      })
+      // Host-only voice content never reaches the browser half.
+      expect('voice' in view).toBe(false)
+      // A healthy voice pack records no diagnostics of its own.
+      expect(registry.diagnostics.filter(d => d.message.includes('voice'))).toEqual([])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('warns and drops a broken voice.json without rejecting the pet', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'mumbler'), { recursive: true })
+      writeFileSync(join(petsDir, 'mumbler', 'pet.json'), JSON.stringify({ id: 'mumbler', displayName: 'Mumbler', spritesheetPath: 'spritesheet.webp' }), 'utf8')
+      writeFileSync(join(petsDir, 'mumbler', 'spritesheet.webp'), 'webp', 'utf8')
+      writeFileSync(join(petsDir, 'mumbler', 'voice.json'), '{ not json', 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('mumbler')).toBeDefined()
+      expect(registry.byId('mumbler')!.voice).toBeUndefined()
+      expect(registry.diagnostics.some(d => d.level === 'warning' && d.message.includes('voice pack is not valid JSON'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('loads the global .voice.json override from the DSH_HOME pets dir', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'plain'), { recursive: true })
+      writeFileSync(join(petsDir, 'plain', 'pet.json'), JSON.stringify({ id: 'plain', displayName: 'Plain', spritesheetPath: 'spritesheet.webp' }), 'utf8')
+      writeFileSync(join(petsDir, 'plain', 'spritesheet.webp'), 'webp', 'utf8')
+      writeFileSync(join(petsDir, '.voice.json'), JSON.stringify({
+        status: { done: ['全局完工'] },
+        panel: { labels: { hide: '全局藏' } },
+      }), 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: petsDir })
+      expect(registry.globalVoice?.overrides.status?.done).toEqual(['全局完工'])
+      expect(registry.globalVoice?.panel?.labels).toEqual({ hide: '全局藏' })
+      // The dotfile itself is never scanned as a pet directory.
+      expect(registry.entries.map(e => e.id)).toEqual(['plain'])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('serves the merged panel chrome (per-pet over global, per slot)', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'plain'), { recursive: true })
+      writeFileSync(join(petsDir, 'plain', 'pet.json'), JSON.stringify({ id: 'plain', displayName: 'Plain', spritesheetPath: 'spritesheet.webp' }), 'utf8')
+      writeFileSync(join(petsDir, 'plain', 'spritesheet.webp'), 'webp', 'utf8')
+      writeFileSync(join(petsDir, 'plain', 'voice.json'), JSON.stringify({
+        panel: { labels: { feed: '宠物投喂' }, stats: { treats: '宠物鱼干 {n}' } },
+      }), 'utf8')
+      writeFileSync(join(petsDir, '.voice.json'), JSON.stringify({
+        panel: { labels: { feed: '全局投喂', hide: '全局藏' } },
+      }), 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: petsDir })
+      const entry = registry.byId('plain')
+      expect(entry).toBeDefined()
+      const view = petEntryView(entry!, registry.globalVoice)
+      // The pet's own slot wins; untouched global slots layer underneath.
+      expect(view.panel?.labels).toEqual({ feed: '宠物投喂', hide: '全局藏' })
+      expect(view.panel?.stats?.treats).toBe('宠物鱼干 {n}')
+      // A pack-less pet would receive the global panel as-is.
+      const bare = resolvePetManifest({ id: 'bare', displayName: 'Bare', spritesheetPath: 'spritesheet.webp' }, join(tmpdir(), 'bare'))
+      expect(petEntryView(bare!, registry.globalVoice).panel?.labels).toEqual({ feed: '全局投喂', hide: '全局藏' })
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('skips an oversized voice.json with a warning instead of reading it', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'loud'), { recursive: true })
+      writeFileSync(join(petsDir, 'loud', 'pet.json'), JSON.stringify({ id: 'loud', displayName: 'Loud', spritesheetPath: 'spritesheet.webp' }), 'utf8')
+      writeFileSync(join(petsDir, 'loud', 'voice.json'), '{ ' + 'x'.repeat(PET_SCAN_JSON_CAP) + ' }', 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('loud')!.voice).toBeUndefined()
+      expect(registry.warnings.some(w => w.includes('scan ceiling'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('skips a non-regular voice.json with a warning', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'odd', 'voice.json'), { recursive: true })
+      writeFileSync(join(petsDir, 'odd', 'pet.json'), JSON.stringify({ id: 'odd', displayName: 'Odd', spritesheetPath: 'spritesheet.webp' }), 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('odd')!.voice).toBeUndefined()
+      expect(registry.warnings.some(w => w.includes('not a regular file'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+describe('status decorations (pet-center M5, #567)', () => {
+  /** A minimal valid PNG header (signature + IHDR) with the given size. */
+  function pngHeader(width: number, height: number): Buffer {
+    const buf = Buffer.alloc(26)
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(buf, 0)
+    buf.writeUInt32BE(13, 8)      // IHDR chunk length
+    buf.write('IHDR', 12)         // chunk type
+    buf.writeUInt32BE(width, 16)  // width
+    buf.writeUInt32BE(height, 20) // height
+    return buf
+  }
+
+  /** A strip whose pixel geometry matches baseManifest() (64x48 cell, 4 cols). */
+  function matchingStrip(): Buffer {
+    return pngHeader(64 * 4, 48)
+  }
+
+  function writeDecoration(dir: string, name: string, manifest: Record<string, unknown>, strip: Buffer | string = 'whale-frames.png'): void {
+    mkdirSync(join(dir, name), { recursive: true })
+    writeFileSync(join(dir, name, 'decoration.json'), JSON.stringify(manifest), 'utf8')
+    writeFileSync(join(dir, name, manifest.entry as string), strip)
+  }
+
+  const baseManifest = () => ({
+    decorationManifestVersion: 1,
+    id: 'whale',
+    displayName: '喷水鲸鱼',
+    license: 'MIT',
+    entry: 'whale-frames.png',
+    cell: { width: 64, height: 48 },
+    columns: 4,
+    phases: { idle: 'hide', thinking: { from: 0, to: 3 } },
+  })
+
+  it('scans built-in decorations and exposes the browser view fields', () => {
+    const root = tempDir()
+    try {
+      const assets = join(root, 'assets')
+      writeDecoration(join(assets, 'decorations'), 'whale', baseManifest(), matchingStrip())
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      const entry = registry.decorationById?.('whale')
+      expect(entry).toBeDefined()
+      expect(entry!.entryUrl).toBe('/api/pet/decoration/whale/whale-frames.png')
+      expect(entry!.servable).toEqual(['decoration.json', 'whale-frames.png'])
+      expect(entry!.phases.thinking).toEqual({ from: 0, to: 3 })
+      // The pet entries list is untouched by decorations.
+      expect(registry.entries).toEqual([])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('lets a user decoration override the built-in by id', () => {
+    const root = tempDir()
+    try {
+      writeDecoration(join(root, 'assets', 'decorations'), 'whale', baseManifest(), matchingStrip())
+      const dsh = join(root, 'dsh')
+      writeDecoration(join(dsh, 'decorations'), 'whale', { ...baseManifest(), displayName: '家用鲸鱼' }, matchingStrip())
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: dsh })
+      expect(registry.decorationById?.('whale')?.id).toBe('whale')
+      expect(registry.warnings.some(w => w.includes('user decoration whale overrides'))).toBe(true)
+      expect(registry.decorationById?.('whale')?.entryUrl).toBe('/api/pet/decoration/whale/whale-frames.png')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('warns and skips a broken descriptor without disturbing pets', () => {
+    const root = tempDir()
+    try {
+      mkdirSync(join(root, 'assets', 'decorations', 'broken'), { recursive: true })
+      writeFileSync(join(root, 'assets', 'decorations', 'broken', 'decoration.json'), '{ not json', 'utf8')
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      expect(registry.decorations).toEqual([])
+      expect(registry.diagnostics.some(d => d.level === 'error' && d.message.includes('broken'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('skips an oversized decoration.json with a warning instead of reading it', () => {
+    const root = tempDir()
+    try {
+      mkdirSync(join(root, 'assets', 'decorations', 'huge'), { recursive: true })
+      writeFileSync(join(root, 'assets', 'decorations', 'huge', 'decoration.json'), '{ ' + 'x'.repeat(PET_SCAN_JSON_CAP) + ' }', 'utf8')
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      expect(registry.decorations).toEqual([])
+      expect(registry.warnings.some(w => w.includes('scan ceiling'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('lists a decoration with a missing strip and warns about the file', () => {
+    const root = tempDir()
+    try {
+      const dir = join(root, 'assets', 'decorations', 'ghost')
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(join(dir, 'decoration.json'), JSON.stringify(baseManifest()), 'utf8')
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      // The entry id comes from the descriptor (the directory name is free).
+      expect(registry.decorationById?.('whale')).toBeDefined()
+      expect(registry.warnings.some(w => w.includes('strip file missing'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('warns and keeps a decoration whose strip geometry mismatches the descriptor', () => {
+    const root = tempDir()
+    try {
+      // Declared 64x48 cell x 4 columns = 256x48; the file is only 128x48
+      // (2 frames worth) — the client would silently render half the frames.
+      const dir = join(root, 'assets', 'decorations', 'short')
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(join(dir, 'decoration.json'), JSON.stringify(baseManifest()), 'utf8')
+      writeFileSync(join(dir, 'whale-frames.png'), pngHeader(128, 48))
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      // Warn-and-keep: the entry still lists (mirroring the missing-strip
+      // discipline) and the warning names the mismatch.
+      expect(registry.decorationById?.('whale')).toBeDefined()
+      expect(registry.warnings.some(w => w.includes('does not match cell'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('does not warn when a matching strip is undecodable (non-image bytes)', () => {
+    const root = tempDir()
+    try {
+      const dir = join(root, 'assets', 'decorations', 'opaque')
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(join(dir, 'decoration.json'), JSON.stringify(baseManifest()), 'utf8')
+      // Unrecognized bytes: the header reader returns undefined, so the scan
+      // stays silent (cannot verify != mismatch). Only the missing-file check
+      // applies.
+      writeFileSync(join(dir, 'whale-frames.png'), Buffer.from('not-an-image'))
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      expect(registry.decorationById?.('whale')).toBeDefined()
+      expect(registry.warnings.some(w => w.includes('does not match cell'))).toBe(false)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})

package/src/registry.ts

@@ -27,12 +27,16 @@
  * @module @linxin666/dsh-pet/registry
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { ActivityPhase, PetAnimation } from './state.ts'
 import { normalizePetRemarks, type PetRemarks, type PetRemarksManifest } from './remarks.ts'
+import { mergeVoicePacks, normalizeVoicePack, type PetPanelView, type VoicePack } from './voice-pack.ts'
+import { parseDecorationManifest } from './decoration.ts'
+import { imageDimensions } from './image-dimensions.ts'
+import { PET_DECORATION_API_VERSION, type DecorationView } from './contracts/status-decoration.ts'
 import { dshHome } from './dsh-home.ts'
 import { parsePetManifest, type PetManifestLive2d, type PetManifestV2, type PetRendererKind } from './manifest-v2.ts'
 import { collectModel3References } from './model3.ts'
@@ -212,6 +216,8 @@ export interface PetDefinition {
   atlasUrl: string
   /** Browser URL of the manifest (served by the host asset route). */
   manifestUrl: string
+  /** Hover-panel chrome overrides (voice.json 'panel'; pet-center M4). */
+  panel?: PetPanelView
 }
 
 /** A resolved pet plus its host-side file location. */
@@ -228,6 +234,11 @@ export interface PetEntry extends PetDefinition {
   servable: readonly string[]
   /** Normalized per-pet remark pools (manifest 'remarks'), when declared. */
   remarks?: PetRemarks
+  /**
+   * Normalized per-pet voice pack (the directory's voice.json; pet-center
+   * M4). Host-side only — the browser half receives its 'panel' slice.
+   */
+  voice?: VoicePack
 }
 
 /** Registry load result: resolved entries plus load warnings. */
@@ -239,6 +250,32 @@ export interface PetRegistry {
   byId(id: string): PetEntry | undefined
   /** The pet an installation falls back to when the selection is unknown. */
   defaultEntry(): PetEntry
+  /**
+   * The global voice override ('$DSH_HOME/pets/.voice.json'), when present —
+   * layers under every per-pet pack and over the built-in pools (M4, #677).
+   */
+  globalVoice?: VoicePack
+  /**
+   * Status decorations (pet-center M5, #567): built-in 'assets/decorations'
+   * entries overridden by same-id user entries under
+   * '$DSH_HOME/pets/decorations'. Independent of the pet entries. Optional
+   * so prebuilt test registries without decorations keep compiling.
+   */
+  decorations?: DecorationEntry[]
+  /** Look up one decoration by id. */
+  decorationById?(id: string): DecorationEntry | undefined
+}
+
+/** One resolved status decoration plus its host-side file location. */
+export interface DecorationEntry extends DecorationView {
+  /** Absolute directory holding the descriptor and strip. */
+  dir: string
+  /** Strip path relative to 'dir' (declared by the descriptor). */
+  entryPath: string
+  /** Descriptor-relative files the decoration asset route may serve. */
+  servable: readonly string[]
+  /** Asset license identifier (required by the descriptor). */
+  license: string
 }
 
 /** One structured registry diagnostic (manifest-v2 era). */
@@ -551,20 +588,23 @@ function scanPetDir(dir: string, options: { assetPrefix?: string; warnings?: str
       options.warnings?.push(diagnostic.message)
     }
     if (!verdict.ok) continue
+    let entry: PetEntry | undefined
     if (verdict.manifest.renderer === 'live2d') {
-      const entry = resolveLive2dEntry(verdict.manifest, entryDir, options)
-      if (entry !== undefined) entries.push(entry)
-      continue
+      entry = resolveLive2dEntry(verdict.manifest, entryDir, options)
+    } else {
+      const legacy = flattenV2Sprite2d(verdict.manifest)
+      if (legacy === undefined) {
+        const note = 'pet ' + verdict.manifest.id + ': sprite2d.atlasRows only supports 9 or 11 under the v1 compat resolver'
+        options.diagnostics?.push({ level: 'error', source: entryDir, message: note })
+        options.warnings?.push(note)
+        continue
+      }
+      entry = resolvePetManifest(legacy, entryDir, options)
     }
-    const legacy = flattenV2Sprite2d(verdict.manifest)
-    if (legacy === undefined) {
-      const note = 'pet ' + verdict.manifest.id + ': sprite2d.atlasRows only supports 9 or 11 under the v1 compat resolver'
-      options.diagnostics?.push({ level: 'error', source: entryDir, message: note })
-      options.warnings?.push(note)
-      continue
-    }
-    const entry = resolvePetManifest(legacy, entryDir, options)
-    if (entry !== undefined) entries.push(entry)
+    if (entry === undefined) continue
+    // Optional voice pack (voice.json) — pure content, warn-and-drop (M4).
+    const voice = loadVoicePackFile(join(entryDir, 'voice.json'), options)
+    entries.push({ ...entry, ...(voice === undefined ? {} : { voice }) })
   }
   return entries
 }
@@ -579,6 +619,176 @@ function readPetJson(file: string, warnings: string[] | undefined): unknown {
   }
 }
 
+/**
+ * Scan-time read ceiling for user-authored JSON descriptors (voice.json,
+ * .voice.json, decoration.json): the registry reads these synchronously at
+ * plugin startup, and a pathological file — multi-GB, or a FIFO/device
+ * symlink — must not hang or exhaust the host before the warn-and-drop
+ * discipline can apply (review-spd follow-up, pet-center M4/M5).
+ */
+export const PET_SCAN_JSON_CAP = 64 * 1024
+
+/**
+ * Stat one scanned JSON descriptor with a regular-file + size guard, so a
+ * pathological user file is skipped with a warning instead of stalling or
+ * OOM-ing the host at startup. Returns the Stats, or undefined when the
+ * caller must skip the file (a warning was recorded).
+ */
+function guardedScannedJsonStat(
+  file: string,
+  options: { warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] },
+  what: string,
+): ReturnType<typeof statSync> | undefined {
+  let st: ReturnType<typeof statSync>
+  try {
+    st = statSync(file)
+  } catch {
+    return undefined
+  }
+  const warn = (message: string): void => {
+    options.warnings?.push(file + ': ' + message)
+    options.diagnostics?.push({ level: 'warning', source: file, message: file + ': ' + message })
+  }
+  if (!st.isFile()) {
+    warn(what + ' is not a regular file; ignored')
+    return undefined
+  }
+  if (st.size > PET_SCAN_JSON_CAP) {
+    warn(what + ' exceeds the ' + PET_SCAN_JSON_CAP + '-byte scan ceiling; ignored')
+    return undefined
+  }
+  return st
+}
+
+/**
+ * Load and normalize one optional voice.json (pet-center M4). A missing
+ * file is silent; a broken file warns and drops. The pack is pure content,
+ * so every issue stays a warning — a bad voice.json never rejects a pet.
+ */
+function loadVoicePackFile(
+  file: string,
+  options: { warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] },
+): VoicePack | undefined {
+  if (!existsSync(file)) return undefined
+  if (guardedScannedJsonStat(file, options, 'voice pack') === undefined) return undefined
+  const warn = (message: string): void => {
+    options.warnings?.push(file + ': ' + message)
+    options.diagnostics?.push({ level: 'warning', source: file, message: file + ': ' + message })
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(file, 'utf8'))
+  } catch (error) {
+    warn('voice pack is not valid JSON; ignored: ' + (error instanceof Error ? error.message : String(error)))
+    return undefined
+  }
+  return normalizeVoicePack(raw, warn)
+}
+
+/** Decoration asset URL prefix (served by the decoration route, M5). */
+export const DECORATION_ASSET_PREFIX = '/api/pet/decoration'
+
+/** Read the pixel dimensions of a decoration strip (PNG/WebP), if decodable. */
+function readImageDimensions(file: string): { width: number; height: number } | undefined {
+  let header: Buffer
+  try {
+    // Only the header is needed for dimensions; cap the read so a huge or
+    // corrupt strip cannot balloon memory during the registry scan.
+    const fd = openSync(file, 'r')
+    try {
+      header = Buffer.alloc(64)
+      const read = readSync(fd, header, 0, header.length, 0)
+      if (read < 0) return undefined
+      header = header.subarray(0, read)
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return undefined
+  }
+  return imageDimensions(header)
+}
+
+/**
+ * Scan one directory of decoration folders ('decoration.json' + strip).
+ * Later scans override earlier ones on id collision; a bad descriptor warns
+ * and skips — the never-throw philosophy holds for decorations too (M5).
+ */
+function scanDecorationDir(dir: string, options: { warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] }): DecorationEntry[] {
+  if (!existsSync(dir)) return []
+  let names: string[] = []
+  try {
+    names = readdirSync(dir).filter(name => !name.startsWith('.'))
+  } catch {
+    return []
+  }
+  names.sort()
+  const entries: DecorationEntry[] = []
+  for (const name of names) {
+    const entryDir = join(dir, name)
+    const manifestFile = join(entryDir, 'decoration.json')
+    if (!existsSync(manifestFile)) continue
+    if (guardedScannedJsonStat(manifestFile, options, 'decoration descriptor') === undefined) continue
+    let raw: unknown
+    try {
+      raw = JSON.parse(readFileSync(manifestFile, 'utf8'))
+    } catch (error) {
+      const message = 'skipping ' + manifestFile + ': ' + (error instanceof Error ? error.message : String(error))
+      options.warnings?.push(message)
+      options.diagnostics?.push({ level: 'error', source: entryDir, message })
+      continue
+    }
+    const verdict = parseDecorationManifest(raw, manifestFile)
+    for (const diagnostic of verdict.diagnostics) {
+      options.diagnostics?.push({ level: diagnostic.level, source: entryDir, message: diagnostic.message })
+      options.warnings?.push(diagnostic.message)
+    }
+    if (!verdict.ok) continue
+    const manifest = verdict.manifest
+    // A missing strip keeps the entry listed (mirroring the live2d closure
+    // discipline) but earns a diagnostic: the ornament will silently render
+    // nothing, and the warning names the file to fix.
+    if (!existsSync(join(entryDir, manifest.entry))) {
+      const message = 'decoration ' + manifest.id + ': strip file missing: ' + manifest.entry
+      options.warnings?.push(message)
+      options.diagnostics?.push({ level: 'warning', source: entryDir, message })
+    } else {
+      // Geometry check: the client renders the strip as a single row of
+      // 'columns' frames (background-position advances by frame width only),
+      // so the strip must be exactly cell.width * columns wide and cell.height
+      // tall. A mismatched strip silently shows the wrong/partial frames —
+      // warn-and-keep, mirroring the missing-strip discipline (never throw).
+      const actual = readImageDimensions(join(entryDir, manifest.entry))
+      if (actual !== undefined) {
+        const expectedWidth = manifest.cell.width * manifest.columns
+        if (actual.width !== expectedWidth || actual.height !== manifest.cell.height) {
+          const message = 'decoration ' + manifest.id + ': strip ' + actual.width + 'x' + actual.height
+            + ' does not match cell ' + manifest.cell.width + 'x' + manifest.cell.height + ' x ' + manifest.columns
+            + ' columns (expected ' + expectedWidth + 'x' + manifest.cell.height + '); frames will render wrong'
+          options.warnings?.push(message)
+          options.diagnostics?.push({ level: 'warning', source: entryDir, message })
+        }
+      }
+    }
+    entries.push({
+      apiVersion: PET_DECORATION_API_VERSION,
+      id: manifest.id,
+      dir: entryDir,
+      entryPath: manifest.entry,
+      servable: ['decoration.json', manifest.entry],
+      license: manifest.license,
+      assetBase: DECORATION_ASSET_PREFIX + '/' + encodeURIComponent(manifest.id),
+      entryUrl: DECORATION_ASSET_PREFIX + '/' + encodeURIComponent(manifest.id) + '/' + manifest.entry,
+      cell: manifest.cell,
+      columns: manifest.columns,
+      durations: manifest.durations,
+      loop: manifest.loop,
+      phases: manifest.phases,
+    })
+  }
+  return entries
+}
+
 /**
  * Load the pet registry: built-in 'assets/*' first, then the hatch-pet
  * custom pets directory, then composed 'extra' manifests (each later source
@@ -611,11 +821,14 @@ export function loadPetRegistry(options: PetRegistryOptions): PetRegistry {
 
   // The pet-center user directory ranks above the legacy hatch-pet source.
   const dshPetsDir = options.dshPetsDir ?? join(dshHome(), 'pets')
+  let globalVoice: VoicePack | undefined
   if (dshPetsDir !== '') {
     for (const entry of scanPetDir(dshPetsDir, { assetPrefix, warnings, diagnostics })) {
       if (byId.has(entry.id)) warnings.push('user pet ' + entry.id + ' overrides an earlier registration')
       byId.set(entry.id, entry)
     }
+    // The global voice override layers under every per-pet pack (M4, #677).
+    globalVoice = loadVoicePackFile(join(dshPetsDir, '.voice.json'), { warnings, diagnostics })
   }
 
   for (const manifest of options.extra ?? []) {
@@ -636,18 +849,63 @@ export function loadPetRegistry(options: PetRegistryOptions): PetRegistry {
     byId.set(entry.id, entry)
   }
 
+  // Status decorations (pet-center M5, #567): built-in entries first,
+  // then same-id user entries under '$DSH_HOME/pets/decorations' override.
+  const decorationById = new Map<string, DecorationEntry>()
+  for (const entry of scanDecorationDir(join(packageRoot, 'assets', 'decorations'), { warnings, diagnostics })) {
+    decorationById.set(entry.id, entry)
+  }
+  if (dshPetsDir !== '') {
+    for (const entry of scanDecorationDir(join(dshPetsDir, 'decorations'), { warnings, diagnostics })) {
+      if (decorationById.has(entry.id)) {
+        warnings.push('user decoration ' + entry.id + ' overrides the built-in one')
+      }
+      decorationById.set(entry.id, entry)
+    }
+  }
+
   const entries = [...byId.values()]
+  const decorations = [...decorationById.values()]
   return {
     entries,
     warnings,
     diagnostics,
     byId: (id: string) => byId.get(id),
     defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0]!,
+    ...(globalVoice === undefined ? {} : { globalVoice }),
+    decorations,
+    decorationById: (id: string) => decorationById.get(id),
   }
 }
 
-/** Strip host-only fields, leaving the client-visible definition. */
-export function petEntryView(entry: PetEntry): PetDefinition {
+/** The built-in default decoration id (M5): the first reference ornament. */
+export const DEFAULT_DECORATION_ID = 'whale'
+
+/** Strip host-only fields, leaving the browser-visible decoration view. */
+export function decorationView(entry: DecorationEntry): DecorationView {
+  return {
+    apiVersion: PET_DECORATION_API_VERSION,
+    id: entry.id,
+    assetBase: entry.assetBase,
+    entryUrl: entry.entryUrl,
+    cell: entry.cell,
+    columns: entry.columns,
+    durations: entry.durations,
+    loop: entry.loop,
+    phases: entry.phases,
+  }
+}
+
+/**
+ * Strip host-only fields, leaving the client-visible definition. When the
+ * registry carries a global voice pack, its panel chrome layers under the
+ * entry's own pack (per-slot merge, pet > global), mirroring the voice-pool
+ * layering (pet-center M4, issue #677).
+ */
+export function petEntryView(entry: PetEntry, globalVoice?: VoicePack): PetDefinition {
+  const panel = globalVoice === undefined
+    ? entry.voice?.panel
+    : mergeVoicePacks(globalVoice, entry.voice)?.panel
   return {
     id: entry.id,
     displayName: entry.displayName,
@@ -662,6 +920,7 @@ export function petEntryView(entry: PetEntry): PetDefinition {
     ...(entry.sequences === undefined ? {} : { sequences: entry.sequences }),
     atlasUrl: entry.atlasUrl,
     manifestUrl: entry.manifestUrl,
+    ...(panel === undefined ? {} : { panel }),
   }
 }