@linxin666/dsh-pet 0.1.14 → 0.1.16

package/lib/types/client/{WhalePet.js → PetSprite.js}

@@ -1,36 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
- * Whale-girl companion component — the browser half's centerpiece. Renders a
+ * Pet sprite companion component — the browser half's centerpiece. Renders a
  * fixed-position floating sprite (React portal onto document.body), plays
- * the spritesheet track matching the host animation snapshot, and exposes
- * the interaction surface: click to pet, hover panel with feed/hide, drag to
- * reposition (persisted via setConfig).
- * @module @linxin666/dsh-pet/client/WhalePet
+ * the track matching the host animation snapshot, and exposes the
+ * interaction surface: click to pet, hover panel with feed/rename/hide, drag
+ * to reposition (persisted via setConfig). Everything visual comes from the
+ * pet definition the host serves ('/api/pet/pets' + the state snapshot's
+ * pet id), so one component renders every registry entry.
+ * @module @linxin666/dsh-pet/client/PetSprite
  */
 import { useEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { framePosition, FRAME_WIDTH, FRAME_HEIGHT, FRAME_COLUMNS, TRACKS, rowOfTrack, trimTrack, detectFrameCounts } from "./spritesheet.js";
+import clsx from 'clsx';
+import { framePosition, rowOfTrack, trimTrack } from "./spritesheet.js";
 import styles from './pet.module.css';
-/** Browser URL of the whale-girl atlas (served by the host half's own route). */
-export const PET_SPRITESHEET_URL = '/pet/whale/spritesheet.webp';
-/** Browser URL of the whale-girl manifest (authoritative per-row frame counts). */
-export const PET_MANIFEST_URL = '/pet/whale/pet.json';
 /** Clamp a drag offset inside the viewport with a margin. */
 function clampOffset(value, max) {
     return Math.max(0, Math.min(max, value));
 }
 /**
  * The floating pet. The spritesheet frame advances on requestAnimationFrame
- * with per-frame durations from TRACKS; the atlas image is loaded once and
- * the background position is written straight to the sprite element (no
- * per-frame React state).
+ * with per-frame durations from the definition's tracks; the atlas image is
+ * loaded once and the background position is written straight to the sprite
+ * element (no per-frame React state).
  */
-export function WhalePet(props) {
-    const { snapshot, display, feedback } = props;
+export function PetSprite(props) {
+    const { snapshot, definition, display, feedback } = props;
     const spriteRef = useRef(null);
     const floatRef = useRef(null);
     const [imageReady, setImageReady] = useState(false);
-    const [frameCounts, setFrameCounts] = useState(null);
     const [hovered, setHovered] = useState(false);
     const [renaming, setRenaming] = useState(false);
     const [nameDraft, setNameDraft] = useState('');
@@ -42,66 +40,46 @@ export function WhalePet(props) {
         index: 0,
         elapsed: 0,
     });
-    // Load the atlas once; then resolve per-row frame counts so tracks never
-    // play the transparent trailing cells of a short row. One decoded Image
-    // feeds both the sprite render and the frame-count detection. The counts
-    // prefer the authoritatively recorded `frames` field on the pet.json
-    // manifest route and only fall back to the getImageData atlas scan when
-    // that field is absent (older manifests).
+    const cell = definition.cell;
+    const columns = definition.columns;
+    const rows = definition.rows;
+    const tracks = definition.tracks;
+    // Load the atlas once; the definition carries the authoritative per-row
+    // frame counts and per-track durations, so nothing else is fetched.
     useEffect(() => {
         let cancelled = false;
         const img = new Image();
         img.onload = () => {
-            if (cancelled)
-                return;
-            setImageReady(true);
-            fetch(PET_MANIFEST_URL)
-                .then((res) => (res.ok ? res.json() : Promise.resolve({})))
-                .then((manifest) => {
-                if (cancelled)
-                    return;
-                const frames = manifest.frames;
-                if (Array.isArray(frames) && frames.length === 9 && frames.every((n) => typeof n === 'number')) {
-                    setFrameCounts(frames);
-                }
-                else {
-                    setFrameCounts(detectFrameCounts(img));
-                }
-            })
-                .catch(() => {
-                if (!cancelled)
-                    setFrameCounts(detectFrameCounts(img));
-            });
+            if (!cancelled)
+                setImageReady(true);
         };
-        img.src = PET_SPRITESHEET_URL;
+        img.src = definition.atlasUrl;
         return () => {
             cancelled = true;
             img.onload = null;
         };
-    }, []);
+    }, [definition.atlasUrl]);
     // Frame loop: advance the current track and write background-position.
     // Offsets must be in SCALED coordinates (background-position applies to the
     // scaled background image), so the current sprite scale rides a ref that
     // the loop reads every tick. Under prefers-reduced-motion the sprite holds
     // its track's first frame instead of animating (presentation-only; the
     // animation state machine is untouched).
