@linxin666/dsh-pet 0.2.2 → 0.2.3

package/lib/client.js

@@ -254,6 +254,7 @@ window.__ModuleLoader__.load({
 			const tracks = definition.tracks;
 			const sequences = definition.sequences;
 			(0, react.useEffect)(() => {
+				if (props.visual !== void 0) return;
 				let cancelled = false;
 				const img = new Image();
 				img.onload = () => {
@@ -264,13 +265,14 @@ window.__ModuleLoader__.load({
 					cancelled = true;
 					img.onload = null;
 				};
-			}, [definition.atlasUrl]);
+			}, [definition.atlasUrl, props.visual]);
 			const spriteScale = display.size / cell.height;
 			const phase = snapshot?.phase ?? "idle";
 			const animation = snapshot?.animation ?? "idle";
 			const scaleRef = (0, react.useRef)(spriteScale);
 			scaleRef.current = spriteScale;
 			(0, react.useEffect)(() => {
+				if (props.visual !== void 0) return;
 				const reduceMotion = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true;
 				const sequence = animation === animationForPhase(phase) ? sequences?.[phase] : void 0;
 				const leadAnimation = sequence?.[0] ?? animation;
@@ -326,7 +328,8 @@ window.__ModuleLoader__.load({
 				columns,
 				rows,
 				tracks,
-				sequences
+				sequences,
+				props.visual
 			]);
 			const feedbackDoneRef = (0, react.useRef)(props.onFeedbackDone);
 			feedbackDoneRef.current = props.onFeedbackDone;
@@ -447,10 +450,12 @@ window.__ModuleLoader__.load({
 						style: {
 							width: spriteWidth,
 							height: spriteHeight,
-							backgroundImage: imageReady ? "url(" + definition.atlasUrl + ")" : void 0,
-							backgroundSize: cell.width * columns * spriteScale + "px " + cell.height * (definition.atlasRows ?? rows.length) * spriteScale + "px",
-							backgroundRepeat: "no-repeat",
-							backgroundPosition: "0 0",
+							...props.visual === void 0 ? {
+								backgroundImage: imageReady ? "url(" + definition.atlasUrl + ")" : void 0,
+								backgroundSize: cell.width * columns * spriteScale + "px " + cell.height * (definition.atlasRows ?? rows.length) * spriteScale + "px",
+								backgroundRepeat: "no-repeat",
+								backgroundPosition: "0 0"
+							} : {},
 							cursor: dragRef.current === null ? "grab" : "grabbing"
 						},
 						onPointerDown,
@@ -461,7 +466,8 @@ window.__ModuleLoader__.load({
 							props.onPet();
 						},
 						role: "button",
-						"aria-label": definition.displayName
+						"aria-label": definition.displayName,
+						children: props.visual
 					}),
 					feedback !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 						ref: bubbleRef,
@@ -606,6 +612,181 @@ window.__ModuleLoader__.load({
 			}), document.body);
 		}
 		//#endregion
+		//#region src/client/renderers/registry.ts
+		/** Renderer dispatch table. */
+		var RendererRegistry = class {
+			renderers = /* @__PURE__ */ new Map();
+			/** Register one renderer implementation (id wins on re-register). */
+			register(renderer) {
+				this.renderers.set(renderer.id, renderer);
+			}
+			/** Whether a renderer kind is available in this build. */
+			has(id) {
+				return this.renderers.has(id);
+			}
+			/** The registered renderer kinds (for diagnostics). */
+			kinds() {
+				return [...this.renderers.keys()].sort();
+			}
+			/** Remove every registration (tests; the client index registers once). */
+			clear() {
+				this.renderers.clear();
+			}
+			/**
+			* Mount a renderer for one activation. An unknown kind renders a clear
+			* diagnostic card into the container instead of failing silently.
+			*/
+			mount(kind, ctx, config) {
+				const renderer = this.renderers.get(kind);
+				if (renderer === void 0) {
+					const note = document.createElement("div");
+					note.dataset.dshPetRendererFallback = kind;
+					note.textContent = "Pet renderer \"" + kind + "\" is not available in this build (supported: " + this.kinds().join(", ") + ").";
+					ctx.container.appendChild(note);
+					ctx.onCleanup(() => note.remove());
+					return { dispose: () => note.remove() };
+				}
+				return renderer.mount(ctx, renderer.validateConfig(config));
+			}
+		};
+		/**
+		* The plugin-wide renderer registry. The client entry registers the
+		* built-in renderers at apply time; the renderer switch and the live2d
+		* bridge dispatch through this instance.
+		*/
+		const defaultPetRendererRegistry = new RendererRegistry();
+		//#endregion
+		//#region src/client/phase-stream.ts
+		/** Create the stream (one per pet entry lifetime, owned by the plugin body). */
+		function createPhaseStream(initial = "idle") {
+			let current = initial;
+			const listeners = /* @__PURE__ */ new Set();
+			return {
+				get: () => current,
+				subscribe(listener) {
+					listeners.add(listener);
+					return () => {
+						listeners.delete(listener);
+					};
+				},
+				push(phase) {
+					if (phase === current) return;
+					current = phase;
+					for (const listener of [...listeners]) listener(phase);
+				}
+			};
+		}
+		//#endregion
+		//#region src/client/renderers/live2d/Live2dVisualMount.tsx
+		/**
+		* Live2D visual mount (pet-center M3) — the React bridge between the pet
+		* center chrome and the imperative live2d renderer. The bridge owns the
+		* contract context (asset base, phase stream, interaction write-back,
+		* activation cleanups), feeds the polled phase into the stream, forwards
+		* sub-4px taps as hit-test coordinates, and renders the localized error
+		* card when the renderer reports a fatal boot failure.
+		* @module @linxin666/dsh-pet/client/renderers/live2d/Live2dVisualMount
+		*/
+		/** Mount the live2d renderer as the sprite's visual (inside the chrome). */
+		function Live2dVisualMount(props) {
+			const containerRef = (0, react.useRef)(null);
+			const streamRef = (0, react.useRef)(null);
+			const handleRef = (0, react.useRef)(null);
+			const downRef = (0, react.useRef)(null);
+			const [error, setError] = (0, react.useState)(null);
+			(0, react.useEffect)(() => {
+				const container = containerRef.current;
+				const live2d = props.definition.live2d;
+				if (container === null || live2d === void 0) return void 0;
+				streamRef.current ??= createPhaseStream(props.phase);
+				const cleanups = [];
+				const ctx = {
+					petId: props.definition.id,
+					assetBase: "/pet/" + encodeURIComponent(props.definition.id),
+					container,
+					phase: streamRef.current,
+					interact: props.onPet,
+					onCleanup: (fn) => {
+						cleanups.push(fn);
+					}
+				};
+				let handle;
+				try {
+					handle = defaultPetRendererRegistry.mount("live2d", ctx, live2d);
+				} catch {
+					setError("load-failed");
+					return () => {
+						for (const fn of cleanups.splice(0)) fn();
+					};
+				}
+				handleRef.current = handle;
+				handle.onError?.(setError);
+				return () => {
+					handleRef.current = null;
+					for (const fn of cleanups.splice(0)) fn();
+					handle.dispose();
+				};
+			}, [props.definition]);
+			(0, react.useEffect)(() => {
+				streamRef.current?.push(props.phase);
+			}, [props.phase]);
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				ref: containerRef,
+				"data-dsh-pet-live2d": props.definition.id,
+				style: {
+					width: "100%",
+					height: "100%"
+				},
+				onPointerDown: (e) => {
+					downRef.current = {
+						x: e.clientX,
+						y: e.clientY
+					};
+				},
+				onPointerUp: (e) => {
+					const down = downRef.current;
+					downRef.current = null;
+					if (down === null) return;
+					if (Math.abs(e.clientX - down.x) > 4 || Math.abs(e.clientY - down.y) > 4) return;
+					const rect = e.currentTarget.getBoundingClientRect();
+					handleRef.current?.tap(e.clientX - rect.left, e.clientY - rect.top);
+				},
+				children: error !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					"data-dsh-pet-live2d-error": error,
+					children: error === "core-missing" ? props.t("pet.live2d.core-missing") : error === "vendor-missing" ? props.t("pet.live2d.vendor-missing") : props.t("pet.live2d.load-failed")
+				})
+			});
+		}
+		//#endregion
+		//#region src/client/renderers/PetRendererSwitch.tsx
+		/**
+		* Renderer switch — the client dispatch seam of the pet center (issue #623,
+		* milestone M2 P5 / M3). The pet's manifest picks the renderer: sprite2d
+		* hands straight through to the sprite; live2d injects its visual INTO the
+		* sprite chrome (the dock, bubbles and panel belong to the pet center, not
+		* the renderer); a renderer this build cannot serve renders a clear
+		* diagnostic card instead of blanking.
+		* @module @linxin666/dsh-pet/client/renderers/PetRendererSwitch
+		*/
+		/** Dispatch one pet definition to its renderer; unknown kinds get a card. */
+		function PetRendererSwitch(props) {
+			const renderer = props.definition.renderer ?? "sprite2d";
+			if (renderer === "sprite2d") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: props.children });
+			if (renderer === "live2d" && defaultPetRendererRegistry.has("live2d") && (0, react.isValidElement)(props.children)) {
+				const visual = /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Live2dVisualMount, {
+					definition: props.definition,
+					phase: props.phase,
+					onPet: props.onPet,
+					t: props.t
+				});
+				return (0, react.cloneElement)(props.children, { visual });
+			}
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				"data-dsh-pet-renderer-fallback": renderer,
+				children: props.t("pet.renderer.unavailable", { renderer })
+			});
+		}
+		//#endregion
 		//#region src/client/PetDockEntry.tsx
 		/**
 		* Global floating pet entry. The pet is host-global (its state, display and
@@ -645,19 +826,25 @@ window.__ModuleLoader__.load({
 			if (visible) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 				"data-pet-dock": true,
 				"data-testid": "pet-dock",
-				children: snapshot === null || definition === null ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PetSprite, {
-					snapshot,
+				children: snapshot === null || definition === null ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PetRendererSwitch, {
 					definition,
-					display: snapshot.display,
-					feedback,
+					phase: snapshot?.phase ?? "idle",
 					onPet: props.pet,
-					onFeed: props.feed,
-					onHide: props.hide,
-					onDragEnd: props.dragEnd,
-					onRename: props.rename,
-					onOpenSession: props.openSession,
-					onFeedbackDone: props.feedbackDone,
-					t: props.t
+					t: props.t,
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PetSprite, {
+						snapshot,
+						definition,
+						display: snapshot.display,
+						feedback,
+						onPet: props.pet,
+						onFeed: props.feed,
+						onHide: props.hide,
+						onDragEnd: props.dragEnd,
+						onRename: props.rename,
+						onOpenSession: props.openSession,
+						onFeedbackDone: props.feedbackDone,
+						t: props.t
+					})
 				})
 			});
 			const display = snapshot?.display ?? DEFAULT_DISPLAY;
@@ -677,6 +864,192 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/contracts/renderer.ts
+		/** Contract version renderers declare against (independent of the manifest). */
+		const PET_RENDERER_API_VERSION = "x-org.linxin666.pet-center/v1alpha1";
+		//#endregion
+		//#region src/client/renderers/live2d/runtime.ts
+		/**
+		* Live2D runtime loading (pet-center M3) — the two scripts a live2d mount
+		* needs, fetched lazily through the plugin's own runtime route: the
+		* user-supplied Cubism Core (proprietary; the plugin never bundles or
+		* downloads it — issue #623 M1 §0) and the plugin-shipped MIT vendor bundle
+		* (pixi.js + untitled-pixi-live2d-engine). Each loads at most once per page;
+		* concurrent mounts share the in-flight promise, and a failure is cached as
+		* 'absent' so a broken install stops retrying the network every mount.
+		*
+		* The vendor surface below is the structural slice the renderer consumes;
+		* the real objects come from 'window.__dshPetLive2d' (lib/live2d-vendor.js),
+		* so this module never imports pixi — the client bundle stays lean.
+		* @module @linxin666/dsh-pet/client/renderers/live2d/runtime
+		*/
+		/** Runtime file URLs the host serves ('/api/pet/runtime/<name>', M3-2). */
+		const CORE_URL = "/api/pet/runtime/live2dcubismcore.min.js";
+		const VENDOR_URL = "/api/pet/runtime/live2d-vendor.js";
+		const defaultInjector = (src) => new Promise((resolve, reject) => {
+			const tag = document.createElement("script");
+			tag.src = src;
+			tag.onload = () => resolve();
+			tag.onerror = () => reject(/* @__PURE__ */ new Error("script failed to load: " + src));
+			document.head.appendChild(tag);
+		});
+		let corePromise;
+		let vendorPromise;
+		/**
+		* Ensure the Cubism Core global exists, injecting the runtime-route script
+		* once when absent. Resolves false when the user has not installed the core
+		* (a normal state — the renderer turns it into install guidance).
+		*/
+		function ensureCubismCore(probe = {}) {
+			if (typeof window !== "undefined" && window.Live2DCubismCore !== void 0) return Promise.resolve(true);
+			if (probe.inject !== void 0) return probe.inject(CORE_URL).then(() => typeof window !== "undefined" && window.Live2DCubismCore !== void 0).catch(() => false);
+			corePromise ??= defaultInjector(CORE_URL).then(() => typeof window !== "undefined" && window.Live2DCubismCore !== void 0).catch(() => false);
+			return corePromise;
+		}
+		/** Ensure the plugin vendor bundle global exists (same caching discipline). */
+		function ensureLive2dVendor(probe = {}) {
+			if (typeof window !== "undefined" && window.__dshPetLive2d !== void 0) return Promise.resolve(window.__dshPetLive2d);
+			if (probe.inject !== void 0) return probe.inject(VENDOR_URL).then(() => typeof window !== "undefined" ? window.__dshPetLive2d : void 0).catch(() => void 0);
+			vendorPromise ??= defaultInjector(VENDOR_URL).then(() => typeof window !== "undefined" ? window.__dshPetLive2d : void 0).catch(() => void 0);
+			return vendorPromise;
+		}
+		//#endregion
+		//#region src/client/renderers/live2d.ts
+		/** The de-facto tap-motion group of Cubism sample models. */
+		const TAP_GROUP = "TapBody";
+		let vendorConfigured = false;
+		/** Configure pixi extensions + the Cubism SDK once per page. */
+		function configureOnce(vendor) {
+			if (vendorConfigured) return;
+			vendorConfigured = true;
+			vendor.extensions.add(vendor.Live2DPlugin);
+			vendor.configureCubismSDK({ memorySizeMB: 32 });
+		}
+		/** Fail-closed config validation (contract: unknown manifest block in). */
+		function validateLive2dConfig(config) {
+			if (typeof config !== "object" || config === null) throw new Error("live2d config is not an object");
+			const source = config;
+			if (typeof source.modelUrl !== "string" || source.modelUrl === "") throw new Error("live2d config modelUrl is required");
+			const motions = source.motions;
+			if (typeof motions !== "object" || motions === null || typeof motions.idle !== "string") throw new Error("live2d config motions.idle is required");
+			return config;
+		}
+		/** The live2d renderer implementation. */
+		const live2dRenderer = {
+			id: "live2d",
+			apiVersion: PET_RENDERER_API_VERSION,
+			validateConfig: validateLive2dConfig,
+			mount(ctx, config) {
+				let disposed = false;
+				let app;
+				let model;
+				let errorListener;
+				let unsubscribe;
+				/** The motion group the current phase maps to (resume target after taps). */
+				let phaseGroup = config.motions.idle;
+				let tapPlaying = false;
+				const playGroup = (group) => {
+					if (model === void 0) return;
+					const groups = model.internalModel.settings.motions ?? {};
+					const count = Array.isArray(groups[group]) ? groups[group].length : 0;
+					if (count === 0) {
+						if (group !== config.motions.idle) playGroup(config.motions.idle);
+						return;
+					}
+					const index = count > 1 ? Math.floor(Math.random() * count) : 0;
+					model.motion(group, index);
+				};
+				const applyPhase = (phase) => {
+					phaseGroup = config.motions[phase] ?? config.motions.idle;
+					playGroup(phaseGroup);
+					const expression = config.expressions?.[phase];
+					if (expression !== void 0 && model !== void 0) model.expression(expression);
+				};
+				const boot = async () => {
+					if (!await ensureCubismCore()) {
+						if (!disposed) errorListener?.("core-missing");
+						return;
+					}
+					const vendor = await ensureLive2dVendor();
+					if (vendor === void 0) {
+						if (!disposed) errorListener?.("vendor-missing");
+						return;
+					}
+					configureOnce(vendor);
+					const pixiApp = new vendor.Application();
+					await pixiApp.init({
+						width: Math.max(1, ctx.container.clientWidth || 160),
+						height: Math.max(1, ctx.container.clientHeight || 174),
+						backgroundAlpha: 0,
+						antialias: true,
+						autoDensity: true,
+						preference: "webgl"
+					});
+					if (disposed) {
+						pixiApp.destroy(true, { children: true });
+						return;
+					}
+					pixiApp.canvas.style.display = "block";
+					pixiApp.canvas.style.width = "100%";
+					pixiApp.canvas.style.height = "100%";
+					ctx.container.appendChild(pixiApp.canvas);
+					const loaded = await vendor.Live2DModel.from(config.modelUrl, {
+						autoHitTest: false,
+						autoFocus: false
+					});
+					if (disposed) {
+						pixiApp.destroy(true, { children: true });
+						return;
+					}
+					app = pixiApp;
+					model = loaded;
+					const fit = Math.min(pixiApp.renderer.width / Math.max(1, loaded.width), pixiApp.renderer.height / Math.max(1, loaded.height)) * .92;
+					loaded.scale.set(fit * (config.scale ?? 1));
+					loaded.anchor.set(.5);
+					loaded.position.set(pixiApp.renderer.width / 2 + (config.translate?.x ?? 0), pixiApp.renderer.height / 2 + (config.translate?.y ?? 0));
+					pixiApp.stage.addChild(loaded);
+					loaded.on("motionFinish", () => {
+						if (tapPlaying) {
+							tapPlaying = false;
+							playGroup(phaseGroup);
+						}
+					});
+					applyPhase(ctx.phase.get());
+					unsubscribe = ctx.phase.subscribe(applyPhase);
+				};
+				boot().catch(() => {
+					if (!disposed) errorListener?.("load-failed");
+				});
+				return {
+					dispose() {
+						if (disposed) return;
+						disposed = true;
+						unsubscribe?.();
+						model = void 0;
+						if (app !== void 0) {
+							app.destroy(true, { children: true });
+							app = void 0;
+						}
+					},
+					tap(x, y) {
+						const current = model;
+						if (disposed || current === void 0) return;
+						const hits = current.hitTest(x, y);
+						const allowed = config.hitAreas;
+						if (!(allowed === void 0 ? hits.length > 0 : hits.some((name) => allowed.includes(name)))) return;
+						const group = (current.internalModel.settings.motions ?? {})[TAP_GROUP];
+						if (!Array.isArray(group) || group.length === 0) return;
+						tapPlaying = true;
+						const index = group.length > 1 ? Math.floor(Math.random() * group.length) : 0;
+						current.motion(TAP_GROUP, index);
+					},
+					onError(listener) {
+						errorListener = listener;
+					}
+				};
+			}
+		};
+		//#endregion
 		//#region \0dsh-css:packages/dsh-pet/src/client/settings-card.module.css.mjs
 		const css$1 = ".kKk9aW_card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:12px;list-style:none;transition:border-color .16s,background .16s}.kKk9aW_card:hover{border-color:var(--dsw-alias-label-dimmed)}.kKk9aW_cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}.kKk9aW_header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}.kKk9aW_header:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}.kKk9aW_headerStatic{border-radius:12px;align-items:center;gap:12px;width:100%;padding:14px 16px;display:flex}.kKk9aW_headText{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}.kKk9aW_name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}.kKk9aW_description{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}.kKk9aW_pending{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;flex:none;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}.kKk9aW_chevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s}.kKk9aW_chevronOpen{transform:rotate(180deg)}.kKk9aW_body{border-top:1px solid var(--dsw-alias-border-l2);margin:0 16px;padding-bottom:8px}.kKk9aW_readOnly{color:var(--dsw-alias-label-tertiary);margin:12px 0 0;font-size:12px;line-height:1.5}.kKk9aW_notExposed{color:var(--dsw-alias-state-warn-primary);margin:12px 0 0;font-size:12px;line-height:1.5}.kKk9aW_footer{border-top:1px solid var(--dsw-alias-border-l2);justify-content:flex-end;align-items:center;gap:8px;padding:12px 0 4px;display:flex}.kKk9aW_failed{min-width:0;color:var(--dsw-alias-label-error);text-overflow:ellipsis;white-space:nowrap;flex:1;margin:0;font-size:12px;line-height:1.5;overflow:hidden}.kKk9aW_discard,.kKk9aW_save{appearance:none;font:inherit;cursor:pointer;border:1px solid #0000;border-radius:8px;padding:5px 14px;font-size:13px;line-height:1.5}.kKk9aW_discard{border-color:var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);background:0 0}.kKk9aW_discard:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-dimmed)}.kKk9aW_save{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3)}.kKk9aW_discard:disabled,.kKk9aW_save:disabled{opacity:.4;cursor:default}.kKk9aW_discard:focus-visible,.kKk9aW_save:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:1px}.kKk9aW_field{flex-direction:column;gap:6px;padding:12px 0;display:flex}.kKk9aW_field+.kKk9aW_field{border-top:1px solid var(--dsw-alias-border-l2)}.kKk9aW_head{align-items:center;gap:8px;display:flex}.kKk9aW_label{min-width:0;color:var(--dsw-alias-label-primary);flex:1;font-size:13px;font-weight:500;line-height:1.5}.kKk9aW_badges{align-items:center;gap:8px;display:inline-flex}.kKk9aW_badge{white-space:nowrap;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary);border-radius:999px;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px}.kKk9aW_reset{font:inherit;color:var(--dsw-alias-label-secondary);cursor:pointer;background:0 0;border:none;padding:0;font-size:12px;line-height:1.5}.kKk9aW_reset:hover:not(:disabled){color:var(--dsw-alias-label-primary)}.kKk9aW_reset:disabled{cursor:default}.kKk9aW_reset:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px;outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}.kKk9aW_input,.kKk9aW_select{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;line-height:1.5}.kKk9aW_input:focus-visible,.kKk9aW_select:focus-visible{border-color:var(--dsw-alias-brand-primary);outline:none}.kKk9aW_input:disabled,.kKk9aW_select:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}.kKk9aW_inputInvalid{border:1px solid var(--dsw-alias-label-error);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 12px;font-size:13px;line-height:1.5}.kKk9aW_inputInvalid:focus-visible{outline:2px solid var(--dsw-alias-label-error);outline-offset:1px;border-color:var(--dsw-alias-label-error)}.kKk9aW_selectWrap{position:relative}.kKk9aW_selectButton{appearance:none;text-align:left;cursor:pointer;justify-content:space-between;align-items:center;gap:8px;width:100%;display:flex}.kKk9aW_selectLabel{text-overflow:ellipsis;white-space:nowrap;min-width:0;overflow:hidden}.kKk9aW_selectChevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s}.kKk9aW_selectChevronOpen{transform:rotate(180deg)}.kKk9aW_selectPopup{z-index:40;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);max-height:240px;box-shadow:0 8px 24px var(--dsw-alias-bg-mask-2);opacity:0;border-radius:8px;flex-direction:column;padding:4px;transition:opacity .1s,transform .1s;display:flex;position:absolute;top:calc(100% + 4px);left:0;right:0;overflow-y:auto;transform:translateY(-4px)}.kKk9aW_selectPopupOpen{opacity:1;transform:none}.kKk9aW_selectPopupClose{opacity:0;pointer-events:none;transform:translateY(-4px)}.kKk9aW_selectOption{color:var(--dsw-alias-label-primary);cursor:pointer;white-space:nowrap;text-overflow:ellipsis;border-radius:6px;padding:6px 10px;font-size:13px;line-height:1.5;overflow:hidden}.kKk9aW_selectOption:hover,.kKk9aW_selectOptionActive{background:var(--dsw-alias-interactive-bg-hover)}.kKk9aW_selectOptionSelected{color:var(--dsw-alias-brand-primary);background:color-mix(in srgb, var(--dsw-alias-brand-primary-new-colorprimary-new-color) 10%, transparent);font-weight:500}.kKk9aW_invalid{color:var(--dsw-alias-label-error);margin:0;font-size:12px;line-height:1.5}.kKk9aW_hint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:1.5}@media (prefers-reduced-motion:reduce){.kKk9aW_card,.kKk9aW_header,.kKk9aW_chevron,.kKk9aW_chevronOpen,.kKk9aW_discard,.kKk9aW_save,.kKk9aW_selectChevron,.kKk9aW_selectChevronOpen,.kKk9aW_selectPopup{transition:none}}";
 		const tagId$1 = "@linxin666/dsh-pet/settings-card.module.css";
