@linxin666/dsh-pet 0.3.24 → 0.3.25

package/package.json

@@ -1,11 +1,23 @@
 {
   "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.24",
+  "version": "0.3.25",
+  "publishConfig": {
+    "access": "public"
+  },
+  "icon": "icon.svg",
   "type": "module",
+  "packageManager": "pnpm@11.7.0",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
   },
+  "scripts": {
+    "build": "tsc -b && tsdown",
+    "test": "vitest run",
+    "pet:cli": "node scripts/dsh-pet.cjs",
+    "typecheck": "tsc -b --pretty false && tsc -p tsconfig.test.json --pretty false",
+    "prepare": "tsdown --config tsdown.prepare.config.ts"
+  },
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
   "exports": {
@@ -36,12 +48,13 @@
     "assets/ouo-neko",
     "assets/blue-throated-bee-eater",
     "assets/decorations",
-    "contracts"
+    "contracts",
+    "icon.svg"
   ],
   "license": "Apache-2.0",
   "dsh": {
     "engines": {
-      "dsh": ">=0.1.5-rc.1"
+      "dsh": ">=0.1.7-rc.1"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -51,39 +64,51 @@
         "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-conversation",
-        "@deepseek-ai/dsh-api-session-controller"
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-ui-workspace"
       ],
       "platform": "web"
     }
   },
   "dependencies": {
-    "clsx": "^2.1.1",
-    "schemastery": "^3.18.0"
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "clsx": "^2.1.1"
   },
   "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.1.7-rc.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.5-rc.1",
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-agent": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-util-time": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-util-values": "^0.1.7-rc.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
     "jsdom": "29.1.1",
+    "lightningcss": "^1.32.0",
     "pixi.js": "^8.19.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
@@ -95,11 +120,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/zhu1090093659/dsh-web.git"
-  },
-  "scripts": {
-    "build": "tsc -b && tsdown",
-    "test": "vitest run",
-    "typecheck": "tsc -b --pretty false && tsc -p tsconfig.test.json --pretty false"
+    "url": "https://github.com/zhu1090093659/dsh-pet.git"
   }
-}
+}

package/src/client/PetDockEntry.tsx

