@linxin666/dsh-pet 0.2.2 → 0.2.3

package/lib/types/routes.js

@@ -8,11 +8,12 @@
  * optional previews), so adding a pet never touches route wiring.
  * @module @linxin666/dsh-pet/routes
  */
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { petEntryView } from './registry.js';
+import { join, sep } from 'node:path';
+import { petEntryView, petPackageRoot } from './registry.js';
 import { isLoopbackRequest } from './loopback.js';
+import { dshHome } from './dsh-home.js';
 /** Browser-facing base path of the pet API. */
 export const PET_API_PREFIX = '/api/pet';
 /** Browser-facing base path of the pet asset routes ('/pet/<id>/...'). */
@@ -20,6 +21,43 @@ export 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.
+ */
+export 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 = 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.
+ */
+export function containedRealpath(base, candidate) {
+    try {
+        const realBase = realpathSync(base);
+        const realCandidate = realpathSync(candidate);
+        return realCandidate === realBase || realCandidate.startsWith(realBase + sep)
+            ? realCandidate
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const MIME_BY_EXT = {
     '.webp': 'image/webp',
     '.png': 'image/png',
@@ -133,10 +171,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))
@@ -198,8 +240,8 @@ function assetHandler(registry) {
             if (file === undefined)
                 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]);
@@ -224,7 +266,29 @@ function assetHandler(registry) {
             res.end();
             return;
         }
-        const resolved = file;
+        // realpath containment: a symlink escaping the pet directory is refused.
+        const resolved = containedRealpath(entry.dir, file);
+        if (resolved === undefined) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        // Enforce the size ceiling before the file is read into memory.
+        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),
@@ -242,12 +306,111 @@ 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). */
+export const PET_RUNTIME_PREFIX = PET_API_PREFIX + '/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' },
+};
+/** Size ceiling for one runtime file (the Cubism Core is ~200 KB today). */
+export const PET_RUNTIME_CAP = 16 * 1024 * 1024;
+/**
+ * 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(PET_RUNTIME_PREFIX.length).replace(/^\/+/, '');
+        let name;
+        try {
+            name = decodeURIComponent(rest);
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const spec = RUNTIME_FILES[name];
+        // Exact-name allow-list: anything with a path separator never matches.
+        if (spec === undefined) {
+            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 === undefined) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        try {
+            if (statSync(resolved).size > PET_RUNTIME_CAP) {
+                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. */
 export function makePetRoutes(deps) {
     const { service } = deps;
     const apiRoutes = [
         getRoute(PET_API_PREFIX + '/state', () => service.state()),
         getRoute(PET_API_PREFIX + '/pets', () => service.pets()),
+        getRoute(PET_API_PREFIX + '/diagnostics', () => service.diagnostics()),
         postRoute(PET_API_PREFIX + '/interact', (body) => {
             const kind = body.kind;
             if (kind !== 'pet' && kind !== 'feed')
@@ -282,9 +445,17 @@ export 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];
 }
 // Re-exported for the package surface (the registry owns the definition now).
 export { petPackageRoot } from './registry.js';

package/lib/types/service.d.ts

@@ -16,7 +16,7 @@ import type { AffinityConfig, PetAffinityView, PetInteraction } from './affinity
 import type { TreatConfig } from './treats.ts';
 import { type LedgerInteractionResult } from './ledger.ts';
 import { type PetDisplayConfig } from './persist.ts';
-import { type PetDefinition, type PetManifest, type PetRegistry } from './registry.ts';
+import { type PetDefinition, type PetManifest, type PetRegistry, type PetRegistryDiagnostic } from './registry.ts';
 import { type PetStateConfig, type PetStateSnapshot } from './state.ts';
 /** Plugin configuration. */
 export interface PetConfig {
@@ -161,6 +161,10 @@ export declare class PetService extends Service {
     pets(): Promise<PetDefinition[]>;
     /** The loaded registry (the asset routes serve its entries). */
     registrySnapshot(): PetRegistry;
+    /** RPC: structured registry diagnostics (pet-center M2, issue #623). */
+    diagnostics(): Promise<{
+        diagnostics: PetRegistryDiagnostic[];
+    }>;
     /** The selected pet's registry entry. */
     activeEntry(): NonNullable<PetRegistry['entries'][number]>;
     /** Currently selected pet id (persisted). */

package/lib/types/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}

package/lib/types/service.js

@@ -94,6 +94,10 @@ export class PetService 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();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-pet",
   "description": "Multi-pet companion plugin for the dsh web GUI: a registry-driven floating pet that reacts to model activity, with per-pet naming, petting/feeding interactions and an affinity score",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -72,10 +72,12 @@
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
     "jsdom": "29.1.1",
+    "pixi.js": "^8.19.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "tsdown": "^0.22.2",
     "typescript": "^6.0.3",
+    "untitled-pixi-live2d-engine": "1.3.5",
     "vite-tsconfig-paths": "^6.1.1",
     "vitest": "^4.1.8"
   },

package/src/client/PetDockEntry.tsx

@@ -16,6 +16,7 @@ import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetStoreInstance } from './pet-store.ts'
 import { PetSprite } from './PetSprite.tsx'
+import { PetRendererSwitch } from './renderers/PetRendererSwitch.tsx'
 import { NS } from './locales.ts'
 import styles from './pet.module.css'
 
@@ -75,20 +76,27 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
         {snapshot === null || definition === null
           ? null
           : (
-            <PetSprite
-              snapshot={snapshot}
+            <PetRendererSwitch
               definition={definition}
-              display={snapshot.display}
-              feedback={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}
-            />
+            >
+              <PetSprite
+                snapshot={snapshot}
+                definition={definition}
+                display={snapshot.display}
+                feedback={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}
+              />
+            </PetRendererSwitch>
           )}
       </span>
     )