-    const spriteScale = display.size / FRAME_HEIGHT;
+    const spriteScale = display.size / cell.height;
     const animation = snapshot?.animation ?? 'idle';
     const scaleRef = useRef(spriteScale);
     scaleRef.current = spriteScale;
     useEffect(() => {
         const reduceMotion = typeof window !== 'undefined'
             && window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches === true;
+        const row = rowOfTrack(animation);
+        const track = trimTrack(tracks[animation], rows[row] ?? tracks[animation].frames.length);
         // Paint one static sprite frame up front either way, so the pet is never
         // blank while the loop heat-up runs.
-        const row = rowOfTrack(animation);
-        const track = frameCounts === null
-            ? TRACKS[animation]
-            : trimTrack(TRACKS[animation], frameCounts[row] ?? TRACKS[animation].frames.length);
         const leadCol = track.frames[0];
-        const lead = framePosition(row, leadCol, scaleRef.current);
+        const lead = framePosition(cell, columns, row, leadCol, scaleRef.current);
         if (spriteRef.current !== null) {
-            spriteRef.current.style.backgroundPosition = `${lead.x}px ${lead.y}px`;
+            spriteRef.current.style.backgroundPosition = lead.x + 'px ' + lead.y + 'px';
         }
         if (reduceMotion)
             return;
@@ -113,9 +91,7 @@ export function WhalePet(props) {
             // Trim the track to the row's real frame count (transparent cells
             // would render as a vanishing pet).
             const row = rowOfTrack(animation);
-            const track = frameCounts === null
-                ? TRACKS[animation]
-                : trimTrack(TRACKS[animation], frameCounts[row] ?? TRACKS[animation].frames.length);
+            const track = trimTrack(tracks[animation], rows[row] ?? tracks[animation].frames.length);
             const st = frameRef.current;
             if (st.track !== animation) {
                 st.track = animation;
@@ -138,17 +114,17 @@ export function WhalePet(props) {
                 }
             }
             const col = track.frames[st.index];
-            const { x, y } = framePosition(row, col, scaleRef.current);
+            const pos = framePosition(cell, columns, row, col, scaleRef.current);
             if (spriteRef.current !== null) {
-                spriteRef.current.style.backgroundPosition = `${x}px ${y}px`;
+                spriteRef.current.style.backgroundPosition = pos.x + 'px ' + pos.y + 'px';
             }
             raf = requestAnimationFrame(tick);
         };
         raf = requestAnimationFrame(tick);
         return () => cancelAnimationFrame(raf);
-    }, [animation, frameCounts]);
+    }, [animation, cell, columns, rows, tracks]);
     // Auto-clear the feedback bubble after its CSS animation. The callback
-    // rides a ref so re-renders never reset the timer: the 800ms poll rebuilds
+    // rides a ref so re-renders never reset the timer: the 2s poll rebuilds
     // `props` every tick, and depending on it would starve the timeout.
     const feedbackDoneRef = useRef(props.onFeedbackDone);
     feedbackDoneRef.current = props.onFeedbackDone;
@@ -160,7 +136,7 @@ export function WhalePet(props) {
     }, [feedback]);
     // Dragging: pointer events on the sprite; position is right/bottom based.
     // `draggedRef` records whether the pointer actually moved, so the browser's
