@linxin666/dsh-pet 0.2.2 → 0.2.4

package/lib/index.js

@@ -2,8 +2,8 @@ import { _ as RemarkPicker, a as AFFINITY_MAX, c as applyInteraction, d as empty
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
 import { Service } from "@deepseek-ai/cordis";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -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,19 +1456,895 @@ 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). */
+const PET_ACTIVITY_PHASES = [
+	"idle",
+	"waiting",
+	"thinking",
+	"tool",
+	"review",
+	"done",
+	"failed"
+];
+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
+* so the drift test can lock the schema file and this validator together;
+* the CLI reuses parsePetManifest instead of these.
+*/
+const KNOWN_TOP_LEVEL = /* @__PURE__ */ new Set([
+	"$schema",
+	"petManifestVersion",
+	"id",
+	"displayName",
+	"description",
+	"version",
+	"author",
+	"license",
+	"homepage",
+	"renderer",
+	"sprite2d",
+	"live2d",
+	"sequences",
+	"remarks"
+]);
+/** sprite2d block field allow-list (drift-locked to the schema file). */
+const KNOWN_SPRITE2D = /* @__PURE__ */ new Set([
+	"spritesheetPath",
+	"cell",
+	"columns",
+	"atlasRows",
+	"frames",
+	"tracks"
+]);
+/** live2d block field allow-list (drift-locked to the schema file). */
+const KNOWN_LIVE2D = /* @__PURE__ */ new Set([
+	"model",
+	"scale",
+	"translate",
+	"motions",
+	"expressions",
+	"hitAreas",
+	"lipSync"
+]);
+var Diagnostics$1 = 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$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unknownKeys$1(source, known) {
+	return Object.keys(source).filter((key) => !known.has(key));
+}
+/**
+* Validate a manifest-relative asset path: no absolute paths, no backslashes,
+* no traversal, plain safe segments only. Returns the normalized path.
+*/
+function safeManifestPath(raw) {
+	if (typeof raw !== "string" || raw.trim() === "") return void 0;
+	const value = raw.trim();
+	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$2.test(segment))) return void 0;
+	return segments.join("/");
+}
+function parseStringBlock(record, key, diag, required) {
+	const value = record[key];
+	if (value === void 0) {
+		if (required) diag.error("missing required field " + JSON.stringify(key));
+		return;
+	}
+	if (typeof value !== "string" || value.trim() === "") {
+		diag.error("field " + JSON.stringify(key) + " must be a non-empty string");
+		return;
+	}
+	return value.trim();
+}
+/** 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$1(raw)) {
+		diag.error("field " + JSON.stringify(field) + " must be an object keyed by activity phase");
+		return;
+	}
+	const result = {};
+	for (const [phase, value] of Object.entries(raw)) {
+		if (!PET_ACTIVITY_PHASES.includes(phase)) {
+			diag.error(field + ": unknown activity phase " + JSON.stringify(phase));
+			continue;
+		}
+		if (typeof value !== "string" || value.trim() === "") {
+			diag.error(field + "." + phase + " must be a non-empty string");
+			continue;
+		}
+		result[phase] = value.trim();
+	}
+	return result;
+}
+/** 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$1(raw)) {
+		diag.warn("sequences must be an object keyed by activity phase; ignoring");
+		return;
+	}
+	const sequences = {};
+	for (const [phase, value] of Object.entries(raw)) {
+		if (!PET_ACTIVITY_PHASES.includes(phase)) {
+			diag.warn("sequences: unknown activity phase " + JSON.stringify(phase) + "; entry dropped");
+			continue;
+		}
+		if (!Array.isArray(value) || value.length < 5 || value.some((item) => typeof item !== "string")) {
+			diag.warn("sequences." + phase + " must be an array of at least 5 animation names; entry dropped");
+			continue;
+		}
+		sequences[phase] = value;
+	}
+	return Object.keys(sequences).length === 0 ? void 0 : sequences;
+}
+function parseSprite2dBlock(raw, diag) {
+	if (!isRecord$1(raw)) {
+		diag.error("renderer sprite2d requires a \"sprite2d\" block object");
+		return;
+	}
+	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$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;
+	if (raw.atlasRows !== void 0) if (typeof raw.atlasRows !== "number" || !Number.isInteger(raw.atlasRows) || raw.atlasRows < 1) diag.error("sprite2d.atlasRows must be a positive integer");
+	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$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$1(raw)) {
+		diag.error("renderer live2d requires a \"live2d\" block object");
+		return;
+	}
+	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");
+	else if (!model.endsWith(".model3.json")) diag.error("live2d.model must point at a .model3.json file");
+	const motions = parsePhaseStringMap(raw.motions, "live2d.motions", diag);
+	if (raw.motions === void 0) diag.error("live2d.motions is required (at least an \"idle\" group)");
+	else if (motions !== void 0 && motions.idle === void 0) diag.error("live2d.motions.idle is required (unmapped phases fall back to it)");
+	const block = {
+		model: model ?? "",
+		motions: motions ?? { idle: "" }
+	};
+	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$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;
+	if (raw.hitAreas !== void 0) if (!Array.isArray(raw.hitAreas) || raw.hitAreas.some((v) => typeof v !== "string" || v.trim() === "")) diag.error("live2d.hitAreas must be an array of non-empty strings");
+	else block.hitAreas = raw.hitAreas;
+	if (raw.lipSync !== void 0) if (typeof raw.lipSync !== "boolean") diag.error("live2d.lipSync must be a boolean");
+	else block.lipSync = raw.lipSync;
+	return diag.hasErrors ? void 0 : block;
+}
+/** 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$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$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$1(source.tracks)) sprite2d.tracks = source.tracks;
+	if (source.spriteVersionNumber === 2) sprite2d.atlasRows = 11;
+	const manifest = {
+		petManifestVersion: 2,
+		id: id ?? "",
+		displayName: displayName ?? "",
+		renderer: "sprite2d",
+		sprite2d
+	};
+	if (typeof source.description === "string" && source.description.trim() !== "") manifest.description = source.description.trim();
+	if (typeof source.license === "string" && source.license.trim() !== "") manifest.license = source.license.trim();
+	const sequences = parseSequences(source.sequences, diag);
+	if (sequences !== void 0) manifest.sequences = sequences;
+	if (source.remarks !== void 0) manifest.remarks = source.remarks;
+	return diag.hasErrors ? void 0 : manifest;
+}
+/** Strict v2 validation (fail-closed on structure). */
+function parseV2(source, diag) {
+	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$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;
+	if (!PET_RENDERER_KINDS.includes(rendererRaw)) diag.error("unknown renderer " + JSON.stringify(rendererRaw) + "; expected one of " + PET_RENDERER_KINDS.join(", "));
+	const renderer = rendererRaw;
+	const manifest = {
+		petManifestVersion: 2,
+		id: id ?? "",
+		displayName: displayName ?? "",
+		renderer
+	};
+	if (license !== void 0) manifest.license = license;
+	if (source.description !== void 0) if (typeof source.description !== "string" || source.description.length > 500) diag.error("description must be a string of at most 500 chars");
+	else manifest.description = source.description;
+	if (source.version !== void 0) if (typeof source.version !== "string" || !SEMVER_PATTERN.test(source.version)) diag.error("version must be a semver string (x.y.z)");
+	else manifest.version = source.version;
+	if (source.author !== void 0) if (typeof source.author !== "string" || source.author.length > 128) diag.error("author must be a string of at most 128 chars");
+	else manifest.author = source.author;
+	if (source.homepage !== void 0) if (typeof source.homepage !== "string") diag.error("homepage must be a string URL");
+	else manifest.homepage = source.homepage;
+	if (renderer === "sprite2d") {
+		const block = parseSprite2dBlock(source.sprite2d, diag);
+		if (block !== void 0) manifest.sprite2d = block;
+		if (source.live2d !== void 0) diag.error("renderer sprite2d must not declare a live2d block");
+	} else if (renderer === "live2d") {
+		const block = parseLive2dBlock(source.live2d, diag);
+		if (block !== void 0) manifest.live2d = block;
+		if (source.sprite2d !== void 0) diag.error("renderer live2d must not declare a sprite2d block");
+	}
+	const sequences = parseSequences(source.sequences, diag);
+	if (sequences !== void 0) manifest.sequences = sequences;
+	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;
+}
+/**
+* Parse one pet manifest: v1 (no petManifestVersion) is compat-read as a
+* sprite2d pet with a migration hint; v2 is validated fail-closed. The parse
+* never throws — every failure comes back as structured diagnostics.
+* @param raw - the parsed pet.json value.
+* @param sourceLabel - human-readable origin for diagnostics (dir or file).
+*/
+function parsePetManifest(raw, sourceLabel) {
+	const diag = new Diagnostics$1(sourceLabel);
+	if (!isRecord$1(raw)) {
+		diag.error("manifest is not an object");
+		return {
+			ok: false,
+			diagnostics: diag.list
+		};
+	}
+	if (raw.petManifestVersion === void 0) {
+		const manifest = compatV1(raw, diag);
+		if (manifest === void 0) return {
+			ok: false,
+			diagnostics: diag.list
+		};
+		diag.warn("v1 compat read: manifest treated as renderer \"sprite2d\"; run scripts/dsh-pet-migrate-v2 to migrate");
+		return {
+			ok: true,
+			manifest,
+			migrated: "v1-compat",
+			diagnostics: diag.list
+		};
+	}
+	const manifest = parseV2(raw, diag);
+	if (manifest === void 0) return {
+		ok: false,
+		diagnostics: diag.list
+	};
+	return {
+		ok: true,
+		manifest,
+		migrated: void 0,
+		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
+/**
+* Live2D .model3.json reference closure — the set of files a model declares
+* (pet-center M2, issue #623). The host asset route only ever serves a pet's
+* declared manifest, its declared primary assets, and this closure; the CLI
+* validator reuses the same extractor so an install-time check proves the
+* serving set is complete.
+*
+* Cubism file family: Moc (.moc3), Textures (images), Physics (.physics3.json),
+* Pose (.pose3.json), DisplayInfo (.cdi3.json), Expressions[].File
+* (.exp3.json), Motions.<group>[].File (.motion3.json), UserData
+* (.userdata3.json). Every reference must be a safe manifest-relative path
+* (safeManifestPath); unsafe entries make the model unloadable.
+*
+* Erasable-syntax-only: scripts/ import this under node strip-only mode.
+* @module @linxin666/dsh-pet/model3
+*/
+/** Collect the safe relative paths one model3.json references. */
+function collectModel3References(model3) {
+	const errors = [];
+	if (typeof model3 !== "object" || model3 === null) return {
+		references: [],
+		errors: ["model3.json is not an object"]
+	};
+	const fileReferences = model3.FileReferences;
+	if (typeof fileReferences !== "object" || fileReferences === null) return {
+		references: [],
+		errors: ["model3.json has no FileReferences"]
+	};
+	const refs = fileReferences;
+	const collected = /* @__PURE__ */ new Set();
+	const push = (raw, field) => {
+		const safe = safeManifestPath(raw);
+		if (safe === void 0) {
+			errors.push(field + " is not a safe relative path: " + JSON.stringify(String(raw)));
+			return;
+		}
+		collected.add(safe);
+	};
+	if (refs.Moc !== void 0) push(refs.Moc, "FileReferences.Moc");
+	if (Array.isArray(refs.Textures)) refs.Textures.forEach((texture, index) => push(texture, "FileReferences.Textures[" + index + "]"));
+	for (const scalar of [
+		"Physics",
+		"Pose",
+		"DisplayInfo",
+		"UserData"
+	]) if (refs[scalar] !== void 0) push(refs[scalar], "FileReferences." + scalar);
+	if (Array.isArray(refs.Expressions)) refs.Expressions.forEach((expression, index) => {
+		const file = typeof expression === "object" && expression !== null ? expression.File : void 0;
+		if (file !== void 0) push(file, "FileReferences.Expressions[" + index + "].File");
+	});
+	if (typeof refs.Motions === "object" && refs.Motions !== null) for (const [group, motions] of Object.entries(refs.Motions)) {
+		if (!Array.isArray(motions)) {
+			errors.push("FileReferences.Motions." + group + " is not an array");
+			continue;
+		}
+		motions.forEach((motion, index) => {
+			const file = typeof motion === "object" && motion !== null ? motion.File : void 0;
+			if (file !== void 0) push(file, "FileReferences.Motions." + group + "[" + index + "].File");
+		});
+	}
+	return {
+		references: [...collected].sort(),
+		errors
+	};
+}
 //#endregion
 //#region src/registry.ts
 /**
 * Pet registry — the multi-pet contract. One pet is a directory holding a
 * 'pet.json' manifest plus an atlas image; nothing else is required, and no
-* host or client code changes when a pet is added. The registry scans three
+* host or client code changes when a pet is added. The registry scans four
 * sources, later sources overriding earlier ones on an id collision:
 *
 *   1. the package's own 'assets' subdirectories (built-in pets);
-*   2. '${CODEX_HOME:-~/.codex}/pets' subdirectories (hatch-pet custom pets);
-*   3. 'PetConfig.pets' manifests composed by the embedding application
+*   2. '${CODEX_HOME:-~/.codex}/pets' subdirectories (hatch-pet custom pets,
+*      legacy source kept readable);
+*   3. '$DSH_HOME/pets' subdirectories (the pet-center user directory);
+*   4. 'PetConfig.pets' manifests composed by the embedding application
 *      (highest precedence).
 *
+* Manifests are parsed through manifest-v2 (pet-center M2, issue #623): v1
+* manifests are compat-read as sprite2d, v2 manifests validate fail-closed,
+* and structured diagnostics ride alongside the legacy warnings. Live2d
+* entries (pet-center M3) list like any other pet: the entry carries the
+* validated live2d block plus the model's reference closure (the servable
+* set the asset route allows), and a model3.json that is unreadable or
+* declares unsafe references rejects the entry with an error diagnostic.
+*
 * The manifest follows the Codex/hatch-pet contract (8 columns x 9 rows of
 * 192x208 cells, the 9-state row order below). Legacy whale-girl manifests
 * that only carry 'frames' keep working: geometry, per-row frame counts and
@@ -1596,6 +2555,33 @@ function normalizeSequences(raw, id, warn) {
 	return Object.keys(sequences).length === 0 ? void 0 : sequences;
 }
 /**
+* Build the fully resolved animation tracks from the contract defaults plus
+* optional per-track overrides. Shared by the sprite2d resolver and the
+* live2d entry builder (which fills the sprite fields with contract
+* defaults so the flat PetDefinition shape holds for every renderer).
+*/
+function buildTracks(rows, columns, trackOverrides, warn) {
+	const tracks = {};
+	for (const [row, animation] of PET_ROW_ORDER.entries()) {
+		const pattern = DEFAULT_TRACK_PATTERNS[animation];
+		const override = trackOverrides[animation];
+		const durations = Array.isArray(override?.durations) && override.durations.length > 0 ? override.durations.filter((value) => typeof value === "number" && Number.isFinite(value) && value > 0) : pattern.durations;
+		if (durations.length === 0) {
+			warn("track " + animation + " carries no usable durations");
+			return;
+		}
+		const frameCount = Math.max(1, Math.min(rows[row], columns));
+		const sized = durations.length >= frameCount ? durations.slice(0, frameCount) : Array.from({ length: frameCount }, (_, index) => durations[index % durations.length]);
+		tracks[animation] = {
+			frames: Array.from({ length: frameCount }, (_, index) => index),
+			durations: sized,
+			loop: typeof override?.loop === "boolean" ? override.loop : pattern.loop,
+			...override?.fallback === void 0 ? pattern.fallback === void 0 ? {} : { fallback: pattern.fallback } : PET_ROW_ORDER.includes(override.fallback) ? { fallback: override.fallback } : pattern.fallback === void 0 ? {} : { fallback: pattern.fallback }
+		};
+	}
+	return tracks;
+}
+/**
 * Normalize one parsed manifest into a renderable pet entry, or undefined
 * (with a warning recorded) when the manifest violates the contract.
 */
@@ -1634,29 +2620,14 @@ function resolvePetManifest(raw, dir, options = {}) {
 	});
 	const remarks = normalizePetRemarks(source.remarks, (message) => warn("manifest " + id + ": " + message));
 	const sequences = normalizeSequences(source.sequences, id, warn);
-	const trackOverrides = typeof source.tracks === "object" && source.tracks !== null ? source.tracks : {};
-	const tracks = {};
-	for (const [row, animation] of PET_ROW_ORDER.entries()) {
-		const pattern = DEFAULT_TRACK_PATTERNS[animation];
-		const override = trackOverrides[animation];
-		const durations = Array.isArray(override?.durations) && override.durations.length > 0 ? override.durations.filter((value) => typeof value === "number" && Number.isFinite(value) && value > 0) : pattern.durations;
-		if (durations.length === 0) {
-			warn("manifest " + id + ": track " + animation + " carries no usable durations");
-			return;
-		}
-		const frameCount = Math.max(1, Math.min(rows[row], columns));
-		const sized = durations.length >= frameCount ? durations.slice(0, frameCount) : Array.from({ length: frameCount }, (_, index) => durations[index % durations.length]);
-		tracks[animation] = {
-			frames: Array.from({ length: frameCount }, (_, index) => index),
-			durations: sized,
-			loop: typeof override?.loop === "boolean" ? override.loop : pattern.loop,
-			...override?.fallback === void 0 ? pattern.fallback === void 0 ? {} : { fallback: pattern.fallback } : PET_ROW_ORDER.includes(override.fallback) ? { fallback: override.fallback } : pattern.fallback === void 0 ? {} : { fallback: pattern.fallback }
-		};
-	}
+	const tracks = buildTracks(rows, columns, typeof source.tracks === "object" && source.tracks !== null ? source.tracks : {}, (message) => warn("manifest " + id + ": " + message));
+	if (tracks === void 0) return void 0;
+	const sheet = spritesheetPath.join("/");
 	return {
 		id,
 		displayName,
 		description,
+		renderer: "sprite2d",
 		cell,
 		columns,
 		rows,
@@ -1666,7 +2637,106 @@ function resolvePetManifest(raw, dir, options = {}) {
 		atlasUrl: assetUrl(assetPrefix, id, spritesheet),
 		manifestUrl: assetUrl(assetPrefix, id, "pet.json"),
 		dir,
-		spritesheetPath: spritesheetPath.join("/"),
+		spritesheetPath: sheet,
+		servable: [sheet],
+		...remarks === void 0 ? {} : { remarks }
+	};
+}
+/**
+* Adapt a validated v2 manifest's sprite2d block onto the legacy flat shape
+* the established resolver consumes (pet-center M2 P2). The legacy resolver
+* only expresses 9-row (default) and 11-row (spriteVersionNumber 2) atlases,
+* so other atlasRows values are rejected here with a diagnostic.
+*/
+function flattenV2Sprite2d(manifest) {
+	const block = manifest.sprite2d;
+	if (block === void 0) return void 0;
+	const legacy = {
+		id: manifest.id,
+		displayName: manifest.displayName,
+		spritesheetPath: block.spritesheetPath
+	};
+	if (manifest.description !== void 0) legacy.description = manifest.description;
+	if (block.cell !== void 0) legacy.cell = block.cell;
+	if (block.columns !== void 0) legacy.columns = block.columns;
+	if (block.frames !== void 0) legacy.frames = block.frames;
+	if (block.tracks !== void 0) legacy.tracks = block.tracks;
+	if (block.atlasRows !== void 0) {
+		if (block.atlasRows === 11) legacy.spriteVersionNumber = 2;
+		else if (block.atlasRows !== 9) return void 0;
+	}
+	if (manifest.sequences !== void 0) legacy.sequences = manifest.sequences;
+	if (manifest.remarks !== void 0) legacy.remarks = manifest.remarks;
+	return legacy;
+}
+/**
+* Resolve a validated live2d manifest into a renderable entry (pet-center
+* M3). The model3.json is read at scan time: its reference closure becomes
+* the entry's servable set (the asset route's allow-list), and a model that
+* is unreadable or declares unsafe references rejects the entry fail-closed
+* with an error diagnostic. Closure files missing on disk warn but keep the
+* entry listed — the client renderer's diagnostic card reports the broken
+* render, matching the registry's never-throw philosophy (install-time
+* strictness belongs to the CLI validator). The sprite fields carry contract
+* defaults: the chrome sizes live2d pets off 'display.size', not the atlas.
+*/
+function resolveLive2dEntry(manifest, dir, options) {
+	const assetPrefix = options.assetPrefix ?? "/pet";
+	const record = (level, message) => {
+		options.diagnostics?.push({
+			level,
+			source: dir,
+			message
+		});
+		options.warnings?.push(message);
+	};
+	const block = manifest.live2d;
+	if (block === void 0) {
+		record("error", "pet " + manifest.id + ": renderer live2d requires a live2d block");
+		return;
+	}
+	let model3;
+	try {
+		model3 = JSON.parse(readFileSync(join(dir, block.model), "utf8"));
+	} catch (error) {
+		record("error", "pet " + manifest.id + ": live2d model " + block.model + " is not readable: " + (error instanceof Error ? error.message : String(error)));
+		return;
+	}
+	const { references, errors } = collectModel3References(model3);
+	if (errors.length > 0) {
+		for (const message of errors) record("error", "pet " + manifest.id + ": live2d model " + block.model + ": " + message);
+		return;
+	}
+	for (const reference of references) if (!existsSync(join(dir, reference))) record("warning", "pet " + manifest.id + ": live2d closure file missing: " + reference);
+	const tracks = buildTracks(DEFAULT_FRAME_COUNTS, 8, {}, (message) => record("warning", "pet " + manifest.id + ": " + message));
+	if (tracks === void 0) return void 0;
+	const remarks = normalizePetRemarks(manifest.remarks, (message) => record("warning", "pet " + manifest.id + ": " + message));
+	const modelUrl = assetUrl(assetPrefix, manifest.id, block.model);
+	const live2d = {
+		modelUrl,
+		modelPath: block.model,
+		...block.scale === void 0 ? {} : { scale: block.scale },
+		...block.translate === void 0 ? {} : { translate: block.translate },
+		motions: block.motions,
+		...block.expressions === void 0 ? {} : { expressions: block.expressions },
+		...block.hitAreas === void 0 ? {} : { hitAreas: block.hitAreas }
+	};
+	return {
+		id: manifest.id,
+		displayName: manifest.displayName,
+		description: manifest.description ?? "",
+		renderer: "live2d",
+		live2d,
+		cell: { ...DEFAULT_PET_CELL },
+		columns: 8,
+		rows: [...DEFAULT_FRAME_COUNTS],
+		atlasRows: 9,
+		tracks,
+		atlasUrl: modelUrl,
+		manifestUrl: assetUrl(assetPrefix, manifest.id, "pet.json"),
+		dir,
+		spritesheetPath: block.model,
+		servable: [block.model, ...references],
 		...remarks === void 0 ? {} : { remarks }
 	};
 }
@@ -1686,8 +2756,39 @@ function scanPetDir(dir, options) {
 		if (!existsSync(manifestFile)) continue;
 		const parsed = readPetJson(manifestFile, options.warnings);
 		if (parsed === void 0) continue;
-		const entry = resolvePetManifest(parsed, join(dir, name), options);
-		if (entry !== void 0) entries.push(entry);
+		const entryDir = join(dir, name);
+		const verdict = parsePetManifest(parsed, entryDir);
+		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;
+		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);
+		}
+		if (entry === void 0) continue;
+		const voice = loadVoicePackFile(join(entryDir, "voice.json"), options);
+		entries.push({
+			...entry,
+			...voice === void 0 ? {} : { voice }
+		});
 	}
 	return entries;
 }
