@linxin666/dsh-pet 0.2.2 → 0.2.4

package/src/client/PetSprite.test.tsx

@@ -11,6 +11,7 @@ import { t } from './locales.ts'
 import type { PetStateView } from '../service.ts'
 import type { PetDefinition, PetTrackDef } from '../registry.ts'
 import type { PetAnimation } from '../state.ts'
+import type { DecorationView } from '../contracts/status-decoration.ts'
 
 /** A minimal pet definition (geometry + tracks) as served by the host. */
 function petDefinition(): PetDefinition {
@@ -24,6 +25,7 @@ function petDefinition(): PetDefinition {
     id: 'whale-girl',
     displayName: '鲸鱼娘',
     description: '测试用鲸鱼娘',
+    renderer: 'sprite2d',
     cell: { width: 192, height: 208 },
     columns: 8,
     rows: [6, 8, 8, 4, 5, 8, 6, 6, 6],
@@ -90,14 +92,9 @@ afterEach(() => {
   vi.restoreAllMocks()
 })
 
-/** Render the pet with mocked callbacks; returns the rename and open spys. */
-function renderPet(overrides: Partial<PetSpriteProps> = {}): {
-  onRename: ReturnType<typeof vi.fn>
-  onOpenSession: ReturnType<typeof vi.fn>
-} {
-  const onRename = vi.fn()
-  const onOpenSession = vi.fn()
-  const props: PetSpriteProps = {
+/** Build the mocked props for one render. */
+function petProps(overrides: Partial<PetSpriteProps> = {}): PetSpriteProps {
+  return {
     snapshot,
     definition: petDefinition(),
     display: snapshot.display,
@@ -106,14 +103,24 @@ function renderPet(overrides: Partial<PetSpriteProps> = {}): {
     onFeed: vi.fn(),
     onHide: vi.fn(),
     onDragEnd: vi.fn(),
-    onRename,
-    onOpenSession,
+    onRename: vi.fn(),
+    onOpenSession: vi.fn(),
     onFeedbackDone: vi.fn(),
     t,
     ...overrides,
   }
-  render(<PetSprite {...props} />)
-  return { onRename, onOpenSession }
+}
+
+/** Render the pet with mocked callbacks; returns the rename/open spys + the RTL result. */
+function renderPet(overrides: Partial<PetSpriteProps> = {}): {
+  onRename: ReturnType<typeof vi.fn>
+  onOpenSession: ReturnType<typeof vi.fn>
+  result: ReturnType<typeof render>
+} {
+  const onRename = vi.fn()
+  const onOpenSession = vi.fn()
+  const result = render(<PetSprite {...petProps({ onRename, onOpenSession, ...overrides })} />)
+  return { onRename, onOpenSession, result }
 }
 
 /** Hover the sprite to open the panel, then click the rename button. */
@@ -142,6 +149,16 @@ function fireComposingKeydown(target: Element, key: string): void {
   fireEvent.compositionEnd(target)
 }
 
+describe('PetSprite custom visual (pet-center M3)', () => {
+  it('renders the visual inside the sprite box and skips the atlas background', () => {
+    renderPet({ visual: <canvas data-testid="custom-visual" /> })
+    const spriteEl = screen.getByRole('button', { name: '鲸鱼娘' })
+    expect(spriteEl.querySelector('[data-testid="custom-visual"]')).toBeTruthy()
+    // The atlas background never applies while a renderer visual owns the box.
+    expect(spriteEl.style.backgroundImage).toBe('')
+  })
+})
+
 describe('PetSprite rename input', () => {
   it('submits the draft on Enter outside composition', () => {
     const { onRename } = renderPet()
@@ -544,3 +561,239 @@ describe('PetSprite definition-driven render', () => {
     expect(sprite.style.backgroundPosition).toBe('0px -960px')
   })
 })
+
+describe('PetSprite panel chrome from the voice pack (pet-center M4)', () => {
+  const voicedDefinition = (): PetDefinition => ({
+    ...petDefinition(),
+    panel: {
+      labels: { feed: '投喂', rename: '起名字', hide: '藏起来', confirm: '好的' },
+      stats: { rank: '好感 {rank}', treats: '鱼干 {n}', points: '{points} 分' },
+    },
+  })
+
+  it('renders pack labels and stat formats, falling back per slot', () => {
+    renderPet({ definition: voicedDefinition() })
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.getByText('投喂')).toBeDefined()
+    expect(screen.getByText('起名字')).toBeDefined()
+    expect(screen.getByText('藏起来')).toBeDefined()
+    expect(screen.getByText('好感 幼鲸')).toBeDefined()
+    expect(screen.getByText('鱼干 3')).toBeDefined()
+    expect(screen.getByText('0 分')).toBeDefined()
+  })
+
+  it('uses the pack confirm label inside the rename row', () => {
+    renderPet({ definition: voicedDefinition() })
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    fireEvent.click(screen.getByText('起名字'))
+    expect(screen.getByText('好的')).toBeDefined()
+  })
+
+  it('hides actions the pack omits', () => {
+    renderPet({
+      definition: {
+        ...petDefinition(),
+        panel: { labels: { feed: '投喂' }, actions: ['feed'] },
+      },
+    })
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.getByText('投喂')).toBeDefined()
+    expect(screen.queryByText('改名')).toBeNull()
+    expect(screen.queryByText('隐藏')).toBeNull()
+  })
+
+  it('renders no action buttons when the pack hides them all', () => {
+    renderPet({ definition: { ...petDefinition(), panel: { actions: [] } } })
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.queryByText('喂食')).toBeNull()
+    expect(screen.queryByText('改名')).toBeNull()
+    expect(screen.queryByText('隐藏')).toBeNull()
+    // The stat rows keep rendering.
+    expect(screen.getByText('亲密度 幼鲸')).toBeDefined()
+    expect(screen.getByText('小鱼干 ×3')).toBeDefined()
+  })
+
+  it('keeps the i18n copy when the pet carries no panel', () => {
+    renderPet()
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.getByText('喂食')).toBeDefined()
+    expect(screen.getByText('改名')).toBeDefined()
+    expect(screen.getByText('隐藏')).toBeDefined()
+    expect(screen.getByText('亲密度 幼鲸')).toBeDefined()
+  })
+
+  it('substitutes cross-slot placeholders in pack stat formats', () => {
+    renderPet({ definition: { ...petDefinition(), panel: { stats: { treats: '鱼干 {n}（{points} 分，{rank}）' } } } })
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    // The host whitelists {rank}/{n}/{points} in every stat slot, so a pack
+    // format may reference any of them; all three live values substitute.
+    expect(screen.getByText('鱼干 3（0 分，幼鲸）')).toBeDefined()
+  })
+})
+describe('PetSprite status decoration (pet-center M5, #567)', () => {
+  const decoration: DecorationView = {
+    apiVersion: 'x-org.linxin666.pet-center/status-decoration-v1',
+    id: 'whale',
+    assetBase: '/api/pet/decoration/whale',
+    entryUrl: '/api/pet/decoration/whale/whale-frames.png',
+    cell: { width: 64, height: 48 },
+    columns: 4,
+    durations: [160, 160, 160, 160],
+    loop: true,
+    phases: {
+      idle: 'hide',
+      waiting: { from: 0, to: 1 },
+      thinking: { from: 0, to: 3 },
+      done: { from: 2, to: 3 },
+    },
+  }
+
+  const ornament = (): HTMLElement | null => document.body.querySelector('[data-dsh-pet-decoration="whale"]')
+
+  it('renders an aria-hidden ornament inside the status bubble for a bound phase', () => {
+    renderPet({ snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking', decoration } })
+    const el = ornament()
+    expect(el).not.toBeNull()
+    expect(el!.getAttribute('aria-hidden')).toBe('true')
+    expect(el!.style.backgroundImage).toContain('whale-frames.png')
+    // The bubble keeps its semantics beside the ornament.
+    const bubble = document.body.querySelector('[role="status"][aria-live="polite"]')
+    expect(bubble).not.toBeNull()
+    expect(bubble!.textContent).toContain('正在思考')
+  })
+
+  it('hides the ornament for phases bound to hide and for the idle default', () => {
+    renderPet({ snapshot: { ...snapshot, bubble: '等待', phase: 'idle', decoration } })
+    expect(ornament()).toBeNull()
+  })
+
+  it('holds the segment first frame under prefers-reduced-motion', () => {
+    renderPet({ snapshot: { ...snapshot, bubble: '完成', phase: 'done', decoration } })
+    const el = ornament()
+    expect(el).not.toBeNull()
+    // The harness matchMedia mock reports reduced motion, so the ornament
+    // rests on the segment's first frame (column 2 of a 24px-wide frame).
+    expect(el!.style.backgroundPosition).toBe('-48px 0px')
+  })
+
+  it('yields the bubble to the whisper (voice moment hides the ornament)', () => {
+    renderPet({ snapshot: { ...snapshot, phase: 'thinking', whisper: '冲了冲了', decoration } })
+    expect(ornament()).toBeNull()
+    expect(document.body.textContent).toContain('冲了冲了')
+  })
+
+  it('renders no ornament when the host serves no decoration', () => {
+    renderPet({ snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking' } })
+    expect(ornament()).toBeNull()
+  })
+
+  it('advances the ornament frames on the rAF loop and wraps when looping', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: false,
+      media: '(prefers-reduced-motion: reduce)',
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    })
+    vi.spyOn(performance, 'now').mockReturnValue(0)
+    const frames: FrameRequestCallback[] = []
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
+      frames.push(callback)
+      return frames.length
+    })
+    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
+    renderPet({ snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking', decoration } })
+    const el = ornament()!
+    // Both the sprite loop and the ornament loop schedule frames; step every
+    // pending callback together (the sprite's idle track never moves).
+    const step = (ts: number): void => { for (const callback of frames.splice(0)) callback(ts) }
+    // frameWidth = round(64 * 18 / 48) = 24 px; thinking binds frames 0..3.
+    expect(el.style.backgroundPosition).toBe('0px 0px')
+    act(() => { step(161) })
+    expect(el.style.backgroundPosition).toBe('-24px 0px')
+    act(() => { step(322) })
+    expect(el.style.backgroundPosition).toBe('-48px 0px')
+    act(() => { step(483) })
+    expect(el.style.backgroundPosition).toBe('-72px 0px')
+    act(() => { step(644) })
+    // The looping segment wraps back to its first frame.
+    expect(el.style.backgroundPosition).toBe('0px 0px')
+  })
+
+  it('holds the segment last frame when the loop is off and stops scheduling', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: false,
+      media: '(prefers-reduced-motion: reduce)',
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    })
+    vi.spyOn(performance, 'now').mockReturnValue(0)
+    const frames: FrameRequestCallback[] = []
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
+      frames.push(callback)
+      return frames.length
+    })
+    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
+    renderPet({ snapshot: { ...snapshot, bubble: '完成', phase: 'done', decoration: { ...decoration, loop: false } } })
+    const el = ornament()!
+    const step = (ts: number): void => { for (const callback of frames.splice(0)) callback(ts) }
+    // done binds frames 2..3; the segment starts on frame 2.
+    expect(el.style.backgroundPosition).toBe('-48px 0px')
+    act(() => { step(161) })
+    expect(el.style.backgroundPosition).toBe('-72px 0px')
+    // The ornament stopped scheduling (only the sprite loop remains pending).
+    expect(frames).toHaveLength(1)
+    act(() => { step(161) })
+    // The last frame holds.
+    expect(el.style.backgroundPosition).toBe('-72px 0px')
+  })
+
+  it('does not restart the frame loop when an equal-content decoration re-renders', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: false,
+      media: '(prefers-reduced-motion: reduce)',
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    })
+    vi.spyOn(performance, 'now').mockReturnValue(0)
+    const frames: FrameRequestCallback[] = []
+    const rafSpy = vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
+      frames.push(callback)
+      return frames.length
+    })
+    const cancelSpy = vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
+    // The definition comes from '/api/pet/pets', fetched once — a state
+    // poll never replaces it, so both renders share one definition object.
+    const definition = petDefinition()
+    const { result } = renderPet({ definition, snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking', decoration } })
+    const step = (ts: number): void => { for (const callback of frames.splice(0)) callback(ts) }
+    act(() => { step(161) })
+    expect(ornament()!.style.backgroundPosition).toBe('-24px 0px')
+    const schedulesBefore = rafSpy.mock.calls.length
+    // The 2 s poll delivers a fresh JSON round-trip: identical content, new
+    // object identities everywhere. The loop must not cancel/restart.
+    const repolled: DecorationView = {
+      ...decoration,
+      cell: { ...decoration.cell },
+      durations: [...decoration.durations],
+      phases: { ...decoration.phases },
+    }
+    result.rerender(<PetSprite {...petProps({ definition, snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking', decoration: repolled } })} />)
+    act(() => { step(322) })
+    expect(ornament()!.style.backgroundPosition).toBe('-48px 0px')
+    expect(cancelSpy).not.toHaveBeenCalled()
+    // One reschedule per loop tick; no effect restart added new schedules.
+    expect(rafSpy.mock.calls.length).toBe(schedulesBefore + 2)
+  })
+})

package/src/client/PetSprite.tsx

@@ -10,17 +10,18 @@
  */
 
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactPortal } from 'react'
+import type { CSSProperties, PointerEvent as ReactPointerEvent, ReactElement, ReactNode, 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 { DecorationView } from '../contracts/status-decoration.ts'
 import type { PetFeedback } from './pet-store.ts'
 import { framePosition, rowOfTrack, trimTrack } from './spritesheet.ts'
 import { sequenceFrameAt } from './sequences.ts'
-import { animationForPhase, type PetAnimation } from '../state.ts'
+import { animationForPhase, type ActivityPhase, type PetAnimation } from '../state.ts'
 import { NS } from './locales.ts'
 import styles from './pet.module.css'
 
@@ -48,6 +49,12 @@ export interface PetSpriteProps {
   onOpenSession: (sessionId: string) => void
   /** Clear the reaction bubble (after its CSS animation). */
   onFeedbackDone: () => void
+  /**
+   * Custom visual replacing the sprite2d atlas animation (pet-center M3).
+   * The chrome (drag, bubbles, panel, tap economy) is untouched: the visual
+   * renders inside the sprite box, and the atlas load + frame loop skip.
+   */
+  visual?: ReactNode
   /** Locale translate seat (namespace-bound). */
   t: TranslateNS<typeof NS>
 }
@@ -57,6 +64,81 @@ function clampOffset(value: number, max: number): number {
   return Math.max(0, Math.min(max, value))
 }
 
+/**
+ * The status decoration ornament (pet-center M5, #567). Renders the active
+ * phase's frame segment as a CSS-background strip at a compact bubble
+ * height; prefers-reduced-motion holds the segment's first frame, and a
+ * missing or undecodable asset simply paints nothing (CSS background
+ * failure) — the bubble text is never disturbed. The span is aria-hidden;
+ * the bubble keeps its own semantics untouched.
+ */
+function StatusOrnament(props: { decoration: DecorationView; phase: ActivityPhase }): ReactElement | null {
+  const { decoration, phase } = props
+  const segment = decoration.phases[phase]
+  const shown = segment !== undefined && segment !== 'hide'
+  const segmentKey = segment !== undefined && segment !== 'hide' ? segment.from + ':' + segment.to : 'none'
+  const spanRef = useRef<HTMLSpanElement | null>(null)
+  const scale = 18 / decoration.cell.height
+  const frameWidth = Math.round(decoration.cell.width * scale)
+  const stripWidth = decoration.columns * frameWidth
+  // Value-stable dependency key: the host serves a fresh DecorationView
+  // object on every state poll (2 s), so the effect must not depend on the
+  // object identity — otherwise each poll would cancel and restart the
+  // frame loop and the animation would jump back to its first frame.
+  const durationsKey = decoration.durations.join(',')
+  useEffect(() => {
+    if (segment === undefined || segment === 'hide') return
+    const el = spanRef.current
+    if (el === null) return
+    const position = (index: number): string => (-index * frameWidth) + 'px 0px'
+    const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches === true
+    el.style.backgroundPosition = position(segment.from)
+    if (reduceMotion) return
+    let raf = 0
+    let index = segment.from
+    let elapsed = 0
+    let last = performance.now()
+    const tick = (ts: number): void => {
+      const delta = ts - last
+      last = ts
+      elapsed += delta
+      const duration = decoration.durations[index] ?? 160
+      if (elapsed >= duration) {
+        elapsed = 0
+        if (index < segment.to) index += 1
+        else if (decoration.loop) index = segment.from
+      }
+      el.style.backgroundPosition = position(index)
+      // A non-looping segment settles on its last frame; stop scheduling
+      // instead of repainting the same position every frame.
+      if (!decoration.loop && index === segment.to) return
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [shown, segmentKey, frameWidth, decoration.loop, durationsKey])
+  if (!shown) return null
+  return (
+    <span
+      ref={spanRef}
+      aria-hidden="true"
+      data-dsh-pet-decoration={decoration.id}
+      style={{
+        display: 'inline-block',
+        width: frameWidth,
+        height: 18,
+        marginRight: 6,
+        verticalAlign: 'middle',
+        flexShrink: 0,
+        backgroundImage: 'url(' + decoration.entryUrl + ')',
+        backgroundSize: stripWidth + 'px 18px',
+        backgroundRepeat: 'no-repeat',
+        backgroundPosition: '0px 0px',
+      }}
+    />
+  )
+}
+
 /**
  * The floating pet. The spritesheet frame advances on requestAnimationFrame
  * with per-frame durations from the definition's tracks; the atlas image is
@@ -104,10 +186,39 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const rows = definition.rows
   const tracks = definition.tracks
   const sequences = definition.sequences
+  // Hover-panel chrome from the pet's voice pack (pet-center M4, issue
+  // #677): every slot falls back to the i18n dictionary when unset. Stat
+  // formats carry {rank}/{n}/{points} placeholders the host validated.
+  const panel = definition.panel
+  const panelLabel = (slot: 'feed' | 'rename' | 'hide' | 'confirm', i18n: string): string =>
+    panel?.labels?.[slot] ?? i18n
+  const panelStat = (
+    slot: 'rank' | 'treats' | 'points',
+    i18nKey: 'pet.rank' | 'pet.treats' | 'pet.points',
+    values: Record<string, string | number>,
+  ): string => {
+    const format = panel?.stats?.[slot] ?? props.t(i18nKey, values)
+    if (panel?.stats?.[slot] === undefined) return format
+    // The host whitelists {rank}/{n}/{points} in every stat slot, so a pack
+    // format may reference any of them; substitute all three live values
+    // (the slot's own value plus the siblings) instead of only the slot's.
+    const all: Record<string, string | number> = {
+      rank: snapshot?.affinity.rank ?? '?',
+      n: snapshot?.treats.stocked ?? 0,
+      points: snapshot?.affinity.points ?? 0,
+    }
+    let text = format
+    for (const [name, value] of Object.entries(all)) text = text.replaceAll('{' + name + '}', String(value))
+    return text
+  }
+  const panelShows = (action: 'feed' | 'rename' | 'hide'): boolean =>
+    panel?.actions === undefined || panel.actions.includes(action)
 
   // Load the atlas once; the definition carries the authoritative per-row
-  // frame counts and per-track durations, so nothing else is fetched.
+  // frame counts and per-track durations, so nothing else is fetched. A
+  // custom visual (pet-center M3) replaces the atlas entirely.
   useEffect(() => {
+    if (props.visual !== undefined) return
     let cancelled = false
     const img = new Image()
     img.onload = () => {
@@ -118,7 +229,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
       cancelled = true
       img.onload = null
     }
-  }, [definition.atlasUrl])
+  }, [definition.atlasUrl, props.visual])
 
   // Frame loop: advance the current track and write background-position.
   // Offsets must be in SCALED coordinates (background-position applies to the
@@ -132,6 +243,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const scaleRef = useRef(spriteScale)
   scaleRef.current = spriteScale
   useEffect(() => {
+    if (props.visual !== undefined) return
     const reduceMotion = typeof window !== 'undefined'
       && window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches === true
     const sequence = animation === animationForPhase(phase) ? sequences?.[phase] : undefined
@@ -200,7 +312,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
     }
     raf = requestAnimationFrame(tick)
     return () => cancelAnimationFrame(raf)
-  }, [animation, phase, cell, columns, rows, tracks, sequences])
+  }, [animation, phase, cell, columns, rows, tracks, sequences, props.visual])
 
   // Auto-clear the feedback bubble after its CSS animation. The callback
   // rides a ref so re-renders never reset the timer: the 2s poll rebuilds
@@ -278,6 +390,8 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const whisper = feedback === null ? snapshot?.whisper : undefined
   const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || whisper !== undefined
   const displayName = snapshot?.name ?? definition.displayName
+  // The host-served status decoration (M5, #567); absent = text-only bubbles.
+  const decoration = snapshot?.decoration
 
   // A settled session list can no longer stay pinned open.
   useEffect(() => {
@@ -343,10 +457,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
         style={{
           width: spriteWidth,
           height: spriteHeight,
-          backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
-          backgroundSize: (cell.width * columns * spriteScale) + 'px ' + (cell.height * (definition.atlasRows ?? rows.length) * spriteScale) + 'px',
-          backgroundRepeat: 'no-repeat',
-          backgroundPosition: '0 0',
+          ...(props.visual === undefined
+            ? {
+                backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
+                backgroundSize: (cell.width * columns * spriteScale) + 'px ' + (cell.height * (definition.atlasRows ?? rows.length) * spriteScale) + 'px',
+                backgroundRepeat: 'no-repeat',
+                backgroundPosition: '0 0',
+              }
+            : {}),
           cursor: dragRef.current === null ? 'grab' : 'grabbing',
         }}
         onPointerDown={onPointerDown}
@@ -360,7 +478,9 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
         }}
         role="button"
         aria-label={definition.displayName}
-      />
+      >
+        {props.visual}
+      </div>
       {feedback !== null && (
         <div key={feedback.at} ref={bubbleRef} className={clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet)}>
           {feedback.text}
@@ -393,6 +513,9 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                 title={props.t('pet.openSessionHint')}
                 onClick={() => { props.onOpenSession(session.sessionId) }}
               >
+                {index === 0 && !speaksWhisper && decoration !== undefined && (
+                  <StatusOrnament decoration={decoration} phase={phase} />
+                )}
                 {speaksWhisper ? whisper : session.bubble}
               </button>
             )
@@ -431,6 +554,9 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
               role="status"
               aria-live="polite"
             >
+              {whisper === undefined && decoration !== undefined && (
+                <StatusOrnament decoration={decoration} phase={phase} />
+              )}
               {whisper ?? statusBubble}
             </div>
           )}
@@ -492,39 +618,45 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                   }
                 }}
               >
-                {props.t('pet.confirm')}
+                {panelLabel('confirm', props.t('pet.confirm'))}
               </button>
             </div>
           ) : (
             <>
               <div className={styles.rankRow}>
                 <span className={styles.nameCell}>{displayName}</span>
-                <span className={styles.statRank}>{props.t('pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
+                <span className={styles.statRank}>{panelStat('rank', 'pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
               </div>
               <div className={styles.rankRow}>
-                <span className={styles.statTreats}>{props.t('pet.treats', { n: snapshot?.treats.stocked ?? 0 })}</span>
-                <span className={styles.statPoints}>{props.t('pet.points', { points: snapshot?.affinity.points ?? 0 })}</span>
+                <span className={styles.statTreats}>{panelStat('treats', 'pet.treats', { n: snapshot?.treats.stocked ?? 0 })}</span>
+                <span className={styles.statPoints}>{panelStat('points', 'pet.points', { points: snapshot?.affinity.points ?? 0 })}</span>
               </div>
               <div className={styles.actions}>
-                <button type="button" className={styles.action} onClick={props.onFeed}>
-                  {props.t('pet.feed')}
-                </button>
-                <button
-                  type="button"
-                  className={styles.action}
-                  onClick={() => {
-                    // Cancel any pending hide so the rename box cannot
-                    // unmount right as the user starts typing (#303).
-                    clearHideTimer()
-                    setNameDraft(displayName)
-                    setRenaming(true)
-                  }}
-                >
-                  {props.t('pet.rename')}
-                </button>
-                <button type="button" className={styles.action} onClick={props.onHide}>
-                  {props.t('pet.hide')}
-                </button>
+                {panelShows('feed') && (
+                  <button type="button" className={styles.action} onClick={props.onFeed}>
+                    {panelLabel('feed', props.t('pet.feed'))}
+                  </button>
+                )}
+                {panelShows('rename') && (
+                  <button
+                    type="button"
+                    className={styles.action}
+                    onClick={() => {
+                      // Cancel any pending hide so the rename box cannot
+                      // unmount right as the user starts typing (#303).
+                      clearHideTimer()
+                      setNameDraft(displayName)
+                      setRenaming(true)
+                    }}
+                  >
+                    {panelLabel('rename', props.t('pet.rename'))}
+                  </button>
+                )}
+                {panelShows('hide') && (
+                  <button type="button" className={styles.action} onClick={props.onHide}>
+                    {panelLabel('hide', props.t('pet.hide'))}
+                  </button>
+                )}
               </div>
             </>
           )}

package/src/client/index.ts

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