-    // trailing click (fired after pointerup) does not pet the whale.
+    // trailing click (fired after pointerup) does not pet the sprite.
     const draggedRef = useRef(false);
     const clearHideTimer = () => {
         if (hideTimerRef.current !== null) {
@@ -196,9 +172,10 @@ export function WhalePet(props) {
             props.onDragEnd(dragPos.right, dragPos.bottom);
     };
     const pos = dragPos ?? { right: display.right, bottom: display.bottom };
-    const spriteWidth = Math.round(FRAME_WIDTH * spriteScale);
-    const spriteHeight = Math.round(FRAME_HEIGHT * spriteScale);
+    const spriteWidth = Math.round(cell.width * spriteScale);
+    const spriteHeight = Math.round(cell.height * spriteScale);
     const statusBubble = feedback === null && !hovered ? snapshot?.bubble : undefined;
+    const displayName = snapshot?.name ?? definition.displayName;
     const float = (_jsxs("div", { ref: floatRef, className: styles.float, style: { right: pos.right, bottom: pos.bottom, zIndex: 2147483000 }, onPointerEnter: () => {
             clearHideTimer();
             setHovered(true);
@@ -208,7 +185,7 @@ export function WhalePet(props) {
             // container. Treat a target still inside the container's DOM (the
             // overflowed panel) as "still hovering"; otherwise give the pointer a
             // short grace period to reach the panel across the gap above it. The
-            // bridge (`.panel::after`) keeps the pointer inside the hit area, and
+            // bridge ('.panel::after') keeps the pointer inside the hit area, and
             // the grace period covers a slow mouse crossing the remaining sliver.
             const next = e.relatedTarget;
             if (next instanceof Node && floatRef.current?.contains(next))
@@ -218,8 +195,8 @@ export function WhalePet(props) {
         }, children: [_jsx("div", { ref: spriteRef, className: styles.sprite, style: {
                     width: spriteWidth,
                     height: spriteHeight,
-                    backgroundImage: imageReady ? `url(${PET_SPRITESHEET_URL})` : undefined,
-                    backgroundSize: `${FRAME_WIDTH * FRAME_COLUMNS * spriteScale}px ${FRAME_HEIGHT * 9 * spriteScale}px`,
+                    backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
+                    backgroundSize: (cell.width * columns * spriteScale) + 'px ' + (cell.height * rows.length * spriteScale) + 'px',
                     backgroundRepeat: 'no-repeat',
                     backgroundPosition: '0 0',
                     cursor: dragRef.current === null ? 'grab' : 'grabbing',
@@ -229,7 +206,7 @@ export function WhalePet(props) {
                     if (draggedRef.current)
                         return;
                     props.onPet();
-                }, role: "button", "aria-label": "whale girl" }), feedback !== null && (_jsx("div", { className: `${styles.bubble} ${feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet}`, children: feedback.text }, feedback.at)), statusBubble !== undefined && (_jsx("div", { className: `${styles.bubble} ${styles.bubbleStatus}`, role: "status", "aria-live": "polite", children: statusBubble })), hovered && dragRef.current === null && (_jsx("div", { className: styles.panel, onPointerEnter: () => {
+                }, role: "button", "aria-label": definition.displayName }), feedback !== null && (_jsx("div", { className: clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet), children: feedback.text }, feedback.at)), statusBubble !== undefined && (_jsx("div", { className: clsx(styles.bubble, styles.bubbleStatus), role: "status", "aria-live": "polite", children: statusBubble })), hovered && dragRef.current === null && (_jsx("div", { className: styles.panel, onPointerEnter: () => {
                     // Reaching the panel (or its bridge) must cancel any hide timer
                     // the container's pointerleave may have armed while the pointer
                     // crossed the sliver between the sprite and the panel.
@@ -257,8 +234,8 @@ export function WhalePet(props) {
                                     props.onRename(trimmed);
                                     setRenaming(false);
                                 }
-                            }, children: props.t('pet.confirm') })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: styles.rankRow, children: [_jsx("span", { className: styles.nameCell, children: snapshot?.name ?? '鲸鱼娘' }), _jsx("span", { children: props.t('pet.rank', { rank: snapshot?.affinity.rank ?? '?' }) })] }), _jsxs("div", { className: styles.rankRow, children: [_jsx("span", { children: props.t('pet.treats', { n: snapshot?.treats.stocked ?? 0 }) }), _jsx("span", { children: props.t('pet.points', { points: snapshot?.affinity.points ?? 0 }) })] }), _jsxs("div", { className: styles.actions, children: [_jsx("button", { type: "button", className: styles.action, onClick: props.onFeed, children: props.t('pet.feed') }), _jsx("button", { type: "button", className: styles.action, onClick: () => {
-                                        setNameDraft(snapshot?.name ?? '');
+                            }, children: props.t('pet.confirm') })] })) : (_jsxs(_Fragment, { children: [_jsxs("div", { className: styles.rankRow, children: [_jsx("span", { className: styles.nameCell, children: displayName }), _jsx("span", { children: props.t('pet.rank', { rank: snapshot?.affinity.rank ?? '?' }) })] }), _jsxs("div", { className: styles.rankRow, children: [_jsx("span", { children: props.t('pet.treats', { n: snapshot?.treats.stocked ?? 0 }) }), _jsx("span", { children: props.t('pet.points', { points: snapshot?.affinity.points ?? 0 }) })] }), _jsxs("div", { className: styles.actions, children: [_jsx("button", { type: "button", className: styles.action, onClick: props.onFeed, children: props.t('pet.feed') }), _jsx("button", { type: "button", className: styles.action, onClick: () => {
+                                        setNameDraft(displayName);
                                         setRenaming(true);
                                     }, children: props.t('pet.rename') }), _jsx("button", { type: "button", className: styles.action, onClick: props.onHide, children: props.t('pet.hide') })] })] })) }))] }));
     return createPortal(float, document.body);

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

@@ -1,22 +1,27 @@
 /**
- * Shared chrome for the plugin settings card: a disclosure header naming the
- * plugin and what its settings govern, the controls inside, and the save that
- * writes them. Renders nothing while the namespace is unavailable — a
+ * Family-shared chrome for plugin settings cards: a disclosure header naming
+ * the plugin and what its settings govern, the controls inside, and the save
+ * that writes them. Renders nothing while the namespace is unavailable — a
  * deployment that does not compose the owning plugin should show no trace of
- * it. Mirrors the official ui-plugin-config PluginCard in a self-contained
- * slice (this package must not depend on a sibling UI package).
+ * it. Inlined into each consumer's client bundle; mirrors the official
+ * ui-plugin-config PluginCard in a self-contained slice.
  */
 import { type ReactNode } from 'react';
 import type { CardShell } from './settings-form.ts';
-import type { SettingsCardKey } from './locales.ts';
+/** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
+export declare const CARD_COPY_KEYS: readonly ["settings.collapse", "settings.expand", "settings.notExposed", "settings.unsaved", "settings.readOnly", "settings.saveFailed", "settings.discard", "settings.save", "settings.saving"];
+/** Copy key the card chrome itself reads. */
+export type CardCopyKey = (typeof CARD_COPY_KEYS)[number];
+/** Key domain for the plugin's own copy (inferred per consumer). */
+export type SettingsCardKey<TKey extends string = string> = TKey | CardCopyKey;
 /** Card chrome shared by every plugin settings card. */
