@linxin666/dsh-pet 0.2.2 → 0.2.3

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";
@@ -1373,19 +1373,409 @@ function savePetPersist(data, dir = petHomeDir()) {
 	writeFileSync(tmp, JSON.stringify(data, null, 2), "utf8");
 	renameSync(tmp, target);
 }
+/** 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$1 = /^[a-z0-9][a-z0-9-]*$/;
+const PATH_SEGMENT_PATTERN$1 = /^[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 = 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));
+}
+/**
+* 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$1.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(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(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(raw)) {
+		diag.error("renderer sprite2d requires a \"sprite2d\" block object");
+		return;
+	}
+	const extra = unknownKeys(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? }");
+	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(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)) {
+		diag.error("renderer live2d requires a \"live2d\" block object");
+		return;
+	}
+	const extra = unknownKeys(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(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$1.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 (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 (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(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");
+	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(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(sourceLabel);
+	if (!isRecord(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
+	};
+}
+//#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 +1986,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 +2051,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 +2068,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,7 +2187,34 @@ 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);
+		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;
+		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;
+		}
+		const entry = resolvePetManifest(legacy, entryDir, options);
 		if (entry !== void 0) entries.push(entry);
 	}
 	return entries;
@@ -1709,11 +2237,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 +2255,21 @@ 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");
+	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);
+	}
 	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));
@@ -1748,6 +2288,7 @@ function loadPetRegistry(options) {
 	return {
 		entries,
 		warnings,
+		diagnostics,
 		byId: (id) => byId.get(id),
 		defaultEntry: () => entries.find((entry) => builtinIds.has(entry.id)) ?? entries[0]
 	};
@@ -1758,6 +2299,8 @@ function petEntryView(entry) {
 		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,
@@ -1841,6 +2384,10 @@ var PetService = class extends Service {
 	registrySnapshot() {
 		return this.registry;
 	}
+	/** RPC: structured registry diagnostics (pet-center M2, issue #623). */
+	async diagnostics() {
+		return { diagnostics: this.registry.diagnostics };
+	}
 	/** The selected pet's registry entry. */
 	activeEntry() {
 		return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry();
@@ -2161,6 +2708,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 +2866,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,7 +2929,7 @@ 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;
@@ -2362,7 +2953,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 +2988,108 @@ 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();
+		});
+	};
+}
+/** 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 +3120,21 @@ 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];
+	return [
+		...apiRoutes,
+		assetRoute,
+		runtimeRoute
+	];
 }
 //#endregion
 //#region src/mount-once.ts