package/src/client/PetSettingsCard.tsx

@@ -48,6 +48,8 @@ export interface PetSettingsCardState extends CardShell {
   petId: CardFieldState
   /** Pet choices (registry ids + display names), loaded from the host. */
   petChoices: readonly { value: string; label: string }[]
+  /** Registry diagnostics (v1 migration hints, invalid entries), host-served. */
+  petDiagnostics: readonly PetDiagnosticView[]
 }
 
 /** The registration-side face the card's slot entry injects. */
@@ -64,6 +66,12 @@ interface PetChoice {
   displayName: string
 }
 
+/** One registry diagnostic as served by '/api/pet/diagnostics' (#623). */
+export interface PetDiagnosticView {
+  level: 'error' | 'warning'
+  message: string
+}
+
 /** Fetch the registry list (the same data the sprite renders from). */
 async function fetchPetChoices(): Promise<PetChoice[]> {
   const response = await fetch('/api/pet/pets')
@@ -71,6 +79,14 @@ async function fetchPetChoices(): Promise<PetChoice[]> {
   return (await response.json()) as PetChoice[]
 }
 
+/** Fetch the registry diagnostics (v1 migration hints, invalid entries). */
+async function fetchPetDiagnostics(): Promise<PetDiagnosticView[]> {
+  const response = await fetch('/api/pet/diagnostics')
+  if (!response.ok) throw new Error('pet diagnostics failed: ' + response.status)
+  const body = (await response.json()) as { diagnostics?: PetDiagnosticView[] }
+  return body.diagnostics ?? []
+}
+
 /** Bridges the 'pet' scope onto the card's staged form. */
 export class PetSettingsCardController {
   private readonly form: CardForm<PetSettings>
@@ -80,6 +96,7 @@ export class PetSettingsCardController {
   // without rebuilding the form.
   private readonly petChoices: string[] = []
   private readonly petLabels = new Map<string, string>()
+  private diagnostics: PetDiagnosticView[] = []
   private loaded = false
   private attempts = 0
 
@@ -95,6 +112,17 @@ export class PetSettingsCardController {
     ])
     this.store = this.form.bind(() => this.projection())
     void this.loadPets()
+    void this.loadDiagnostics()
+  }
+
+  /** Fetch registry diagnostics once (soft-fail: an empty list on error). */
+  private async loadDiagnostics(): Promise<void> {
+    try {
+      this.diagnostics = await fetchPetDiagnostics()
+      this.store.set(this.projection())
+    } catch {
+      this.diagnostics = []
+    }
   }
 
   /** Resolve the registry choices once (retried a few times on failure). */
@@ -124,6 +152,7 @@ export class PetSettingsCardController {
       bottom: this.form.field('bottom'),
       petId: this.form.field('petId'),
       petChoices: this.petChoices.map(id => ({ value: id, label: this.petLabels.get(id) ?? id })),
+      petDiagnostics: this.diagnostics,
     }
   }
 