-export interface PluginSettingsCardProps {
+export interface PluginSettingsCardProps<TKey extends string = string> {
     /** Locale reader for this card's copy. */
-    t: (key: SettingsCardKey) => string;
+    t: (key: SettingsCardKey<TKey>, params?: Record<string, string | number>) => string;
     /** Locale key of the plugin's name. */
-    titleKey: SettingsCardKey;
+    titleKey: TKey;
     /** Locale key of the line describing what this plugin's settings govern. */
-    descriptionKey: SettingsCardKey;
+    descriptionKey: TKey;
     /** The card's form state: availability, writability, and what a save would do. */
     state: CardShell;
     /** Write every staged edit. */
@@ -31,7 +36,7 @@ export interface PluginSettingsCardProps {
  * @param props - the plugin's copy keys, its form state, and its controls.
  * @returns the card, or nothing while the namespace is still loading.
  */
-export declare function PluginSettingsCard(props: PluginSettingsCardProps): import("react").JSX.Element | null;
+export declare function PluginSettingsCard<TKey extends string = string>(props: PluginSettingsCardProps<TKey>): import("react").JSX.Element | null;
 /** Props every field control needs regardless of its value type. */
 export interface FieldProps {
     /** Stable id associating the label with its control. */
@@ -75,4 +80,14 @@ export declare function BooleanField(props: FieldProps & {
     /** Copy for the off option. */
     offLabel: string;
 }): import("react").JSX.Element;
+/** A staged enumerated field rendered as a select. */
+export declare function ChoiceField(props: FieldProps & {
+    /** Copy for the inherit option (draft text is the empty string). */
+    inheritLabel: string;
+    /** Choices rendered in order; `value` is the draft/stored text. */
+    choices: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+}): import("react").JSX.Element;
 //# sourceMappingURL=PluginSettingsCard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"PluginSettingsCard.d.ts","sourceRoot":"","sources":["../../../src/client/PluginSettingsCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGnD,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,MAAM,CAAA;IACnC,uCAAuC;IACvC,QAAQ,EAAE,eAAe,CAAA;IACzB,4EAA4E;IAC5E,cAAc,EAAE,eAAe,CAAA;IAC/B,kFAAkF;IAClF,KAAK,EAAE,SAAS,CAAA;IAChB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,sCA0GhE;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAA;IACV,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAA;IACnB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAA;IAChB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB,wBAAwB;IACxB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,oEAAoE;IACpE,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED,kHAAkH;AAClH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG;IAC7C,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,+BAqCA;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG;IAC/C,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAA;IACpB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAA;CACjB,+BAmCA"}
+{"version":3,"file":"PluginSettingsCard.d.ts","sourceRoot":"","sources":["../../../src/client/PluginSettingsCard.tsx"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAGnD,oGAAoG;AACpG,eAAO,MAAM,cAAc,kMAUjB,CAAA;AAEV,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzD,oEAAoE;AACpE,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,GAAG,WAAW,CAAA;AAE9E,wDAAwD;AACxD,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM;IACnE,0CAA0C;IAC1C,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,CAAA;IACnF,uCAAuC;IACvC,QAAQ,EAAE,IAAI,CAAA;IACd,4EAA4E;IAC5E,cAAc,EAAE,IAAI,CAAA;IACpB,kFAAkF;IAClF,KAAK,EAAE,SAAS,CAAA;IAChB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,EAAE,SAAS,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,uBAAuB,CAAC,IAAI,CAAC,sCAiHpG;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAA;IACV,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAA;IACnB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAA;IAChB,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAA;IACvB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAA;IACjB,wBAAwB;IACxB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,oEAAoE;IACpE,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED,kHAAkH;AAClH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG;IAC7C,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,+BAqCA;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG;IAC/C,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAA;IACpB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAA;CACjB,+BAmCA;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG;IAC9C,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAA;IACpB,mEAAmE;IACnE,OAAO,EAAE,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzD,+BAsCA"}

package/lib/types/client/PluginSettingsCard.js

@@ -1,14 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Generated by scripts/sync-shared.mjs from shared/client/settings/PluginSettingsCard.tsx. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
- * Shared chrome for the plugin settings card: a disclosure header naming the
- * plugin and what its settings govern, the controls inside, and the save that
- * writes them. Renders nothing while the namespace is unavailable — a
+ * Family-shared chrome for plugin settings cards: a disclosure header naming
+ * the plugin and what its settings govern, the controls inside, and the save
+ * that writes them. Renders nothing while the namespace is unavailable — a
  * deployment that does not compose the owning plugin should show no trace of
- * it. Mirrors the official ui-plugin-config PluginCard in a self-contained
- * slice (this package must not depend on a sibling UI package).
+ * it. Inlined into each consumer's client bundle; mirrors the official
+ * ui-plugin-config PluginCard in a self-contained slice.
  */
 import { useState } from 'react';
 import css from './settings-card.module.css';
+/** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
+export const CARD_COPY_KEYS = [
+    'settings.collapse',
+    'settings.expand',
+    'settings.notExposed',
+    'settings.unsaved',
+    'settings.readOnly',
+    'settings.saveFailed',
+    'settings.discard',
+    'settings.save',
+    'settings.saving',
+];
 /**
  * Render one plugin settings card.
  * @param props - the plugin's copy keys, its form state, and its controls.
@@ -20,6 +33,7 @@ export function PluginSettingsCard(props) {
     if (!state.available)
         return null;
     const title = props.t(props.titleKey);
+    const description = props.t(props.descriptionKey);
     const blocked = !state.dirty || state.invalid || state.saving;
     const cardClass = open ? `${css.cardOpen} ${css.card}` : css.card;
     // The namespace exists but the Host does not serve it to this client (the
@@ -27,12 +41,14 @@ export function PluginSettingsCard(props) {
     // that explains the gap instead of vanishing, so a missing card never
     // reads as a missing plugin.
     if (!state.exposed) {
-        return (_jsxs("li", { className: cardClass, children: [_jsxs("button", { type: "button", className: css.header, "aria-expanded": open, "aria-label": `${props.t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`, onClick: () => { setOpen(!open); }, children: [_jsxs("span", { className: css.headText, children: [_jsx("span", { className: css.name, children: title }), _jsx("span", { className: css.description, children: props.t(props.descriptionKey) })] }), _jsx("svg", { width: "14", height: "14", viewBox: "0 0 14 14", fill: "none", xmlns: "http://www.w3.org/2000/svg", className: open ? `${css.chevron} ${css.chevronOpen}` : css.chevron, children: _jsx("path", { d: "M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z", fill: "currentColor" }) })] }), open
+        return (_jsxs("li", { className: cardClass, children: [_jsxs("button", { type: "button", className: css.header, "aria-expanded": open, "aria-label": `${props.t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`, onClick: () => { setOpen(!open); }, children: [_jsxs("span", { className: css.headText, children: [_jsx("span", { className: css.name, title: title, children: title }), _jsx("span", { className: css.description, title: description, children: description })] }), _jsx("svg", { width: "14", height: "14", viewBox: "0 0 14 14", fill: "none", xmlns: "http://www.w3.org/2000/svg", className: open ? `${css.chevron} ${css.chevronOpen}` : css.chevron, children: _jsx("path", { d: "M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z", fill: "currentColor" }) })] }), open
                     ? (_jsx("div", { className: css.body, children: _jsx("p", { className: css.notExposed, role: "status", children: props.t('settings.notExposed') }) }))
                     : null] }));
     }
-    return (_jsxs("li", { className: cardClass, children: [_jsxs("button", { type: "button", className: css.header, "aria-expanded": open, "aria-label": `${props.t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`, onClick: () => { setOpen(!open); }, children: [_jsxs("span", { className: css.headText, children: [_jsx("span", { className: css.name, children: title }), _jsx("span", { className: css.description, children: props.t(props.descriptionKey) })] }), state.dirty ? _jsx("span", { className: css.pending, children: props.t('settings.unsaved') }) : null, _jsx("svg", { width: "14", height: "14", viewBox: "0 0 14 14", fill: "none", xmlns: "http://www.w3.org/2000/svg", className: open ? `${css.chevron} ${css.chevronOpen}` : css.chevron, children: _jsx("path", { d: "M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z", fill: "currentColor" }) })] }), open
-                ? (_jsxs("div", { className: css.body, children: [!state.writable ? _jsx("p", { className: css.readOnly, role: "status", children: props.t('settings.readOnly') }) : null, props.children, _jsxs("div", { className: css.footer, children: [state.failed ? _jsx("p", { className: css.failed, role: "status", children: props.t('settings.saveFailed') }) : null, _jsx("button", { type: "button", className: css.discard, disabled: !state.dirty || state.saving, onClick: props.onDiscard, children: props.t('settings.discard') }), _jsx("button", { type: "button", className: css.save, disabled: blocked, onClick: props.onSave, children: props.t(!state.saving ? 'settings.save' : 'settings.saving') })] })] }))
+    return (_jsxs("li", { className: cardClass, children: [_jsxs("button", { type: "button", className: css.header, "aria-expanded": open, "aria-label": `${props.t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`, onClick: () => { setOpen(!open); }, children: [_jsxs("span", { className: css.headText, children: [_jsx("span", { className: css.name, title: title, children: title }), _jsx("span", { className: css.description, title: description, children: description })] }), state.dirty ? _jsx("span", { className: css.pending, title: props.t('settings.unsaved'), children: props.t('settings.unsaved') }) : null, _jsx("svg", { width: "14", height: "14", viewBox: "0 0 14 14", fill: "none", xmlns: "http://www.w3.org/2000/svg", className: open ? `${css.chevron} ${css.chevronOpen}` : css.chevron, children: _jsx("path", { d: "M11.8486 5.5L11.4238 5.92383L8.69727 8.65137C8.44157 8.90706 8.21562 9.13382 8.01172 9.29785C7.79912 9.46883 7.55595 9.61756 7.25 9.66602C7.08435 9.69222 6.91565 9.69222 6.75 9.66602C6.44405 9.61756 6.20088 9.46883 5.98828 9.29785C5.78438 9.13382 5.55843 8.90706 5.30273 8.65137L2.57617 5.92383L2.15137 5.5L3 4.65137L3.42383 5.07617L6.15137 7.80273C6.42595 8.07732 6.59876 8.24849 6.74023 8.3623C6.87291 8.46904 6.92272 8.47813 6.9375 8.48047C6.97895 8.48703 7.02105 8.48703 7.0625 8.48047C7.07728 8.47813 7.12709 8.46904 7.25977 8.3623C7.40124 8.24849 7.57405 8.07732 7.84863 7.80273L10.5762 5.07617L11 4.65137L11.8486 5.5Z", fill: "currentColor" }) })] }), open
+                ? (_jsxs("div", { className: css.body, children: [!state.writable ? _jsx("p", { className: css.readOnly, role: "status", children: props.t('settings.readOnly') }) : null, props.children, _jsxs("div", { className: css.footer, children: [state.failed
+                                    ? (_jsxs("p", { className: css.failed, role: "status", children: [props.t('settings.saveFailed'), state.failedReason ? ' - ' + state.failedReason : ''] }))
+                                    : null, _jsx("button", { type: "button", className: css.discard, disabled: !state.dirty || state.saving, onClick: props.onDiscard, children: props.t('settings.discard') }), _jsx("button", { type: "button", className: css.save, disabled: blocked, onClick: props.onSave, children: props.t(!state.saving ? 'settings.save' : 'settings.saving') })] })] }))
                 : null] }));
 }
 /** A staged value field. `numeric` only hints the keypad: which drafts a field accepts is decided by its spec. */
@@ -47,3 +63,9 @@ export function BooleanField(props) {
                         ? (_jsxs("span", { className: css.badges, children: [_jsx("span", { className: css.badge, children: props.overriddenLabel }), _jsx("button", { type: "button", className: css.reset, disabled: props.disabled, onClick: props.onReset, children: props.resetLabel })] }))
                         : null] }), _jsxs("select", { id: props.id, className: css.select, value: props.text, disabled: props.disabled, onChange: (event) => { props.onEdit(event.target.value); }, children: [_jsx("option", { value: "", children: props.inheritLabel }), _jsx("option", { value: "true", children: props.onLabel }), _jsx("option", { value: "false", children: props.offLabel })] }), _jsx("p", { className: css.hint, children: props.hint })] }));
 }