@@ -1701,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
@@ -1709,11 +2939,13 @@ function readPetJson(file, warnings) {
 function loadPetRegistry(options) {
 	const { packageRoot, assetPrefix = "/pet" } = options;
 	const warnings = [];
+	const diagnostics = [];
 	const byId = /* @__PURE__ */ new Map();
 	const builtinIds = /* @__PURE__ */ new Set();
 	for (const entry of scanPetDir(join(packageRoot, "assets"), {
 		assetPrefix,
-		warnings
+		warnings,
+		diagnostics
 	})) {
 		if (byId.has(entry.id)) {
 			warnings.push("duplicate built-in pet id " + entry.id + "; the first one wins");
@@ -1725,11 +2957,28 @@ function loadPetRegistry(options) {
 	const petsDir = options.petsDir ?? codexPetsDir();
 	if (petsDir !== "") for (const entry of scanPetDir(petsDir, {
 		assetPrefix,
-		warnings
+		warnings,
+		diagnostics
 	})) {
 		if (byId.has(entry.id)) warnings.push("custom pet " + entry.id + " overrides the built-in one");
 		byId.set(entry.id, entry);
 	}
+	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);
+		}
+		globalVoice = loadVoicePackFile(join(dshPetsDir, ".voice.json"), {
+			warnings,
+			diagnostics
+		});
+	}
 	for (const manifest of options.extra ?? []) {
 		const raw = manifest.spritesheetPath;
 		const dir = raw === void 0 || isAbsolute(raw) ? join(packageRoot, "assets", "extra") : dirname(resolve(packageRoot, raw));
@@ -1744,20 +2993,61 @@ 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)
 	};
 }