@@ -197,6 +226,16 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         onEdit={(text) => { props.edit('petId', text) }}
         onReset={() => { props.resetField('petId') }}
       />
+      {state.petDiagnostics.length === 0 ? null : (
+        <li className={sectionCss.diagnostics} data-dsh-part="diagnostics">
+          <span className={sectionCss.diagnosticsTitle}>{t('settings.diagnosticsTitle')}</span>
+          <ul>
+            {state.petDiagnostics.map((diagnostic, index) => (
+              <li key={index} data-level={diagnostic.level}>{diagnostic.message}</li>
+            ))}
+          </ul>
+        </li>
+      )}
       <BooleanField
         id="settings-pet-visible"
         label={t('settings.visible')}

package/src/client/PetSprite.test.tsx

@@ -24,6 +24,7 @@ function petDefinition(): PetDefinition {
     id: 'whale-girl',
     displayName: '鲸鱼娘',
     description: '测试用鲸鱼娘',
+    renderer: 'sprite2d',
     cell: { width: 192, height: 208 },
     columns: 8,
     rows: [6, 8, 8, 4, 5, 8, 6, 6, 6],
@@ -142,6 +143,16 @@ function fireComposingKeydown(target: Element, key: string): void {
   fireEvent.compositionEnd(target)
 }
 
+describe('PetSprite custom visual (pet-center M3)', () => {
+  it('renders the visual inside the sprite box and skips the atlas background', () => {
+    renderPet({ visual: <canvas data-testid="custom-visual" /> })
+    const spriteEl = screen.getByRole('button', { name: '鲸鱼娘' })
+    expect(spriteEl.querySelector('[data-testid="custom-visual"]')).toBeTruthy()
+    // The atlas background never applies while a renderer visual owns the box.
+    expect(spriteEl.style.backgroundImage).toBe('')
+  })
+})
+
 describe('PetSprite rename input', () => {
   it('submits the draft on Enter outside composition', () => {
     const { onRename } = renderPet()

package/src/client/PetSprite.tsx

@@ -10,7 +10,7 @@
  */
 
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactPortal } from 'react'
+import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactNode, ReactPortal } from 'react'
 import { createPortal } from 'react-dom'
 import clsx from 'clsx'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
@@ -48,6 +48,12 @@ export interface PetSpriteProps {
   onOpenSession: (sessionId: string) => void
   /** Clear the reaction bubble (after its CSS animation). */
   onFeedbackDone: () => void
+  /**
+   * Custom visual replacing the sprite2d atlas animation (pet-center M3).
+   * The chrome (drag, bubbles, panel, tap economy) is untouched: the visual
+   * renders inside the sprite box, and the atlas load + frame loop skip.
+   */
+  visual?: ReactNode
   /** Locale translate seat (namespace-bound). */
   t: TranslateNS<typeof NS>
 }
@@ -106,8 +112,10 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const sequences = definition.sequences
 
   // Load the atlas once; the definition carries the authoritative per-row
-  // frame counts and per-track durations, so nothing else is fetched.
+  // frame counts and per-track durations, so nothing else is fetched. A
+  // custom visual (pet-center M3) replaces the atlas entirely.
   useEffect(() => {
+    if (props.visual !== undefined) return
     let cancelled = false
     const img = new Image()
     img.onload = () => {
@@ -118,7 +126,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
       cancelled = true
       img.onload = null
     }
-  }, [definition.atlasUrl])
+  }, [definition.atlasUrl, props.visual])
 
   // Frame loop: advance the current track and write background-position.
   // Offsets must be in SCALED coordinates (background-position applies to the
@@ -132,6 +140,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const scaleRef = useRef(spriteScale)
   scaleRef.current = spriteScale
   useEffect(() => {
+    if (props.visual !== undefined) return
     const reduceMotion = typeof window !== 'undefined'
       && window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches === true
     const sequence = animation === animationForPhase(phase) ? sequences?.[phase] : undefined
@@ -200,7 +209,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
     }
     raf = requestAnimationFrame(tick)
     return () => cancelAnimationFrame(raf)
-  }, [animation, phase, cell, columns, rows, tracks, sequences])
+  }, [animation, phase, cell, columns, rows, tracks, sequences, props.visual])
 
   // Auto-clear the feedback bubble after its CSS animation. The callback
   // rides a ref so re-renders never reset the timer: the 2s poll rebuilds
