@linxin666/dsh-pet 0.3.5 → 0.3.9

package/lib/types/voice-pack.js

@@ -28,6 +28,7 @@
  * @module @linxin666/dsh-pet/voice-pack
  */
 import { STATUS_SCENES, TOOL_CATEGORIES, WHISPER_CATEGORIES, WHISPER_RESULTS, } from "./chatter.js";
+import { normalizePetRemarks } from "./remarks.js";
 /** Schema version this module normalizes (optional field; missing = 1). */
 export const VOICE_PACK_V1 = 1;
 /** Hover-panel action buttons a pack can show or hide (canonical order). */
@@ -225,7 +226,7 @@ export function normalizePanel(raw, onWarning = () => { }) {
     return panel;
 }
 /** Voice-pack top-level fields ('$schema' mirrors the schema twin; drift-locked in tests). */
-export const VOICE_PACK_KEYS = new Set(['$schema', 'voicePackVersion', 'status', 'tools', 'toolRemaining', 'whispers', 'panel']);
+export const VOICE_PACK_KEYS = new Set(['$schema', 'voicePackVersion', 'status', 'tools', 'toolRemaining', 'whispers', 'panel', 'remarks', 'ranks']);
 /** Allowed whisper-section fields (drift-locked in tests). */
 export const WHISPER_KEYS = new Set(['categories', 'results']);
 /**
@@ -318,14 +319,37 @@ export function normalizeVoicePack(raw, onWarning = () => { }) {
         }
     }
     const panel = raw.panel === undefined ? undefined : normalizePanel(raw.panel, onWarning);
+    const remarks = raw.remarks === undefined ? undefined : normalizePetRemarks(raw.remarks, onWarning);
+    const ranksRaw = raw.ranks;
+    let ranks;
+    if (ranksRaw !== undefined) {
+        if (!isRecord(ranksRaw)) {
+            onWarning('ranks must be an object');
+        }
+        else {
+            const out = {};
+            for (const [key, value] of Object.entries(ranksRaw)) {
+                if (typeof value === 'string' && value.trim() !== '') {
+                    out[key] = value.trim().slice(0, VOICE_STAT_MAX);
+                }
+                else {
+                    onWarning('invalid rank name for ' + key);
+                }
+            }
+            if (Object.keys(out).length > 0)
+                ranks = out;
+        }
+    }
     if (overrides.status === undefined && overrides.tools === undefined
         && overrides.toolRemaining === undefined && overrides.whispers === undefined
-        && panel === undefined) {
+        && panel === undefined && remarks === undefined && ranks === undefined) {
         return undefined;
     }
     return {
         overrides,
         ...(panel === undefined ? {} : { panel }),
+        ...(remarks === undefined ? {} : { remarks }),
+        ...(ranks === undefined ? {} : { ranks }),
     };
 }
 /**
@@ -338,6 +362,8 @@ export function mergeVoicePacks(...layers) {
     const overrides = {};
     const labels = {};
     const stats = {};
+    let remarks;
+    let ranks;
     let actions;
     let panelSeen = false;
     let any = false;
@@ -365,6 +391,12 @@ export function mergeVoicePacks(...layers) {
             if (layer.panel.actions !== undefined)
                 actions = layer.panel.actions;
         }
+        if (layer.remarks !== undefined) {
+            remarks = { ...(remarks ?? {}), ...layer.remarks };
+        }
+        if (layer.ranks !== undefined) {
+            ranks = { ...(ranks ?? {}), ...layer.ranks };
+        }
     }
     if (!any)
         return undefined;
@@ -377,5 +409,7 @@ export function mergeVoicePacks(...layers) {
     return {
         overrides,
         ...(panelSeen && !panelEmpty ? { panel } : {}),
+        ...(remarks !== undefined ? { remarks } : {}),
+        ...(ranks !== undefined ? { ranks } : {}),
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-pet",
   "description": "Multi-pet companion plugin for the dsh web GUI: a registry-driven floating pet that reacts to model activity, with per-pet naming, petting/feeding interactions and an affinity score",
-  "version": "0.3.5",
+  "version": "0.3.9",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -40,17 +40,17 @@
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.1-rc.1"
+      "dsh": ">=0.1.2-alpha.1"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-api-session-controller"
       ],
       "platform": "web"
     }
@@ -64,15 +64,19 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/access.ts

@@ -1,23 +1,13 @@
 /**
- * Pet trust fence: loopback (the desktop) always passes; a live paired-device
- * cookie is an additional allow path when remote-web-ui is loaded. The pet
- * never depends on that plugin — without the service the fence stays
- * loopback-only (same pattern as skill-explorer / aionui-panel).
+ * Pet trust fence: loopback (the desktop) always passes; a live
+ * paired-device cookie is an additional allow path when remote-web-ui is
+ * loaded. The pet never depends on that plugin — without the service the
+ * fence stays loopback-only. The decision logic lives in the generated
+ * pair-access.ts copy (shared by git-graph / pet / skill-explorer).
  */
 import type { IncomingMessage } from 'node:http'
 import type { Context } from '@deepseek-ai/cordis'
