@linxin666/dsh-pet 0.1.14 → 0.1.16

package/src/client/{WhalePet.tsx → PetSprite.tsx}

@@ -1,47 +1,47 @@
 /**
- * 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 type { PointerEvent as ReactPointerEvent, ReactPortal } from 'react'
 import { createPortal } from 'react-dom'
+import clsx from 'clsx'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetStateView } from '../service.ts'
+import type { PetDefinition } from '../registry.ts'
 import type { PetFeedback } from './pet-store.ts'
-import { framePosition, FRAME_WIDTH, FRAME_HEIGHT, FRAME_COLUMNS, TRACKS, rowOfTrack, trimTrack, detectFrameCounts } from './spritesheet.ts'
+import { framePosition, rowOfTrack, trimTrack } from './spritesheet.ts'
 import type { PetAnimation } from '../state.ts'
 import { NS } from './locales.ts'
 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'
-
-/** Props injected by the slot registration (store actions + locale). */
-export interface WhalePetProps {
+/** Props injected by the plugin apply body (store actions + locale). */
+export interface PetSpriteProps {
   /** Latest host snapshot; null while loading. */
   snapshot: PetStateView | null
+  /** The selected pet's registry definition (atlas URL + geometry + tracks). */
+  definition: PetDefinition
   /** Display configuration (persisted by the host). */
   display: PetDisplayConfig
   /** Active reaction bubble, if any. */
   feedback: PetFeedback | null
-  /** Pet the whale girl (click). */
+  /** Pet the sprite (click). */
   onPet: () => void
-  /** Feed the whale girl (panel button). */
+  /** Feed the sprite (panel button). */
   onFeed: () => void
-  /** Hide the whale girl (panel button). */
+  /** Hide the sprite (panel button). */
   onHide: () => void
   /** Persist a drag position. */
   onDragEnd: (right: number, bottom: number) => void
-  /** Rename the pet (persisted by the host). */
+  /** Rename the selected pet (persisted by the host). */
   onRename: (name: string) => void
   /** Clear the reaction bubble (after its CSS animation). */
   onFeedbackDone: () => void
@@ -56,16 +56,15 @@ function clampOffset(value: number, max: number): number {
 
 /**
  * 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: WhalePetProps): ReactPortal {
-  const { snapshot, display, feedback } = props
+export function PetSprite(props: PetSpriteProps): ReactPortal {
+  const { snapshot, definition, display, feedback } = props
   const spriteRef = useRef<HTMLDivElement | null>(null)
   const floatRef = useRef<HTMLDivElement | null>(null)
   const [imageReady, setImageReady] = useState(false)
-  const [frameCounts, setFrameCounts] = useState<number[] | null>(null)
   const [hovered, setHovered] = useState(false)
   const [renaming, setRenaming] = useState(false)
   const [nameDraft, setNameDraft] = useState('')
@@ -78,39 +77,25 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
     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<{ frames?: unknown }>({})))
-        .then((manifest: { frames?: unknown }) => {
-          if (cancelled) return
-          const frames = manifest.frames
-          if (Array.isArray(frames) && frames.length === 9 && frames.every((n) => typeof n === 'number')) {
-            setFrameCounts(frames as number[])
-          } 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
@@ -118,23 +103,21 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
   // 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
     let raf = 0
@@ -145,9 +128,7 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
       // 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
@@ -169,18 +150,18 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
         }
       }
       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
@@ -192,7 +173,7 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
 
   // 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 = (): void => {
     if (hideTimerRef.current !== null) {
@@ -226,9 +207,10 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
   }
 
   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 = (
     <div
@@ -245,7 +227,7 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
         // 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)) return
@@ -259,8 +241,8 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
         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',
@@ -275,15 +257,15 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
           props.onPet()
         }}
         role="button"
-        aria-label="whale girl"
+        aria-label={definition.displayName}
       />
       {feedback !== null && (
-        <div key={feedback.at} className={`${styles.bubble} ${feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet}`}>
+        <div key={feedback.at} className={clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet)}>
           {feedback.text}
         </div>
       )}
       {statusBubble !== undefined && (
-        <div className={`${styles.bubble} ${styles.bubbleStatus}`} role="status" aria-live="polite">
+        <div className={clsx(styles.bubble, styles.bubbleStatus)} role="status" aria-live="polite">
           {statusBubble}
         </div>
       )}
@@ -340,7 +322,7 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
           ) : (
             <>
               <div className={styles.rankRow}>
-                <span className={styles.nameCell}>{snapshot?.name ?? '鲸鱼娘'}</span>
+                <span className={styles.nameCell}>{displayName}</span>
                 <span>{props.t('pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
               </div>
               <div className={styles.rankRow}>
@@ -355,7 +337,7 @@ export function WhalePet(props: WhalePetProps): ReactPortal {
                   type="button"
                   className={styles.action}
                   onClick={() => {
-                    setNameDraft(snapshot?.name ?? '')
+                    setNameDraft(displayName)
                     setRenaming(true)
                   }}
                 >

package/src/client/PluginSettingsCard.tsx

@@ -1,25 +1,44 @@
+// 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, type ReactNode } from 'react'
 import type { CardShell } from './settings-form.ts'
-import type { SettingsCardKey } from './locales.ts'
 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',
+] as const
+
+/** 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. */
@@ -35,11 +54,12 @@ 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 function PluginSettingsCard(props: PluginSettingsCardProps) {
+export function PluginSettingsCard<TKey extends string = string>(props: PluginSettingsCardProps<TKey>) {
   const [open, setOpen] = useState(false)
   const { state } = 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
@@ -57,8 +77,8 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
           onClick={() => { setOpen(!open) }}
         >
           <span className={css.headText}>
-            <span className={css.name}>{title}</span>
-            <span className={css.description}>{props.t(props.descriptionKey)}</span>
+            <span className={css.name} title={title}>{title}</span>
+            <span className={css.description} title={description}>{description}</span>
           </span>
           <svg
             width="14"
@@ -94,10 +114,10 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
         onClick={() => { setOpen(!open) }}
       >
         <span className={css.headText}>
-          <span className={css.name}>{title}</span>
-          <span className={css.description}>{props.t(props.descriptionKey)}</span>
+          <span className={css.name} title={title}>{title}</span>
+          <span className={css.description} title={description}>{description}</span>
         </span>
-        {state.dirty ? <span className={css.pending}>{props.t('settings.unsaved')}</span> : null}
+        {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
         <svg
           width="14"
           height="14"
@@ -118,7 +138,13 @@ export function PluginSettingsCard(props: PluginSettingsCardProps) {
             {!state.writable ? <p className={css.readOnly} role="status">{props.t('settings.readOnly')}</p> : null}
             {props.children}
             <div className={css.footer}>
-              {state.failed ? <p className={css.failed} role="status">{props.t('settings.saveFailed')}</p> : null}
+              {state.failed
+                ? (
+                  <p className={css.failed} role="status">
+                    {props.t('settings.saveFailed')}{state.failedReason ? ' - ' + state.failedReason : ''}
+                  </p>
+                )
+                : null}
               <button
                 type="button"
                 className={css.discard}
@@ -259,4 +285,50 @@ export function BooleanField(props: FieldProps & {
       <p className={css.hint}>{props.hint}</p>
     </div>
   )
-}
+}
+
+/** A staged enumerated field rendered as a select. */
+export 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 }>
+}) {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden
+          ? (
+            <span className={css.badges}>
+              <span className={css.badge}>{props.overriddenLabel}</span>
+              <button
+                type="button"
+                className={css.reset}
+                disabled={props.disabled}
+                onClick={props.onReset}
+              >
+                {props.resetLabel}
+              </button>
+            </span>
+          )
+          : null}
+      </div>
+      <select
+        id={props.id}
+        className={css.select}
+        value={props.text}
+        disabled={props.disabled}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      >
+        <option value="">{props.inheritLabel}</option>
+        {props.choices.map(choice => (
+          <option key={choice.value} value={choice.value}>{choice.label}</option>
+        ))}
+      </select>
+      <p className={props.invalid ? css.invalid : css.hint}>
+        {props.invalid ? props.invalidLabel : props.hint}
+      </p>
+    </div>
+  )
+}

package/src/client/index.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
  */
@@ -20,6 +21,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetInteractResult, PetStateView } from '../service.ts'
 import type { PetInteraction } from '../affinity.ts'