+/** A staged enumerated field rendered as a select. */
+export function ChoiceField(props) {
+    return (_jsxs("div", { className: css.field, children: [_jsxs("div", { className: css.head, children: [_jsx("label", { className: css.label, htmlFor: props.id, children: props.label }), props.overridden
+                        ? (_jsxs("span", { className: css.badges, children: [_jsx("span", { className: css.badge, children: props.overriddenLabel }), _jsx("button", { type: "button", className: css.reset, disabled: props.disabled, onClick: props.onReset, children: props.resetLabel })] }))
+                        : null] }), _jsxs("select", { id: props.id, className: css.select, value: props.text, disabled: props.disabled, onChange: (event) => { props.onEdit(event.target.value); }, children: [_jsx("option", { value: "", children: props.inheritLabel }), props.choices.map(choice => (_jsx("option", { value: choice.value, children: choice.label }, choice.value)))] }), _jsx("p", { className: props.invalid ? css.invalid : css.hint, children: props.invalid ? props.invalidLabel : props.hint })] }));
+}

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

@@ -1,11 +1,12 @@
 /**
- * dsh-pet browser half — mounts the whale-girl as a global floating surface
- * and drives it from the host's same-origin `/api/pet/*` JSON endpoints: poll
- * the host snapshot (~800 ms), forward interactions, persist drag positions.
- * The pet is host-global (no session dimension), so it mounts directly onto
- * `document.body` via a single React root rather than a session-scoped slot —
- * on the new-conversation screen no session exists, and a dock-mounted pet
- * would vanish there (issue #48). When the pet is hidden the entry becomes a
+ * dsh-pet browser half — mounts the selected pet as a global floating
+ * surface and drives it from the host's same-origin '/api/pet/*' JSON
+ * endpoints: fetch the registry list once, poll the host snapshot (~2 s),
+ * forward interactions, persist drag positions. The pet is host-global (no
+ * session dimension), so it mounts directly onto 'document.body' via a
+ * single React root rather than a session-scoped slot — on the
+ * new-conversation screen no session exists, and a dock-mounted pet would
+ * vanish there (issue #48). When the pet is hidden the entry becomes a
  * fixed-position summon button.
  * @module @linxin666/dsh-pet/client
  */