-import { isLoopbackRequest } from './loopback.ts'
-
-/** Structural pairing lookup (no package dependency on remote-web-ui). */
-interface PairingAccess {
-  isPairedDevice(request: IncomingMessage): boolean
-}
-
-/** ctx.get is optional on the test harness; production Context always has it. */
-type LookupCtx = Context & {
-  get?(name: string, strict?: boolean): unknown
-  remoteWebUiPairing?: PairingAccess
-}
+import { isPairedOrLoopbackAllowed } from './pair-access.ts'
 
 /**
  * Whether this request may enter any /api/pet or /pet asset route.
@@ -26,15 +16,5 @@ type LookupCtx = Context & {
  * @returns true for loopback, or a live paired-device cookie.
  */
 export function isPetAllowed(ctx: Context, request: IncomingMessage): boolean {
-  if (isLoopbackRequest(request)) return true
-  const bag = ctx as LookupCtx
-  const fromGet = typeof bag.get === 'function' ? bag.get('remoteWebUiPairing', false) : undefined
-  const pairing = (isPairingAccess(fromGet) ? fromGet : bag.remoteWebUiPairing)
-  return pairing?.isPairedDevice(request) === true
-}
-
-function isPairingAccess(value: unknown): value is PairingAccess {
-  return value !== undefined
-    && value !== null
-    && typeof (value as PairingAccess).isPairedDevice === 'function'
+  return isPairedOrLoopbackAllowed(ctx, request)
 }

package/src/affinity.ts

@@ -56,6 +56,19 @@ export const AFFINITY_RANKS = [
   { min: 100_000, name: '鲸生共渡', emoji: '*********' },
 ] as const
 
