@linxin666/dsh-pet 0.2.3 → 0.2.4

package/lib/index.js

@@ -145,6 +145,40 @@ const STATUS_POOLS = {
 		"蹲一个继续的指令"
 	]
 };
+/** Every status scene key, in declaration order (voice-pack key allow-list). */
+const STATUS_SCENES = [
+	"prepare",
+	"waiting",
+	"thinking",
+	"review",
+	"toolResult",
+	"done",
+	"failed",
+	"toolFailed",
+	"maxTokens",
+	"interrupted",
+	"blocked"
+];
+/** Every tool-family key, in declaration order (voice-pack key allow-list). */
+const TOOL_CATEGORIES = [
+	"read",
+	"write",
+	"edit",
+	"shell",
+	"grep",
+	"find",
+	"ls",
+	"webSearch",
+	"webFetch",
+	"mcp",
+	"memory",
+	"subagent",
+	"todo",
+	"browser",
+	"git",
+	"ask",
+	"generic"
+];
 /** Map a raw tool name onto its copy family (working-activity style regexes). */
 function toolCategory(toolName) {
 	const name = toolName.toLowerCase();
@@ -420,12 +454,14 @@ function toolArgHint(toolName, argumentsJson) {
 * stretch keeps changing its wording.
 */
 var StatusVoice = class {
+	pools;
 	rotateMs;
 	counters = /* @__PURE__ */ new Map();
 	lastScene = "";
 	lastLine = "";
 	lastLineAt = Number.NEGATIVE_INFINITY;
-	constructor(rotateMs = STATUS_ROTATE_MS) {
+	constructor(pools = () => BUILTIN_VOICE_PACK, rotateMs = STATUS_ROTATE_MS) {
+		this.pools = pools;
 		this.rotateMs = rotateMs;
 	}
 	/** Draw the next line of one pool, advancing its round-robin cursor. */
@@ -442,18 +478,31 @@ var StatusVoice = class {
 		this.lastLineAt = nowMs;
 		return this.lastLine;
 	}
+	/**
+	* A scene's effective pool: the voice-pack override when it carries lines,
+	* else the built-in pool. Empty overrides fall back rather than blank the
+	* bubble — a scene line always renders.
+	*/
+	scenePool(scene) {
+		const override = this.pools().status?.[scene];
+		return override !== void 0 && override.length > 0 ? override : STATUS_POOLS[scene];
+	}
 	/** Status line for a phase scene. */
 	scene(scene, nowMs) {
-		return this.voice("scene:" + scene, "pool:" + scene, STATUS_POOLS[scene], nowMs);
+		return this.voice("scene:" + scene, "pool:" + scene, this.scenePool(scene), nowMs);
 	}
 	/** Status line for a tool call, with the real-argument hint when known. */
 	tool(toolName, displayName, hint, nowMs) {
 		const category = toolCategory(toolName);
-		return this.voice("tool:" + category, "tool:" + category, TOOL_POOLS[category], nowMs).replace("{tool}", displayName).replace("{hint}", hint ?? displayName);
+		const override = this.pools().tools?.[category];
+		const pool = override !== void 0 && override.length > 0 ? override : TOOL_POOLS[category];
+		return this.voice("tool:" + category, "tool:" + category, pool, nowMs).replaceAll("{tool}", displayName).replaceAll("{hint}", hint ?? displayName);
 	}
 	/** Status line while sibling tools still run (always reflects the count). */
 	toolRemaining(count, nowMs) {
-		return this.voice("toolRemaining", "toolRemaining", TOOL_REMAINING_POOL, nowMs).replace("{n}", String(count));
+		const override = this.pools().toolRemaining;
+		const pool = override !== void 0 && override.length > 0 ? override : TOOL_REMAINING_POOL;
+		return this.voice("toolRemaining", "toolRemaining", pool, nowMs).replaceAll("{n}", String(count));
 	}
 };
 /** Murmur pacing: cooldown between whispers and output volume that earns one. */
@@ -786,26 +835,52 @@ const WHISPER_RULES = [
 		]
 	}
 ];
+/** The built-in voice pack: the plugin's default copy, unchanged since v1. */
+const BUILTIN_VOICE_PACK = {
+	status: STATUS_POOLS,
+	tools: TOOL_POOLS,
+	toolRemaining: TOOL_REMAINING_POOL,
+	whispers: {
+		generic: WHISPER_GENERIC_POOL,
+		rules: WHISPER_RULES
+	}
+};
 /**
 * The murmur engine (碎碎念): watches the model's own output and lets the pet
 * whisper its inner voice. Two ways to earn a whisper:
 *  - a keyword rule matches the fresh chunk text (themed whisper);
 *  - enough output volume flowed by without one (ambient whisper).
 * A cooldown keeps whispers occasional; all picks are round-robin so tests
-* reproduce exact lines.
+* reproduce exact lines. The voice-pack provider (pet-center M4) swaps the
+* pools at draw time, so a pet switch re-voices live engines in place.
 */
 var WhisperEngine = class {
+	pools;
 	cooldownMs;
 	charBudget;
 	counters = /* @__PURE__ */ new Map();
 	genericCursor = 0;
 	lastWhisperAt = Number.NEGATIVE_INFINITY;
 	charsSinceWhisper = 0;
-	constructor(cooldownMs = WHISPER_COOLDOWN_MS, charBudget = 420) {
+	constructor(pools = () => BUILTIN_VOICE_PACK, cooldownMs = WHISPER_COOLDOWN_MS, charBudget = 420) {
+		this.pools = pools;
 		this.cooldownMs = cooldownMs;
 		this.charBudget = charBudget;
 	}
 	/**
+	* Effective keyword rules: an override replaces the built-in rules as a
+	* whole; an explicit empty array disables keyword-triggered whispers.
+	*/
+	rules() {
+		const override = this.pools().whispers?.rules;
+		return override === void 0 ? WHISPER_RULES : override;
+	}
+	/** Effective ambient pool (an explicit empty array mutes ambient whispers). */
+	generic() {
+		const override = this.pools().whispers?.generic;
+		return override === void 0 ? WHISPER_GENERIC_POOL : override;
+	}
+	/**
 	* Feed one model-output chunk (reasoning or text). Returns the whisper to
 	* show, or undefined when the moment stays quiet.
 	*/
@@ -816,8 +891,9 @@ var WhisperEngine = class {
 			return;
 		}
 		const haystack = text.toLowerCase();
-		for (let ruleIndex = 0; ruleIndex < WHISPER_RULES.length; ruleIndex += 1) {
-			const rule = WHISPER_RULES[ruleIndex];
+		const rules = this.rules();
+		for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex += 1) {
+			const rule = rules[ruleIndex];
 			if (!rule.keywords.some((keyword) => haystack.includes(keyword))) continue;
 			const index = (this.counters.get(ruleIndex) ?? 0) % rule.pool.length;
 			this.counters.set(ruleIndex, index + 1);
@@ -825,7 +901,9 @@ var WhisperEngine = class {
 		}
 		this.charsSinceWhisper += text.length;
 		if (this.charsSinceWhisper < this.charBudget) return void 0;
-		const line = WHISPER_GENERIC_POOL[this.genericCursor % WHISPER_GENERIC_POOL.length];
+		const generic = this.generic();
+		if (generic.length === 0) return void 0;
+		const line = generic[this.genericCursor % generic.length];
 		this.genericCursor += 1;
 		return this.speak(line, nowMs);
 	}
@@ -837,14 +915,19 @@ var WhisperEngine = class {
 };
 //#endregion
 //#region src/event-projection.ts
-/** Fresh projection runtime for a newly seen session. */
-function emptyProjectionRuntime() {
+/**
+* Fresh projection runtime for a newly seen session. The optional voice-pack
+* provider (pet-center M4, issue #677) hands both chatter engines their
+* pools; engines resolve overrides at draw time, so swapping the provider's
+* pack re-voices live runtimes without rebuilding them.
+*/
+function emptyProjectionRuntime(pools) {
 	return {
 		activeTools: /* @__PURE__ */ new Set(),
 		officialEventsSeen: false,
 		stepHadFailure: false,
-		voice: new StatusVoice(),
-		whispers: new WhisperEngine()
+		voice: new StatusVoice(pools),
+		whispers: new WhisperEngine(pools)
 	};
 }
 /** Keep tool names readable inside the compact status bubble. */
@@ -1373,6 +1456,307 @@ function savePetPersist(data, dir = petHomeDir()) {
 	writeFileSync(tmp, JSON.stringify(data, null, 2), "utf8");
 	renameSync(tmp, target);
 }
+/** Hover-panel action buttons a pack can show or hide (canonical order). */
+const PANEL_ACTIONS = [
+	"feed",
+	"rename",
+	"hide"
+];
+/** Panel label slots (unset slots keep the client's i18n dictionary copy). */
+const PANEL_LABEL_KEYS = [
+	"feed",
+	"rename",
+	"hide",
+	"confirm"
+];
+/** Panel stat slots ({rank}/{n}/{points} interpolate the live values). */
+const PANEL_STAT_KEYS = [
+	"rank",
+	"treats",
+	"points"
+];
+/** Any '{token}' placeholder (no nesting, no newlines). */
+const PLACEHOLDER_PATTERN = /{[^{}]*}/g;
+/** Allowed placeholder tokens per pool kind (absent kind = none allowed). */
+const PLACEHOLDER_WHITELIST = {
+	tools: ["{tool}", "{hint}"],
+	toolRemaining: ["{n}"],
+	stat: [
+		"{rank}",
+		"{n}",
+		"{points}"
+	]
+};
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Trim, length-cap and placeholder-check one copy line; undefined to drop. */
+function normalizeLine(raw, kind, onWarning) {
+	const trimmed = raw.trim();
+	if (trimmed === "") return void 0;
+	let capped = trimmed.length > 160 ? trimmed.slice(0, 160) : trimmed;
+	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 void 0;
+	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;
+	}
+	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).
+*/
+function normalizePool(raw, kind, onWarning = () => {}) {
+	if (raw === void 0) return void 0;
+	const entries = typeof raw === "string" ? [raw] : Array.isArray(raw) ? raw : void 0;
+	if (entries === void 0) {
+		onWarning("pool must be a string or an array of strings");
+		return;
+	}
+	if (entries.length > 64) onWarning("pool has more than 64 lines; extra lines are ignored");
+	const pool = [];
+	for (const entry of entries.slice(0, 64)) {
+		if (typeof entry !== "string") {
+			onWarning("non-string pool entry dropped");
+			continue;
+		}
+		const line = normalizeLine(entry, kind, onWarning);
+		if (line !== void 0) pool.push(line);
+	}
+	return pool;
+}
+/** Normalize the ordered keyword-rule list ([] disables the keyword channel). */
+function normalizeWhisperRules(raw, onWarning = () => {}) {
+	if (raw === void 0) return void 0;
+	if (!Array.isArray(raw)) {
+		onWarning("whispers.rules must be an array");
+		return;
+	}
+	if (raw.length > 32) onWarning("whispers.rules has more than 32 rules; extra rules are ignored");
+	const rules = [];
+	for (const item of raw.slice(0, 32)) {
+		if (!isRecord$2(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 = item.keywords;
+		const keywords = [];
+		if (Array.isArray(keywordsRaw)) {
+			for (const entry of keywordsRaw.slice(0, 16)) {
+				if (typeof entry !== "string") {
+					onWarning("non-string keyword dropped");
+					continue;
+				}
+				const trimmed = entry.trim().toLowerCase().slice(0, 40);
+				if (trimmed !== "") keywords.push(trimmed);
+			}
+			if (keywordsRaw.length > 16) onWarning("rule has more than 16 keywords; extra keywords are ignored");
+		}
+		const pool = normalizePool(item.pool, "whisperRule", onWarning);
+		if (keywords.length === 0 || pool === void 0 || 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). */
+function normalizePanel(raw, onWarning = () => {}) {
+	if (!isRecord$2(raw)) {
+		onWarning("panel must be an object");
+		return;
+	}
+	const panel = {};
+	const labelsRaw = raw.labels;
+	if (labelsRaw !== void 0) if (!isRecord$2(labelsRaw)) onWarning("panel.labels must be an object");
+	else {
+		const labels = {};
+		for (const key of PANEL_LABEL_KEYS) {
+			const value = labelsRaw[key];
+			if (value === void 0) continue;
+			if (typeof value !== "string") {
+				onWarning("panel.labels." + key + " must be a string");
+				continue;
+			}
+			const line = normalizeLine(value, "label", onWarning);
+			if (line !== void 0) labels[key] = line.slice(0, 40);
+		}
+		if (Object.keys(labels).length > 0) panel.labels = labels;
+	}
+	const statsRaw = raw.stats;
+	if (statsRaw !== void 0) if (!isRecord$2(statsRaw)) onWarning("panel.stats must be an object");
+	else {
+		const stats = {};
+		for (const key of PANEL_STAT_KEYS) {
+			const value = statsRaw[key];
+			if (value === void 0) continue;
+			if (typeof value !== "string") {
+				onWarning("panel.stats." + key + " must be a string");
+				continue;
+			}
+			const line = normalizeLine(value, "stat", onWarning);
+			if (line !== void 0) stats[key] = line.slice(0, 80);
+		}
+		if (Object.keys(stats).length > 0) panel.stats = stats;
+	}
+	const actionsRaw = raw.actions;
+	if (actionsRaw !== void 0) if (!Array.isArray(actionsRaw)) onWarning("panel.actions must be an array");
+	else {
+		const seen = /* @__PURE__ */ new Set();
+		for (const entry of actionsRaw) {
+			if (typeof entry !== "string" || !PANEL_ACTIONS.includes(entry)) {
+				onWarning("unknown panel action dropped: " + String(entry));
+				continue;
+			}
+			seen.add(entry);
+		}
+		panel.actions = PANEL_ACTIONS.filter((action) => seen.has(action));
+	}
+	if (panel.labels === void 0 && panel.stats === void 0 && panel.actions === void 0) return void 0;
+	return panel;
+}
+/** Voice-pack top-level fields ('$schema' mirrors the schema twin; drift-locked in tests). */
+const VOICE_PACK_KEYS = /* @__PURE__ */ new Set([
+	"$schema",
+	"voicePackVersion",
+	"status",
+	"tools",
+	"toolRemaining",
+	"whispers",
+	"panel"
+]);
+/** Allowed whisper-section fields (drift-locked in tests). */
+const WHISPER_KEYS = /* @__PURE__ */ 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.
+*/
+function normalizeVoicePack(raw, onWarning = () => {}) {
+	if (raw === void 0) return void 0;
+	if (!isRecord$2(raw)) {
+		onWarning("voice.json must be a JSON object; the file is ignored");
+		return;
+	}
+	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 !== void 0 && (typeof version !== "number" || version !== 1)) onWarning("voicePackVersion " + String(version) + " is not supported; reading as v1 best-effort");
+	const overrides = {};
+	const statusRaw = raw.status;
+	if (statusRaw !== void 0) if (!isRecord$2(statusRaw)) onWarning("status must be an object");
+	else for (const key of Object.keys(statusRaw)) {
+		if (!STATUS_SCENES.includes(key)) {
+			onWarning("unknown status scene " + key + " ignored");
+			continue;
+		}
+		const pool = normalizePool(statusRaw[key], "status", onWarning);
+		if (pool !== void 0 && pool.length > 0) overrides.status = {
+			...overrides.status,
+			[key]: pool
+		};
+	}
+	const toolsRaw = raw.tools;
+	if (toolsRaw !== void 0) if (!isRecord$2(toolsRaw)) onWarning("tools must be an object");
+	else for (const key of Object.keys(toolsRaw)) {
+		if (!TOOL_CATEGORIES.includes(key)) {
+			onWarning("unknown tool family " + key + " ignored");
+			continue;
+		}
+		const pool = normalizePool(toolsRaw[key], "tools", onWarning);
+		if (pool !== void 0 && pool.length > 0) overrides.tools = {
+			...overrides.tools,
+			[key]: pool
+		};
+	}
+	const remainingRaw = raw.toolRemaining;
+	if (remainingRaw !== void 0) {
+		const pool = normalizePool(remainingRaw, "toolRemaining", onWarning);
+		if (pool !== void 0 && pool.length > 0) overrides.toolRemaining = pool;
+	}
+	const whispersRaw = raw.whispers;
+	if (whispersRaw !== void 0) if (!isRecord$2(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 !== void 0 || rules !== void 0) overrides.whispers = {
+			...generic === void 0 ? {} : { generic },
+			...rules === void 0 ? {} : { rules }
+		};
+	}
+	const panel = raw.panel === void 0 ? void 0 : normalizePanel(raw.panel, onWarning);
+	if (overrides.status === void 0 && overrides.tools === void 0 && overrides.toolRemaining === void 0 && overrides.whispers === void 0 && panel === void 0) return;
+	return {
+		overrides,
+		...panel === void 0 ? {} : { 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).
+*/
+function mergeVoicePacks(...layers) {
+	const overrides = {};
+	const labels = {};
+	const stats = {};
+	let actions;
+	let panelSeen = false;
+	let any = false;
+	for (const layer of layers) {
+		if (layer === void 0) continue;
+		any = true;
+		if (layer.overrides.status !== void 0) overrides.status = {
+			...overrides.status,
+			...layer.overrides.status
+		};
+		if (layer.overrides.tools !== void 0) overrides.tools = {
+			...overrides.tools,
+			...layer.overrides.tools
+		};
+		if (layer.overrides.toolRemaining !== void 0) overrides.toolRemaining = layer.overrides.toolRemaining;
+		if (layer.overrides.whispers !== void 0) overrides.whispers = {
+			...overrides.whispers,
+			...layer.overrides.whispers
+		};
+		if (layer.panel !== void 0) {
+			panelSeen = true;
+			if (layer.panel.labels !== void 0) Object.assign(labels, layer.panel.labels);
+			if (layer.panel.stats !== void 0) Object.assign(stats, layer.panel.stats);
+			if (layer.panel.actions !== void 0) actions = layer.panel.actions;
+		}
+	}
+	if (!any) return void 0;
+	const panel = {
+		...Object.keys(labels).length > 0 ? { labels } : {},
+		...Object.keys(stats).length > 0 ? { stats } : {},
+		...actions === void 0 ? {} : { actions }
+	};
+	const panelEmpty = panel.labels === void 0 && panel.stats === void 0 && panel.actions === void 0;
+	return {
+		overrides,
+		...panelSeen && !panelEmpty ? { panel } : {}
+	};
+}
 /** Renderer kinds the pet center knows how to dispatch (M1 §2). */
 const PET_RENDERER_KINDS = ["sprite2d", "live2d"];
 /** The seven ActivityPhase semantics (pet-center owned; M1 §1). */
@@ -1385,8 +1769,8 @@ const PET_ACTIVITY_PHASES = [
 	"done",
 	"failed"
 ];
-const PET_ID_PATTERN$1 = /^[a-z0-9][a-z0-9-]*$/;
-const PATH_SEGMENT_PATTERN$1 = /^[A-Za-z0-9._-]+$/;
+const PET_ID_PATTERN$2 = /^[a-z0-9][a-z0-9-]*$/;
+const PATH_SEGMENT_PATTERN$2 = /^[A-Za-z0-9._-]+$/;
 const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 /**
 * Field allow-lists mirroring contracts/pet-manifest-v2.schema.json. Exported
@@ -1428,7 +1812,7 @@ const KNOWN_LIVE2D = /* @__PURE__ */ new Set([
 	"hitAreas",
 	"lipSync"
 ]);
-var Diagnostics = class {
+var Diagnostics$1 = class {
 	list = [];
 	source;
 	constructor(source) {
@@ -1450,10 +1834,10 @@ var Diagnostics = class {
 		return this.list.some((d) => d.level === "error");
 	}
 };
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function unknownKeys(source, known) {
+function unknownKeys$1(source, known) {
 	return Object.keys(source).filter((key) => !known.has(key));
 }
 /**
@@ -1466,7 +1850,7 @@ function safeManifestPath(raw) {
 	if (isAbsolute(value) || value.includes("\\") || /^[a-z][a-z0-9+.-]*:/i.test(value)) return void 0;
 	const segments = value.split("/").filter((segment) => segment !== "");
 	if (segments.length === 0) return void 0;
-	if (segments.some((segment) => segment === "." || segment === ".." || !PATH_SEGMENT_PATTERN$1.test(segment))) return void 0;
+	if (segments.some((segment) => segment === "." || segment === ".." || !PATH_SEGMENT_PATTERN$2.test(segment))) return void 0;
 	return segments.join("/");
 }
 function parseStringBlock(record, key, diag, required) {
@@ -1484,7 +1868,7 @@ function parseStringBlock(record, key, diag, required) {
 /** Validate the phase-keyed string map shape shared by motions/expressions. */
 function parsePhaseStringMap(raw, field, diag) {
 	if (raw === void 0) return void 0;
-	if (!isRecord(raw)) {
+	if (!isRecord$1(raw)) {
 		diag.error("field " + JSON.stringify(field) + " must be an object keyed by activity phase");
 		return;
 	}
@@ -1505,7 +1889,7 @@ function parsePhaseStringMap(raw, field, diag) {
 /** Structural gate for sequences: content stays warn-and-drop (registry's job). */
 function parseSequences(raw, diag) {
 	if (raw === void 0) return void 0;
-	if (!isRecord(raw)) {
+	if (!isRecord$1(raw)) {
 		diag.warn("sequences must be an object keyed by activity phase; ignoring");
 		return;
 	}
@@ -1524,16 +1908,16 @@ function parseSequences(raw, diag) {
 	return Object.keys(sequences).length === 0 ? void 0 : sequences;
 }
 function parseSprite2dBlock(raw, diag) {
-	if (!isRecord(raw)) {
+	if (!isRecord$1(raw)) {
 		diag.error("renderer sprite2d requires a \"sprite2d\" block object");
 		return;
 	}
-	const extra = unknownKeys(raw, KNOWN_SPRITE2D);
+	const extra = unknownKeys$1(raw, KNOWN_SPRITE2D);
 	if (extra.length > 0) diag.error("sprite2d: unknown field(s) " + extra.map((k) => JSON.stringify(k)).join(", "));
 	const spritesheetPath = safeManifestPath(raw.spritesheetPath);
 	if (spritesheetPath === void 0) diag.error("sprite2d.spritesheetPath must be a safe manifest-relative path");
 	const block = { spritesheetPath: spritesheetPath ?? "" };
-	if (raw.cell !== void 0) if (!isRecord(raw.cell)) diag.error("sprite2d.cell must be an object { width?, height? }");
+	if (raw.cell !== void 0) if (!isRecord$1(raw.cell)) diag.error("sprite2d.cell must be an object { width?, height? }");
 	else block.cell = raw.cell;
 	if (raw.columns !== void 0) if (typeof raw.columns !== "number" || !Number.isInteger(raw.columns) || raw.columns < 1) diag.error("sprite2d.columns must be a positive integer");
 	else block.columns = raw.columns;
@@ -1541,16 +1925,16 @@ function parseSprite2dBlock(raw, diag) {
 	else block.atlasRows = raw.atlasRows;
 	if (raw.frames !== void 0) if (!Array.isArray(raw.frames) || raw.frames.some((v) => typeof v !== "number" || !Number.isInteger(v) || v < 0)) diag.error("sprite2d.frames must be an array of non-negative integers");
 	else block.frames = raw.frames;
-	if (raw.tracks !== void 0) if (!isRecord(raw.tracks)) diag.error("sprite2d.tracks must be an object keyed by animation");
+	if (raw.tracks !== void 0) if (!isRecord$1(raw.tracks)) diag.error("sprite2d.tracks must be an object keyed by animation");
 	else block.tracks = raw.tracks;
 	return diag.hasErrors ? void 0 : block;
 }
 function parseLive2dBlock(raw, diag) {
-	if (!isRecord(raw)) {
+	if (!isRecord$1(raw)) {
 		diag.error("renderer live2d requires a \"live2d\" block object");
 		return;
 	}
-	const extra = unknownKeys(raw, KNOWN_LIVE2D);
+	const extra = unknownKeys$1(raw, KNOWN_LIVE2D);
 	if (extra.length > 0) diag.error("live2d: unknown field(s) " + extra.map((k) => JSON.stringify(k)).join(", "));
 	const model = safeManifestPath(raw.model);
 	if (model === void 0) diag.error("live2d.model must be a safe manifest-relative path to a .model3.json");
@@ -1564,7 +1948,7 @@ function parseLive2dBlock(raw, diag) {
 	};
 	if (raw.scale !== void 0) if (typeof raw.scale !== "number" || !Number.isFinite(raw.scale) || raw.scale <= 0 || raw.scale > 10) diag.error("live2d.scale must be a number in (0, 10]");
 	else block.scale = raw.scale;
-	if (raw.translate !== void 0) if (!isRecord(raw.translate) || raw.translate.x !== void 0 && typeof raw.translate.x !== "number" || raw.translate.y !== void 0 && typeof raw.translate.y !== "number") diag.error("live2d.translate must be an object { x?: number, y?: number }");
+	if (raw.translate !== void 0) if (!isRecord$1(raw.translate) || raw.translate.x !== void 0 && typeof raw.translate.x !== "number" || raw.translate.y !== void 0 && typeof raw.translate.y !== "number") diag.error("live2d.translate must be an object { x?: number, y?: number }");
 	else block.translate = raw.translate;
 	const expressions = parsePhaseStringMap(raw.expressions, "live2d.expressions", diag);
 	if (expressions !== void 0) block.expressions = expressions;
@@ -1577,16 +1961,16 @@ function parseLive2dBlock(raw, diag) {
 /** v1 compat read: map the legacy flat manifest onto the v2 sprite2d shape. */
 function compatV1(source, diag) {
 	const id = parseStringBlock(source, "id", diag, true);
-	if (id !== void 0 && !PET_ID_PATTERN$1.test(id)) diag.error("id " + JSON.stringify(id) + " is not a lowercase kebab id");
+	if (id !== void 0 && !PET_ID_PATTERN$2.test(id)) diag.error("id " + JSON.stringify(id) + " is not a lowercase kebab id");
 	const displayName = typeof source.displayName === "string" && source.displayName.trim() !== "" ? source.displayName.trim() : id;
 	const spritesheetPath = safeManifestPath(source.spritesheetPath === void 0 ? "spritesheet.webp" : source.spritesheetPath);
 	if (spritesheetPath === void 0) diag.error("spritesheetPath " + JSON.stringify(String(source.spritesheetPath)) + " is not a safe relative path");
 	if (source.license === void 0) diag.warn("v1 compat read: no license field; run scripts/dsh-pet-migrate-v2 to migrate this pet");
 	const sprite2d = { spritesheetPath: spritesheetPath ?? "spritesheet.webp" };
-	if (isRecord(source.cell)) sprite2d.cell = source.cell;
+	if (isRecord$1(source.cell)) sprite2d.cell = source.cell;
 	if (typeof source.columns === "number") sprite2d.columns = source.columns;
 	if (Array.isArray(source.frames)) sprite2d.frames = source.frames;
-	if (isRecord(source.tracks)) sprite2d.tracks = source.tracks;
+	if (isRecord$1(source.tracks)) sprite2d.tracks = source.tracks;
 	if (source.spriteVersionNumber === 2) sprite2d.atlasRows = 11;
 	const manifest = {
 		petManifestVersion: 2,
@@ -1604,11 +1988,11 @@ function compatV1(source, diag) {
 }
 /** Strict v2 validation (fail-closed on structure). */
 function parseV2(source, diag) {
-	const extra = unknownKeys(source, KNOWN_TOP_LEVEL);
+	const extra = unknownKeys$1(source, KNOWN_TOP_LEVEL);
 	if (extra.length > 0) diag.error("unknown top-level field(s) " + extra.map((k) => JSON.stringify(k)).join(", "));
 	if (source.petManifestVersion !== 2) diag.error("petManifestVersion must be 2 (got " + JSON.stringify(source.petManifestVersion) + ")");
 	const id = parseStringBlock(source, "id", diag, true);
-	if (id !== void 0 && (!PET_ID_PATTERN$1.test(id) || id.length > 64)) diag.error("id " + JSON.stringify(id) + " must be a lowercase kebab id of at most 64 chars");
+	if (id !== void 0 && (!PET_ID_PATTERN$2.test(id) || id.length > 64)) diag.error("id " + JSON.stringify(id) + " must be a lowercase kebab id of at most 64 chars");
 	const displayName = parseStringBlock(source, "displayName", diag, true);
 	const license = parseStringBlock(source, "license", diag, true);
 	const rendererRaw = source.renderer === void 0 ? "sprite2d" : source.renderer;
@@ -1640,7 +2024,7 @@ function parseV2(source, diag) {
 	}
 	const sequences = parseSequences(source.sequences, diag);
 	if (sequences !== void 0) manifest.sequences = sequences;
-	if (source.remarks !== void 0 && !isRecord(source.remarks)) diag.error("remarks must be an object of remark pools");
+	if (source.remarks !== void 0 && !isRecord$1(source.remarks)) diag.error("remarks must be an object of remark pools");
 	else if (source.remarks !== void 0) manifest.remarks = source.remarks;
 	return diag.hasErrors ? void 0 : manifest;
 }
@@ -1652,8 +2036,8 @@ function parseV2(source, diag) {
 * @param sourceLabel - human-readable origin for diagnostics (dir or file).
 */
 function parsePetManifest(raw, sourceLabel) {
-	const diag = new Diagnostics(sourceLabel);
-	if (!isRecord(raw)) {
+	const diag = new Diagnostics$1(sourceLabel);
+	if (!isRecord$1(raw)) {
 		diag.error("manifest is not an object");
 		return {
 			ok: false,
@@ -1686,6 +2070,191 @@ function parsePetManifest(raw, sourceLabel) {
 		diagnostics: diag.list
 	};
 }
+const DECORATION_ENTRY_EXTENSIONS = [".webp", ".png"];
+/** Field allow-list (drift-locked to the schema twin in tests). */
+const KNOWN_DECORATION_TOP_LEVEL = /* @__PURE__ */ new Set([
+	"$schema",
+	"decorationManifestVersion",
+	"id",
+	"displayName",
+	"license",
+	"entry",
+	"cell",
+	"columns",
+	"frameMs",
+	"durations",
+	"loop",
+	"phases"
+]);
+const PET_ID_PATTERN$1 = /^[a-z0-9][a-z0-9-]*$/;
+const PATH_SEGMENT_PATTERN$1 = /^[A-Za-z0-9._-]+$/;
+var Diagnostics = class {
+	list = [];
+	source;
+	constructor(source) {
+		this.source = source;
+	}
+	error(message) {
+		this.list.push({
+			level: "error",
+			message: this.source + ": " + message
+		});
+	}
+	warn(message) {
+		this.list.push({
+			level: "warning",
+			message: this.source + ": " + message
+		});
+	}
+	get hasErrors() {
+		return this.list.some((d) => d.level === "error");
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unknownKeys(source, known) {
+	return Object.keys(source).filter((key) => !known.has(key));
+}
+/** Positive integer in [min, max], else undefined. */
+function finiteInt$1(value, min, max) {
+	return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max ? value : void 0;
+}
+/**
+* Validate a descriptor-relative entry path: no absolute paths, no
+* backslashes, no traversal, plain safe segments only, and an exact
+* lowercase PNG/WebP extension (the adopted entry discipline — SVG/CSS are
+* not accepted). The extension match is case-sensitive on purpose: the
+* asset route serves the declared path verbatim, so a case-mismatched
+* suffix (frames.PNG vs frames.png) would pass a lenient check but 403 on
+* case-sensitive filesystems.
+* Returns the normalized path or undefined.
+*/
+function safeDecorationEntry(raw) {
+	if (typeof raw !== "string" || raw.trim() === "") return void 0;
+	const value = raw.trim();
+	if (value.length > 256) return void 0;
+	if (isAbsolute(value) || value.includes("\\") || /^[a-z][a-z0-9+.-]*:/i.test(value)) return void 0;
+	const segments = value.split("/").filter((segment) => segment !== "");
+	if (segments.length === 0) return void 0;
+	if (segments.some((segment) => segment === "." || segment === ".." || !PATH_SEGMENT_PATTERN$1.test(segment))) return void 0;
+	const last = segments[segments.length - 1];
+	const dot = last.lastIndexOf(".");
+	if (dot <= 0 || !DECORATION_ENTRY_EXTENSIONS.includes(last.slice(dot))) return void 0;
+	return segments.join("/");
+}
+/** Normalize one phase binding value; undefined (warning) on bad content. */
+function normalizeSegment(raw, columns, diag) {
+	if (raw === "hide") return "hide";
+	if (!isRecord(raw)) {
+		diag.warn("phase binding must be \"hide\" or { from, to }; binding dropped");
+		return;
+	}
+	const from = finiteInt$1(raw.from, 0, columns - 1);
+	const to = finiteInt$1(raw.to, 0, columns - 1);
+	if (from === void 0 || to === void 0 || from > to) {
+		diag.warn("phase frame segment out of range; binding dropped");
+		return;
+	}
+	return {
+		from,
+		to
+	};
+}
+/**
+* Parse and validate one decoration.json document. Fail-closed over the
+* structure (types, key sets, paths, ranges); phase-binding content issues
+* drop that binding only (warn-and-drop, the registry never-throw rule).
+*/
+function parseDecorationManifest(raw, source = "decoration.json") {
+	const diag = new Diagnostics(source);
+	if (!isRecord(raw)) {
+		diag.error("descriptor must be a JSON object");
+		return {
+			ok: false,
+			diagnostics: diag.list
+		};
+	}
+	for (const key of unknownKeys(raw, KNOWN_DECORATION_TOP_LEVEL)) diag.error("unknown top-level field " + JSON.stringify(key));
+	if (raw.decorationManifestVersion !== 1) diag.error("decorationManifestVersion must be 1");
+	const id = typeof raw.id === "string" ? raw.id.trim() : "";
+	if (!PET_ID_PATTERN$1.test(id)) diag.error("id must be a lowercase kebab id");
+	if (id.length > 64) diag.error("id must be at most 64 characters");
+	const license = typeof raw.license === "string" ? raw.license.trim() : "";
+	if (license === "") diag.error("license is required (asset provenance)");
+	if (license.length > 128) diag.error("license must be at most 128 characters");
+	const entry = safeDecorationEntry(raw.entry);
+	if (entry === void 0) diag.error("entry must be a safe relative PNG/WebP path");
+	const rawCell = isRecord(raw.cell) ? raw.cell : {};
+	for (const key of Object.keys(rawCell)) if (key !== "width" && key !== "height") diag.warn("unknown cell field " + JSON.stringify(key) + " ignored");
+	const cellWidth = finiteInt$1(rawCell.width, 1, 256);
+	const cellHeight = finiteInt$1(rawCell.height, 1, 256);
+	if (cellWidth === void 0 || cellHeight === void 0) diag.error("cell width/height must be integers in [1, 256]");
+	const columns = finiteInt$1(raw.columns, 1, 16);
+	if (columns === void 0) diag.error("columns must be an integer in [1, 16]");
+	if (diag.hasErrors || id === "" || entry === void 0 || columns === void 0) return {
+		ok: false,
+		diagnostics: diag.list
+	};
+	const displayName = typeof raw.displayName === "string" && raw.displayName.trim() !== "" ? raw.displayName.trim().slice(0, 64) : id;
+	let loop;
+	if (raw.loop === void 0 || typeof raw.loop === "boolean") loop = raw.loop ?? true;
+	else {
+		diag.warn("loop must be a boolean; defaulting to true");
+		loop = true;
+	}
+	const rawDurations = raw.durations;
+	let durations;
+	if (Array.isArray(rawDurations)) {
+		const usable = rawDurations.filter((v) => typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 2e3);
+		if (usable.length !== columns) {
+			diag.warn("durations length must equal columns; using the constant frameMs instead");
+			durations = [];
+		} else durations = usable;
+	} else if (rawDurations !== void 0) {
+		diag.warn("durations must be an array; using the constant frameMs instead");
+		durations = [];
+	} else durations = [];
+	if (durations.length === 0) {
+		const frameMs = finiteInt$1(raw.frameMs, 1, 2e3) ?? 120;
+		durations = Array.from({ length: columns }, () => frameMs);
+	}
+	const phases = {};
+	const rawPhases = raw.phases;
+	if (isRecord(rawPhases)) for (const [key, value] of Object.entries(rawPhases)) {
+		if (!PET_ACTIVITY_PHASES.includes(key)) {
+			diag.warn("unknown phase " + JSON.stringify(key) + "; binding ignored");
+			continue;
+		}
+		const segment = normalizeSegment(value, columns, diag);
+		if (segment !== void 0) phases[key] = segment;
+	}
+	else if (rawPhases !== void 0) diag.warn("phases must be an object; all phases hide");
+	if (!Object.values(phases).some((segment) => segment !== "hide")) diag.warn("no phase shows the ornament; the decoration stays hidden");
+	return {
+		ok: true,
+		manifest: {
+			decorationManifestVersion: 1,
+			id,
+			displayName,
+			license,
+			entry,
+			cell: {
+				width: cellWidth,
+				height: cellHeight
+			},
+			columns,
+			durations,
+			loop,
+			phases
+		},
+		diagnostics: diag.list
+	};
+}
+//#endregion
+//#region src/contracts/status-decoration.ts
+/** Contract version decorations declare against (independent of manifests). */
+const PET_DECORATION_API_VERSION = "x-org.linxin666.pet-center/status-decoration-v1";
 //#endregion
 //#region src/model3.ts
 /**
@@ -2198,24 +2767,28 @@ function scanPetDir(dir, options) {
 			options.warnings?.push(diagnostic.message);
 		}
 		if (!verdict.ok) continue;
-		if (verdict.manifest.renderer === "live2d") {
-			const entry = resolveLive2dEntry(verdict.manifest, entryDir, options);
-			if (entry !== void 0) entries.push(entry);
-			continue;
-		}
-		const legacy = flattenV2Sprite2d(verdict.manifest);
-		if (legacy === void 0) {
-			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;
+		let entry;
+		if (verdict.manifest.renderer === "live2d") entry = resolveLive2dEntry(verdict.manifest, entryDir, options);
+		else {
+			const legacy = flattenV2Sprite2d(verdict.manifest);
+			if (legacy === void 0) {
+				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 !== void 0) entries.push(entry);
+		if (entry === void 0) continue;
+		const voice = loadVoicePackFile(join(entryDir, "voice.json"), options);
+		entries.push({
+			...entry,
+			...voice === void 0 ? {} : { voice }
+		});
 	}
 	return entries;
 }
@@ -2229,6 +2802,135 @@ function readPetJson(file, warnings) {
 	}
 }
 /**
+* 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;
+	}
+	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;
+	}
+	if (st.size > 65536) {
+		warn(what + " exceeds the 65536-byte scan ceiling; ignored");
+		return;
+	}
+	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 void 0;
+	if (guardedScannedJsonStat(file, options, "voice pack") === void 0) return void 0;
+	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;
+	}
+	return normalizeVoicePack(raw, warn);
+}
+/** Decoration asset URL prefix (served by the decoration route, M5). */
+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") === void 0) 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;
+		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: "/api/pet/decoration/" + encodeURIComponent(manifest.id),
+			entryUrl: "/api/pet/decoration/" + 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
 * overrides an earlier one on id collision). The registry never throws on a
@@ -2262,13 +2964,20 @@ function loadPetRegistry(options) {
 		byId.set(entry.id, entry);
 	}
 	const dshPetsDir = options.dshPetsDir ?? join(dshHome(), "pets");
-	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);
+	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);
+		}
+		globalVoice = loadVoicePackFile(join(dshPetsDir, ".voice.json"), {
+			warnings,
+			diagnostics
+		});
 	}
 	for (const manifest of options.extra ?? []) {
 		const raw = manifest.spritesheetPath;
@@ -2284,17 +2993,55 @@ function loadPetRegistry(options) {
 		if (byId.has(entry.id)) warnings.push("composed pet " + entry.id + " overrides an earlier registration");
 		byId.set(entry.id, entry);
 	}
+	const decorationById = /* @__PURE__ */ 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]
+		defaultEntry: () => entries.find((entry) => builtinIds.has(entry.id)) ?? entries[0],
+		...globalVoice === void 0 ? {} : { globalVoice },
+		decorations,
+		decorationById: (id) => decorationById.get(id)
+	};
+}
+/** The built-in default decoration id (M5): the first reference ornament. */
+const DEFAULT_DECORATION_ID = "whale";
+/** Strip host-only fields, leaving the browser-visible decoration view. */
+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. */
-function petEntryView(entry) {
+/**
+* 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).
+*/
+function petEntryView(entry, globalVoice) {
+	const panel = globalVoice === void 0 ? entry.voice?.panel : mergeVoicePacks(globalVoice, entry.voice)?.panel;
 	return {
 		id: entry.id,
 		displayName: entry.displayName,
@@ -2308,7 +3055,8 @@ function petEntryView(entry) {
 		tracks: entry.tracks,
 		...entry.sequences === void 0 ? {} : { sequences: entry.sequences },
 		atlasUrl: entry.atlasUrl,
-		manifestUrl: entry.manifestUrl
+		manifestUrl: entry.manifestUrl,
+		...panel === void 0 ? {} : { panel }
 	};
 }
 /** Hard cap on simultaneously displayed session bubbles (most recent first). */
@@ -2327,10 +3075,18 @@ var PetService = class 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;
 	* disposed sessions are removed by the 'session/disposed' listener.
@@ -2362,8 +3118,26 @@ var PetService = class extends Service {
 		};
 		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 !== void 0 && 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;
@@ -2378,7 +3152,7 @@ var PetService = class 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() {
@@ -2388,6 +3162,15 @@ var PetService = class 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 void 0;
+		const entry = this.registry.decorationById?.(DEFAULT_DECORATION_ID);
+		return entry === void 0 ? void 0 : decorationView(entry);
+	}
 	/** The selected pet's registry entry. */
 	activeEntry() {
 		return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry();
@@ -2471,7 +3254,7 @@ var PetService = class extends Service {
 		let activity = this.sessionActivity.get(session);
 		if (activity === void 0) {
 			activity = {
-				runtime: emptyProjectionRuntime(),
+				runtime: emptyProjectionRuntime(this.voicePools()),
 				machine: new PetStateMachine(this.stateConfig)
 			};
 			this.sessionActivity.set(session, activity);
@@ -2565,6 +3348,7 @@ var PetService = class 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) : void 0;
 		if (selected !== void 0) {
 			this.ledger.setPetId(selected.id);
@@ -2617,6 +3401,7 @@ var PetService = class extends Service {
 		}
 		const whisper = (this.displaySession === void 0 ? void 0 : this.sessionActivity.get(this.displaySession))?.whisper;
 		const freshWhisper = whisper !== void 0 && Date.now() - whisper.at < 8e3 ? whisper.text : void 0;
+		const decoration = this.activeDecoration();
 		return {
 			animation: snapshot.animation,
 			...snapshot.bubble === void 0 ? {} : { bubble: snapshot.bubble },
@@ -2624,6 +3409,7 @@ var PetService = class extends Service {
 			sessionActive: snapshot.sessionActive,
 			sessions,
 			...freshWhisper === void 0 ? {} : { whisper: freshWhisper },
+			...decoration === void 0 ? {} : { decoration },
 			affinity: this.ledger.affinityView(Date.now()),
 			display: { ...this.ledger.snapshot.display },
 			pet: {
@@ -2935,7 +3721,7 @@ function assetHandler(registry, caps) {
 			file = existsSync(preview) ? preview : void 0;
 		}
 		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),
@@ -3083,6 +3869,121 @@ 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 === void 0) {
+			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 === void 0) {
+			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;
+		}
+		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. */
 function makePetRoutes(deps) {
 	const { service } = deps;
@@ -3130,10 +4031,16 @@ function makePetRoutes(deps) {
 			vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), "lib")
 		})
 	};
+	const decorationRoute = {
+		kind: "prefix",
+		path: DECORATION_ASSET_PREFIX,
+		handler: decorationHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS)
+	};
 	return [
 		...apiRoutes,
 		assetRoute,
-		runtimeRoute
+		runtimeRoute,
+		decorationRoute
 	];
 }
 //#endregion
@@ -3198,7 +4105,8 @@ function makePetSettingsSchema(fallbackPetId) {
 		right: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(24),
 		bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
 		petId: z.string().default(fallbackPetId),
-		enabled: z.boolean().default(true)
+		enabled: z.boolean().default(true),
+		decorationEnabled: z.boolean().default(true)
 	});
 }
 /** Register the pet service and its API + asset routes on the context. */
@@ -3219,7 +4127,8 @@ function applyImpl(ctx, config = {}) {
 		right: service.display().right,
 		bottom: service.display().bottom,
 		petId: service.selectedPetId(),
-		enabled: config.enabled ?? true
+		enabled: config.enabled ?? true,
+		decorationEnabled: config.decorationEnabled ?? true
 	};
 	const routes = makePetRoutes({ service });
 	let disposeRoutes;