@linxin666/dsh-pet 0.2.2 → 0.2.4

package/lib/types/chatter.d.ts

@@ -17,6 +17,11 @@
  * plugin has always shown, so existing installs keep their wording until the
  * scene cycles. No emoji anywhere (repository rule); ～ is the whale-girl's
  * signature.
+ *
+ * Since pet-center M4 (issue #677) every pool is overridable through a
+ * {@link VoicePoolsProvider}: the built-in pools are the fallback layer, and
+ * voice packs (per-pet voice.json / the global .voice.json) layer their
+ * pools on top at draw time.
  * @module @linxin666/dsh-pet/chatter
  */
 /** Status copy scenes — the situations a session bubble can report. */
@@ -27,6 +32,10 @@ export declare const STATUS_ROTATE_MS = 4000;
 export declare const STATUS_POOLS: Readonly<Record<StatusScene, readonly string[]>>;
 /** Tool families for friendlier per-tool status copy. */
 export type ToolCategory = 'read' | 'write' | 'edit' | 'shell' | 'grep' | 'find' | 'ls' | 'webSearch' | 'webFetch' | 'mcp' | 'memory' | 'subagent' | 'todo' | 'browser' | 'git' | 'ask' | 'generic';
+/** Every status scene key, in declaration order (voice-pack key allow-list). */
+export declare const STATUS_SCENES: readonly StatusScene[];
+/** Every tool-family key, in declaration order (voice-pack key allow-list). */
+export declare const TOOL_CATEGORIES: readonly ToolCategory[];
 /** Map a raw tool name onto its copy family (working-activity style regexes). */
 export declare function toolCategory(toolName: string): ToolCategory;
 /**
@@ -52,16 +61,23 @@ export declare function toolArgHint(toolName: string, argumentsJson: string): st
  * stretch keeps changing its wording.
  */
 export declare class StatusVoice {
+    private readonly pools;
     private readonly rotateMs;
     private readonly counters;
     private lastScene;
     private lastLine;
     private lastLineAt;
-    constructor(rotateMs?: number);
+    constructor(pools?: VoicePoolsProvider, rotateMs?: number);
     /** Draw the next line of one pool, advancing its round-robin cursor. */
     private draw;
     /** Reuse the stable line or advance when the cadence elapsed. */
     private voice;
+    /**
+     * A scene's effective pool: the voice-pack override when it carries lines,
+     * else the built-in pool. Empty overrides fall back rather than blank the
+     * bubble — a scene line always renders.
+     */
+    private scenePool;
     /** Status line for a phase scene. */
     scene(scene: StatusScene, nowMs: number): string;
     /** Status line for a tool call, with the real-argument hint when known. */
@@ -85,22 +101,64 @@ export declare const WHISPER_TTL_MS = 8000;
 export declare const WHISPER_GENERIC_POOL: readonly string[];
 /** Keyword-triggered whisper rules, most specific moods first. */
 export declare const WHISPER_RULES: readonly WhisperRule[];
+/**
+ * Voice-pack overrides (pet-center M4, issue #677): the content a voice
+ * pack can replace, one pool at a time. Every field is optional — missing
+ * keys inherit the built-in pools. Resolution happens at draw time through
+ * a provider function, so swapping pets (or editing the global file) re-
+ * voices live engines without rebuilding them.
+ *
+ * Override semantics:
+ *  - status/tools/toolRemaining: a non-empty override replaces the built-in
+ *    pool for that key; an empty override falls back to the built-in pool
+ *    (a scene line always renders, so it can never be blanked).
+ *  - whispers.generic / whispers.rules: the override REPLACES the built-in
+ *    section; an empty array mutes that channel (ambient or keyword).
+ */
+export interface VoicePackOverrides {
+    /** Status copy pools by scene; each key replaces that scene's pool. */
+    status?: Partial<Record<StatusScene, readonly string[]>>;
+    /** Tool copy pools by family; each key replaces that family's pool. */
+    tools?: Partial<Record<ToolCategory, readonly string[]>>;
+    /** The parallel-tools count line pool ({n} interpolates the count). */
+    toolRemaining?: readonly string[];
+    /** Murmur pools; each section replaces the built-in one as a whole. */
+    whispers?: {
+        /** Ambient inner-whisper pool (empty mutes ambient whispers). */
+        generic?: readonly string[];
+        /** Ordered keyword rules (empty disables keyword-triggered whispers). */
+        rules?: readonly WhisperRule[];
+    };
+}
+/** Read the current effective voice-pack overrides (draw-time resolution). */
+export type VoicePoolsProvider = () => VoicePackOverrides;
+/** The built-in voice pack: the plugin's default copy, unchanged since v1. */
+export declare const BUILTIN_VOICE_PACK: VoicePackOverrides;
 /**
  * The murmur engine (碎碎念): watches the model's own output and lets the pet
  * whisper its inner voice. Two ways to earn a whisper:
  *  - a keyword rule matches the fresh chunk text (themed whisper);
  *  - enough output volume flowed by without one (ambient whisper).
  * A cooldown keeps whispers occasional; all picks are round-robin so tests
- * reproduce exact lines.
+ * reproduce exact lines. The voice-pack provider (pet-center M4) swaps the
+ * pools at draw time, so a pet switch re-voices live engines in place.
  */
 export declare class WhisperEngine {
+    private readonly pools;
     private readonly cooldownMs;
     private readonly charBudget;
     private readonly counters;
     private genericCursor;
     private lastWhisperAt;
     private charsSinceWhisper;
-    constructor(cooldownMs?: number, charBudget?: number);
+    constructor(pools?: VoicePoolsProvider, cooldownMs?: number, charBudget?: number);
+    /**
+     * Effective keyword rules: an override replaces the built-in rules as a
+     * whole; an explicit empty array disables keyword-triggered whispers.
+     */
+    private rules;
+    /** Effective ambient pool (an explicit empty array mutes ambient whispers). */
+    private generic;
     /**
      * Feed one model-output chunk (reasoning or text). Returns the whisper to
      * show, or undefined when the moment stays quiet.

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

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

package/lib/types/chatter.js

@@ -17,6 +17,11 @@
  * plugin has always shown, so existing installs keep their wording until the
  * scene cycles. No emoji anywhere (repository rule); ～ is the whale-girl's
  * signature.
+ *
+ * Since pet-center M4 (issue #677) every pool is overridable through a
+ * {@link VoicePoolsProvider}: the built-in pools are the fallback layer, and
+ * voice packs (per-pet voice.json / the global .voice.json) layer their
+ * pools on top at draw time.
  * @module @linxin666/dsh-pet/chatter
  */
 /** While a scene persists, its copy advances on this cadence (ms). */
@@ -156,6 +161,16 @@ export const STATUS_POOLS = {
         '蹲一个继续的指令',
     ],
 };
+/** Every status scene key, in declaration order (voice-pack key allow-list). */
+export const STATUS_SCENES = [
+    'prepare', 'waiting', 'thinking', 'review', 'toolResult', 'done',
+    'failed', 'toolFailed', 'maxTokens', 'interrupted', 'blocked',
+];
+/** Every tool-family key, in declaration order (voice-pack key allow-list). */
+export const TOOL_CATEGORIES = [
+    'read', 'write', 'edit', 'shell', 'grep', 'find', 'ls', 'webSearch',
+    'webFetch', 'mcp', 'memory', 'subagent', 'todo', 'browser', 'git', 'ask', 'generic',
+];
 /** Map a raw tool name onto its copy family (working-activity style regexes). */
 export function toolCategory(toolName) {
     const name = toolName.toLowerCase();
@@ -414,12 +429,16 @@ export function toolArgHint(toolName, argumentsJson) {
  * stretch keeps changing its wording.
  */
 export class StatusVoice {
+    pools;
     rotateMs;
     counters = new Map();
     lastScene = '';
     lastLine = '';
     lastLineAt = Number.NEGATIVE_INFINITY;
-    constructor(rotateMs = STATUS_ROTATE_MS) {
+    constructor(pools = () => BUILTIN_VOICE_PACK, rotateMs = STATUS_ROTATE_MS) {
+        // Plain property assignment, not parameter properties: this module is
+        // imported by scripts/ under node's strip-only mode (pet-center M4).
+        this.pools = pools;
         this.rotateMs = rotateMs;
     }
     /** Draw the next line of one pool, advancing its round-robin cursor. */
@@ -437,22 +456,35 @@ export class StatusVoice {
         this.lastLineAt = nowMs;
         return this.lastLine;
     }
+    /**
+     * A scene's effective pool: the voice-pack override when it carries lines,
+     * else the built-in pool. Empty overrides fall back rather than blank the
+     * bubble — a scene line always renders.
+     */
+    scenePool(scene) {
+        const override = this.pools().status?.[scene];
+        return override !== undefined && override.length > 0 ? override : STATUS_POOLS[scene];
+    }
     /** Status line for a phase scene. */
     scene(scene, nowMs) {
-        return this.voice('scene:' + scene, 'pool:' + scene, STATUS_POOLS[scene], nowMs);
+        return this.voice('scene:' + scene, 'pool:' + scene, this.scenePool(scene), nowMs);
     }
     /** Status line for a tool call, with the real-argument hint when known. */
     tool(toolName, displayName, hint, nowMs) {
         const category = toolCategory(toolName);
-        const line = this.voice('tool:' + category, 'tool:' + category, TOOL_POOLS[category], nowMs);
+        const override = this.pools().tools?.[category];
+        const pool = override !== undefined && override.length > 0 ? override : TOOL_POOLS[category];
+        const line = this.voice('tool:' + category, 'tool:' + category, pool, nowMs);
         return line
-            .replace('{tool}', displayName)
-            .replace('{hint}', hint ?? displayName);
+            .replaceAll('{tool}', displayName)
+            .replaceAll('{hint}', hint ?? displayName);
     }
     /** Status line while sibling tools still run (always reflects the count). */
     toolRemaining(count, nowMs) {
-        return this.voice('toolRemaining', 'toolRemaining', TOOL_REMAINING_POOL, nowMs)
-            .replace('{n}', String(count));
+        const override = this.pools().toolRemaining;
+        const pool = override !== undefined && override.length > 0 ? override : TOOL_REMAINING_POOL;
+        return this.voice('toolRemaining', 'toolRemaining', pool, nowMs)
+            .replaceAll('{n}', String(count));
     }
 }
 /** Murmur pacing: cooldown between whispers and output volume that earns one. */
@@ -701,25 +733,48 @@ export const WHISPER_RULES = [
         ],
     },
 ];
+/** The built-in voice pack: the plugin's default copy, unchanged since v1. */
+export const BUILTIN_VOICE_PACK = {
+    status: STATUS_POOLS,
+    tools: TOOL_POOLS,
+    toolRemaining: TOOL_REMAINING_POOL,
+    whispers: { generic: WHISPER_GENERIC_POOL, rules: WHISPER_RULES },
+};
 /**
  * The murmur engine (碎碎念): watches the model's own output and lets the pet
  * whisper its inner voice. Two ways to earn a whisper:
  *  - a keyword rule matches the fresh chunk text (themed whisper);
  *  - enough output volume flowed by without one (ambient whisper).
  * A cooldown keeps whispers occasional; all picks are round-robin so tests
- * reproduce exact lines.
+ * reproduce exact lines. The voice-pack provider (pet-center M4) swaps the
+ * pools at draw time, so a pet switch re-voices live engines in place.
  */
 export class WhisperEngine {
+    pools;
     cooldownMs;
     charBudget;
     counters = new Map();
     genericCursor = 0;
     lastWhisperAt = Number.NEGATIVE_INFINITY;
     charsSinceWhisper = 0;
-    constructor(cooldownMs = WHISPER_COOLDOWN_MS, charBudget = WHISPER_CHAR_BUDGET) {
+    constructor(pools = () => BUILTIN_VOICE_PACK, cooldownMs = WHISPER_COOLDOWN_MS, charBudget = WHISPER_CHAR_BUDGET) {
+        this.pools = pools;
         this.cooldownMs = cooldownMs;
         this.charBudget = charBudget;
     }
+    /**
+     * Effective keyword rules: an override replaces the built-in rules as a
+     * whole; an explicit empty array disables keyword-triggered whispers.
+     */
+    rules() {
+        const override = this.pools().whispers?.rules;
+        return override === undefined ? WHISPER_RULES : override;
+    }
+    /** Effective ambient pool (an explicit empty array mutes ambient whispers). */
+    generic() {
+        const override = this.pools().whispers?.generic;
+        return override === undefined ? WHISPER_GENERIC_POOL : override;
+    }
     /**
      * Feed one model-output chunk (reasoning or text). Returns the whisper to
      * show, or undefined when the moment stays quiet.
@@ -733,8 +788,9 @@ export class WhisperEngine {
             return undefined;
         }
         const haystack = text.toLowerCase();
-        for (let ruleIndex = 0; ruleIndex < WHISPER_RULES.length; ruleIndex += 1) {
-            const rule = WHISPER_RULES[ruleIndex];
+        const rules = this.rules();
+        for (let ruleIndex = 0; ruleIndex < rules.length; ruleIndex += 1) {
+            const rule = rules[ruleIndex];
             if (!rule.keywords.some(keyword => haystack.includes(keyword)))
                 continue;
             const index = (this.counters.get(ruleIndex) ?? 0) % rule.pool.length;
@@ -744,7 +800,10 @@ export class WhisperEngine {
         this.charsSinceWhisper += text.length;
         if (this.charsSinceWhisper < this.charBudget)
             return undefined;
-        const line = WHISPER_GENERIC_POOL[this.genericCursor % WHISPER_GENERIC_POOL.length];
+        const generic = this.generic();
+        if (generic.length === 0)
+            return undefined;
+        const line = generic[this.genericCursor % generic.length];
         this.genericCursor += 1;
         return this.speak(line, nowMs);
     }

package/lib/types/client/PetDockEntry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PetDockEntry.d.ts","sourceRoot":"","sources":["../../../src/client/PetDockEntry.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAmC,KAAK,YAAY,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEtD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,CAAA;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAA;IACf,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,2DAA2D;IAC3D,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,iCAAiC;IACjC,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAC3B,WAAW,GACT,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;AAI1B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAsDnE"}
+{"version":3,"file":"PetDockEntry.d.ts","sourceRoot":"","sources":["../../../src/client/PetDockEntry.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAmC,KAAK,YAAY,EAAE,MAAM,OAAO,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGtD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,CAAA;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,IAAI,CAAA;IACf,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,qCAAqC;IACrC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAChD,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,2DAA2D;IAC3D,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACxC,iCAAiC;IACjC,YAAY,EAAE,MAAM,IAAI,CAAA;CACzB;AAED,yFAAyF;AACzF,MAAM,MAAM,iBAAiB,GAC3B,WAAW,GACT,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;AAI1B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,CA6DnE"}

package/lib/types/client/PetDockEntry.js

@@ -13,6 +13,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import { useEffect, useSyncExternalStore } from 'react';
 import { PetSprite } from './PetSprite.js';
+import { PetRendererSwitch } from './renderers/PetRendererSwitch.js';
 import styles from './pet.module.css';
 const DEFAULT_DISPLAY = { visible: true, size: 160, right: 24, bottom: 20 };
 /**
@@ -35,7 +36,7 @@ export function PetDockEntry(props) {
     if (visible) {
         return (_jsx("span", { "data-pet-dock": true, "data-testid": "pet-dock", children: snapshot === null || definition === null
                 ? null
-                : (_jsx(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 })) }));
+                : (_jsx(PetRendererSwitch, { definition: definition, phase: snapshot?.phase ?? 'idle', onPet: props.pet, t: props.t, children: _jsx(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 }) })) }));
     }
     const display = snapshot?.display ?? DEFAULT_DISPLAY;
     return (_jsx("button", { type: "button", className: styles.summon, style: {

package/lib/types/client/PetSettingsCard.d.ts

@@ -24,6 +24,8 @@ export interface PetSettings {
     bottom?: number;
     /** Selected pet id (a registry entry). */
     petId?: string;
+    /** Status-decoration master switch (pet-center M5, #567). */
+    decorationEnabled?: boolean;
 }
 /** What the pet settings card renders. */
 export interface PetSettingsCardState extends CardShell {
@@ -39,11 +41,15 @@ export interface PetSettingsCardState extends CardShell {
     bottom: CardFieldState;
     /** Selected pet. */
     petId: CardFieldState;
+    /** Status-decoration master switch. */
+    decorationEnabled: 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. */
 export interface PetSettingsCardFace extends CardActions {
@@ -52,16 +58,24 @@ export interface PetSettingsCardFace extends CardActions {
         petSettingsCard: SnapshotStore<PetSettingsCardState>;
     };
 }
+/** One registry diagnostic as served by '/api/pet/diagnostics' (#623). */
+export interface PetDiagnosticView {
+    level: 'error' | 'warning';
+    message: string;
+}
 /** Bridges the 'pet' scope onto the card's staged form. */
 export declare class PetSettingsCardController {
     private readonly form;
     private readonly store;
     private readonly petChoices;
     private readonly petLabels;
+    private diagnostics;
     private loaded;
     private attempts;
     /** @param scope - the bound settings scope for the 'pet' namespace. */
     constructor(scope: SettingsScope<PetSettings>);
+    /** Fetch registry diagnostics once (soft-fail: an empty list on error). */
+    private loadDiagnostics;
     /** Resolve the registry choices once (retried a few times on failure). */
     private loadPets;
     private projection;

package/lib/types/client/PetSettingsCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PetSettingsCard.d.ts","sourceRoot":"","sources":["../../../src/client/PetSettingsCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAC7F,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAI1F,OAAO,EAAoD,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,IAAI,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAG1J,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qBAAqB;IACrB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,oBAAqB,SAAQ,SAAS;IACrD,4BAA4B;IAC5B,OAAO,EAAE,cAAc,CAAA;IACvB,qBAAqB;IACrB,OAAO,EAAE,cAAc,CAAA;IACvB,iBAAiB;IACjB,IAAI,EAAE,cAAc,CAAA;IACpB,mBAAmB;IACnB,KAAK,EAAE,cAAc,CAAA;IACrB,oBAAoB;IACpB,MAAM,EAAE,cAAc,CAAA;IACtB,oBAAoB;IACpB,KAAK,EAAE,cAAc,CAAA;IACrB,wEAAwE;IACxE,UAAU,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACxD;AAED,gEAAgE;AAChE,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,KAAK,EAAE;QACL,iEAAiE;QACjE,eAAe,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAA;KACrD,CAAA;CACF;AAeD,2DAA2D;AAC3D,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAI3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,QAAQ,CAAI;IAEpB,uEAAuE;IACvE,YAAY,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,EAW5C;IAED,0EAA0E;YAC5D,QAAQ;IAgBtB,OAAO,CAAC,UAAU;IAalB;;;OAGG;IACH,MAAM,IAAI,mBAAmB,CAE5B;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI,CAEd;CACF;AAED,0DAA0D;AAC1D,MAAM,MAAM,oBAAoB,GAC9B,WAAW,CAAC,KAAK,CAAC,GAChB,UAAU,CAAC,mBAAmB,CAAC,CAAA;AAEnC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,+BAuF1D;AAED,8DAA8D;AAC9D,MAAM,MAAM,uBAAuB,GACjC,YAAY,CAAC,kBAAkB,CAAC,GAC9B,WAAW,CAAC,KAAK,CAAC,GAClB,UAAU,CAAC,mBAAmB,CAAC,CAAA;AAEnC,mEAAmE;AACnE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,SAAS,CAO5E"}
+{"version":3,"file":"PetSettingsCard.d.ts","sourceRoot":"","sources":["../../../src/client/PetSettingsCard.tsx"],"names":[],"mappings":"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"}

package/lib/types/client/PetSettingsCard.js

@@ -9,6 +9,14 @@ async function fetchPetChoices() {
         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);
+    const body = (await response.json());
+    return body.diagnostics ?? [];
+}
 /** Bridges the 'pet' scope onto the card's staged form. */
 export class PetSettingsCardController {
     form;
@@ -18,12 +26,14 @@ export class PetSettingsCardController {
     // without rebuilding the form.
     petChoices = [];
     petLabels = new Map();
+    diagnostics = [];
     loaded = false;
     attempts = 0;
     /** @param scope - the bound settings scope for the 'pet' namespace. */
     constructor(scope) {
         this.form = new CardForm(scope, [
             booleanField('enabled'),
+            booleanField('decorationEnabled'),
             booleanField('visible'),
             numberField('size'),
             numberField('right'),
@@ -32,6 +42,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). */
+    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() {
@@ -56,12 +77,14 @@ export class PetSettingsCardController {
         return {
             ...this.form.shell(),
             enabled: this.form.field('enabled'),
+            decorationEnabled: this.form.field('decorationEnabled'),
             visible: this.form.field('visible'),
             size: this.form.field('size'),
             right: this.form.field('right'),
             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,
         };
     }
     /**
@@ -94,7 +117,7 @@ export function PetSettingsCard(props) {
         invalidLabel: t('settings.invalidNumber'),
         disabled,
     };
-    return (_jsxs(PluginSettingsCard, { t: t, titleKey: "settings.title", descriptionKey: "settings.description", state: state, onSave: props.save, onDiscard: props.discard, alwaysOpen: true, children: [_jsx(BooleanField, { id: "settings-pet-enabled", label: t('settings.enabled'), hint: t('settings.enabledHint'), inheritLabel: t('settings.inherit'), onLabel: t('settings.on'), offLabel: t('settings.off'), ...fieldProps, ...state.enabled, onEdit: (text) => { props.edit('enabled', text); }, onReset: () => { props.resetField('enabled'); } }), _jsx(ChoiceField, { id: "settings-pet-pet", label: t('settings.pet'), hint: t('settings.petHint'), inheritLabel: t('settings.inherit'), ...fieldProps, ...state.petId, choices: state.petChoices, onEdit: (text) => { props.edit('petId', text); }, onReset: () => { props.resetField('petId'); } }), _jsx(BooleanField, { id: "settings-pet-visible", label: t('settings.visible'), hint: t('settings.visibleHint'), inheritLabel: t('settings.inherit'), onLabel: t('settings.on'), offLabel: t('settings.off'), ...fieldProps, ...state.visible, onEdit: (text) => { props.edit('visible', text); }, onReset: () => { props.resetField('visible'); } }), _jsx(ValueField, { id: "settings-pet-size", label: t('settings.size'), hint: t('settings.sizeHint'), numeric: true, ...fieldProps, ...state.size, onEdit: (text) => { props.edit('size', text); }, onReset: () => { props.resetField('size'); } }), _jsx(ValueField, { id: "settings-pet-right", label: t('settings.right'), hint: t('settings.rightHint'), numeric: true, ...fieldProps, ...state.right, onEdit: (text) => { props.edit('right', text); }, onReset: () => { props.resetField('right'); } }), _jsx(ValueField, { id: "settings-pet-bottom", label: t('settings.bottom'), hint: t('settings.bottomHint'), numeric: true, ...fieldProps, ...state.bottom, onEdit: (text) => { props.edit('bottom', text); }, onReset: () => { props.resetField('bottom'); } })] }));
+    return (_jsxs(PluginSettingsCard, { t: t, titleKey: "settings.title", descriptionKey: "settings.description", state: state, onSave: props.save, onDiscard: props.discard, alwaysOpen: true, children: [_jsx(BooleanField, { id: "settings-pet-enabled", label: t('settings.enabled'), hint: t('settings.enabledHint'), inheritLabel: t('settings.inherit'), onLabel: t('settings.on'), offLabel: t('settings.off'), ...fieldProps, ...state.enabled, onEdit: (text) => { props.edit('enabled', text); }, onReset: () => { props.resetField('enabled'); } }), _jsx(BooleanField, { id: "settings-pet-decoration", label: t('settings.decoration'), hint: t('settings.decorationHint'), inheritLabel: t('settings.inherit'), onLabel: t('settings.on'), offLabel: t('settings.off'), ...fieldProps, ...state.decorationEnabled, onEdit: (text) => { props.edit('decorationEnabled', text); }, onReset: () => { props.resetField('decorationEnabled'); } }), _jsx(ChoiceField, { id: "settings-pet-pet", label: t('settings.pet'), hint: t('settings.petHint'), inheritLabel: t('settings.inherit'), ...fieldProps, ...state.petId, choices: state.petChoices, onEdit: (text) => { props.edit('petId', text); }, onReset: () => { props.resetField('petId'); } }), state.petDiagnostics.length === 0 ? null : (_jsxs("li", { className: sectionCss.diagnostics, "data-dsh-part": "diagnostics", children: [_jsx("span", { className: sectionCss.diagnosticsTitle, children: t('settings.diagnosticsTitle') }), _jsx("ul", { children: state.petDiagnostics.map((diagnostic, index) => (_jsx("li", { "data-level": diagnostic.level, children: diagnostic.message }, index))) })] })), _jsx(BooleanField, { id: "settings-pet-visible", label: t('settings.visible'), hint: t('settings.visibleHint'), inheritLabel: t('settings.inherit'), onLabel: t('settings.on'), offLabel: t('settings.off'), ...fieldProps, ...state.visible, onEdit: (text) => { props.edit('visible', text); }, onReset: () => { props.resetField('visible'); } }), _jsx(ValueField, { id: "settings-pet-size", label: t('settings.size'), hint: t('settings.sizeHint'), numeric: true, ...fieldProps, ...state.size, onEdit: (text) => { props.edit('size', text); }, onReset: () => { props.resetField('size'); } }), _jsx(ValueField, { id: "settings-pet-right", label: t('settings.right'), hint: t('settings.rightHint'), numeric: true, ...fieldProps, ...state.right, onEdit: (text) => { props.edit('right', text); }, onReset: () => { props.resetField('right'); } }), _jsx(ValueField, { id: "settings-pet-bottom", label: t('settings.bottom'), hint: t('settings.bottomHint'), numeric: true, ...fieldProps, ...state.bottom, onEdit: (text) => { props.edit('bottom', text); }, onReset: () => { props.resetField('bottom'); } })] }));
 }
 /** Render the pet settings card as a first-level settings page. */
 export function PetSettingsSection(props) {

package/lib/types/client/PetSprite.d.ts

@@ -8,7 +8,7 @@
  * pet id), so one component renders every registry entry.
  * @module @linxin666/dsh-pet/client/PetSprite
  */
-import type { ReactPortal } from 'react';
+import type { ReactNode, ReactPortal } from 'react';
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
 import type { PetDisplayConfig } from '../persist.ts';
 import type { PetStateView } from '../service.ts';
@@ -39,6 +39,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>;
 }

package/lib/types/client/PetSprite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PetSprite.d.ts","sourceRoot":"","sources":["../../../src/client/PetSprite.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAoD,WAAW,EAAE,MAAM,OAAO,CAAA;AAG1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAIjD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,8EAA8E;IAC9E,UAAU,EAAE,aAAa,CAAA;IACzB,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,CAAA;IACzB,sCAAsC;IACtC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAClD,uDAAuD;IACvD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,4DAA4D;IAC5D,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAA;IAC1B,+CAA+C;IAC/C,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;CAC1B;AAOD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAud5D"}
+{"version":3,"file":"PetSprite.d.ts","sourceRoot":"","sources":["../../../src/client/PetSprite.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAkE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAA;AAGnH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAIjD,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAA;AAGjC,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,8EAA8E;IAC9E,UAAU,EAAE,aAAa,CAAA;IACzB,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,CAAA;IACzB,sCAAsC;IACtC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAA;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,sCAAsC;IACtC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,+BAA+B;IAC/B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAClD,uDAAuD;IACvD,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,4DAA4D;IAC5D,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAA;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,+CAA+C;IAC/C,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAA;CAC1B;AAkFD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,WAAW,CAygB5D"}