+import type { PetDefinition } from '../registry.ts'
 import { createElement } from 'react'
 import { createRoot } from 'react-dom/client'
 import { createPetStore, type PetStoreInstance } from './pet-store.ts'
@@ -30,10 +32,12 @@ import { NS, en, zh, t } from './locales.ts'
 /** The host pet API as the browser sees it (same-origin JSON endpoints). */
 interface PetHttpApi {
   state(): Promise<PetStateView>
+  pets(): Promise<PetDefinition[]>
   interact(kind: PetInteraction): Promise<PetInteractResult>
   setVisible(visible: boolean): Promise<{ ok: true; display: PetDisplayConfig }>
   setConfig(patch: Partial<PetDisplayConfig>): Promise<{ ok: true; display: PetDisplayConfig }>
   setName(name: string): Promise<{ ok: true; name: string } | { ok: false; error: string }>
+  setPet(petId: string): Promise<{ ok: true; petId: string } | { ok: false; error: string }>
 }
 
 /** Same-origin JSON fetch helper (GET without body, POST with JSON body). */
@@ -46,7 +50,7 @@ async function petFetch<T>(path: string, body?: unknown): Promise<T> {
         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()) as T
 }
@@ -54,14 +58,16 @@ async function petFetch<T>(path: string, body?: unknown): Promise<T> {
 /** The live host API instance (always defined; failures surface per call). */
 const petApi: PetHttpApi = {
   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'
@@ -71,14 +77,16 @@ export const inject = ['slots', 'locale', 'connection', 'settingsScope', 'remote
 
 /** 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.
      */
@@ -103,7 +111,6 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
-
 /**
  * Client plugin body: register dictionaries, mount the global pet entry and
  * poll loop while the plugin is enabled, and seat the settings card in the
@@ -122,8 +129,9 @@ export function apply(ctx: ClientContext): void {
       : 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',
@@ -145,10 +153,24 @@ export function apply(ctx: ClientContext): void {
       // it stateless on the new-conversation screen (no session to scope by).
       const petStore: PetStoreInstance = 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 = (): void => {
+        if (!petsLoaded) {
+          petApi.pets().then((list) => {
+            petsLoaded = true
+            setPets(list)
+          }, () => {
+            // Retry on the next poll tick.
+          })
+        }
         petApi.state().then((snapshot) => {
           setSnapshot(snapshot)
         }, () => {
@@ -161,7 +183,7 @@ export function apply(ctx: ClientContext): void {
         // 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: number | undefined
         const stop = (): void => {
           if (timer !== undefined) {
@@ -253,8 +275,8 @@ export function apply(ctx: ClientContext): void {
       // 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/src/client/locales.ts

@@ -17,11 +17,13 @@ export const zh = {
   'pet.rank': '亲密度 {rank}',
   'pet.points': '{points} 点',
   'pet.treats': '小鱼干 ×{n}',
-  'pet.state.loading': '鲸鱼娘正在赶来…',
-  'pet.state.error': '鲸鱼娘迷路了（连接失败）',
+  'pet.state.loading': '宠物正在赶来…',
+  'pet.state.error': '宠物迷路了（连接失败）',
   // 插件设置卡片（settings.plugin.item 席位）。
   'settings.title': '宠物',
-  'settings.description': '鲸鱼娘的显示布局与名字。',
+  'settings.description': '选择宠物并调整它的显示布局。',
+  'settings.pet': '宠物',
+  'settings.petHint': '选择显示哪只宠物；每只宠物独立命名，可在宠物悬浮面板改名。',
   'settings.enabled': '启用宠物',
   'settings.enabledHint': '关闭后隐藏宠物并停止轮询，可在设置里重新启用。',
   'settings.visible': '显示宠物',
@@ -32,8 +34,6 @@ export const zh = {
   'settings.rightHint': '距视口右边缘的水平内缩距离。',
   'settings.bottom': '距底部（px）',
   'settings.bottomHint': '距视口底边的垂直内缩距离。',
-  'settings.name': '名字',
-  'settings.nameHint': '宠物显示名，1–20 个字符。',
   'settings.inherit': '继承',
   'settings.on': '开',
   'settings.off': '关',
@@ -62,11 +62,13 @@ export const en = {
   'pet.rank': 'Affinity {rank}',
   'pet.points': '{points} pts',
   'pet.treats': 'Treats ×{n}',
-  'pet.state.loading': 'The whale girl is on her way…',
-  'pet.state.error': 'The whale girl is lost (connection failed)',
+  'pet.state.loading': 'The pet is on its way…',
+  'pet.state.error': 'The pet is lost (connection failed)',
   // Plugin settings card (the `settings.plugin.item` seat).
   'settings.title': 'Pet',
-  'settings.description': 'The whale girl\u2019s display layout and name.',
+  '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.',
   'settings.enabled': 'Enable the pet',
   'settings.enabledHint': 'When off, the pet hides and polling stops; re-enable it here.',
   'settings.visible': 'Show the pet',
@@ -77,8 +79,6 @@ export const en = {
   'settings.rightHint': 'Horizontal inset from the viewport right edge.',
   'settings.bottom': 'Bottom inset (px)',
   'settings.bottomHint': 'Vertical inset from the viewport bottom edge.',
-  'settings.name': 'Name',
-  'settings.nameHint': 'The pet\u2019s display name, 1\u201320 characters.',
   'settings.inherit': 'Inherit',
   'settings.on': 'On',
   'settings.off': 'Off',