+/** English translations for the 9 built-in affinity rank names (#1226). */
+export const AFFINITY_RANKS_EN: Readonly<Record<string, string>> = {
+  '幼鲸': 'Baby Whale',
+  '伙伴': 'Companion',
+  '挚友': 'Close Friend',
+  '深海羁绊': 'Deep Sea Bond',
+  '心有灵犀': 'Kindred Spirit',
+  '传说羁绊': 'Legendary Bond',
+  '神话羁绊': 'Mythic Bond',
+  '永恒之契': 'Eternal Covenant',
+  '鲸生共渡': 'Lifelong Companion',
+}
+
 /** Interaction tuning (all in points / ms). */
 export interface AffinityConfig {
   /** Points per completed turn. */

package/src/announce.ts

@@ -0,0 +1,103 @@
+/**
+ * The pet announcement-bubble contract (dsh-usage linkage): a sibling plugin
+ * pushes one structured announcement through `pet.announce(...)`, the host
+ * validates it into a bounded payload, and the browser half renders it as a
+ * dedicated, specially styled bubble above the session bubble stack.
+ *
+ * The validation lives in this pure module so the wire contract has exactly
+ * one home and stays testable without the cordis service.
+ * @module @linxin666/dsh-pet/announce
+ */
+
+/** One plugin-authored announcement bubble. */
+export interface PetAnnouncement {
+  /** Authoring plugin's source tag (`dsh-usage` for the usage statistics). */
+  source: string
+  /** Bubble content kind: a spend estimate, an account balance, or a plan-quota status. */
+  kind: 'balance' | 'cost' | 'plan'
+  /** Lead text (usually the provider display name). */
+  title: string
+  /** Balance or today-spend amount, formatted for display (kinds `balance` and `cost`). */
+  amount?: string
+  /** Plan usage percent 0-100 (kind `plan`). */
+  percent?: number
+  /** ISO 8601 reset instant (kind `plan`). */
+  resetAt?: string
+  /** Short trailing note (plan tier name, peak-period status, currency code, ...). */
+  note?: string
+  /** Visual tone; drives the bubble's accent color. */
+  tone: 'ok' | 'warn' | 'low'
+  /** Freshness window in ms; an expired announcement stops rendering. */
+  ttlMs: number
+  /** Epoch ms the announcement arrived. */
+  at: number
+}
+
+/** Default freshness window. */
+export const ANNOUNCE_DEFAULT_TTL_MS = 10_000
+
+/**
+ * Hard TTL ceiling. A repeating announcer (dsh-usage) declares its poll
+ * cadence as the TTL, so an `always`-mode bubble stays continuous across
+ * polls; the ceiling means a source that dies unmounts its bubble within at
+ * most one missed refresh cycle rather than lingering forever.
+ */
+export const ANNOUNCE_MAX_TTL_MS = 7_200_000
+
+/** Hard bounds: lengths and the TTL range (1 s .. 60 s). */
+const TITLE_MAX = 80
+const TEXT_MAX = 120
+const SOURCE_MAX = 64
+
+function boundedString(value: unknown, max: number): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  if (trimmed === '') return undefined
+  return trimmed.length <= max ? trimmed : trimmed.slice(0, max)
+}
+
+/**
+ * Validate one announce payload. Unknown fields are dropped, oversized text
+ * is truncated, and anything structurally wrong resolves to undefined — a
+ * malformed announcement never reaches the pet's bubble surface.
+ * @param input - the payload a sibling plugin passed to `pet.announce`.
+ * @param now - epoch ms the announcement arrived.
+ */
+export function parseAnnouncement(input: unknown, now: number): PetAnnouncement | undefined {
+  if (typeof input !== 'object' || input === null) return undefined
+  const data = input as Record<string, unknown>
+  const source = boundedString(data.source, SOURCE_MAX)
+  const title = boundedString(data.title, TITLE_MAX)
+  if (source === undefined || title === undefined) return undefined
+  const kind = data.kind === 'balance' || data.kind === 'cost' || data.kind === 'plan' ? data.kind : undefined
+  if (kind === undefined) return undefined
+  const amount = boundedString(data.amount, TEXT_MAX)
+  const resetAt = boundedString(data.resetAt, TEXT_MAX)
+  const note = boundedString(data.note, TITLE_MAX)
+  const percent = typeof data.percent === 'number' && Number.isFinite(data.percent)
+    ? Math.max(0, Math.min(100, data.percent))
+    : undefined
+  if ((kind === 'balance' || kind === 'cost') && amount === undefined) return undefined
+  if (kind === 'plan' && percent === undefined) return undefined
+  const tone = data.tone === 'warn' || data.tone === 'low' ? data.tone : 'ok'
+  const ttlMs = typeof data.ttlMs === 'number' && Number.isFinite(data.ttlMs)
+    ? Math.max(1000, Math.min(ANNOUNCE_MAX_TTL_MS, data.ttlMs))
+    : ANNOUNCE_DEFAULT_TTL_MS
+  return {
+    source,
+    kind,
+    title,
+    ...(amount !== undefined ? { amount } : {}),
+    ...(percent !== undefined ? { percent } : {}),
+    ...(resetAt !== undefined ? { resetAt } : {}),
+    ...(note !== undefined ? { note } : {}),
+    tone,
+    ttlMs,
+    at: now,
+  }
+}
+
+/** Whether an announcement is still fresh at `now`. */
+export function announcementFresh(announcement: PetAnnouncement, now: number): boolean {
+  return now - announcement.at < announcement.ttlMs
+}

package/src/client/PetDockEntry.test.tsx