@@ -14,13 +15,15 @@ import type { ClientContext, SettingsScope, SettingsScopeSpec } from '@deepseek-
 export declare const inject: string[];
 /** Re-exported for consumers that type against the injected face. */
 export type { PetInjected, PetDockEntryProps } from './PetDockEntry.tsx';
+export type { PetSpriteProps } from './PetSprite.tsx';
 export type { PetUiState, PetFeedback } from './pet-store.ts';
 export type { PetSettingsCardFace, PetSettingsCardState } from './PetSettingsCard.tsx';
+export type { PetDefinition } from '../registry.ts';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface SlotMap {
         /**
          * The child slot the Web UI plugin group declares; this card registers
-         * into the group instead of the top-level `settings.plugin.item` list.
+         * into the group instead of the top-level 'settings.plugin.item' list.
          * Spelled here with the same shape so this package can register without
          * depending on the sibling UI package.
          */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAwD7G,yBAAyB;AACzB,eAAO,MAAM,MAAM,UAA+D,CAAA;AAElF,qEAAqE;AACrE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACxE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAEtF,OAAO,QAAQ,kCAAkC,CAAC;IAChD,UAAU,OAAO;QACf;;;;;WAKG;QACH,oBAAoB,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,4BAA4B,CAAA;SAAE,CAAA;KAC3F;CACF;AAED,sEAAsE;AACtE,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf;;;;WAIG;QACH,aAAa,CAAC,EAAE;YAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;SAAE,CAAA;KAC1E;CACF;AAGD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAoK9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AA6D7G,yBAAyB;AACzB,eAAO,MAAM,MAAM,UAA+D,CAAA;AAElF,qEAAqE;AACrE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACxE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC7D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACtF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,QAAQ,kCAAkC,CAAC;IAChD,UAAU,OAAO;QACf;;;;;WAKG;QACH,oBAAoB,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,4BAA4B,CAAA;SAAE,CAAA;KAC3F;CACF;AAED,sEAAsE;AACtE,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,KAAK,CAAA;CACjB;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf;;;;WAIG;QACH,aAAa,CAAC,EAAE;YAAE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;SAAE,CAAA;KAC1E;CACF;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAmL9C"}

package/lib/types/client/index.js

@@ -1,11 +1,12 @@
 /**
- * dsh-pet browser half — mounts the whale-girl as a global floating surface
- * and drives it from the host's same-origin `/api/pet/*` JSON endpoints: poll
- * the host snapshot (~800 ms), forward interactions, persist drag positions.
- * The pet is host-global (no session dimension), so it mounts directly onto
- * `document.body` via a single React root rather than a session-scoped slot —
- * on the new-conversation screen no session exists, and a dock-mounted pet
- * would vanish there (issue #48). When the pet is hidden the entry becomes a
+ * dsh-pet browser half — mounts the selected pet as a global floating
+ * surface and drives it from the host's same-origin '/api/pet/*' JSON
+ * endpoints: fetch the registry list once, poll the host snapshot (~2 s),
+ * forward interactions, persist drag positions. The pet is host-global (no
+ * session dimension), so it mounts directly onto 'document.body' via a
+ * single React root rather than a session-scoped slot — on the
+ * new-conversation screen no session exists, and a dock-mounted pet would
+ * vanish there (issue #48). When the pet is hidden the entry becomes a
  * fixed-position summon button.
  * @module @linxin666/dsh-pet/client
  */
@@ -25,20 +26,22 @@ async function petFetch(path, body) {
             body: JSON.stringify(body),
         });
     if (!response.ok) {
-        throw new Error(`pet ${path} failed: ${response.status}`);
+        throw new Error('pet ' + path + ' failed: ' + response.status);
     }
     return (await response.json());
 }
 /** The live host API instance (always defined; failures surface per call). */
 const petApi = {
     state: () => petFetch('/api/pet/state'),
+    pets: () => petFetch('/api/pet/pets'),
     interact: (kind) => petFetch('/api/pet/interact', { kind }),
     setVisible: (visible) => petFetch('/api/pet/set-visible', { visible }),
     setConfig: (patch) => petFetch('/api/pet/set-config', patch),
     setName: (name) => petFetch('/api/pet/set-name', { name }),
+    setPet: (petId) => petFetch('/api/pet/set-pet', { petId }),
 };
 /** Poll interval for the host snapshot. */
