@linxin666/dsh-pet 0.2.3 → 0.2.4

package/lib/types/registry.js

@@ -26,11 +26,14 @@
  * whale-girl manifest overrides its own durations.
  * @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 { normalizePetRemarks } from './remarks.js';
+import { mergeVoicePacks, normalizeVoicePack } from './voice-pack.js';
+import { parseDecorationManifest } from './decoration.js';
+import { PET_DECORATION_API_VERSION } from './contracts/status-decoration.js';
 import { dshHome } from './dsh-home.js';
 import { parsePetManifest } from './manifest-v2.js';
 import { collectModel3References } from './model3.js';
@@ -376,22 +379,25 @@ function scanPetDir(dir, options) {
         }
         if (!verdict.ok)
             continue;
+        let entry;
         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);
         }
-        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;
+        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;
 }
@@ -405,6 +411,136 @@ function readPetJson(file, warnings) {
         return undefined;
     }
 }
+/**
+ * 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, options, what) {
+    let st;
+    try {
+        st = statSync(file);
+    }
+    catch {
+        return undefined;
+    }
+    const warn = (message) => {
+        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, options) {
+    if (!existsSync(file))
+        return undefined;
+    if (guardedScannedJsonStat(file, options, 'voice pack') === undefined)
+        return undefined;
+    const warn = (message) => {
+        options.warnings?.push(file + ': ' + message);
+        options.diagnostics?.push({ level: 'warning', source: file, message: file + ': ' + message });
+    };
+    let raw;
+    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, options) {
+    if (!existsSync(dir))
+        return [];
+    let names = [];
+    try {
+        names = readdirSync(dir).filter(name => !name.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    names.sort();
+    const entries = [];
+    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;
+        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
@@ -435,12 +571,15 @@ export function loadPetRegistry(options) {
     }
     // The pet-center user directory ranks above the legacy hatch-pet source.
     const dshPetsDir = options.dshPetsDir ?? join(dshHome(), 'pets');
+    let globalVoice;
     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 ?? []) {
         const raw = manifest.spritesheetPath;
@@ -461,17 +600,59 @@ export function loadPetRegistry(options) {
             warnings.push('composed pet ' + entry.id + ' overrides an earlier registration');
         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();
+    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) => byId.get(id),
         defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0],
+        ...(globalVoice === undefined ? {} : { globalVoice }),
+        decorations,
+        decorationById: (id) => decorationById.get(id),
     };
 }
-/** Strip host-only fields, leaving the client-visible definition. */
-export function petEntryView(entry) {
+/** 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) {
+    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, globalVoice) {
+    const panel = globalVoice === undefined
+        ? entry.voice?.panel
+        : mergeVoicePacks(globalVoice, entry.voice)?.panel;
     return {
         id: entry.id,
         displayName: entry.displayName,
@@ -486,6 +667,7 @@ export function petEntryView(entry) {
         ...(entry.sequences === undefined ? {} : { sequences: entry.sequences }),
         atlasUrl: entry.atlasUrl,
         manifestUrl: entry.manifestUrl,
+        ...(panel === undefined ? {} : { panel }),
     };
 }
 /** The absolute file a pet's atlas resolves to (host asset route). */

package/lib/types/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAM9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAMtC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,yBAAyB;aACzB,QAAQ;IACR,iDAAiD;aACjD,KAAK;IACL,8EAA8E;aAC9E,KAAK;CACG,CAAA;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrF;AAsPD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAA8B,CAAA;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAmB,CAAA;AAE/C,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAiFD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAkDnH;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAM9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAMtC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,yBAAyB;aACzB,QAAQ;IACR,iDAAiD;aACjD,KAAK;IACL,8EAA8E;aAC9E,KAAK;CACG,CAAA;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrF;AAsPD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAA8B,CAAA;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAmB,CAAA;AAE/C,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwMD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAwDnH;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}

package/lib/types/routes.js

@@ -11,7 +11,7 @@
 import { existsSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
-import { petEntryView, petPackageRoot } from './registry.js';
+import { DECORATION_ASSET_PREFIX, petEntryView, petPackageRoot } from './registry.js';
 import { isLoopbackRequest } from './loopback.js';
 import { dshHome } from './dsh-home.js';
 /** Browser-facing base path of the pet API. */
@@ -248,7 +248,7 @@ function assetHandler(registry, caps) {
             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),
@@ -404,6 +404,129 @@ function runtimeHandler(roots) {
         });
     };
 }