-/** Strip host-only fields, leaving the client-visible definition. */
-function petEntryView(entry) {
+/** 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. 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,
 		description: entry.description,
+		renderer: entry.renderer,
+		...entry.live2d === void 0 ? {} : { live2d: entry.live2d },
 		cell: entry.cell,
 		columns: entry.columns,
 		rows: entry.rows,
@@ -1765,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). */
@@ -1784,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.
@@ -1819,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;
@@ -1835,12 +3152,25 @@ 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() {
 		return this.registry;
 	}
+	/** RPC: structured registry diagnostics (pet-center M2, issue #623). */
+	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();
@@ -1924,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);
@@ -2018,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);
@@ -2070,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 },
@@ -2077,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: {
@@ -2161,6 +3494,46 @@ const PET_ASSET_PREFIX = "/pet";
 const MANIFEST_FILE = "pet.json";
 const PREVIEW_DIR = "previews";
 const PREVIEW_PATTERN = /^[A-Za-z0-9._-]+$/;
+/**
+* Per-class size ceilings for served pet assets, in bytes (pet-center M2 P3,
+* issue #623). Constants are tested directly; makePetRoutes accepts an
+* override so tests can exercise the 413 path with tiny caps.
+*/
+const PET_ASSET_CAPS = {
+	/** pet.json manifest. */
+	manifest: 64 * 1024,
+	/** Atlas, preview and Live2D texture imagery. */
+	image: 20 * 1024 * 1024,
+	/** Live2D model closure files (.moc3, motion/physics/expression JSON; M3). */
+	model: 32 * 1024 * 1024
+};
+/** Imagery extensions classify into the image cap; everything else served from a closure is model-class. */
+const IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".webp",
+	".png",
+	".gif",
+	".jpg",
+	".jpeg"
+]);
+/** Lowercased file extension ('' when none). */
+function extensionOf(file) {
+	const dot = file.lastIndexOf(".");
+	return dot < 0 ? "" : file.slice(dot).toLowerCase();
+}
+/**
+* realpath containment: resolve both sides and require the candidate to stay
+* inside the base directory. A pet directory (or an atlas/preview inside it)
+* that is a symlink escaping its root is rejected, never followed.
+*/
+function containedRealpath(base, candidate) {
+	try {
+		const realBase = realpathSync(base);
+		const realCandidate = realpathSync(candidate);
+		return realCandidate === realBase || realCandidate.startsWith(realBase + sep) ? realCandidate : void 0;
+	} catch {
+		return;
+	}
+}
 const MIME_BY_EXT = {
 	".webp": "image/webp",
 	".png": "image/png",
@@ -2279,10 +3652,14 @@ function dirAliases(registry) {
 /**
 * The one asset handler behind the '/pet' prefix. Resolves the pet by id (or
 * legacy directory alias), then serves exactly the files a manifest declares:
-* pet.json, the declared spritesheet path, and optional 'previews/<name>'
-* media. Composed pets without a manifest file get a synthesized pet.json.
+* pet.json, the entry's servable set (the sprite2d atlas, or the live2d
+* model3.json plus its reference closure — pet-center M3), and optional
+* 'previews/<name>' media. The servable match is an exact string comparison
+* against scan-time normalized paths, so crafted '..' or '.' segments never
+* match; containedRealpath stays as the second layer. Composed pets without
+* a manifest file get a synthesized pet.json.
 */
-function assetHandler(registry) {
+function assetHandler(registry, caps) {
 	const aliases = dirAliases(registry);
 	return (req, res) => {
 		if (!guard(req, res)) return;
@@ -2338,13 +3715,13 @@ function assetHandler(registry) {
 			const manifestFile = join(entry.dir, MANIFEST_FILE);
 			file = existsSync(manifestFile) ? manifestFile : void 0;
 			if (file === void 0) synthesized = true;
-		} else if (rest.length > 0 && rel === entry.spritesheetPath) file = join(entry.dir, entry.spritesheetPath);
+		} else if (rest.length > 0 && entry.servable.includes(rel)) file = join(entry.dir, rel);
 		else if (rest.length === 2 && rest[0] === PREVIEW_DIR && PREVIEW_PATTERN.test(rest[1])) {
 			const preview = join(entry.dir, PREVIEW_DIR, rest[1]);
 			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),
@@ -2362,7 +3739,24 @@ function assetHandler(registry) {
 			res.end();
 			return;
 		}
-		const resolved = file;
+		const resolved = containedRealpath(entry.dir, file);
+		if (resolved === void 0) {
+			res.writeHead(403);
+			res.end();
+			return;
+		}
+		const cap = rest.length === 1 && rest[0] === MANIFEST_FILE ? caps.manifest : IMAGE_EXTENSIONS.has(extensionOf(rel)) ? caps.image : caps.model;
+		try {
+			if (statSync(resolved).size > cap) {
+				res.writeHead(413);
+				res.end();
+				return;
+			}
+		} catch {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
 		readFile(resolved).then((body) => {
 			res.writeHead(200, {
 				"content-type": mimeFor(resolved),
@@ -2380,12 +3774,223 @@ function assetHandler(registry) {
 		});
 	};
 }
-/** Build the full route family (API + assets) for one service. */
+/** Browser-facing base path of the plugin runtime files (pet-center M3). */
+const PET_RUNTIME_PREFIX = "/api/pet/runtime";
+/**
+* The runtime files the route may serve, by exact name (no slashes, no
+* user-controlled path segments, so traversal is structurally impossible):
+* the user-supplied Cubism Core from the pet runtime directory (the plugin
+* never bundles or downloads it — issue #623 M1 §0) and the plugin-shipped
+* MIT vendor bundle from the package lib directory.
+*/
+const RUNTIME_FILES = {
+	"live2dcubismcore.min.js": { root: "runtimeDir" },
+	"live2d-vendor.js": { root: "vendorDir" },
+	"live2d-vendor.js.map": { root: "vendorDir" }
+};
+/**
+* The runtime handler behind '/api/pet/runtime/<name>'. A missing file
+* answers 404 with a JSON marker the client renderer turns into install
+* guidance (the Cubism Core is user-supplied, so its absence is a normal
+* state, not an error).
+*/
+function runtimeHandler(roots) {
+	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 rest = pathname.slice(16).replace(/^\/+/, "");
+		let name;
+		try {
+			name = decodeURIComponent(rest);
+		} catch {
+			res.writeHead(400);
+			res.end();
+			return;
+		}
+		const spec = RUNTIME_FILES[name];
+		if (spec === void 0) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const base = spec.root === "runtimeDir" ? roots.runtimeDir : roots.vendorDir;
+		const file = join(base, name);
+		if (!existsSync(file)) {
+			json(res, 404, {
+				ok: false,
+				error: "runtime-file-missing",
+				file: name
+			});
+			return;
+		}
+		const resolved = containedRealpath(base, file);
+		if (resolved === void 0) {
+			res.writeHead(403);
+			res.end();
+			return;
+		}
+		try {
+			if (statSync(resolved).size > 16777216) {
+				res.writeHead(413);
+				res.end();
+				return;
+			}
+		} catch {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		readFile(resolved).then((body) => {
+			res.writeHead(200, {
+				"content-type": name.endsWith(".map") ? "application/json" : "application/javascript; charset=utf-8",
+				"content-length": String(body.byteLength),
+				"cache-control": "no-cache"
+			});
+			if (req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			res.end(body);
+		}, () => {
+			res.writeHead(404);
+			res.end();
+		});
+	};
+}
+/**
+* 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;
 	const apiRoutes = [
 		getRoute("/api/pet/state", () => service.state()),
 		getRoute("/api/pet/pets", () => service.pets()),
+		getRoute("/api/pet/diagnostics", () => service.diagnostics()),
 		postRoute("/api/pet/interact", (body) => {
 			const kind = body.kind;
 			if (kind !== "pet" && kind !== "feed") return Promise.reject(/* @__PURE__ */ new Error("invalid-kind"));
@@ -2416,9 +4021,27 @@ function makePetRoutes(deps) {
 	const assetRoute = {
 		kind: "prefix",
 		path: PET_ASSET_PREFIX,
-		handler: assetHandler(service.registrySnapshot())
+		handler: assetHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS)
+	};
+	const runtimeRoute = {
+		kind: "prefix",
+		path: PET_RUNTIME_PREFIX,
+		handler: runtimeHandler({
+			runtimeDir: deps.runtimeDir ?? join(dshHome(), "pets", ".runtime"),
+			vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), "lib")
+		})
 	};
-	return [...apiRoutes, assetRoute];
+	const decorationRoute = {
+		kind: "prefix",
+		path: DECORATION_ASSET_PREFIX,
+		handler: decorationHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS)
+	};
+	return [
+		...apiRoutes,
+		assetRoute,
+		runtimeRoute,
+		decorationRoute
+	];
 }
 //#endregion
 //#region src/mount-once.ts
@@ -2482,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. */
@@ -2503,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;