@@ -343,10 +352,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
         style={{
           width: spriteWidth,
           height: spriteHeight,
-          backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
-          backgroundSize: (cell.width * columns * spriteScale) + 'px ' + (cell.height * (definition.atlasRows ?? rows.length) * spriteScale) + 'px',
-          backgroundRepeat: 'no-repeat',
-          backgroundPosition: '0 0',
+          ...(props.visual === undefined
+            ? {
+                backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
+                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={onPointerDown}
@@ -360,7 +373,9 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
         }}
         role="button"
         aria-label={definition.displayName}
-      />
+      >
+        {props.visual}
+      </div>
       {feedback !== null && (
         <div key={feedback.at} ref={bubbleRef} className={clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet)}>
           {feedback.text}

package/src/client/index.ts

@@ -26,6 +26,8 @@ import { createElement } from 'react'
 import { createRoot } from 'react-dom/client'
 import { createPetStore, type PetStoreInstance } from './pet-store.ts'
 import { PetDockEntry, type PetInjected } from './PetDockEntry.tsx'
+import { defaultPetRendererRegistry } from './renderers/registry.ts'
+import { live2dRenderer } from './renderers/live2d.ts'
 import { PetSettingsSection, PetSettingsCardController, type PetSettings } from './PetSettingsCard.tsx'
 import { NS, en, zh, t } from './locales.ts'
 
@@ -103,6 +105,10 @@ declare module '@deepseek-ai/cordis' {
 export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'pet: dictionaries')
 
+  // Built-in renderers dispatch through the plugin-wide registry (pet-center
+  // M3). Registration is idempotent (id wins), so re-applies stay clean.
+  defaultPetRendererRegistry.register(live2dRenderer)
+
   const binder = ctx.get('webUiSettings') ?? ctx.settingsScope
   const settingsScope = binder.bind<PetSettings>({ namespace: PET_SETTINGS_NS })
   const enabled = (): boolean => {

package/src/client/locales.ts

@@ -19,11 +19,16 @@ export const zh = {
   '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.section 席位）。
   'settings.title': '宠物',
+  'settings.diagnosticsTitle': '宠物目录诊断',
   'settings.description': '选择宠物并调整它的显示布局。',
   'settings.pet': '宠物',
   'settings.petHint': '选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。',
@@ -67,11 +72,16 @@ export const en = {
   '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',
   // First-level settings section (the `settings.section` seat).
   '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.',