@linxin666/dsh-pet 0.3.3 → 0.3.5

package/src/client/PetDockEntry.test.tsx

@@ -79,6 +79,12 @@ function injected(): PetInjected {
     rename: vi.fn(),
     openSession: vi.fn(),
     feedbackDone: vi.fn(),
+    gameplay: {
+      touch: vi.fn(),
+      setMode: vi.fn(),
+      workTick: vi.fn(),
+      buy: vi.fn(),
+    },
   }
 }
 

package/src/client/PetDockEntry.tsx

@@ -11,12 +11,14 @@
  * @module @linxin666/dsh-pet/client/PetDockEntry
  */
 
-import { useEffect, useSyncExternalStore, type ReactElement } from 'react'
+import { useEffect, useRef, 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 { PetSprite } from './PetSprite.tsx'
 import { PetRendererSwitch } from './renderers/PetRendererSwitch.tsx'
+import { createDragStream, type DragStream } from './drag-stream.ts'
+import { GameplayHud, type GameplayApi, type GameplayBus } from './gameplay-hud.tsx'
 import { NS } from './locales.ts'
 import styles from './pet.module.css'
 
@@ -42,6 +44,8 @@ export interface PetInjected {
   openSession: (sessionId: string) => void
   /** Clear the reaction bubble. */
   feedbackDone: () => void
+  /** Gameplay verb API (miku-pet generalization); wired but unused for pets without a gameplay block. */
+  gameplay: GameplayApi
 }
 
 /** Composed props of the global pet entry (locale + injected; no slot runtime share). */
@@ -70,6 +74,15 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
     ensure()
   }, [ensure])
 
+  // Per-pet gameplay wiring: the coordination bus (HUD taps <-> chrome,
+  // HUD track overrides <-> frames2d mount) and the shared drag stream.
+  const auxRef = useRef<{ id: string; bus: GameplayBus; drag: DragStream } | null>(null)
+  if (definition !== null && (auxRef.current === null || auxRef.current.id !== definition.id)) {
+    auxRef.current = { id: definition.id, bus: {}, drag: createDragStream() }
+  }
+  const aux = auxRef.current
+  const gameplay = definition?.gameplay
+
   if (visible) {
     return (
       <span data-pet-dock data-testid="pet-dock">
@@ -80,6 +93,7 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
               definition={definition}
               phase={snapshot?.phase ?? 'idle'}
               onPet={props.pet}
+              {...(aux === null ? {} : { drag: aux.drag, bus: aux.bus })}
               t={props.t}
             >
               <PetSprite
@@ -94,6 +108,23 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
                 onRename={props.rename}
                 onOpenSession={props.openSession}
                 onFeedbackDone={props.feedbackDone}
+                dragDisabled={snapshot.gameplay?.mode === 'work'}
+                {...(gameplay === undefined || aux === null
+                  ? {}
+                  : {
+                      onGameplayTap: (fx: number, fy: number) => aux.bus.tap?.(fx, fy),
+                      onGameplayMenu: () => aux.bus.openCard?.(),
+                      hud: (
+                        <GameplayHud
+                          definition={definition}
+                          store={store}
+                          api={props.gameplay}
+                          bus={aux.bus}
+                          drag={aux.drag}
+                          t={props.t}
+                        />
+                      ),
+                    })}
                 t={props.t}
               />
             </PetRendererSwitch>

package/src/client/PetSprite.test.tsx

@@ -159,16 +159,17 @@ describe('PetSprite custom visual (pet-center M3)', () => {
   })
 })
 