@@ -1461,7 +1834,7 @@ window.__ModuleLoader__.load({
 		};
 		//#endregion
 		//#region \0dsh-css:packages/dsh-pet/src/client/settings-section.module.css.mjs
-		const css = ".t0P0pa_sectionList{margin:0;padding:0;list-style:none}";
+		const css = ".t0P0pa_sectionList{margin:0;padding:0;list-style:none}.t0P0pa_diagnostics{border:1px dashed var(--dsw-alias-border-l2);color:var(--dsw-alias-label-dimmed);border-radius:8px;margin:8px 0;padding:8px 12px;font-size:12px}.t0P0pa_diagnosticsTitle{color:var(--dsw-alias-label);margin-bottom:4px;font-weight:600;display:block}.t0P0pa_diagnostics ul{margin:0;padding-left:16px}.t0P0pa_diagnostics li[data-level=error]{color:var(--dsw-alias-error,#c04848)}";
 		const tagId = "@linxin666/dsh-pet/settings-section.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -1470,7 +1843,11 @@ window.__ModuleLoader__.load({
 			tag.textContent = css;
 			document.head.appendChild(tag);
 		}
-		var settings_section_module_css_default = { "sectionList": "t0P0pa_sectionList" };
+		var settings_section_module_css_default = {
+			"diagnostics": "t0P0pa_diagnostics",
+			"diagnosticsTitle": "t0P0pa_diagnosticsTitle",
+			"sectionList": "t0P0pa_sectionList"
+		};
 		//#endregion
 		//#region src/client/PetSettingsCard.tsx
 		/** Fetch the registry list (the same data the sprite renders from). */
