@linxin666/dsh-pet 0.2.3 → 0.2.4

package/src/registry.ts

@@ -27,12 +27,15 @@
  * @module @linxin666/dsh-pet/registry
  */
 
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, 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 { 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 +215,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 +233,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 +249,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 +587,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
-    }
-    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 = 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 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 +618,138 @@ 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'
+
+/**
+ * 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 })
+    }
+    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 +782,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 +810,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 +881,7 @@ export function petEntryView(entry: PetEntry): PetDefinition {
     ...(entry.sequences === undefined ? {} : { sequences: entry.sequences }),
     atlasUrl: entry.atlasUrl,
     manifestUrl: entry.manifestUrl,
+    ...(panel === undefined ? {} : { panel }),
   }
 }
 

package/src/routes.ts

@@ -16,7 +16,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import type { PetService } from './service.ts'
 import type { PetInteraction } from './affinity.ts'
-import { petEntryView, petPackageRoot, type PetEntry, type PetRegistry } from './registry.ts'
+import { DECORATION_ASSET_PREFIX, petEntryView, petPackageRoot, type PetEntry, type PetRegistry } from './registry.ts'
 import { isLoopbackRequest } from './loopback.ts'
 import { dshHome } from './dsh-home.ts'
 
@@ -263,7 +263,7 @@ function assetHandler(registry: PetRegistry, caps: PetAssetCaps): WebRoute['hand
       file = existsSync(preview) ? preview : undefined
     }
     if (synthesized) {
-      const body = Buffer.from(JSON.stringify(petEntryView(entry), null, 2), 'utf8')
+      const body = Buffer.from(JSON.stringify(petEntryView(entry, registry.globalVoice), null, 2), 'utf8')
       res.writeHead(200, {
         'content-type': 'application/json; charset=utf-8',
         'content-length': String(body.byteLength),
@@ -427,6 +427,125 @@ function runtimeHandler(roots: { runtimeDir: string; vendorDir: string }): WebRo
   }
 }
 
+/**
+ * The decoration asset handler behind '/api/pet/decoration/<id>/<file>'
+ * (pet-center M5, #567). Serves exactly the files a decoration descriptor
+ * declares — decoration.json and the PNG/WebP strip — by exact allow-list
+ * match, with realpath containment and the same size ceilings as pet
+ * assets. Crafted '..' or '.' segments never match the normalized closure.
+ */
+function decorationHandler(registry: PetRegistry, caps: PetAssetCaps): WebRoute['handler'] {
+  return (req: IncomingMessage, res: ServerResponse): void => {
+    if (!guard(req, res)) return
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    let pathname: string
+    try {
+      pathname = new URL(req.url ?? '/', 'http://pet.local').pathname
+    } catch {
+      res.writeHead(400)
+      res.end()
+      return
+    }
+    const segments = pathname.split('/').filter(segment => segment !== '')
+    const prefixSegments = DECORATION_ASSET_PREFIX.split('/').filter(segment => segment !== '')
+    if (segments.length < prefixSegments.length + 2) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    for (let i = 0; i < prefixSegments.length; i += 1) {
+      if (segments[i] !== prefixSegments[i]) {
+        res.writeHead(404)
+        res.end()
+        return
+      }
+    }
+    let id: string
+    try {
+      id = decodeURIComponent(segments[prefixSegments.length])
+    } catch {
+      res.writeHead(400)
+      res.end()
+      return
+    }
+    const entry = registry.decorationById?.(id)
+    if (entry === undefined) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    const rest: string[] = []
+    for (const segment of segments.slice(prefixSegments.length + 1)) {
+      let decoded: string
+      try {
+        decoded = decodeURIComponent(segment)
+      } catch {
+        res.writeHead(400)
+        res.end()
+        return
+      }
+      rest.push(decoded)
+    }
+    const rel = rest.join('/')
+    if (!entry.servable.includes(rel)) {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    const file = join(entry.dir, rel)
+    const resolved = containedRealpath(entry.dir, file)
+    if (resolved === undefined) {
+      res.writeHead(403)
+      res.end()
+      return
+    }
+    const cap = rel === 'decoration.json' ? caps.manifest : caps.image
+    let stat: ReturnType<typeof statSync>
+    try {
+      stat = statSync(resolved)
+      if (stat.size > cap) {
+        res.writeHead(413)
+        res.end()
+        return
+      }
+    } catch {
+      res.writeHead(404)
+      res.end()
+      return
+    }
+    // Weak ETag from size + mtime: 'no-cache' forces revalidation, and the
+    // validator lets repeat requests settle as 304 — the ornament remounts
+    // on whisper and display-session flips, and without a validator each
+    // remount would re-download the full strip body.
+    const etag = '"' + stat.size.toString(16) + '-' + Math.round(stat.mtimeMs).toString(16) + '"'
+    if (req.headers['if-none-match'] === etag) {
+      res.writeHead(304, { etag, 'cache-control': 'no-cache' })
+      res.end()
+      return
+    }
+    readFile(resolved).then((body) => {
+      res.writeHead(200, {
+        'content-type': mimeFor(resolved),
+        'content-length': String(body.byteLength),
+        'cache-control': 'no-cache',
+        etag,
+      })
+      if (req.method === 'HEAD') {
+        res.end()
+        return
+      }
+      res.end(body)
+    }, () => {
+      res.writeHead(404)
+      res.end()
+    })
+  }
+}
+
 /** Build the full route family (API + assets + runtime) for one service. */
 export function makePetRoutes(deps: { service: PetService; assetCaps?: PetAssetCaps } & PetRuntimeRoots): WebRoute[] {
   const { service } = deps
@@ -477,7 +596,13 @@ export function makePetRoutes(deps: { service: PetService; assetCaps?: PetAssetC
     }),
   }
 
-  return [...apiRoutes, assetRoute, runtimeRoute]
+  const decorationRoute: WebRoute = {
+    kind: 'prefix',
+    path: DECORATION_ASSET_PREFIX,
+    handler: decorationHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
+  }
+
+  return [...apiRoutes, assetRoute, runtimeRoute, decorationRoute]
 }
 
 // Re-exported for the package surface (the registry owns the definition now).