@@ -120,6 +120,7 @@ export function PetDockEntry(props: PetDockEntryProps): ReactElement {
                 onFeedbackDone={props.feedbackDone}
                 portalTarget={props.portalTarget}
                 dragDisabled={snapshot.gameplay?.mode === 'work'}
+                {...(aux === null ? {} : { bus: aux.bus })}
                 {...(gameplay === undefined || aux === null
                   ? {}
                   : {

package/src/client/PetSettingsCard.test.tsx

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client'
+import { PetSettingsCardController, type PetSettings } from './PetSettingsCard.tsx'
+
+vi.mock('@deepseek-ai/dsh-client-store', () => ({ // test-standards-allow: the SDK client bundle is a browser module factory and cannot be imported by Vitest
+  createSnapshotStore: (initial: unknown) => {
+    let value = initial
+    const listeners = new Set<() => void>()
+    return {
+      getSnapshot: () => value,
+      set: (next: unknown) => { value = next; for (const listener of listeners) listener() },
+      subscribe: (listener: () => void) => {
+        listeners.add(listener)
+        return () => { listeners.delete(listener) }
+      },
+    }
+  },
+}))
+
+function unavailableForm() {
+  const mutate = vi.fn(async () => false)
+  const scope = {
+    getSnapshot: () => ({ status: 'unavailable', writable: true, value: undefined, base: undefined, user: undefined }),
+    subscribe: () => () => {},
+    mutate,
+  } as unknown as ConfigForm<PetSettings>
+  return { scope, mutate }
+}
+
+function response(value: unknown, ok = true): Response {
+  return { ok, status: ok ? 200 : 500, json: async () => value } as Response
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+describe('pet selection without a Host settings form', () => {
+  it('user saves the selected pet through its persisted API and confirms the read-back', async () => {
+    // Given the aggregate shell exposes no pet configuration form
+    vi.useFakeTimers()
+    const { scope, mutate } = unavailableForm()
+    let selected = 'whale-girl'
+    const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      const path = String(input)
+      if (path === '/api/pet/pets') return response([{ id: 'whale-girl', displayName: '鲸鱼娘' }, { id: 'jyn', displayName: '女仆鲸鱼娘' }])
+      if (path === '/api/pet/diagnostics') return response({ diagnostics: [] })
+      if (path === '/api/pet/state') return response({ pet: { id: selected } })
+      if (path === '/api/pet/set-pet') {
+        selected = JSON.parse(String(init?.body)).petId as string
+        return response({ ok: true, petId: selected })
+      }
+      throw new Error('unexpected request: ' + path)
+    })
+    vi.stubGlobal('fetch', fetch)
+    const controller = new PetSettingsCardController(scope)
+    await vi.advanceTimersByTimeAsync(0)
+    const face = controller.inject()
+    const state = () => face.hooks.petSettingsCard.getSnapshot()
+
+    // When the user chooses the maid whale and clicks Save
+    expect(state()).toMatchObject({ petSelectionFallback: true, petId: { text: 'whale-girl' }, dirty: false })
+    face.edit('petId', '')
+    expect(state()).toMatchObject({ dirty: false, petId: { text: 'whale-girl' } })
+    face.edit('petId', 'jyn')
+    expect(state()).toMatchObject({ dirty: true, petId: { text: 'jyn' } })
+    face.save()
+    await vi.waitFor(() => { expect(state().saving).toBe(false) })
+
+    // Then the pet service holds it, the draft clears, and the absent Host form is untouched
+    expect(selected).toBe('jyn')
+    expect(state()).toMatchObject({ dirty: false, failed: false, petId: { text: 'jyn' } })
+    expect(mutate).not.toHaveBeenCalled()
+    expect(fetch).toHaveBeenCalledWith('/api/pet/set-pet', expect.objectContaining({ body: JSON.stringify({ petId: 'jyn' }) }))
+    controller.dispose()
+  })
+
+  it('user keeps the draft when the pet API refuses the selection', async () => {
+    // Given the Host has no pet form and the pet API still serves its selection
+    vi.useFakeTimers()
+    const { scope } = unavailableForm()
+    vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL) => {
+      const path = String(input)
+      if (path === '/api/pet/pets') return response([{ id: 'whale-girl', displayName: '鲸鱼娘' }, { id: 'jyn', displayName: '女仆鲸鱼娘' }])
+      if (path === '/api/pet/diagnostics') return response({ diagnostics: [] })
+      if (path === '/api/pet/state') return response({ pet: { id: 'whale-girl' } })
+      if (path === '/api/pet/set-pet') return response({ ok: false, error: 'unknown-pet' })
+      throw new Error('unexpected request: ' + path)
+    }))
+    const controller = new PetSettingsCardController(scope)
+    await vi.advanceTimersByTimeAsync(0)
+    const face = controller.inject()
+    // When the user saves a selection the pet API refuses
+    face.edit('petId', 'jyn')
+    face.save()
+    await vi.waitFor(() => { expect(face.hooks.petSettingsCard.getSnapshot().saving).toBe(false) })
+    // Then the choice remains staged and the failure is visible
+    expect(face.hooks.petSettingsCard.getSnapshot()).toMatchObject({ dirty: true, failed: true, petId: { text: 'jyn' } })
+    controller.dispose()
+  })
+})

package/src/client/PetSettingsCard.tsx