-const POLL_MS = 800;
+const POLL_MS = 2000;
 /** Settings namespace the pet settings card edits (the Host plugin registers it). */
 const PET_SETTINGS_NS = 'pet';
 /** Required services. */
@@ -59,8 +62,9 @@ export function apply(ctx) {
             ? snapshot.value?.enabled ?? true
             : snapshot.status === 'unavailable';
     };
-    // Plugin configuration card: one staged form over the `pet` settings
-    // namespace, contributed to the Web UI plugin group.
+    // Plugin configuration card: one staged form over the 'pet' settings
+    // namespace, contributed to the Web UI plugin group. The controller loads
+    // the petId choices from the registry endpoint itself.
     const petSettings = new PetSettingsCardController(settingsScope);
     ctx.slots.inject('web-ui.plugin.item', () => ctx.slots.register({
         name: 'web-ui.plugin.item',
@@ -81,9 +85,23 @@ export function apply(ctx) {
             // it stateless on the new-conversation screen (no session to scope by).
             const petStore = createPetStore().create();
             const setSnapshot = petStore.actions.setSnapshot;
+            const setPets = petStore.actions.setPets;
             const setState = petStore.actions.setState;
             const setFeedback = petStore.actions.setFeedback;
+            // The registry list is fetched lazily with retries baked into the poll
+            // cycle: until it lands, the dock entry renders nothing and every 2s
+            // tick tries again. After it lands, one list feeds both the sprite and
+            // the settings card's choices.
+            let petsLoaded = false;
             const pollNow = () => {
+                if (!petsLoaded) {
+                    petApi.pets().then((list) => {
+                        petsLoaded = true;
+                        setPets(list);
+                    }, () => {
+                        // Retry on the next poll tick.
+                    });
+                }
                 petApi.state().then((snapshot) => {
                     setSnapshot(snapshot);
                 }, () => {
@@ -95,7 +113,7 @@ export function apply(ctx) {
                 // change while the page is hidden, so a background interval would
                 // only burn RPCs (browser throttling is an unreliable backstop).
                 // Coming back to the tab refreshes the pet immediately instead of
-                // waiting out the next 800 ms cycle.
+                // waiting out the next 2 s cycle.
                 let timer;
                 const stop = () => {
                     if (timer !== undefined) {
@@ -187,8 +205,8 @@ export function apply(ctx) {
             // for a global floating surface — the dock is session-scoped, so a pet
             // mounted there would vanish on the new-conversation screen (issue #48).
             // The entry therefore mounts straight onto document.body via a single
-            // React root for the page lifetime: WhalePet portals itself to body when
-            // visible, and the hidden-state summon button is fixed-positioned.
+            // React root for the page lifetime: PetSprite portals itself to body
+            // when visible, and the hidden-state summon button is fixed-positioned.
             const container = document.createElement('div');
             container.dataset.dshPetRoot = '';
             document.body.appendChild(container);

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

@@ -15,10 +15,12 @@ export declare const zh: {
     readonly 'pet.rank': "亲密度 {rank}";
     readonly 'pet.points': "{points} 点";
     readonly 'pet.treats': "小鱼干 ×{n}";
-    readonly 'pet.state.loading': "鲸鱼娘正在赶来…";
-    readonly 'pet.state.error': "鲸鱼娘迷路了（连接失败）";
+    readonly 'pet.state.loading': "宠物正在赶来…";
+    readonly 'pet.state.error': "宠物迷路了（连接失败）";
     readonly 'settings.title': "宠物";
-    readonly 'settings.description': "鲸鱼娘的显示布局与名字。";
+    readonly 'settings.description': "选择宠物并调整它的显示布局。";
+    readonly 'settings.pet': "宠物";
+    readonly 'settings.petHint': "选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。";
     readonly 'settings.enabled': "启用宠物";
     readonly 'settings.enabledHint': "关闭后隐藏宠物并停止轮询，可在设置里重新启用。";
     readonly 'settings.visible': "显示宠物";
@@ -29,8 +31,6 @@ export declare const zh: {
     readonly 'settings.rightHint': "距视口右边缘的水平内缩距离。";
     readonly 'settings.bottom': "距底部（px）";
     readonly 'settings.bottomHint': "距视口底边的垂直内缩距离。";
-    readonly 'settings.name': "名字";
-    readonly 'settings.nameHint': "宠物显示名，1–20 个字符。";
     readonly 'settings.inherit': "继承";
     readonly 'settings.on': "开";
     readonly 'settings.off': "关";
@@ -58,10 +58,12 @@ export declare const en: {
     readonly 'pet.rank': "Affinity {rank}";
     readonly 'pet.points': "{points} pts";
     readonly 'pet.treats': "Treats ×{n}";
-    readonly 'pet.state.loading': "The whale girl is on her way…";
-    readonly 'pet.state.error': "The whale girl is lost (connection failed)";
+    readonly 'pet.state.loading': "The pet is on its way…";
+    readonly 'pet.state.error': "The pet is lost (connection failed)";
     readonly 'settings.title': "Pet";
-    readonly 'settings.description': "The whale girl’s display layout and name.";
+    readonly 'settings.description': "Pick a pet and tune its display layout.";
+    readonly 'settings.pet': "Pet";
+    readonly 'settings.petHint': "Choose which pet shows. Names are stored per pet; rename from the pet hover panel.";
     readonly 'settings.enabled': "Enable the pet";
     readonly 'settings.enabledHint': "When off, the pet hides and polling stops; re-enable it here.";
     readonly 'settings.visible': "Show the pet";
@@ -72,8 +74,6 @@ export declare const en: {
     readonly 'settings.rightHint': "Horizontal inset from the viewport right edge.";
     readonly 'settings.bottom': "Bottom inset (px)";
     readonly 'settings.bottomHint': "Vertical inset from the viewport bottom edge.";
-    readonly 'settings.name': "Name";
-    readonly 'settings.nameHint': "The pet’s display name, 1–20 characters.";
     readonly 'settings.inherit': "Inherit";
     readonly 'settings.on': "On";
     readonly 'settings.off': "Off";