@@ -1479,12 +1856,19 @@ window.__ModuleLoader__.load({
 			if (!response.ok) throw new Error("pet pets failed: " + response.status);
 			return await response.json();
 		}
+		/** Fetch the registry diagnostics (v1 migration hints, invalid entries). */
+		async function fetchPetDiagnostics() {
+			const response = await fetch("/api/pet/diagnostics");
+			if (!response.ok) throw new Error("pet diagnostics failed: " + response.status);
+			return (await response.json()).diagnostics ?? [];
+		}
 		/** Bridges the 'pet' scope onto the card's staged form. */
 		var PetSettingsCardController = class {
 			form;
 			store;
 			petChoices = [];
 			petLabels = /* @__PURE__ */ new Map();
+			diagnostics = [];
 			loaded = false;
 			attempts = 0;
 			/** @param scope - the bound settings scope for the 'pet' namespace. */
@@ -1499,6 +1883,16 @@ window.__ModuleLoader__.load({
 				]);
 				this.store = this.form.bind(() => this.projection());
 				this.loadPets();
+				this.loadDiagnostics();
+			}
+			/** Fetch registry diagnostics once (soft-fail: an empty list on error). */
+			async loadDiagnostics() {
+				try {
+					this.diagnostics = await fetchPetDiagnostics();
+					this.store.set(this.projection());
+				} catch {
+					this.diagnostics = [];
+				}
 			}
 			/** Resolve the registry choices once (retried a few times on failure). */
 			async loadPets() {
@@ -1528,7 +1922,8 @@ window.__ModuleLoader__.load({
 					petChoices: this.petChoices.map((id) => ({
 						value: id,
 						label: this.petLabels.get(id) ?? id
-					}))
+					})),
+					petDiagnostics: this.diagnostics
 				};
 			}
 			/**
@@ -1604,6 +1999,17 @@ window.__ModuleLoader__.load({
 							props.resetField("petId");
 						}
 					}),
+					state.petDiagnostics.length === 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
+						className: settings_section_module_css_default.diagnostics,
+						"data-dsh-part": "diagnostics",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: settings_section_module_css_default.diagnosticsTitle,
+							children: t("settings.diagnosticsTitle")
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", { children: state.petDiagnostics.map((diagnostic, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", {
+							"data-level": diagnostic.level,
+							children: diagnostic.message
+						}, index)) })]
+					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(BooleanField, {
 						id: "settings-pet-visible",
 						label: t("settings.visible"),
@@ -1695,10 +2101,15 @@ window.__ModuleLoader__.load({
 			"pet.treats": "小鱼干 ×{n}",
 			"pet.state.loading": "宠物正在赶来…",
 			"pet.state.error": "宠物迷路了（连接失败）",
+			"pet.renderer.unavailable": "这只宠物需要的渲染器（{renderer}）在当前版本不可用。",
+			"pet.live2d.core-missing": "Live2D 核心未安装：请把官方 live2dcubismcore.min.js 放入 $DSH_HOME/pets/.runtime/ 后刷新（步骤见宠物插件 README）。",
+			"pet.live2d.vendor-missing": "Live2D 组件缺失，请升级宠物插件。",
+			"pet.live2d.load-failed": "Live2D 模型加载失败，请检查该宠物目录的完整性。",
 			"pet.openSessionHint": "点击跳转到对应会话",
 			"pet.moreSessions": "展开其余 {n} 个会话的气泡",
 			"pet.collapseSessions": "收起会话气泡",
 			"settings.title": "宠物",
+			"settings.diagnosticsTitle": "宠物目录诊断",
 			"settings.description": "选择宠物并调整它的显示布局。",
 			"settings.pet": "宠物",
 			"settings.petHint": "选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。",
@@ -1741,10 +2152,15 @@ window.__ModuleLoader__.load({
 			"pet.treats": "Treats ×{n}",
 			"pet.state.loading": "The pet is on its way…",
 			"pet.state.error": "The pet is lost (connection failed)",
+			"pet.renderer.unavailable": "This pet needs a renderer ({renderer}) that is not available in this build.",
+			"pet.live2d.core-missing": "Live2D Cubism Core is not installed: place the official live2dcubismcore.min.js under $DSH_HOME/pets/.runtime/ and refresh (see the pet plugin README).",
+			"pet.live2d.vendor-missing": "The Live2D component is missing; please update the pet plugin.",
+			"pet.live2d.load-failed": "The Live2D model failed to load; check the pet directory is complete.",
 			"pet.openSessionHint": "Click to jump to this session",
 			"pet.moreSessions": "Expand {n} more session bubbles",
 			"pet.collapseSessions": "Collapse session bubbles",
 			"settings.title": "Pet",
+			"settings.diagnosticsTitle": "Pet directory diagnostics",
 			"settings.description": "Pick a pet and tune its display layout.",
 			"settings.pet": "Pet",
 			"settings.petHint": "Choose which pet shows. Names are stored per pet; rename from the pet hover panel.",
@@ -1842,6 +2258,7 @@ window.__ModuleLoader__.load({
 				zh,
 				en
 			}), "pet: dictionaries");
+			defaultPetRendererRegistry.register(live2dRenderer);
 			const settingsScope = (ctx.get("webUiSettings") ?? ctx.settingsScope).bind({ namespace: PET_SETTINGS_NS });
 			const enabled = () => {
 				const snapshot = settingsScope.getSnapshot();