package/src/service.ts

@@ -36,6 +36,8 @@ import {
   type PetDisplayConfig,
 } from './persist.ts'
 import {
+  DEFAULT_DECORATION_ID,
+  decorationView,
   loadPetRegistry,
   petEntryView,
   petPackageRoot,
@@ -44,7 +46,9 @@ import {
   type PetRegistry,
   type PetRegistryDiagnostic,
 } from './registry.ts'
-import { WHISPER_TTL_MS } from './chatter.ts'
+import { WHISPER_TTL_MS, type VoicePackOverrides, type VoicePoolsProvider } from './chatter.ts'
+import { mergeVoicePacks } from './voice-pack.ts'
+import type { DecorationView } from './contracts/status-decoration.ts'
 import {
   defaultPetStateConfig,
   PetStateMachine,
@@ -65,6 +69,8 @@ export interface PetConfig {
   persistDir?: string
   /** Master switch for the plugin (browser half + host routes). */
   enabled?: boolean
+  /** Status-decoration master switch (pet-center M5, #567); defaults to on. */
+  decorationEnabled?: boolean
   /** Prebuilt registry (tests); defaults to scanning the package + user dirs. */
   registry?: PetRegistry
   /** Extra manifest entries composed by the embedding application. */
@@ -91,6 +97,11 @@ export interface PetSettingsSection {
   bottom: number
   /** Master switch for the plugin (browser half + host routes). */
   enabled?: boolean
+  /**
+   * Status-decoration master switch (pet-center M5, #567). Defaults to on;
+   * the settings surface mirrors this field and can turn it off.
+   */
+  decorationEnabled?: boolean
 }
 
 /** Settings namespace of the pet capability. Spelled here rather than imported: the browser half spells the same value. */
@@ -159,6 +170,12 @@ export interface PetStateView {
    * rendered by the client as a distinct whisper bubble.
    */
   whisper?: string
+  /**
+   * The active status decoration (pet-center M5, #567), when the master
+   * switch is on and the default decoration entry exists. Absent means the
+   * browser half renders no ornament.
+   */
+  decoration?: DecorationView
 }
 
 /** Result of `pet.interact`. */
@@ -200,9 +217,17 @@ export class PetService extends Service {
   private readonly registry: PetRegistry
   private readonly persistDir: string
   private enabled: boolean
+  /** Status-decoration master switch (M5, #567); mirrored from settings. */
+  private decorationEnabled: boolean
   private disposeActivity: (() => void) | undefined
   /** Session whose most recent meaningful event currently drives the global pet. */
   private displaySession: Session | undefined
+  /**
+   * Effective voice-pack overrides for the currently selected pet (M4,
+   * #677). Cached per pet id; the registry is an immutable snapshot, so the
+   * global pack and each entry's pack cannot change behind the cache.
+   */
+  private voiceCache: { petId: string; overrides: VoicePackOverrides } | undefined
   /**
    * Per-session activity, most recent last (Map insertion order). Bounded by
    * MAX_SESSION_BUBBLES so a burst of sessions cannot grow it without bound;
@@ -237,10 +262,28 @@ export class PetService extends Service {
     this.stateConfig = { ...defaultPetStateConfig, ...(config.state ?? {}) }
     this.machine = new PetStateMachine(this.stateConfig)
     this.enabled = config.enabled ?? true
+    this.decorationEnabled = config.decorationEnabled ?? true
 
     this.syncActivity()
   }
 
+  /**
+   * The draw-time voice-pool provider handed to every projection runtime.
+   * It re-resolves when the selected pet changes, so live engines re-voice
+   * on the next draw without being rebuilt (M4, #677).
+   */
+  private voicePools(): VoicePoolsProvider {
+    return () => {
+      const entry = this.activeEntry()
+      if (this.voiceCache !== undefined && this.voiceCache.petId === entry.id) {
+        return this.voiceCache.overrides
+      }
+      const overrides = mergeVoicePacks(this.registry.globalVoice, entry.voice)?.overrides ?? {}
+      this.voiceCache = { petId: entry.id, overrides }
+      return overrides
+    }
+  }
+
   /** Whether the pet service consumes session activity while enabled. */
   isEnabled(): boolean {
     return this.enabled
@@ -258,7 +301,7 @@ export class PetService extends Service {
 
   /** RPC: the registry entries the browser half renders and selects from. */
   async pets(): Promise<PetDefinition[]> {
-    return this.registry.entries.map(petEntryView)
+    return this.registry.entries.map(entry => petEntryView(entry, this.registry.globalVoice))
   }
 
   /** The loaded registry (the asset routes serve its entries). */
@@ -271,6 +314,16 @@ export class PetService extends Service {
     return { diagnostics: this.registry.diagnostics }
   }
 
+  /**
+   * The active status decoration view (M5, #567): the default 'whale' entry
+   * (user directories override built-ins by id), gated by the master switch.
+   */
+  private activeDecoration(): DecorationView | undefined {
+    if (!this.decorationEnabled) return undefined
+    const entry = this.registry.decorationById?.(DEFAULT_DECORATION_ID)
+    return entry === undefined ? undefined : decorationView(entry)
+  }
+
   /** The selected pet's registry entry. */
   activeEntry(): NonNullable<PetRegistry['entries'][number]> {
     return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry()
@@ -370,7 +423,7 @@ export class PetService extends Service {
     let activity = this.sessionActivity.get(session)
     if (activity === undefined) {
       activity = {
-        runtime: emptyProjectionRuntime(),
+        runtime: emptyProjectionRuntime(this.voicePools()),
         machine: new PetStateMachine(this.stateConfig),
       }
       this.sessionActivity.set(session, activity)
@@ -449,6 +502,7 @@ export class PetService extends Service {
    * @param section - the resolved settings section.
    */
   applySettingsSection(section: PetSettingsSection): void {
+    this.decorationEnabled = section.decorationEnabled ?? true
     const selected = typeof section.petId === 'string' ? this.registry.byId(section.petId) : undefined
     if (selected !== undefined) {
       this.ledger.setPetId(selected.id)
@@ -524,6 +578,7 @@ export class PetService extends Service {
     const freshWhisper = whisper !== undefined && Date.now() - whisper.at < WHISPER_TTL_MS
       ? whisper.text
       : undefined
+    const decoration = this.activeDecoration()
     // Read-only: the ledger settles on economic events only, never on a read,
     // so polling the state cannot trigger pet.json writes.
     return {
@@ -533,6 +588,7 @@ export class PetService extends Service {
       sessionActive: snapshot.sessionActive,
       sessions,
       ...(freshWhisper === undefined ? {} : { whisper: freshWhisper }),
+      ...(decoration === undefined ? {} : { decoration }),
       affinity: this.ledger.affinityView(Date.now()),
       display: { ...this.ledger.snapshot.display },
       pet: {