@@ -9,7 +9,7 @@ import { cleanup, render, screen } from '@testing-library/react'
 // The npm SDK's client half is a closure-factory bundle for the GUI's
 // __ModuleLoader__ (not importable under vitest); provide the defineStore
 // the pet store needs (same fake-store pattern as the settings-card tests).
-vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
+vi.mock('@deepseek-ai/dsh-client-store', () => ({
   defineStore: (spec: {
     init: () => unknown
     actions: Record<string, (draft: never, ...args: never[]) => void>

package/src/client/PetDockEntry.tsx

@@ -4,10 +4,11 @@
  * 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 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.
+ * (see index.ts): while visible it renders the floating PetSprite (a portal
+ * into the plugin root, so the root owns the whole surface), 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
  */
 
@@ -52,6 +53,15 @@ export interface PetInjected {
 export type PetDockEntryProps =
   PetInjected
   & PropsLocale<typeof NS>
+  & {
+    /**
+     * DOM node the floating sprite chrome portals into. Defaults to
+     * document.body; the plugin apply passes its [data-dsh-plugin="pet"]
+     * root so root-keyed suppressors (the portrait mobile layer) and skins
+     * own the whole pet surface as one unit.
+     */
+    portalTarget?: Element
+  }
 
 const DEFAULT_DISPLAY: PetDisplayConfig = { visible: true, size: 160, right: 24, bottom: 20 }
 
@@ -108,6 +118,7 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
                 onRename={props.rename}
                 onOpenSession={props.openSession}
                 onFeedbackDone={props.feedbackDone}
+                portalTarget={props.portalTarget}
                 dragDisabled={snapshot.gameplay?.mode === 'work'}
                 {...(gameplay === undefined || aux === null
                   ? {}

package/src/client/PetSettingsCard.tsx

@@ -9,7 +9,8 @@
 
 import type { ReactNode } from 'react'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 // Type-only: pulls the settings-surface SlotMap merge (the 'settings.section' entry).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import { PluginSettingsCard, ValueField, BooleanField, ChoiceField } from './PluginSettingsCard.tsx'

package/src/client/PetSprite.test.tsx

@@ -176,6 +176,24 @@ describe('PetSprite hide control (#1126)', () => {
   })
 })
 
+describe('PetSprite affinity rank localization (#1226)', () => {
+  it('localizes the rank name in the hover panel when document language is en', () => {
+    document.documentElement.lang = 'en'
+    try {
+      renderPet({
+        snapshot: {
+          ...snapshot,
+          affinity: { ...snapshot.affinity, rank: '幼鲸' },
+        },
+      })
+      fireEvent.pointerOver(screen.getByRole('button', { name: '鲸鱼娘' }))
+      expect(screen.getByText('Affinity Baby Whale')).toBeTruthy()
+    } finally {
+      document.documentElement.lang = 'zh'
+    }
+  })
+})
+
 describe('PetSprite rename input', () => {
   it('submits the draft on Enter outside composition', () => {
     const { onRename } = renderPet()
@@ -1104,3 +1122,21 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     expect(timerSpy.mock.calls.length).toBe(schedulesBefore + 1)
   })
 })
+
+
+describe('PetSprite portal target', () => {
+  it('portals the float into the provided target instead of document.body', () => {
+    const host = document.createElement('div')
+    document.body.appendChild(host)
+    renderPet({ portalTarget: host })
+    // The float (sprite chrome) lands inside the owning root, so a
+    // root-keyed suppressor (the portrait mobile layer) hides it as one unit.
+    expect(host.querySelector('[role="button"]')).not.toBeNull()
+  })
+
+  it('portals the float into document.body when no target is given', () => {
+    renderPet()
+    expect(document.body.querySelector('[role="button"]')).not.toBeNull()
+  })
+})
+

package/src/client/PetSprite.tsx

@@ -16,6 +16,7 @@ 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 { announcementFresh, type PetAnnouncement } from '../announce.ts'
 import type { PetDefinition } from '../registry.ts'
 import type { DecorationView } from '../contracts/status-decoration.ts'
 import type { PetFeedback } from './pet-store.ts'
@@ -78,6 +79,14 @@ export interface PetSpriteProps {
   onGameplayMenu?: () => void
   /** Disable the drag gesture (gameplay work mode blocks dragging). */
   dragDisabled?: boolean
+  /**
+   * DOM node the floating chrome portals into. Defaults to document.body
+   * (the legacy behavior); the plugin apply passes its owning root (the
+   * [data-dsh-plugin="pet"] container) so the root owns the whole surface
+   * and a root-keyed suppressor (the portrait mobile layer) hides the pet
+   * as one unit instead of missing the portaled sprite.
+   */
+  portalTarget?: Element
   /** Locale translate seat (namespace-bound). */
   t: TranslateNS<typeof NS>
 }
@@ -176,6 +185,52 @@ function StatusOrnament(props: { decoration: DecorationView; phase: ActivityPhas
   )
 }
 
+/**
+ * The announcement bubble (dsh-usage linkage): a dedicated, specially
+ * designed surface for sibling-plugin facts — a balance or today-spend pill,
+ * or a plan-quota card with a tone-tinted accent, a mini meter for percent
+ * windows, and the reset instant. It rides the top of the session bubble
+ * stack (column-reverse puts the DOM-last child farthest from the sprite)
+ * and persists for its TTL instead of the short feedback pop.
+ */
+function UsageAnnouncementBubble(props: { announcement: PetAnnouncement }): ReactNode {
+  const { announcement } = props
+  const tone = announcement.tone === 'low'
+    ? styles.bubbleUsageLow
+    : announcement.tone === 'warn'
+      ? styles.bubbleUsageWarn
+      : styles.bubbleUsageOk
+  return (
+    <div
+      className={clsx(styles.bubble, styles.bubbleUsage, tone)}
+      role="status"
+      aria-live="polite"
+      data-dsh-pet-announcement={announcement.source}
+    >
+      <span className={styles.bubbleUsageHead}>
+        <span className={styles.bubbleUsageTitle}>{announcement.title}</span>
+        {(announcement.kind === 'balance' || announcement.kind === 'cost') && announcement.amount !== undefined && (
+          <span className={styles.bubbleUsageValue}>{announcement.amount}</span>
+        )}
+        {announcement.kind === 'plan' && announcement.percent !== undefined && (
+          <span className={styles.bubbleUsageValue}>{Math.round(announcement.percent) + '%'}</span>
+        )}
+      </span>
+      {announcement.kind === 'plan' && announcement.percent !== undefined && (
+        <span className={styles.bubbleUsageMeter}>
+          <span
+            className={styles.bubbleUsageMeterFill}
+            style={{ width: Math.min(100, Math.max(0, announcement.percent)) + '%' }}
+          />
+        </span>
+      )}
+      {announcement.note !== undefined && (
+        <span className={styles.bubbleUsageNote}>{announcement.note}</span>
+      )}
+    </div>
+  )
+}
+
 /**
  * The floating pet. The spritesheet frame advances on requestAnimationFrame
  * with per-frame durations from the definition's tracks; the atlas image is
@@ -432,6 +487,13 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const statusBubble = feedback === null && sessionBubbles.length === 0
     ? snapshot?.bubble
     : undefined
+  // The freshest plugin-authored announcement (dsh-usage linkage): a
+  // dedicated, specially styled bubble above the session stack. The host
+  // already TTL-filters; this client-side check covers the last poll tick.
+  const announcement = snapshot?.announcement
+  const usageAnnouncement = feedback === null && announcement !== undefined && announcementFresh(announcement, Date.now())
+    ? announcement
+    : 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
@@ -439,7 +501,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   // 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 bubblePresent = feedback !== null || sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined
   const displayName = snapshot?.name ?? definition.displayName
   // The host-served status decoration (M5, #567); absent = text-only bubbles.
   const decoration = snapshot?.decoration
@@ -549,7 +611,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
           {feedback.text}
         </div>
       )}
-      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined) && (
+      {feedback === null && (sessionBubbles.length > 0 || statusBubble !== undefined || usageAnnouncement !== undefined) && (
         <div
           ref={bubbleRef}
           className={styles.bubbleStack}
@@ -620,6 +682,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
               {statusBubble}
             </div>
           )}
+          {usageAnnouncement !== undefined && <UsageAnnouncementBubble announcement={usageAnnouncement} />}
         </div>
       )}
       {hovered && dragRef.current === null && (
@@ -685,7 +748,15 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
             <>
               <div className={styles.rankRow}>
                 <span className={styles.nameCell}>{displayName}</span>
-                <span className={styles.statRank}>{panelStat('rank', 'pet.rank', { rank: snapshot?.affinity.rank ?? '?' })}</span>
+                <span className={styles.statRank}>
+                  {(() => {
+                    const rawRank = snapshot?.affinity.rank ?? '?'
+                    const rankKey = `pet.rank.name.${rawRank}`
+                    const localized = props.t(rankKey as any)
+                    const rankName = localized !== rankKey ? localized : rawRank
+                    return panelStat('rank', 'pet.rank', { rank: rankName })
+                  })()}
+                </span>
               </div>
               <div className={styles.rankRow}>
                 <span className={styles.statTreats}>{panelStat('treats', 'pet.treats', { n: snapshot?.treats.stocked ?? 0 })}</span>
@@ -730,5 +801,5 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
     </div>
   )
 
-  return createPortal(float, document.body)
+  return createPortal(float, props.portalTarget ?? document.body)
 }

package/src/client/gameplay-hud.test.tsx

@@ -9,7 +9,7 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 // The npm SDK's client half is a closure-factory bundle for the GUI's
 // __ModuleLoader__ (not importable under vitest); provide the defineStore
 // the pet store needs (same fake-store pattern as PetDockEntry.test.tsx).
-vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
+vi.mock('@deepseek-ai/dsh-client-store', () => ({
   defineStore: (spec: {
     init: () => unknown
     actions: Record<string, (draft: never, ...args: never[]) => void>

package/src/client/index.test.tsx

@@ -12,7 +12,7 @@ import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 // The npm SDK's client half is a closure-factory bundle for the GUI's
 // __ModuleLoader__ (not importable under vitest); provide defineStore /
 // createSnapshotStore (same fake-store pattern as the settings-card tests).
-vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
+vi.mock('@deepseek-ai/dsh-client-store', () => ({
   defineStore: (spec: {
     init: () => unknown
     actions: Record<string, (draft: never, ...args: never[]) => void>
@@ -48,7 +48,7 @@ vi.mock('@deepseek-ai/dsh-client-runtime/client', () => ({
     }
   },
 }))
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
 import { apply } from './index.ts'
 
 beforeAll(() => {

package/src/client/index.ts

@@ -4,19 +4,26 @@
  * 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.
+ * single React root — the [data-dsh-plugin="pet"] container — rather than a
+ * session-scoped slot: on the new-conversation screen no session exists, and
+ * a dock-mounted pet would vanish there (issue #48). The sprite chrome
+ * portals into that same root, so the root owns the whole surface and a
+ * root-keyed suppressor can hide it as one unit. When the pet is hidden the
+ * entry becomes a fixed-position summon button.
  * @module @linxin666/dsh-pet/client
  */
 
-import type { ClientContext, ISessions, SessionId, SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client'
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type { ISessions } from '@deepseek-ai/dsh-api-session-controller/client'
+import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client'
+import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-ui-settings/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 // Type-only: pulls the settings-surface Context merge (ctx.settingsScope).
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls the ctx.slots merge (the renderer owns the slot registry since 0.1.2).
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { PetDisplayConfig } from '../persist.ts'
 import type { PetGameplayVerbResult, PetInteractResult, PetStateView } from '../service.ts'
@@ -381,7 +388,11 @@ export function apply(ctx: ClientContext): void {
       container.dataset.dshPlugin = 'pet'
       document.body.appendChild(container)
       const petRoot = createRoot(container)
-      petRoot.render(createElement(PetDockEntry, { ...injected(), t }))
+      // The sprite chrome portals into THIS root (not document.body): the
+      // root then owns the whole surface, so a root-keyed suppressor (the
+      // portrait mobile layer, which hides [data-dsh-plugin="pet"]) really
+      // hides the sprite instead of missing the portaled float.
+      petRoot.render(createElement(PetDockEntry, { ...injected(), t, portalTarget: container }))
 
       let uiGone = false
       disposeUi = () => {