@linxin666/dsh-pet 0.1.15 → 0.1.16

package/lib/index.js

@@ -2,11 +2,11 @@ import { a as AFFINITY_MAX, c as applyInteraction, d as emptyAffinity, f as rank
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "schemastery";
 import { Service } from "@deepseek-ai/cordis";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
-import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
 //#region src/event-projection.ts
 /** Fresh projection runtime for a newly seen session. */
 function emptyProjectionRuntime() {
@@ -259,11 +259,23 @@ var PetLedger = class {
 		};
 		this.dirty = true;
 	}
-	/** Replace the pet display name (validation stays a caller concern). */
-	setName(name) {
+	/** Replace the selected pet id (validation stays a caller concern). */
+	setPetId(petId) {
+		if (this.current.petId === petId) return;
 		this.current = {
 			...this.current,
-			name
+			petId
+		};
+		this.dirty = true;
+	}
+	/** Replace one pet's display name (validation stays a caller concern). */
+	setPetName(petId, name) {
+		this.current = {
+			...this.current,
+			names: {
+				...this.current.names,
+				[petId]: name
+			}
 		};
 		this.dirty = true;
 	}
@@ -327,7 +339,7 @@ var PetLedger = class {
 		if (kind === "feed") {
 			const consume = consumeTreat(this.current.treats);
 			if (!consume.ok) return {
-				reaction: "没有小鱼干了，多陪鲸鱼娘工作一会儿吧～",
+				reaction: "没有小鱼干了，多陪我工作一会儿吧～",
 				delta: 0,
 				affinity: this.affinityView(nowMs)
 			};
@@ -401,11 +413,16 @@ const defaultDisplayConfig = {
 	bottom: 20
 };
 const DISPLAY_INSET_MAX = 1e4;
-/** Default pet name (used until the user renames the pet). */
+/** Pet id the legacy single-pet installs resolve to on migration. */
+const DEFAULT_PET_ID = "whale-girl";
+/** Default pet name (used only when a manifest carries no displayName). */
 const DEFAULT_PET_NAME = "鲸鱼娘";
+/** Name constraints. */
+const PET_NAME_MAX_LENGTH = 20;
 function emptyPersist() {
 	return {
-		name: DEFAULT_PET_NAME,
+		petId: DEFAULT_PET_ID,
+		names: {},
 		affinity: emptyAffinity(),
 		treats: emptyTreatLedger(),
 		display: { ...defaultDisplayConfig }
@@ -423,6 +440,18 @@ function petHomeDir() {
 function finiteNum(value, fallback) {
 	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+/** Sanitize the per-pet names map (string keys, non-empty trimmed values). */
+function loadPetNames(parsed) {
+	const names = {};
+	if (typeof parsed.names !== "object" || parsed.names === null) return names;
+	for (const [id, value] of Object.entries(parsed.names)) {
+		if (id === "" || typeof value !== "string") continue;
+		const name = value.trim();
+		if (name === "") continue;
+		names[id] = name.slice(0, 20);
+	}
+	return names;
+}
 /** Clamp one count/score into [0, max]. */
 function clamp(value, max) {
 	return Math.min(max, Math.max(0, value));
@@ -455,8 +484,12 @@ function loadPetPersist(dir = petHomeDir()) {
 			right: Math.round(clamp(finiteNum(rawDisplay.right, base.display.right), DISPLAY_INSET_MAX)),
 			bottom: Math.round(clamp(finiteNum(rawDisplay.bottom, base.display.bottom), DISPLAY_INSET_MAX))
 		};
+		const petId = typeof parsed.petId === "string" && parsed.petId.trim() !== "" ? parsed.petId.trim() : base.petId;
+		const names = loadPetNames(parsed);
+		if (typeof parsed.name === "string" && parsed.name.trim() !== "" && names[petId] === void 0) names[petId] = parsed.name.trim().slice(0, 20);
 		return {
-			name: typeof parsed.name === "string" && parsed.name.trim() !== "" ? parsed.name : base.name,
+			petId,
+			names,
 			affinity,
 			treats,
 			display
@@ -473,6 +506,352 @@ function savePetPersist(data, dir = petHomeDir()) {
 	writeFileSync(tmp, JSON.stringify(data, null, 2), "utf8");
 	renameSync(tmp, target);
 }
+//#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
+* 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
+*      (highest precedence).
+*
+* 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
+* per-track rhythm all fall back to the hatch-pet contract defaults, and the
+* whale-girl manifest overrides its own durations.
+* @module @linxin666/dsh-pet/registry
+*/
+/** Fixed row order of the 9-state animation contract. */
+const PET_ROW_ORDER = [
+	"idle",
+	"running-right",
+	"running-left",
+	"waving",
+	"jumping",
+	"failed",
+	"waiting",
+	"running",
+	"review"
+];
+/** Atlas cell size in px (Codex/hatch-pet contract). */
+const DEFAULT_PET_CELL = {
+	width: 192,
+	height: 208
+};
+/** Columns per row (max frames per track). */
+const DEFAULT_PET_COLUMNS = 8;
+/** Rows in the atlas (fixed by the animation contract). */
+const DEFAULT_PET_ROW_COUNT = 9;
+/**
+* Per-row used-column counts from the hatch-pet contract table. Manifests
+* that carry no 'frames' field (the Codex custom-pet shape) resolve here.
+*/
+const DEFAULT_FRAME_COUNTS = [
+	6,
+	8,
+	8,
+	4,
+	5,
+	8,
+	6,
+	6,
+	6
+];
+/** Absolute package root, resolved from a module URL (lib/ or src/). */
+function petPackageRoot(importMetaUrl) {
+	return fileURLToPath(new URL("../", importMetaUrl));
+}
+/** Resolve the hatch-pet custom pets directory (CODEX_HOME or ~/.codex). */
+function codexPetsDir(env = process.env, home = homedir()) {
+	const raw = env.CODEX_HOME !== void 0 && env.CODEX_HOME.trim() !== "" ? env.CODEX_HOME.trim() : join(home, ".codex");
+	return join(raw === "~" ? home : raw.startsWith("~/") || raw.startsWith("~\\") ? join(home, raw.slice(2)) : raw, "pets");
+}
+/** Finite non-negative integer guard, else the fallback. */
+function finiteInt(value, fallback, max) {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= max ? value : fallback;
+}
+/** Build the browser URL of one pet asset. */
+function assetUrl(prefix, id, file) {
+	const path = file.split("/").filter((segment) => segment !== "").join("/");
+	return prefix + "/" + encodeURIComponent(id) + "/" + path;
+}
+/** Default per-track rhythm (hatch-pet contract table). */
+const DEFAULT_TRACK_PATTERNS = {
+	idle: {
+		durations: [
+			280,
+			110,
+			110,
+			140,
+			140,
+			320
+		],
+		loop: true
+	},
+	"running-right": {
+		durations: [
+			120,
+			120,
+			120,
+			120,
+			120,
+			120,
+			120,
+			220
+		],
+		loop: true
+	},
+	"running-left": {
+		durations: [
+			120,
+			120,
+			120,
+			120,
+			120,
+			120,
+			120,
+			220
+		],
+		loop: true
+	},
+	waving: {
+		durations: [
+			140,
+			140,
+			140,
+			280
+		],
+		loop: true
+	},
+	jumping: {
+		durations: [
+			140,
+			140,
+			140,
+			140,
+			280
+		],
+		loop: false,
+		fallback: "idle"
+	},
+	failed: {
+		durations: [
+			140,
+			140,
+			140,
+			140,
+			140,
+			140,
+			140,
+			240
+		],
+		loop: false,
+		fallback: "idle"
+	},
+	waiting: {
+		durations: [
+			150,
+			150,
+			150,
+			150,
+			150,
+			260
+		],
+		loop: true
+	},
+	running: {
+		durations: [
+			120,
+			120,
+			120,
+			120,
+			120,
+			220
+		],
+		loop: true
+	},
+	review: {
+		durations: [
+			150,
+			150,
+			150,
+			150,
+			150,
+			280
+		],
+		loop: true
+	}
+};
+/** Stable id charset: keeps asset URLs plain and filesystem-safe. */
+const PET_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+/** Safe path-segment charset for atlas files. */
+const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+const PET_NAME_MAX_LENGTH$1 = 80;
+/**
+* Normalize one parsed manifest into a renderable pet entry, or undefined
+* (with a warning recorded) when the manifest violates the contract.
+*/
+function resolvePetManifest(raw, dir, options = {}) {
+	const { assetPrefix = "/pet", warnings = [] } = options;
+	const warn = (message) => {
+		warnings.push(message);
+	};
+	if (typeof raw !== "object" || raw === null) {
+		warn("manifest is not an object");
+		return;
+	}
+	const source = raw;
+	const id = typeof source.id === "string" ? source.id.trim() : "";
+	if (!PET_ID_PATTERN.test(id)) {
+		warn("manifest id " + JSON.stringify(String(source.id)) + " is not a lowercase kebab id");
+		return;
+	}
+	const displayName = typeof source.displayName === "string" && source.displayName.trim() !== "" ? source.displayName.trim().slice(0, PET_NAME_MAX_LENGTH$1) : id;
+	const description = typeof source.description === "string" ? source.description.trim() : "";
+	const spritesheet = typeof source.spritesheetPath === "string" && source.spritesheetPath.trim() !== "" ? source.spritesheetPath.trim() : "spritesheet.webp";
+	const spritesheetPath = spritesheet.split("/").filter((segment) => segment !== "");
+	if (spritesheetPath.length === 0 || isAbsolute(spritesheet) || spritesheet.includes("\\") || spritesheetPath.some((segment) => segment === ".." || !PATH_SEGMENT_PATTERN.test(segment))) {
+		warn("manifest spritesheetPath " + JSON.stringify(spritesheet) + " is not a safe relative path");
+		return;
+	}
+	const rawCell = typeof source.cell === "object" && source.cell !== null ? source.cell : {};
+	const cell = {
+		width: finiteInt(rawCell.width, DEFAULT_PET_CELL.width, 2048),
+		height: finiteInt(rawCell.height, DEFAULT_PET_CELL.height, 2048)
+	};
+	const columns = finiteInt(source.columns, 8, 32);
+	const rows = DEFAULT_FRAME_COUNTS.map((fallback, index) => {
+		return finiteInt(Array.isArray(source.frames) ? source.frames[index] : void 0, fallback, columns);
+	});
+	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 }
+		};
+	}
+	return {
+		id,
+		displayName,
+		description,
+		cell,
+		columns,
+		rows,
+		tracks,
+		atlasUrl: assetUrl(assetPrefix, id, spritesheet),
+		manifestUrl: assetUrl(assetPrefix, id, "pet.json"),
+		dir,
+		spritesheetPath: spritesheetPath.join("/")
+	};
+}
+/** Scan one directory of pet folders; entries come back in name order. */
+function scanPetDir(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 manifestFile = join(dir, name, "pet.json");
+		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);
+	}
+	return entries;
+}
+/** Read and parse one manifest file; undefined (warning recorded) on failure. */
+function readPetJson(file, warnings) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch (error) {
+		warnings?.push("skipping " + file + ": " + (error instanceof Error ? error.message : String(error)));
+		return;
+	}
+}
+/**
+* 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
+* bad manifest: it skips it and records a warning.
+*/
+function loadPetRegistry(options) {
+	const { packageRoot, assetPrefix = "/pet" } = options;
+	const warnings = [];
+	const byId = /* @__PURE__ */ new Map();
+	const builtinIds = /* @__PURE__ */ new Set();
+	for (const entry of scanPetDir(join(packageRoot, "assets"), {
+		assetPrefix,
+		warnings
+	})) {
+		if (byId.has(entry.id)) {
+			warnings.push("duplicate built-in pet id " + entry.id + "; the first one wins");
+			continue;
+		}
+		byId.set(entry.id, entry);
+		builtinIds.add(entry.id);
+	}
+	const petsDir = options.petsDir ?? codexPetsDir();
+	if (petsDir !== "") for (const entry of scanPetDir(petsDir, {
+		assetPrefix,
+		warnings
+	})) {
+		if (byId.has(entry.id)) warnings.push("custom pet " + entry.id + " overrides the built-in one");
+		byId.set(entry.id, entry);
+	}
+	for (const manifest of options.extra ?? []) {
+		const entry = resolvePetManifest(manifest, manifest.spritesheetPath === void 0 || isAbsolute(manifest.spritesheetPath) ? join(packageRoot, "assets", "extra") : dirname(resolve(packageRoot, manifest.spritesheetPath)), {
+			assetPrefix,
+			warnings
+		});
+		if (entry === void 0) continue;
+		if (byId.has(entry.id)) warnings.push("composed pet " + entry.id + " overrides an earlier registration");
+		byId.set(entry.id, entry);
+	}
+	const entries = [...byId.values()];
+	return {
+		entries,
+		warnings,
+		byId: (id) => byId.get(id),
+		defaultEntry: () => entries.find((entry) => builtinIds.has(entry.id)) ?? entries[0]
+	};
+}
+/** Strip host-only fields, leaving the client-visible definition. */
+function petEntryView(entry) {
+	return {
+		id: entry.id,
+		displayName: entry.displayName,
+		description: entry.description,
+		cell: entry.cell,
+		columns: entry.columns,
+		rows: entry.rows,
+		tracks: entry.tracks,
+		atlasUrl: entry.atlasUrl,
+		manifestUrl: entry.manifestUrl
+	};
+}
 /**
 * Cordis service exposing the pet RPC domain. Lazy: nothing is scanned or
 * written until an economic event or interaction arrives; event listeners
@@ -483,6 +862,7 @@ var PetService = class extends Service {
 	static inject = [];
 	machine;
 	ledger;
+	registry;
 	persistDir;
 	enabled;
 	disposeActivity;
@@ -492,11 +872,21 @@ var PetService = class extends Service {
 	constructor(ctx, config = {}) {
 		super(ctx, "pet");
 		this.persistDir = config.persistDir ?? petHomeDir();
+		this.registry = config.registry ?? loadPetRegistry({
+			packageRoot: petPackageRoot(import.meta.url),
+			...config.pets === void 0 ? {} : { extra: config.pets }
+		});
+		if (this.registry.entries.length === 0) throw new Error("[dsh-pet] no valid pet manifests found; nothing to render");
+		let persist = loadPetPersist(this.persistDir);
+		if (this.registry.byId(persist.petId) === void 0) persist = {
+			...persist,
+			petId: this.registry.defaultEntry().id
+		};
 		const ledgerConfig = {
 			affinity: config.affinity,
 			treats: config.treats
 		};
-		this.ledger = new PetLedger(loadPetPersist(this.persistDir), ledgerConfig);
+		this.ledger = new PetLedger(persist, ledgerConfig);
 		this.machine = new PetStateMachine({
 			...defaultPetStateConfig,
 			...config.state ?? {}
@@ -516,9 +906,42 @@ var PetService = class extends Service {
 	display() {
 		return { ...this.ledger.snapshot.display };
 	}
-	/** Current persisted pet name (read-only view). */
-	petName() {
-		return this.ledger.snapshot.name;
+	/** RPC: the registry entries the browser half renders and selects from. */
+	async pets() {
+		return this.registry.entries.map(petEntryView);
+	}
+	/** The loaded registry (the asset routes serve its entries). */
+	registrySnapshot() {
+		return this.registry;
+	}
+	/** The selected pet's registry entry. */
+	activeEntry() {
+		return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry();
+	}
+	/** Currently selected pet id (persisted). */
+	selectedPetId() {
+		return this.ledger.snapshot.petId;
+	}
+	/** The display name of one pet (user rename or manifest displayName). */
+	petName(petId = this.selectedPetId()) {
+		const stored = this.ledger.snapshot.names[petId];
+		if (stored !== void 0 && stored.trim() !== "") return stored;
+		return this.registry.byId(petId)?.displayName ?? "鲸鱼娘";
+	}
+	/** RPC: switch the selected pet (persisted, settings document mirrored). */
+	async setPetId(petId) {
+		const entry = this.registry.byId(petId);
+		if (entry === void 0) return {
+			ok: false,
+			error: "unknown-pet"
+		};
+		this.ledger.setPetId(entry.id);
+		this.flush();
+		this.syncSettingsFromPet();
+		return {
+			ok: true,
+			petId: entry.id
+		};
 	}
 	/** Start or stop the session-activity listeners that drive the pet. */
 	setEnabled(enabled) {
@@ -612,7 +1035,7 @@ var PetService = class extends Service {
 			display: this.ledger.snapshot.display
 		};
 	}
-	/** RPC: rename the pet (trimmed, 1–20 chars). */
+	/** RPC: rename the selected pet (trimmed, 1–20 chars, per-pet storage). */
 	async setName(name) {
 		const trimmed = name.trim();
 		if (trimmed === "") return {
@@ -623,28 +1046,28 @@ var PetService = class extends Service {
 			ok: false,
 			error: "name-too-long"
 		};
-		this.ledger.setName(trimmed);
+		this.ledger.setPetName(this.selectedPetId(), trimmed);
 		this.flush();
-		this.syncSettingsFromPet();
 		return {
 			ok: true,
 			name: trimmed
 		};
 	}
 	/**
-	* Apply a committed settings section to the persisted display config. Called
-	* by the settings surface on every change; values are clamped exactly like
-	* the setConfig RPC so both write paths converge.
+	* Apply a committed settings section to the persisted selection and display
+	* config. Called by the settings surface on every change; values are
+	* clamped exactly like the setConfig RPC so both write paths converge.
 	* @param section - the resolved settings section.
 	*/
 	applySettingsSection(section) {
+		if (typeof section.petId === "string" && this.registry.byId(section.petId) !== void 0) this.ledger.setPetId(section.petId);
+		else if (section.petId !== void 0) this.syncSettingsFromPet();
 		const next = { ...this.ledger.snapshot.display };
 		next.visible = section.visible && (section.enabled ?? true);
 		next.size = Math.round(Math.min(512, Math.max(32, section.size)));
 		next.right = Math.round(Math.min(DISPLAY_INSET_MAX, Math.max(0, section.right)));
 		next.bottom = Math.round(Math.min(DISPLAY_INSET_MAX, Math.max(0, section.bottom)));
 		this.ledger.setDisplay(next);
-		this.ledger.setName(section.name.trim());
 		this.flush();
 	}
 	/** Mirror the persisted display config into the settings document (best-effort). */
@@ -657,7 +1080,7 @@ var PetService = class extends Service {
 			size: snapshot.display.size,
 			right: snapshot.display.right,
 			bottom: snapshot.display.bottom,
-			name: snapshot.name
+			petId: snapshot.petId
 		}).catch(() => {});
 	}
 	/** Award the turn reward once per completed turn (idempotent per session + turn). */
@@ -670,6 +1093,7 @@ var PetService = class extends Service {
 	}
 	view() {
 		const snapshot = this.machine.render();
+		const entry = this.activeEntry();
 		return {
 			animation: snapshot.animation,
 			...snapshot.bubble === void 0 ? {} : { bubble: snapshot.bubble },
@@ -677,7 +1101,12 @@ var PetService = class extends Service {
 			sessionActive: snapshot.sessionActive,
 			affinity: this.ledger.affinityView(Date.now()),
 			display: { ...this.ledger.snapshot.display },
-			name: this.ledger.snapshot.name,
+			pet: {
+				id: entry.id,
+				displayName: entry.displayName,
+				description: entry.description
+			},
+			name: this.petName(),
 			treats: {
 				stocked: this.ledger.snapshot.treats.treats,
 				max: this.ledger.treatMax
@@ -692,21 +1121,36 @@ var PetService = class extends Service {
 };
 //#endregion
 //#region src/routes.ts
+/**
+* Pet HTTP routes — the browser half talks to the host through plain
+* same-origin JSON endpoints ('/api/pet/*') and loads pet assets from
+* '/pet/<id>/*'. The '/plugins/' endpoint only serves client bundles and RPC
+* domains are platform-registered, so the pet serves its own API and media —
+* the same pattern as dsh-remote-web-ui's '/api/pair' family. The asset route
+* is one prefix registration serving every registry entry (manifest, atlas,
+* optional previews), so adding a pet never touches route wiring.
+* @module @linxin666/dsh-pet/routes
+*/
 /** Browser-facing base path of the pet API. */
 const PET_API_PREFIX = "/api/pet";
-/** Browser-facing base path of the pet asset routes. */
-const PET_ASSET_PREFIX = "/pet/whale";
-/** Relative (to package root) asset files exposed under the prefix. */
-const ASSET_FILES = [{
-	name: "spritesheet.webp",
-	mime: "image/webp"
-}, {
-	name: "pet.json",
-	mime: "application/json"
-}];
-/** Absolute package root, resolved from this module's own location (lib/). */
-function petPackageRoot(importMetaUrl) {
-	return fileURLToPath(new URL("../", importMetaUrl));
+/** Browser-facing base path of the pet asset routes ('/pet/<id>/...'). */
+const PET_ASSET_PREFIX = "/pet";
+const MANIFEST_FILE = "pet.json";
+const PREVIEW_DIR = "previews";
+const PREVIEW_PATTERN = /^[A-Za-z0-9._-]+$/;
+const MIME_BY_EXT = {
+	".webp": "image/webp",
+	".png": "image/png",
+	".gif": "image/gif",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".json": "application/json"
+};
+/** Content type by file extension (safe fallback: octet-stream). */
+function mimeFor(file) {
+	const dot = file.lastIndexOf(".");
+	if (dot < 0) return "application/octet-stream";
+	return MIME_BY_EXT[file.slice(dot).toLowerCase()] ?? "application/octet-stream";
 }
 /** Write one JSON response. */
 function json(res, status, body) {
@@ -789,60 +1233,157 @@ function postRoute(path, run) {
 		}
 	};
 }
-/** Build the full route family (API + assets) for one service + package root. */
+/** Legacy URL aliases: each entry's directory basename (e.g. 'whale'). */
+function dirAliases(registry) {
+	const aliases = /* @__PURE__ */ new Map();
+	for (const entry of registry.entries) {
+		const alias = entry.dir.split(/[\\/]/).pop() ?? "";
+		if (alias !== "" && !aliases.has(alias)) aliases.set(alias, entry);
+	}
+	return aliases;
+}
+/**
+* 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.
+*/
+function assetHandler(registry) {
+	const aliases = dirAliases(registry);
+	return (req, res) => {
+		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 !== "");
+		if (segments[0] !== "pet" || segments[1] === void 0) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		let id;
+		try {
+			id = decodeURIComponent(segments[1]);
+		} catch {
+			res.writeHead(400);
+			res.end();
+			return;
+		}
+		const entry = registry.byId(id) ?? aliases.get(id);
+		if (entry === void 0) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const rest = [];
+		for (const segment of segments.slice(2)) {
+			let decoded;
+			try {
+				decoded = decodeURIComponent(segment);
+			} catch {
+				res.writeHead(400);
+				res.end();
+				return;
+			}
+			rest.push(decoded);
+		}
+		const rel = rest.join("/");
+		let file;
+		let synthesized = false;
+		if (rest.length === 1 && rest[0] === MANIFEST_FILE) {
+			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 === 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");
+			res.writeHead(200, {
+				"content-type": "application/json; charset=utf-8",
+				"content-length": String(body.byteLength),
+				"cache-control": "no-cache"
+			});
+			if (req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			res.end(body);
+			return;
+		}
+		if (file === void 0) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const resolved = file;
+		readFile(resolved).then((body) => {
+			res.writeHead(200, {
+				"content-type": mimeFor(resolved),
+				"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) for one service. */
 function makePetRoutes(deps) {
-	const { service, packageRoot } = deps;
+	const { service } = deps;
 	const apiRoutes = [
-		getRoute(`${PET_API_PREFIX}/state`, () => service.state()),
-		postRoute(`${PET_API_PREFIX}/interact`, (body) => {
+		getRoute("/api/pet/state", () => service.state()),
+		getRoute("/api/pet/pets", () => service.pets()),
+		postRoute("/api/pet/interact", (body) => {
 			const kind = body.kind;
 			if (kind !== "pet" && kind !== "feed") return Promise.reject(/* @__PURE__ */ new Error("invalid-kind"));
 			return service.interact(kind);
 		}),
-		postRoute(`${PET_API_PREFIX}/set-visible`, (body) => {
+		postRoute("/api/pet/set-visible", (body) => {
 			const visible = body.visible;
 			if (typeof visible !== "boolean") return Promise.reject(/* @__PURE__ */ new Error("invalid-visible"));
 			return service.setVisible(visible);
 		}),
-		postRoute(`${PET_API_PREFIX}/set-config`, (body) => service.setConfig({
+		postRoute("/api/pet/set-config", (body) => service.setConfig({
 			...typeof body.size === "number" ? { size: body.size } : {},
 			...typeof body.right === "number" ? { right: body.right } : {},
 			...typeof body.bottom === "number" ? { bottom: body.bottom } : {},
 			...typeof body.visible === "boolean" ? { visible: body.visible } : {}
 		})),
-		postRoute(`${PET_API_PREFIX}/set-name`, (body) => {
+		postRoute("/api/pet/set-name", (body) => {
 			const name = body.name;
 			if (typeof name !== "string") return Promise.reject(/* @__PURE__ */ new Error("invalid-name"));
 			return service.setName(name);
+		}),
+		postRoute("/api/pet/set-pet", (body) => {
+			const petId = body.petId;
+			if (typeof petId !== "string") return Promise.reject(/* @__PURE__ */ new Error("invalid-pet"));
+			return service.setPetId(petId);
 		})
 	];
-	const assetRoutes = ASSET_FILES.map((file) => ({
-		kind: "exact",
-		path: `${PET_ASSET_PREFIX}/${file.name}`,
-		handler: (req, res) => {
-			if (req.method !== "GET" && req.method !== "HEAD") {
-				res.writeHead(405);
-				res.end();
-				return;
-			}
-			return readFile(join(packageRoot, "assets", "whale", file.name)).then((body) => {
-				res.writeHead(200, {
-					"content-type": file.mime,
-					"content-length": String(body.byteLength),
-					"cache-control": "no-cache"
-				});
-				if (req.method === "HEAD") {
-					res.end();
-					return;
-				}
-				res.end(body);
-			}, () => {
-				res.writeHead(404);
-				res.end();
-			});
-		}
-	}));
-	return [...apiRoutes, ...assetRoutes];
+	const assetRoute = {
+		kind: "prefix",
+		path: PET_ASSET_PREFIX,
+		handler: assetHandler(service.registrySnapshot())
+	};
+	return [...apiRoutes, assetRoute];
 }
 //#endregion
 //#region src/index.ts
@@ -850,31 +1391,44 @@ function makePetRoutes(deps) {
 const name = "pet";
 /** Services required before the pet can mount its surfaces. */
 const inject = ["webServer"];
-/** Settings section schema: the display fields and name the web settings surface edits. */
-const PET_SETTINGS_SCHEMA = z.object({
-	visible: z.boolean().default(true),
-	size: z.number().step(1).min(32).max(512).default(160),
-	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),
-	name: z.string().min(1).max(20).pattern(/\S/).default(DEFAULT_PET_NAME),
-	enabled: z.boolean().default(true)
-});
+/**
+* Settings section schema: pet selection and display fields the web settings
+* surface edits. petId is a plain string on purpose: the service clamps the
+* resolved value against the registry, so a stored selection that points at
+* a removed pet cannot invalidate the section (a strict union would refuse
+* the whole registration). The settings card renders the actual registry
+* choices itself from '/api/pet/pets'.
+*/
+function makePetSettingsSchema(fallbackPetId) {
+	return z.object({
+		visible: z.boolean().default(true),
+		size: z.number().step(1).min(32).max(512).default(160),
+		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)
+	});
+}
 /** Register the pet service and its API + asset routes on the context. */
 function apply(ctx, config = {}) {
-	const service = new PetService(ctx, config);
+	const registry = config.registry ?? loadPetRegistry({
+		packageRoot: petPackageRoot(import.meta.url),
+		...config.pets === void 0 ? {} : { extra: config.pets }
+	});
+	const service = new PetService(ctx, {
+		...config,
+		registry
+	});
 	let current = () => base;
 	const base = {
 		visible: service.display().visible,
 		size: service.display().size,
 		right: service.display().right,
 		bottom: service.display().bottom,
-		name: service.petName(),
+		petId: service.selectedPetId(),
 		enabled: config.enabled ?? true
 	};
-	const routes = makePetRoutes({
-		service,
-		packageRoot: petPackageRoot(import.meta.url)
-	});
+	const routes = makePetRoutes({ service });
 	let disposeRoutes;
 	const syncRoutes = () => {
 		const enabled = current().enabled ?? true;
@@ -889,7 +1443,7 @@ function apply(ctx, config = {}) {
 			disposeRoutes = void 0;
 		}
 	};
-	installSettingsSection(ctx, settingsNamespace("pet"), PET_SETTINGS_SCHEMA, base, {
+	installSettingsSection(ctx, settingsNamespace("pet"), makePetSettingsSchema(service.selectedPetId()), base, {
 		setSource: (source) => {
 			current = source;
 		},
@@ -903,4 +1457,4 @@ function apply(ctx, config = {}) {
 	syncRoutes();
 }
 //#endregion
-export { AFFINITY_MAX, AFFINITY_RANKS, PET_API_PREFIX, PET_ASSET_PREFIX, PET_SETTINGS_SCHEMA, PetService, PetStateMachine, animationForPhase, apply, applyInteraction, applyTurnReward, consumeTreat, defaultDisplayConfig, defaultTreatConfig, emptyAffinity, emptyPersist, emptyTreatLedger, inject, loadPetPersist, makePetRoutes, name, petHomeDir, petPackageRoot, rankOf, rowOf, savePetPersist, settleTreatGrants };
+export { AFFINITY_MAX, AFFINITY_RANKS, DEFAULT_FRAME_COUNTS, DEFAULT_PET_CELL, DEFAULT_PET_COLUMNS, DEFAULT_PET_ID, DEFAULT_PET_NAME, DEFAULT_PET_ROW_COUNT, DEFAULT_TRACK_PATTERNS, PET_API_PREFIX, PET_ASSET_PREFIX, PET_NAME_MAX_LENGTH, PET_ROW_ORDER, PetService, PetStateMachine, animationForPhase, apply, applyInteraction, applyTurnReward, codexPetsDir, consumeTreat, defaultDisplayConfig, defaultTreatConfig, emptyAffinity, emptyPersist, emptyTreatLedger, inject, loadPetPersist, loadPetRegistry, makePetRoutes, makePetSettingsSchema, name, petEntryView, petHomeDir, petPackageRoot, rankOf, resolvePetManifest, rowOf, savePetPersist, settleTreatGrants };