+/**
+ * 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, caps) {
+    return (req, res) => {
+        if (!guard(req, res))
+            return;
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405);
+            res.end();
+            return;
+        }
+        let pathname;
+        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;
+        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 = [];
+        for (const segment of segments.slice(prefixSegments.length + 1)) {
+            let decoded;
+            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;
+        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) {
     const { service } = deps;
@@ -455,7 +578,12 @@ export function makePetRoutes(deps) {
             vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), 'lib'),
         }),
     };
-    return [...apiRoutes, assetRoute, runtimeRoute];
+    const decorationRoute = {
+        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).
 export { petPackageRoot } from './registry.js';

package/lib/types/service.d.ts

@@ -17,6 +17,7 @@ import type { TreatConfig } from './treats.ts';
 import { type LedgerInteractionResult } from './ledger.ts';
 import { type PetDisplayConfig } from './persist.ts';
 import { type PetDefinition, type PetManifest, type PetRegistry, type PetRegistryDiagnostic } from './registry.ts';
+import type { DecorationView } from './contracts/status-decoration.ts';
 import { type PetStateConfig, type PetStateSnapshot } from './state.ts';
 /** Plugin configuration. */
 export interface PetConfig {
@@ -30,6 +31,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. */
@@ -55,6 +58,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. */
 export declare const PET_SETTINGS_NAMESPACE = "pet";
@@ -119,6 +127,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`. */
 export type PetInteractResult = LedgerInteractionResult;
@@ -141,9 +155,17 @@ export declare class PetService extends Service {
     private readonly registry;
     private readonly persistDir;
     private enabled;
+    /** Status-decoration master switch (M5, #567); mirrored from settings. */
+    private decorationEnabled;
     private disposeActivity;
     /** Session whose most recent meaningful event currently drives the global pet. */
     private displaySession;
+    /**
+     * 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;
     /**
      * Per-session activity, most recent last (Map insertion order). Bounded by
      * MAX_SESSION_BUBBLES so a burst of sessions cannot grow it without bound;
@@ -151,6 +173,12 @@ export declare class PetService extends Service {
      */
     private readonly sessionActivity;
     constructor(ctx: Context, config?: PetConfig);
+    /**
+     * 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;
     /** Whether the pet service consumes session activity while enabled. */
     isEnabled(): boolean;
     /** RPC: current pet state snapshot. */
@@ -165,6 +193,11 @@ export declare class PetService extends Service {
     diagnostics(): Promise<{
         diagnostics: PetRegistryDiagnostic[];
     }>;
+    /**
+     * 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;
     /** The selected pet's registry entry. */
     activeEntry(): NonNullable<PetRegistry['entries'][number]>;
     /** Currently selected pet id (persisted). */

package/lib/types/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}

package/lib/types/service.js

@@ -15,8 +15,9 @@ import { Service } from '@deepseek-ai/cordis';
 import { emptyProjectionRuntime, isActivityPhase, projectOfficialEvent, } from './event-projection.js';
 import { PetLedger } from './ledger.js';
 import { DEFAULT_PET_NAME, DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN, PET_NAME_MAX_LENGTH, loadPetPersist, petHomeDir, savePetPersist, } from './persist.js';
-import { loadPetRegistry, petEntryView, petPackageRoot, } from './registry.js';
+import { DEFAULT_DECORATION_ID, decorationView, loadPetRegistry, petEntryView, petPackageRoot, } from './registry.js';
 import { WHISPER_TTL_MS } from './chatter.js';
+import { mergeVoicePacks } from './voice-pack.js';
 import { defaultPetStateConfig, PetStateMachine, } from './state.js';
 /** Settings namespace of the pet capability. Spelled here rather than imported: the browser half spells the same value. */
 export const PET_SETTINGS_NAMESPACE = 'pet';
@@ -36,9 +37,17 @@ export class PetService extends Service {
     registry;
     persistDir;
     enabled;
+    /** Status-decoration master switch (M5, #567); mirrored from settings. */
+    decorationEnabled;
     disposeActivity;
     /** Session whose most recent meaningful event currently drives the global pet. */
     displaySession;
+    /**
+     * 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.
+     */
+    voiceCache;
     /**
      * Per-session activity, most recent last (Map insertion order). Bounded by
      * MAX_SESSION_BUBBLES so a burst of sessions cannot grow it without bound;
@@ -72,8 +81,25 @@ 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).
+     */
+    voicePools() {
+        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() {
         return this.enabled;
@@ -88,7 +114,7 @@ export class PetService extends Service {
     }
     /** RPC: the registry entries the browser half renders and selects from. */
     async pets() {
-        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). */
     registrySnapshot() {
@@ -98,6 +124,16 @@ export class PetService extends Service {
     async diagnostics() {
         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.
+     */
+    activeDecoration() {
+        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() {
         return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry();
@@ -199,7 +235,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);
@@ -277,6 +313,7 @@ export class PetService extends Service {
      * @param section - the resolved settings section.
      */
     applySettingsSection(section) {
+        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);
@@ -355,6 +392,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 {
@@ -364,6 +402,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: {