@linxin666/dsh-pet 0.1.15 → 0.1.16

package/src/client/PetDockEntry.tsx

@@ -1,11 +1,13 @@
 /**
  * Global floating pet entry. The pet is host-global (its state, display and
- * interactions live on `/api/pet/*` endpoints with no session dimension), so
+ * interactions live on '/api/pet/*' endpoints with no session dimension), so
  * it must not ride a session-scoped slot — on the new-conversation screen no
  * session exists to scope a slot by, and the pet would vanish (issue #48).
- * The client half therefore mounts this entry straight onto `document.body`
- * (see index.ts): while visible it renders the floating WhalePet (a portal),
- * while hidden it renders a fixed-position summon button.
+ * The client half therefore mounts this entry straight onto 'document.body'
+ * (see index.ts): while visible it renders the floating PetSprite (a
+ * portal), while hidden it renders a fixed-position summon button. Which
+ * sprite renders is decided by the host snapshot's pet id resolved against
+ * the registry list — no per-pet component exists.
  * @module @linxin666/dsh-pet/client/PetDockEntry
  */
 
@@ -13,27 +15,27 @@ import { useEffect, useSyncExternalStore, type ReactElement } from 'react'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetStoreInstance } from './pet-store.ts'
-import { WhalePet } from './WhalePet.tsx'
+import { PetSprite } from './PetSprite.tsx'
 import { NS } from './locales.ts'
 import styles from './pet.module.css'
 
 /** Injected actions handed to the dock entry component. */
 export interface PetInjected {
-  /** The app-wide pet store instance (snapshot + feedback). */
+  /** The app-wide pet store instance (snapshot + registry list + feedback). */
   store: PetStoreInstance
-  /** Ensure the first snapshot is fetched (called on mount). */
+  /** Ensure the first snapshot (and registry list) is fetched (called on mount). */
   ensure: () => void
-  /** Pet the whale girl (click). */
+  /** Pet the sprite (click). */
   pet: () => void
-  /** Feed the whale girl. */
+  /** Feed the sprite. */
   feed: () => void
-  /** Hide the whale girl. */
+  /** Hide the sprite. */
   hide: () => void
-  /** Summon the hidden whale girl back. */
+  /** Summon the hidden sprite back. */
   summon: () => void
   /** Persist a drag position. */
   dragEnd: (right: number, bottom: number) => void
-  /** Rename the pet (persisted by the host). */
+  /** Rename the selected pet (persisted by the host). */
   rename: (name: string) => void
   /** Clear the reaction bubble. */
   feedbackDone: () => void
@@ -47,7 +49,7 @@ export type PetDockEntryProps =
 const DEFAULT_DISPLAY: PetDisplayConfig = { visible: true, size: 160, right: 24, bottom: 20 }
 
 /**
- * Dock entry: while the pet is visible, mount the floating WhalePet (it
+ * Dock entry: while the pet is visible, mount the floating PetSprite (it
  * portals itself onto document.body); while hidden, render the summon
  * button so the pet can always come back. The store is the plugin-owned
  * single instance — the slot system provides none because the pet is
@@ -58,6 +60,7 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
   const ui = useSyncExternalStore(store.subscribe, store.getSnapshot)
   const snapshot = ui.snapshot
   const feedback = ui.feedback
+  const definition = ui.pets.find(entry => entry.id === snapshot?.pet.id) ?? null
   const visible = snapshot?.display.visible ?? true
 
   useEffect(() => {
@@ -67,18 +70,23 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
   if (visible) {
     return (
       <span data-pet-dock data-testid="pet-dock">
-        <WhalePet
-          snapshot={snapshot}
-          display={snapshot?.display ?? DEFAULT_DISPLAY}
-          feedback={feedback}
-          onPet={props.pet}
-          onFeed={props.feed}
-          onHide={props.hide}
-          onDragEnd={props.dragEnd}
-          onRename={props.rename}
-          onFeedbackDone={props.feedbackDone}
-          t={props.t}
-        />
+        {snapshot === null || definition === null
+          ? null
+          : (
+            <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}
+              onFeedbackDone={props.feedbackDone}
+              t={props.t}
+            />
+          )}
       </span>
     )
   }
@@ -96,7 +104,7 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
       onClick={props.summon}
       data-testid="pet-summon"
     >
-      {props.t('pet.summon', { name: snapshot?.name ?? '鲸鱼娘' })}
+      {props.t('pet.summon', { name: snapshot?.name ?? '' })}
     </button>
   )
 }

package/src/client/PetSettingsCard.tsx

@@ -1,13 +1,15 @@
 /**
- * The pet settings card: display layout and name, bound to the `pet` settings
- * namespace the host plugin registers. Registered into the
- * `settings.plugin.item` slot the plugin-configuration section renders.
+ * The pet settings card: pet selection plus display layout, bound to the
+ * 'pet' settings namespace the host plugin registers. Registered into the
+ * 'web-ui.plugin.item' slot the plugin-configuration section renders. The
+ * petId choices come from the registry endpoint ('/api/pet/pets') — the same
+ * list the sprite renders from — so the card carries no per-pet knowledge.
  */
 
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
-import { PluginSettingsCard, ValueField, BooleanField } from './PluginSettingsCard.tsx'
-import { CardForm, booleanField, numberField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
+import { PluginSettingsCard, ValueField, BooleanField, ChoiceField } from './PluginSettingsCard.tsx'
+import { CardForm, booleanField, choiceField, numberField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
 
 /** The pet's settings fields this card edits (the namespace's full schema). */
 export interface PetSettings {
@@ -21,8 +23,8 @@ export interface PetSettings {
   right?: number
   /** Vertical inset from the viewport bottom edge, px. */
   bottom?: number
-  /** User-customizable pet display name. */
-  name?: string
+  /** Selected pet id (a registry entry). */
+  petId?: string
 }
 
 /** What the pet settings card renders. */
@@ -37,8 +39,10 @@ export interface PetSettingsCardState extends CardShell {
   right: CardFieldState
   /** Bottom inset. */
   bottom: CardFieldState
-  /** Pet name. */
-  name: CardFieldState
+  /** Selected pet. */
+  petId: CardFieldState
+  /** Pet choices (registry ids + display names), loaded from the host. */
+  petChoices: readonly { value: string; label: string }[]
 }
 
 /** The registration-side face the card's slot entry injects. */
@@ -49,12 +53,32 @@ export interface PetSettingsCardFace extends CardActions {
   }
 }
 
-/** Bridges the `pet` scope onto the card's staged form. */
+/** One registry choice as served by '/api/pet/pets'. */
+interface PetChoice {
+  id: string
+  displayName: string
+}
+
+/** Fetch the registry list (the same data the sprite renders from). */
+async function fetchPetChoices(): Promise<PetChoice[]> {
+  const response = await fetch('/api/pet/pets')
+  if (!response.ok) throw new Error('pet pets failed: ' + response.status)
+  return (await response.json()) as PetChoice[]
+}
+
+/** Bridges the 'pet' scope onto the card's staged form. */
 export class PetSettingsCardController {
   private readonly form: CardForm<PetSettings>
   private readonly store: SnapshotStore<PetSettingsCardState>
+  // The choice list rides a mutable array shared with the choiceField spec,
+  // so loading the registry re-validates and re-formats the petId field
+  // without rebuilding the form.
+  private readonly petChoices: string[] = []
+  private readonly petLabels = new Map<string, string>()
+  private loaded = false
+  private attempts = 0
 
-  /** @param scope - the bound settings scope for the `pet` namespace. */
+  /** @param scope - the bound settings scope for the 'pet' namespace. */
   constructor(scope: SettingsScope<PetSettings>) {
     this.form = new CardForm(scope, [
       booleanField('enabled'),
@@ -62,9 +86,27 @@ export class PetSettingsCardController {
       numberField('size'),
       numberField('right'),
       numberField('bottom'),
-      textField('name'),
+      choiceField('petId', this.petChoices),
     ])
     this.store = this.form.bind(() => this.projection())
+    void this.loadPets()
+  }
+
+  /** Resolve the registry choices once (retried a few times on failure). */
+  private async loadPets(): Promise<void> {
+    if (this.loaded) return
+    try {
+      const list = await fetchPetChoices()
+      this.petChoices.splice(0, this.petChoices.length, ...list.map(choice => choice.id))
+      for (const choice of list) this.petLabels.set(choice.id, choice.displayName)
+      this.loaded = true
+      this.store.set(this.projection())
+    } catch {
+      this.attempts += 1
+      if (this.attempts < 3) {
+        window.setTimeout(() => { void this.loadPets() }, 3000)
+      }
+    }
   }
 
   private projection(): PetSettingsCardState {
@@ -75,7 +117,8 @@ export class PetSettingsCardController {
       size: this.form.field('size'),
       right: this.form.field('right'),
       bottom: this.form.field('bottom'),
-      name: this.form.field('name'),
+      petId: this.form.field('petId'),
+      petChoices: this.petChoices.map(id => ({ value: id, label: this.petLabels.get(id) ?? id })),
     }
   }
 
@@ -130,6 +173,17 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         onEdit={(text) => { props.edit('enabled', text) }}
         onReset={() => { props.resetField('enabled') }}
       />
+      <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') }}
+      />
       <BooleanField
         id="settings-pet-visible"
         label={t('settings.visible')}
@@ -172,15 +226,6 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         onEdit={(text) => { props.edit('bottom', text) }}
         onReset={() => { props.resetField('bottom') }}
       />
-      <ValueField
-        id="settings-pet-name"
-        label={t('settings.name')}
-        hint={t('settings.nameHint')}
-        {...fieldProps}
-        {...state.name}
-        onEdit={(text) => { props.edit('name', text) }}
-        onReset={() => { props.resetField('name') }}
-      />
     </PluginSettingsCard>
   )
 }

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

@@ -1,14 +1,47 @@
 // @vitest-environment jsdom
 /**
- * WhalePet rename-box keyboard handling. The rename input must treat
+ * PetSprite rename-box keyboard handling. The rename input must treat
  * Enter/Escape keydowns that arrive during IME composition (candidate
  * selection) as composition input, never as submit/cancel (issue #89).
  */
 import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
-import { WhalePet, type WhalePetProps } from './WhalePet.tsx'
+import { PetSprite, type PetSpriteProps } from './PetSprite.tsx'
 import { t } from './locales.ts'
 import type { PetStateView } from '../service.ts'
+import type { PetDefinition, PetTrackDef } from '../registry.ts'
+import type { PetAnimation } from '../state.ts'
+
+/** A minimal pet definition (geometry + tracks) as served by the host. */
+function petDefinition(): PetDefinition {
+  const track = (frames: number[], durations: number[], loop = true, fallback?: PetAnimation): PetTrackDef => ({
+    frames,
+    durations,
+    loop,
+    ...(fallback === undefined ? {} : { fallback }),
+  })
+  return {
+    id: 'whale-girl',
+    displayName: '鲸鱼娘',
+    description: '测试用鲸鱼娘',
+    cell: { width: 192, height: 208 },
+    columns: 8,
+    rows: [6, 8, 8, 4, 5, 8, 6, 6, 6],
+    tracks: {
+      idle: track([0, 1, 2, 3, 4, 5], [400, 400, 400, 400, 400, 400]),
+      'running-right': track([0, 1, 2, 3, 4, 5, 6, 7], [225, 225, 225, 225, 225, 225, 225, 225]),
+      'running-left': track([0, 1, 2, 3, 4, 5, 6, 7], [225, 225, 225, 225, 225, 225, 225, 225]),
+      waving: track([0, 1, 2, 3], [350, 350, 350, 350]),
+      jumping: track([0, 1, 2, 3, 4], [300, 300, 300, 300, 300], false, 'idle'),
+      failed: track([0, 1, 2, 3, 4, 5, 6, 7], [450, 450, 450, 450, 450, 450, 450, 450], false, 'idle'),
+      waiting: track([0, 1, 2, 3, 4, 5], [450, 450, 450, 450, 450, 450]),
+      running: track([0, 1, 2, 3, 4, 5], [250, 250, 250, 250, 250, 250]),
+      review: track([0, 1, 2, 3, 4, 5], [550, 550, 550, 550, 550, 550]),
+    },
+    atlasUrl: '/pet/whale-girl/spritesheet.webp',
+    manifestUrl: '/pet/whale-girl/pet.json',
+  }
+}
 
 /** Snapshot fixture: idle whale girl named 泡泡. */
 const snapshot: PetStateView = {
@@ -26,6 +59,7 @@ const snapshot: PetStateView = {
     feedCooldown: false,
   },
   display: { visible: true, size: 160, right: 24, bottom: 20 },
+  pet: { id: 'whale-girl', displayName: '鲸鱼娘', description: '测试用鲸鱼娘' },
   name: '泡泡',
   treats: { stocked: 3, max: 5 },
 }
@@ -55,10 +89,11 @@ afterEach(() => {
 })
 
 /** Render the pet with mocked callbacks; returns the rename spy. */
-function renderPet(overrides: Partial<WhalePetProps> = {}): { onRename: ReturnType<typeof vi.fn> } {
+function renderPet(overrides: Partial<PetSpriteProps> = {}): { onRename: ReturnType<typeof vi.fn> } {
   const onRename = vi.fn()
-  const props: WhalePetProps = {
+  const props: PetSpriteProps = {
     snapshot,
+    definition: petDefinition(),
     display: snapshot.display,
     feedback: null,
     onPet: vi.fn(),
@@ -70,13 +105,13 @@ function renderPet(overrides: Partial<WhalePetProps> = {}): { onRename: ReturnTy
     t,
     ...overrides,
   }
-  render(<WhalePet {...props} />)
+  render(<PetSprite {...props} />)
   return { onRename }
 }
 
 /** Hover the sprite to open the panel, then click the rename button. */
 function openRename(): HTMLInputElement {
-  fireEvent.pointerOver(screen.getByRole('button', { name: 'whale girl' }))
+  fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
   fireEvent.click(screen.getByText('改名'))
   return screen.getByPlaceholderText('输入新名字') as HTMLInputElement
 }
@@ -100,7 +135,7 @@ function fireComposingKeydown(target: Element, key: string): void {
   fireEvent.compositionEnd(target)
 }
 
-describe('WhalePet rename input', () => {
+describe('PetSprite rename input', () => {
   it('submits the draft on Enter outside composition', () => {
     const { onRename } = renderPet()
     const input = openRename()
@@ -138,7 +173,7 @@ describe('WhalePet rename input', () => {
   })
 })
 
-describe('WhalePet status bubble', () => {
+describe('PetSprite status bubble', () => {
   const workingSnapshot: PetStateView = {
     ...snapshot,
     animation: 'running',
@@ -160,3 +195,16 @@ describe('WhalePet status bubble', () => {
     expect(screen.queryByText('正在思考')).toBeNull()
   })
 })
+
+describe('PetSprite definition-driven render', () => {
+  it('labels the sprite with the pet display name', () => {
+    renderPet()
+    expect(screen.queryByRole('button', { name: '鲸鱼娘' })).not.toBeNull()
+  })
+
+  it('shows the renamed snapshot name in the hover panel', () => {
+    renderPet()
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.queryByText('泡泡')).not.toBeNull()
+  })
+})

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)
                   }}
                 >