-describe('PetSprite always-visible close control', () => {
-  it('renders a corner close button and hides without petting', () => {
+describe('PetSprite hide control (#1126)', () => {
+  it('does not render an intrusive corner close button and allows hiding via hover panel', () => {
     const onHide = vi.fn()
     const onPet = vi.fn()
     renderPet({ onHide, onPet })
 
-    const close = screen.getByTestId('pet-close')
-    expect(close.getAttribute('aria-label')).toBe('隐藏')
-    expect(close.getAttribute('title')).toBe('隐藏')
-    fireEvent.click(close)
+    expect(screen.queryByTestId('pet-close')).toBeNull()
+
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    const hideBtn = screen.getByText('隐藏')
+    fireEvent.click(hideBtn)
 
     expect(onHide).toHaveBeenCalledTimes(1)
     expect(onPet).not.toHaveBeenCalled()
@@ -423,27 +424,18 @@ describe('PetSprite status bubble', () => {
     expect(screen.queryByText('正在使用 grep')).not.toBeNull()
   })
 
-  it('lets the inner whisper take over the status bubble', () => {
-    renderPet({ snapshot: { ...workingSnapshot, whisper: '哼哧哼哧，大脑转得飞快～' } })
-    // The whisper speaks THROUGH the bubble: it replaces (not accompanies)
-    // the status copy, so the pet never shows two bubbles at once.
-    expect(screen.queryByText('哼哧哼哧，大脑转得飞快～')).not.toBeNull()
-    expect(screen.queryByText('正在思考')).toBeNull()
-  })
-
-  it('lets the whisper take over the display session bubble in the stack', () => {
+  it('lets a session whisper take over its own bubble while others stay collapsed', () => {
     const { onOpenSession } = renderPet({
       snapshot: {
         ...workingSnapshot,
-        whisper: '我在这儿陪着你呢，别急别急',
         sessions: [
-          { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考' },
+          { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: '我在这儿陪着你呢，别急别急' },
           { sessionId: 's-b', animation: 'running-right', phase: 'tool', bubble: '正在使用 grep' },
         ],
       },
     })
-    // The primary bubble (the display session) speaks the whisper instead
-    // of its status copy; the collapsed extra session hides behind the badge.
+    // The lead session's bubble speaks ITS whisper instead of its status
+    // copy; the collapsed extra session hides behind the badge.
     expect(screen.queryByText('我在这儿陪着你呢，别急别急')).not.toBeNull()
     expect(screen.queryByText('正在思考')).toBeNull()
     expect(screen.queryByText('正在使用 grep')).toBeNull()
@@ -455,9 +447,28 @@ describe('PetSprite status bubble', () => {
     expect(onOpenSession).toHaveBeenCalledWith('s-a')
   })
 
+  it('renders each session whisper on its own expanded bubble', () => {
+    renderPet({
+      snapshot: {
+        ...workingSnapshot,
+        sessions: [
+          { sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: 'A 的碎碎念' },
+          { sessionId: 's-b', animation: 'running-right', phase: 'tool', bubble: '正在使用 grep', whisper: 'B 的碎碎念' },
+        ],
+      },
+    })
+    fireEvent.pointerOver(screen.getByText('A 的碎碎念').closest('div')!)
+    expect(screen.queryByText('A 的碎碎念')).not.toBeNull()
+    expect(screen.queryByText('B 的碎碎念')).not.toBeNull()
+    expect(screen.queryByText('正在思考')).toBeNull()
+  })
+
   it('lets transient interaction feedback take over the whisper too', () => {
     renderPet({
-      snapshot: { ...workingSnapshot, whisper: '哼哧哼哧，大脑转得飞快～' },
+      snapshot: {
+        ...workingSnapshot,
+        sessions: [{ sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: '哼哧哼哧，大脑转得飞快～' }],
+      },
       feedback: { text: '摸摸成功', kind: 'pet', at: 1 },
     })
     expect(screen.queryByText('摸摸成功')).not.toBeNull()
@@ -677,6 +688,35 @@ describe('PetSprite panel chrome from the voice pack (pet-center M4)', () => {
     expect(screen.getByText('鱼干 3（0 分，幼鲸）')).toBeDefined()
   })
 })
+describe('PetSprite gameplay entry in the hover panel (miku generalization)', () => {
+  it('renders a 玩法 action and routes clicks to the HUD channel', () => {
+    const onGameplayMenu = vi.fn()
+    renderPet({ onGameplayMenu })
+    // The entry lives in the hover panel; a closed panel shows no chrome.
+    expect(screen.queryByText('玩法')).toBeNull()
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.getByText('玩法')).toBeDefined()
+    fireEvent.click(screen.getByText('玩法'))
+    expect(onGameplayMenu).toHaveBeenCalledTimes(1)
+  })
+
+  it('omits the 玩法 action when the pet carries no gameplay HUD', () => {
+    renderPet()
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.queryByText('玩法')).toBeNull()
+  })
+
+  it('keeps the 玩法 entry when a voice pack hides every panel action', () => {
+    renderPet({
+      definition: { ...petDefinition(), panel: { actions: [] } },
+      onGameplayMenu: vi.fn(),
+    })
+    fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+    expect(screen.getByText('玩法')).toBeDefined()
+    expect(screen.queryByText('喂食')).toBeNull()
+  })
+})
+
 describe('PetSprite status decoration (pet-center M5, #567)', () => {
   const decoration: DecorationView = {
     apiVersion: 'x-org.linxin666.pet-center/status-decoration-v1',
@@ -724,7 +764,14 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
   })
 
   it('yields the bubble to the whisper (voice moment hides the ornament)', () => {
-    renderPet({ snapshot: { ...snapshot, phase: 'thinking', whisper: '冲了冲了', decoration } })
+    renderPet({
+      snapshot: {
+        ...snapshot,
+        phase: 'thinking',
+        decoration,
+        sessions: [{ sessionId: 's-a', animation: 'running', phase: 'thinking', bubble: '正在思考', whisper: '冲了冲了' }],
+      },
+    })
     expect(ornament()).toBeNull()
     expect(document.body.textContent).toContain('冲了冲了')
   })

package/src/client/PetSprite.tsx

@@ -43,6 +43,8 @@ export interface PetSpriteProps {
   onHide: () => void
   /** Persist a drag position. */
   onDragEnd: (right: number, bottom: number) => void
+  /** Drag gesture notifications for renderers with a drag track (frames2d). */
+  onDraggingChange?: (dragging: boolean) => void
   /** Rename the selected pet (persisted by the host). */
   onRename: (name: string) => void
   /** Navigate to the session one status bubble reports on. */
@@ -55,6 +57,27 @@ export interface PetSpriteProps {
    * renders inside the sprite box, and the atlas load + frame loop skip.
    */
   visual?: ReactNode
+  /**
+   * Gameplay overlay (miku-pet generalization): rendered inside the float
+   * container so hover containment and stacking work unchanged. Absent for
+   * pets without a gameplay block.
+   */
+  hud?: ReactNode
+  /**
+   * Gameplay tap sink: receives the tap point as sprite-box fractions
+   * (0..1). When present the chrome reports the tap IN ADDITION to the
+   * affinity pet; the HUD decides zones/no-ops.
+   */
+  onGameplayTap?: (fractionX: number, fractionY: number) => void
+  /**
+   * Gameplay entry (miku-pet generalization): when present the hover panel
+   * renders a 玩法 action that opens/closes the gameplay card. The chrome
+   * wires it to the HUD through the per-pet bus (openCard), mirroring the
+   * onGameplayTap sink. Absent for pets without a gameplay block.
+   */
+  onGameplayMenu?: () => void
+  /** Disable the drag gesture (gameplay work mode blocks dragging). */
+  dragDisabled?: boolean
   /** Locale translate seat (namespace-bound). */
   t: TranslateNS<typeof NS>
 }
@@ -365,6 +388,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   useEffect(() => () => clearHideTimer(), [])
 
   const onPointerDown = (e: ReactPointerEvent<HTMLDivElement>): void => {
+    if (props.dragDisabled === true) return
     e.preventDefault()
     ;(e.target as HTMLElement).setPointerCapture?.(e.pointerId)
     const current = dragPos ?? { right: display.right, bottom: display.bottom }
@@ -377,7 +401,10 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
     if (drag === null) return
     const dx = e.clientX - drag.startX
     const dy = e.clientY - drag.startY
-    if (Math.abs(dx) > 4 || Math.abs(dy) > 4) draggedRef.current = true
+    if (Math.abs(dx) > 4 || Math.abs(dy) > 4) {
+      if (!draggedRef.current) props.onDraggingChange?.(true)
+      draggedRef.current = true
+    }
     const right = clampOffset(drag.right - dx, window.innerWidth - 40)
     const bottom = clampOffset(drag.bottom - dy, window.innerHeight - 40)
     setDragPos({ right, bottom })
@@ -385,6 +412,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const onPointerUp = (): void => {
     if (dragRef.current === null) return
     dragRef.current = null
+    if (draggedRef.current) props.onDraggingChange?.(false)
     if (dragPos !== null) props.onDragEnd(dragPos.right, dragPos.bottom)
   }
 
@@ -404,14 +432,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const statusBubble = feedback === null && sessionBubbles.length === 0
     ? snapshot?.bubble
     : undefined
-  // The display session's inner whisper (碎碎念) — short inner-voice copy
-  // woken by the model's output. Instead of a second bubble of its own, a
-  // fresh whisper takes over the display session's bubble (the stack top, or
-  // the single status bubble) and re-tints it, so the pet never wears two
-  // voices at once. Interaction feedback takes over the whole bubble area
-  // while it plays, so whispers yield to it like status copy.
-  const whisper = feedback === null ? snapshot?.whisper : undefined
-  const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || whisper !== undefined
+  // Each session's inner whisper (碎碎念) rides its own bubble — short
+  // inner-voice copy woken by that session's activity, never the model's or
+  // another session's. Instead of a second bubble of its own, a fresh
+  // whisper takes over its session's bubble and re-tints it, so the pet
+  // never wears two voices at once. Interaction feedback takes over the
+  // whole bubble area while it plays, so whispers yield to it like status
+  // copy.
+  const bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined
   const displayName = snapshot?.name ?? definition.displayName
   // The host-served status decoration (M5, #567); absent = text-only bubbles.
   const decoration = snapshot?.decoration
@@ -497,10 +525,16 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
           onPointerDown={onPointerDown}
           onPointerMove={onPointerMove}
           onPointerUp={onPointerUp}
-          onClick={() => {
+          onClick={(e) => {
             // A pointer sequence that moved (dragged) still fires a trailing
             // click; skip the pet when that happened.
             if (draggedRef.current) return
+            if (props.onGameplayTap !== undefined && spriteRef.current !== null) {
+              const rect = spriteRef.current.getBoundingClientRect()
+              if (rect.width > 0 && rect.height > 0) {
+                props.onGameplayTap((e.clientX - rect.left) / rect.width, (e.clientY - rect.top) / rect.height)
+              }
+            }
             props.onPet()
           }}
           role="button"
@@ -508,32 +542,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
         >
           {props.visual}
         </div>
-        <button
-          type="button"
-          className={styles.closeButton}
-          aria-label={panelLabel('hide', props.t('pet.hide'))}
-          title={panelLabel('hide', props.t('pet.hide'))}
-          data-testid="pet-close"
-          onPointerDown={(e) => {
-            // Keep the close control from starting a drag on the sprite.
-            e.stopPropagation()
-          }}
-          onClick={(e) => {
-            // The close control sits beside the pet button; do not pet as a
-            // side effect of closing the overlay.
-            e.stopPropagation()
-            props.onHide()
-          }}
-        >
-          ×
-        </button>
       </div>
+      {props.hud}
       {feedback !== null && (
         <div key={feedback.at} ref={bubbleRef} className={clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet)}>
           {feedback.text}
         </div>
       )}
-      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || whisper !== undefined) && (
+      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined) && (
         <div
           ref={bubbleRef}
           className={styles.bubbleStack}
@@ -541,15 +557,14 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
           onPointerLeave={() => setStackPeek(false)}
         >
           {visibleSessions.map((session, index) => {
-            // The whisper rides the display session's bubble — the stack's
-            // primary entry (DOM-first, rendered bottom-most by the reversed
-            // column so it stays glued to the sprite when extras open above).
-            // The key swap restarts the entrance animation so the mood change
-            // reads as the bubble re-speaking.
-            const speaksWhisper = index === 0 && whisper !== undefined
+            // A session's whisper rides ITS OWN bubble (the stack lead when
+            // the current session has one, any bubble when the stack is
+            // expanded). The key swap restarts the entrance animation so the
+            // mood change reads as the bubble re-speaking.
+            const speaksWhisper = session.whisper !== undefined
             const bubble = (
               <button
-                key={speaksWhisper ? 'whisper:' + whisper : session.sessionId}
+                key={speaksWhisper ? 'whisper:' + session.whisper : session.sessionId}
                 type="button"
                 className={clsx(
                   styles.bubble,
@@ -563,7 +578,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                 {index === 0 && !speaksWhisper && decoration !== undefined && (
                   <StatusOrnament decoration={decoration} phase={phase} />
                 )}
-                {speaksWhisper ? whisper : session.bubble}
+                {session.whisper ?? session.bubble}
               </button>
             )
             // The primary bubble carries the '+N' badge while other sessions
@@ -592,19 +607,17 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
               </span>
             )
           })}
-          {sessionBubbles.length === 0 && (statusBubble !== undefined || whisper !== undefined) && (
-            // The key swap (status copy <-> whisper) restarts the entrance
-            // animation on every mood change.
+          {sessionBubbles.length === 0 && statusBubble !== undefined && (
             <div
-              key={whisper === undefined ? 'status' : 'whisper:' + whisper}
-              className={clsx(styles.bubble, styles.bubbleStatus, whisper !== undefined && styles.bubbleWhisper)}
+              key="status"
+              className={clsx(styles.bubble, styles.bubbleStatus)}
               role="status"
               aria-live="polite"
             >
-              {whisper === undefined && decoration !== undefined && (
+              {decoration !== undefined && (
                 <StatusOrnament decoration={decoration} phase={phase} />
               )}
-              {whisper ?? statusBubble}
+              {statusBubble}
             </div>
           )}
         </div>
@@ -704,6 +717,11 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                     {panelLabel('hide', props.t('pet.hide'))}
                   </button>
                 )}
+                {props.onGameplayMenu !== undefined && (
+                  <button type="button" className={styles.action} onClick={props.onGameplayMenu}>
+                    {props.t('pet.gameplay.menu')}
+                  </button>
+                )}
               </div>
             </>
           )}

package/src/client/PluginSettingsCard.tsx

@@ -39,6 +39,8 @@ export interface PluginSettingsCardProps<TKey extends string = string> {
   titleKey: TKey
   /** Locale key of the line describing what this plugin's settings govern. */
   descriptionKey: TKey
+  /** Optional rich header description rendered instead of the plain t(descriptionKey) text (the plain text stays as the tooltip). */
+  descriptionNode?: ReactNode
   /** The card's form state: availability, writability, and what a save would do. */
   state: CardShell
   /** Write every staged edit. */
@@ -87,7 +89,7 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
       <div className={css.headerStatic}>
         <span className={css.headText}>
           <span className={css.name} title={title}>{title}</span>
-          <span className={css.description} title={description}>{description}</span>
+          <span className={css.description} title={description}>{props.descriptionNode ?? description}</span>
         </span>
         {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
       </div>
@@ -102,7 +104,7 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
       >
         <span className={css.headText}>
           <span className={css.name} title={title}>{title}</span>
-          <span className={css.description} title={description}>{description}</span>
+          <span className={css.description} title={description}>{props.descriptionNode ?? description}</span>
         </span>
         {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
         <svg

package/src/client/drag-stream.ts

@@ -0,0 +1,35 @@
+/**
+ * Drag stream — bridges the chrome's pointer drag state onto the renderer
+ * contract's { get, subscribe } shape, so renderers with a dedicated drag
+ * track (frames2d) can follow the chrome-owned drag gesture. Dispatch is
+ * change-only, mirroring the phase stream.
+ * @module @linxin666/dsh-pet/client/drag-stream
+ */
+
+/** The renderer-facing drag stream. */
+export interface DragStream {
+  /** Whether the chrome reports an active drag gesture. */
+  get(): boolean
+  /** Subscribe to drag state changes; returns the unsubscribe. */
+  subscribe(listener: (dragging: boolean) => void): () => void
+  /** Feed a fresh drag state; no-op when unchanged. */
+  push(dragging: boolean): void
+}
+
+/** Create the stream (one per pet activation, owned by the renderer switch). */
+export function createDragStream(): DragStream {
+  let current = false
+  const listeners = new Set<(dragging: boolean) => void>()
+  return {
+    get: () => current,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    push(dragging) {
+      if (dragging === current) return
+      current = dragging
+      for (const listener of [...listeners]) listener(dragging)
+    },
+  }
+}