@@ -1,15 +1,17 @@
 /**
- * The pet settings card: pet selection plus display layout, bound to the
- * 'pet' settings namespace the host plugin registers. Rendered as an
- * always-open first-level settings page; the section wrapper below mounts it
- * as the content of the top-level 'settings.section' nav entry. 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.
+ * The pet settings card: pet selection plus display layout, staged over the
+ * 'pet' profile entry's own configuration (a plugin's settings ARE its Cordis
+ * Config since 0.1.7, so the Host serves one form per profile entry).
+ * Rendered as an always-open first-level settings page; the section wrapper
+ * below mounts it as the content of the top-level 'settings.section' nav
+ * entry. 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 { ReactNode } from 'react'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ConfigForm } 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'
@@ -39,6 +41,8 @@ export interface PetSettings {
 
 /** What the pet settings card renders. */
 export interface PetSettingsCardState extends CardShell {
+  /** The aggregate shell has no Host settings form; pet selection uses its own persisted API. */
+  petSelectionFallback: boolean
   /** Plugin master switch. */
   enabled: CardFieldState
   /** Master switch. */
@@ -96,6 +100,15 @@ async function fetchPetDiagnostics(): Promise<PetDiagnosticView[]> {
   return body.diagnostics ?? []
 }
 
+/** Read the selection from the same persisted state the pet renders. */
+async function fetchSelectedPetId(): Promise<string> {
+  const response = await fetch('/api/pet/state')
+  if (!response.ok) throw new Error('pet state failed: ' + response.status)
+  const body = (await response.json()) as { pet?: { id?: unknown } }
+  if (typeof body.pet?.id !== 'string') throw new Error('pet state has no selected pet')
+  return body.pet.id
+}
+
 /** Bridges the 'pet' scope onto the card's staged form. */
 export class PetSettingsCardController {
   private readonly form: CardForm<PetSettings>
@@ -106,14 +119,18 @@ export class PetSettingsCardController {
   private readonly petChoices: string[] = []
   private readonly petLabels = new Map<string, string>()
   private diagnostics: PetDiagnosticView[] = []
+  private selectedPetId: string | undefined
+  private stagedPetId: string | undefined
+  private savingPet = false
+  private petSaveFailed = false
   private loaded = false
   private attempts = 0
   private disposed = false
   /** Pending deferred-load or retry timer; cancelled by dispose(). */
   private pendingTimer: number | undefined
 
-  /** @param scope - the bound settings scope for the 'pet' namespace. */
-  constructor(scope: SettingsScope<PetSettings>) {
+  /** @param scope - the bound configuration form for the 'pet' entry. */
+  constructor(scope: ConfigForm<PetSettings>) {
     this.form = new CardForm(scope, [
       booleanField('enabled'),
       booleanField('decorationEnabled'),
@@ -134,6 +151,7 @@ export class PetSettingsCardController {
       if (this.disposed) return
       void this.loadPets()
       void this.loadDiagnostics()
+      void this.loadSelectedPet()
     }, 0)
   }
 
@@ -171,9 +189,65 @@ export class PetSettingsCardController {
     }
   }
 
+  private async loadSelectedPet(): Promise<void> {
+    try {
+      const petId = await fetchSelectedPetId()
+      if (this.disposed) return
+      this.selectedPetId = petId
+      this.store.set(this.projection())
+    } catch {
+      // The Host form remains the authority when it is available. An absent
+      // pet API leaves the fallback unavailable rather than inventing state.
+    }
+  }
+
+  private fallback(): boolean {
+    const shell = this.form.shell()
+    return shell.available && !shell.exposed && this.selectedPetId !== undefined
+  }
+
+  private async savePetSelection(): Promise<void> {
+    const petId = this.stagedPetId
+    if (petId === undefined || this.savingPet || !this.petChoices.includes(petId)) return
+    this.savingPet = true
+    this.petSaveFailed = false
+    this.store.set(this.projection())
+    try {
+      const response = await fetch('/api/pet/set-pet', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ petId }),
+      })
+      const result = (await response.json()) as { ok?: boolean; petId?: string }
+      if (!response.ok || result.ok !== true || result.petId !== petId || await fetchSelectedPetId() !== petId) {
+        throw new Error('pet selection was not persisted')
+      }
+      this.selectedPetId = petId
+      if (this.stagedPetId === petId) this.stagedPetId = undefined
+    } catch {
+      this.petSaveFailed = true
+    } finally {
+      this.savingPet = false
+      if (!this.disposed) this.store.set(this.projection())
+    }
+  }
+
   private projection(): PetSettingsCardState {
+    const fallback = this.fallback()
+    const shell = this.form.shell()
+    const configuredPet = this.form.field('petId')
     return {
-      ...this.form.shell(),
+      ...shell,
+      ...(fallback ? {
+        exposed: true,
+        writable: true,
+        dirty: this.stagedPetId !== undefined && this.stagedPetId !== this.selectedPetId,
+        invalid: this.stagedPetId !== undefined && !this.petChoices.includes(this.stagedPetId),
+        saving: this.savingPet,
+        failed: this.petSaveFailed,
+        failedReason: undefined,
+      } : {}),
+      petSelectionFallback: fallback,
       enabled: this.form.field('enabled'),
       decorationEnabled: this.form.field('decorationEnabled'),
       visible: this.form.field('visible'),
@@ -181,7 +255,11 @@ export class PetSettingsCardController {
       right: this.form.field('right'),
       bottom: this.form.field('bottom'),
       bubbleScale: this.form.field('bubbleScale'),
-      petId: this.form.field('petId'),
+      petId: fallback
+        ? { text: this.stagedPetId ?? this.selectedPetId ?? '', overridden: false, invalid: this.stagedPetId !== undefined && !this.petChoices.includes(this.stagedPetId) }
+        : configuredPet.text === '' && this.selectedPetId !== undefined
+          ? { ...configuredPet, text: this.selectedPetId }
+          : configuredPet,
       petChoices: this.petChoices.map(id => ({ value: id, label: this.petLabels.get(id) ?? id })),
       petDiagnostics: this.diagnostics,
     }
@@ -192,7 +270,31 @@ export class PetSettingsCardController {
    * @returns the card's snapshot and its form actions.
    */
   inject(): PetSettingsCardFace {
-    return { hooks: { petSettingsCard: this.store }, ...this.form.actions() }
+    const actions = this.form.actions()
+    return {
+      hooks: { petSettingsCard: this.store },
+      edit: (field, value) => {
+        if (!this.fallback()) return actions.edit(field, value)
+        if (field !== 'petId') return
+        this.stagedPetId = value === '' ? undefined : value
+        this.petSaveFailed = false
+        this.store.set(this.projection())
+      },
+      resetField: (field) => {
+        if (!this.fallback()) return actions.resetField(field)
+        if (field !== 'petId') return
+        this.stagedPetId = undefined
+        this.petSaveFailed = false
+        this.store.set(this.projection())
+      },
+      save: () => { if (this.fallback()) void this.savePetSelection(); else actions.save() },
+      discard: () => {
+        if (!this.fallback()) return actions.discard()
+        this.stagedPetId = undefined
+        this.petSaveFailed = false
+        this.store.set(this.projection())
+      },
+    }
   }
 
   /**
@@ -235,12 +337,13 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
       t={t}
       titleKey="settings.title"
       descriptionKey="settings.description"
+      descriptionNode={state.petSelectionFallback ? t('settings.petHint') : undefined}
       state={state}
       onSave={props.save}
       onDiscard={props.discard}
       alwaysOpen
     >
-      <BooleanField
+      {state.petSelectionFallback ? null : <BooleanField
         id="settings-pet-enabled"
         label={t('settings.enabled')}
         hint={t('settings.enabledHint')}
@@ -251,8 +354,8 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.enabled}
         onEdit={(text) => { props.edit('enabled', text) }}
         onReset={() => { props.resetField('enabled') }}
-      />
-      <BooleanField
+      />}
+      {state.petSelectionFallback ? null : <BooleanField
         id="settings-pet-decoration"
         label={t('settings.decoration')}
         hint={t('settings.decorationHint')}
@@ -263,7 +366,7 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.decorationEnabled}
         onEdit={(text) => { props.edit('decorationEnabled', text) }}
         onReset={() => { props.resetField('decorationEnabled') }}
-      />
+      />}
       <ChoiceField
         id="settings-pet-pet"
         label={t('settings.pet')}
@@ -285,7 +388,7 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
           </ul>
         </li>
       )}
-      <BooleanField
+      {state.petSelectionFallback ? null : <BooleanField
         id="settings-pet-visible"
         label={t('settings.visible')}
         hint={t('settings.visibleHint')}
@@ -296,8 +399,8 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.visible}
         onEdit={(text) => { props.edit('visible', text) }}
         onReset={() => { props.resetField('visible') }}
-      />
-      <ValueField
+      />}
+      {state.petSelectionFallback ? null : <ValueField
         id="settings-pet-size"
         label={t('settings.size')}
         hint={t('settings.sizeHint')}
@@ -306,8 +409,8 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.size}
         onEdit={(text) => { props.edit('size', text) }}
         onReset={() => { props.resetField('size') }}
-      />
-      <ValueField
+      />}
+      {state.petSelectionFallback ? null : <ValueField
         id="settings-pet-right"
         label={t('settings.right')}
         hint={t('settings.rightHint')}
@@ -316,8 +419,8 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.right}
         onEdit={(text) => { props.edit('right', text) }}
         onReset={() => { props.resetField('right') }}
-      />
-      <ValueField
+      />}
+      {state.petSelectionFallback ? null : <ValueField
         id="settings-pet-bottom"
         label={t('settings.bottom')}
         hint={t('settings.bottomHint')}
@@ -326,8 +429,8 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.bottom}
         onEdit={(text) => { props.edit('bottom', text) }}
         onReset={() => { props.resetField('bottom') }}
-      />
-      <ValueField
+      />}
+      {state.petSelectionFallback ? null : <ValueField
         id="settings-pet-bubble-scale"
         label={t('settings.bubbleScale')}
         hint={t('settings.bubbleScaleHint')}
@@ -336,7 +439,7 @@ export function PetSettingsCard(props: PetSettingsCardProps) {
         {...state.bubbleScale}
         onEdit={(text) => { props.edit('bubbleScale', text) }}
         onReset={() => { props.resetField('bubbleScale') }}
-      />
+      />}
     </PluginSettingsCard>
   )
 }

package/src/client/PetSprite.tsx

@@ -18,6 +18,8 @@ import { bubbleScaleFor, 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 { GameplayBus } from './gameplay-hud.ts'
+import type { PetRoamDirection } from '../gameplay.ts'
 import type { DecorationView } from '../contracts/status-decoration.ts'
 import type { PetFeedback } from './pet-store.ts'
 import { framePosition, rowOfTrack, trimTrack } from './spritesheet.ts'
@@ -79,6 +81,11 @@ export interface PetSpriteProps {
   onGameplayMenu?: () => void
   /** Disable the drag gesture (gameplay work mode blocks dragging). */
   dragDisabled?: boolean
+  /**
+   * Per-pet coordination bus. The chrome registers `walk` here so the gameplay
+   * HUD can roam the pet (the same two-way shape the HUD's `tap` uses).
+   */
+  bus?: GameplayBus
   /**
    * DOM node the floating chrome portals into. Defaults to document.body
    * (the legacy behavior); the plugin apply passes its owning root (the
@@ -482,6 +489,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
 
   const onPointerDown = (e: ReactPointerEvent<HTMLDivElement>): void => {
     if (props.dragDisabled === true) return
+    endWalk(false)
     e.preventDefault()
     ;(e.target as HTMLElement).setPointerCapture?.(e.pointerId)
     const current = dragPos ?? { right: display.right, bottom: display.bottom }
@@ -512,6 +520,93 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
   const pos = dragPos ?? { right: display.right, bottom: display.bottom }
   const spriteWidth = Math.round(cell.width * spriteScale)
   const spriteHeight = Math.round(cell.height * spriteScale)
+
+  // --- roaming ---------------------------------------------------------
+  // The gameplay HUD rolls when the pet may wander; this side owns the motion
+  // (clamped to the viewport), the walk art's facing and the persisted resting
+  // spot -- the walk ends on the same write a drag ends with. The walk art
+  // faces left, so a rightward walk mirrors the sprite (a vertical walk keeps
+  // the side view); every other track stays unmirrored.
+  const [facingRight, setFacingRight] = useState(false)
+  const walkRafRef = useRef(0)
+  const walkTargetRef = useRef<{ right: number; bottom: number } | null>(null)
+  const dragPosRef = useRef(dragPos)
+  dragPosRef.current = dragPos
+
+  /** Stop an active walk; `persist` lands the pet on the spot it reached. */
+  const endWalk = (persist: boolean): void => {
+    if (walkRafRef.current === 0) return
+    window.cancelAnimationFrame(walkRafRef.current)
+    walkRafRef.current = 0
+    setFacingRight(false)
+    const settled = walkTargetRef.current
+    walkTargetRef.current = null
+    if (persist && settled !== null) props.onDragEnd(settled.right, settled.bottom)
+  }
+
+  useEffect(() => {
+    const bus = props.bus
+    if (bus === undefined) return undefined
+    bus.walk = (direction: PetRoamDirection, distance: number, speed: number): number => {
+      if (dragRef.current !== null || walkRafRef.current !== 0) return 0
+      const current = dragPosRef.current ?? { right: display.right, bottom: display.bottom }
+      // Keep the whole sprite on screen with an 8px breathing margin. `right`
+      // and `bottom` are CSS offsets: right grows leftwards, bottom upwards.
+      const margin = 8
+      const maxRight = Math.max(margin, window.innerWidth - spriteWidth - margin)
+      const maxBottom = Math.max(margin, window.innerHeight - spriteHeight - margin)
+      const wanted = { ...current }
+      if (direction === 'left') wanted.right = current.right + distance
+      else if (direction === 'right') wanted.right = current.right - distance
+      else if (direction === 'up') wanted.bottom = current.bottom + distance
+      else wanted.bottom = current.bottom - distance
+      const target = {
+        right: Math.max(margin, clampOffset(wanted.right, maxRight)),
+        bottom: Math.max(margin, clampOffset(wanted.bottom, maxBottom)),
+      }
+      const travelled = direction === 'left' ? target.right - current.right
+        : direction === 'right' ? current.right - target.right
+          : direction === 'up' ? target.bottom - current.bottom
+            : current.bottom - target.bottom
+      if (travelled < 1) return 0
+      const duration = Math.max(150, (travelled / Math.max(1, speed)) * 1000)
+      const startedAt = performance.now()
+      // The crawl art faces left, so only a rightward walk mirrors it; a
+      // vertical walk keeps the side view (there is no front/back art).
+      setFacingRight(direction === 'right')
+      walkTargetRef.current = current
+      const step = (now: number): void => {
+        const t = Math.min(1, (now - startedAt) / duration)
+        const next = {
+          right: current.right + (target.right - current.right) * t,
+          bottom: current.bottom + (target.bottom - current.bottom) * t,
+        }
+        walkTargetRef.current = next
+        setDragPos(next)
+        if (t < 1) {
+          walkRafRef.current = window.requestAnimationFrame(step)
+          return
+        }
+        walkRafRef.current = 0
+        walkTargetRef.current = null
+        setFacingRight(false)
+        props.onDragEnd(next.right, next.bottom)
+      }
+      walkRafRef.current = window.requestAnimationFrame(step)
+      return travelled
+    }
+    return () => {
+      bus.walk = undefined
+      if (walkRafRef.current !== 0) {
+        window.cancelAnimationFrame(walkRafRef.current)
+        walkRafRef.current = 0
+      }
+      // A cancelled walk must not leave the sprite mirrored.
+      setFacingRight(false)
+      walkTargetRef.current = null
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one registration per sprite
+  }, [props.bus, definition.id, display.right, display.bottom, spriteWidth])
   // Bubble typography follows the sprite's own scale (#1549), bounded so a
   // shrunk pet never carries unreadably small text.
   const bubbleScale = bubbleScaleFor(display)
@@ -630,6 +725,7 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
                 }
               : {}),
             cursor: dragRef.current === null ? 'grab' : 'grabbing',
+            ...(facingRight ? { transform: 'scaleX(-1)' } : {}),
           }}
           onPointerDown={onPointerDown}
           onPointerMove={onPointerMove}