@linxin666/dsh-pet 0.2.7 → 0.2.8

package/src/client/PetSprite.test.tsx

@@ -687,7 +687,7 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     expect(ornament()).toBeNull()
   })
 
-  it('advances the ornament frames on the rAF loop and wraps when looping', () => {
+  it('advances the ornament frames on the duration timer and wraps when looping', () => {
     vi.spyOn(window, 'matchMedia').mockReturnValue({
       matches: false,
       media: '(prefers-reduced-motion: reduce)',
@@ -698,7 +698,17 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
       removeListener: () => {},
       dispatchEvent: () => false,
     })
-    vi.spyOn(performance, 'now').mockReturnValue(0)
+    let now = 0
+    vi.spyOn(performance, 'now').mockImplementation(() => now)
+    // The ornament schedules by frame duration (setTimeout), the sprite
+    // still uses rAF; capture both so stepping advances both loops.
+    const timers: { at: number; callback: () => void }[] = []
+    let timerId = 0
+    vi.spyOn(window, 'setTimeout').mockImplementation(((callback: () => void, delay = 0) => {
+      timers.push({ at: now + delay, callback })
+      return ++timerId
+    }) as typeof window.setTimeout)
+    vi.spyOn(window, 'clearTimeout').mockImplementation(() => {})
     const frames: FrameRequestCallback[] = []
     vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
       frames.push(callback)
@@ -707,18 +717,31 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     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) }
+    // Run the sprite rAF callbacks immediately (its idle track never moves);
+    // run ornament timers as the clock reaches them, repeatedly, because a
+    // due timer reschedules the next one at now + duration.
+    const step = (ms: number): void => {
+      for (const callback of frames.splice(0)) callback(now)
+      now += ms
+      for (;;) {
+        const due = timers.filter(t => t.at <= now)
+        if (due.length === 0) break
+        for (const t of due) {
+          const idx = timers.indexOf(t)
+          if (idx >= 0) timers.splice(idx, 1)
+          t.callback()
+        }
+      }
+    }
     // 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) })
+    act(() => { step(161) })
     expect(el.style.backgroundPosition).toBe('-48px 0px')
-    act(() => { step(483) })
+    act(() => { step(161) })
     expect(el.style.backgroundPosition).toBe('-72px 0px')
-    act(() => { step(644) })
+    act(() => { step(161) })
     // The looping segment wraps back to its first frame.
     expect(el.style.backgroundPosition).toBe('0px 0px')
   })
@@ -734,7 +757,15 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
       removeListener: () => {},
       dispatchEvent: () => false,
     })
-    vi.spyOn(performance, 'now').mockReturnValue(0)
+    let now = 0
+    vi.spyOn(performance, 'now').mockImplementation(() => now)
+    const timers: { at: number; callback: () => void }[] = []
+    let timerId = 0
+    vi.spyOn(window, 'setTimeout').mockImplementation(((callback: () => void, delay = 0) => {
+      timers.push({ at: now + delay, callback })
+      return ++timerId
+    }) as typeof window.setTimeout)
+    vi.spyOn(window, 'clearTimeout').mockImplementation(() => {})
     const frames: FrameRequestCallback[] = []
     vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
       frames.push(callback)
@@ -743,13 +774,25 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     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) }
+    const step = (ms: number): void => {
+      for (const callback of frames.splice(0)) callback(now)
+      now += ms
+      for (;;) {
+        const due = timers.filter(t => t.at <= now)
+        if (due.length === 0) break
+        for (const t of due) {
+          const idx = timers.indexOf(t)
+          if (idx >= 0) timers.splice(idx, 1)
+          t.callback()
+        }
+      }
+    }
     // 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)
+    // The ornament stopped scheduling timers (only the sprite rAF remains).
+    expect(timers).toHaveLength(0)
     act(() => { step(161) })
     // The last frame holds.
     expect(el.style.backgroundPosition).toBe('-72px 0px')
@@ -767,6 +810,13 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
       dispatchEvent: () => false,
     })
     vi.spyOn(performance, 'now').mockReturnValue(0)
+    const timers: { at: number; callback: () => void }[] = []
+    let timerId = 0
+    vi.spyOn(window, 'setTimeout').mockImplementation(((callback: () => void, delay = 0) => {
+      timers.push({ at: delay, callback })
+      return ++timerId
+    }) as typeof window.setTimeout)
+    vi.spyOn(window, 'clearTimeout').mockImplementation(() => {})
     const frames: FrameRequestCallback[] = []
     vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
       frames.push(callback)
@@ -784,15 +834,15 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     })
     const el = ornament()!
     // The ornament settles on its only frame, exactly like the reduced-motion
-    // hold — no rAF loop may start, so only the sprite's idle loop is pending.
+    // hold — no timer may start (only the sprite's idle rAF is pending).
     expect(el.style.backgroundPosition).toBe('-72px 0px')
-    expect(frames).toHaveLength(1)
+    expect(timers).toHaveLength(0)
     const step = (ts: number): void => { for (const callback of frames.splice(0)) callback(ts) }
     act(() => { step(161) })
     act(() => { step(322) })
     // The frame never moves and the ornament never reschedules itself.
     expect(el.style.backgroundPosition).toBe('-72px 0px')
-    expect(frames).toHaveLength(1)
+    expect(timers).toHaveLength(0)
   })
 
   it('does not advance the background while a frame is still in play', () => {
@@ -806,7 +856,15 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
       removeListener: () => {},
       dispatchEvent: () => false,
     })
-    vi.spyOn(performance, 'now').mockReturnValue(0)
+    let now = 0
+    vi.spyOn(performance, 'now').mockImplementation(() => now)
+    const timers: { at: number; callback: () => void }[] = []
+    let timerId = 0
+    vi.spyOn(window, 'setTimeout').mockImplementation(((callback: () => void, delay = 0) => {
+      timers.push({ at: now + delay, callback })
+      return ++timerId
+    }) as typeof window.setTimeout)
+    vi.spyOn(window, 'clearTimeout').mockImplementation(() => {})
     const frames: FrameRequestCallback[] = []
     vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
       frames.push(callback)
@@ -815,7 +873,19 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
     renderPet({ snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking', decoration } })
     const el = ornament()!
-    const step = (ts: number): void => { for (const callback of frames.splice(0)) callback(ts) }
+    const step = (ms: number): void => {
+      for (const callback of frames.splice(0)) callback(now)
+      now += ms
+      for (;;) {
+        const due = timers.filter(t => t.at <= now)
+        if (due.length === 0) break
+        for (const t of due) {
+          const idx = timers.indexOf(t)
+          if (idx >= 0) timers.splice(idx, 1)
+          t.callback()
+        }
+      }
+    }
     // thinking binds frames 0..3 at 160 ms/frame. The effect holds frame 0;
     // a step at 80 ms — inside the first frame — must not move the ornament,
     // and only crossing the 160 ms boundary advances to the next frame.
@@ -826,6 +896,58 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
     expect(el.style.backgroundPosition).toBe('-24px 0px')
   })
 
+  it('catches up every due frame after a long idle gap', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({
+      matches: false,
+      media: '(prefers-reduced-motion: reduce)',
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    })
+    let now = 0
+    vi.spyOn(performance, 'now').mockImplementation(() => now)
+    const timers: { at: number; callback: () => void }[] = []
+    let timerId = 0
+    vi.spyOn(window, 'setTimeout').mockImplementation(((callback: () => void, delay = 0) => {
+      timers.push({ at: now + delay, callback })
+      return ++timerId
+    }) as typeof window.setTimeout)
+    vi.spyOn(window, 'clearTimeout').mockImplementation(() => {})
+    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()!
+    const step = (ms: number): void => {
+      for (const callback of frames.splice(0)) callback(now)
+      now += ms
+      for (;;) {
+        const due = timers.filter(t => t.at <= now)
+        if (due.length === 0) break
+        for (const t of due) {
+          const idx = timers.indexOf(t)
+          if (idx >= 0) timers.splice(idx, 1)
+          t.callback()
+        }
+      }
+    }
+    // A 500 ms gap (jank / background tab) spans three 160 ms frames; the
+    // ornament must advance through all of them (0 -> 1 -> 2 -> 3), not
+    // drop the surplus time.
+    expect(el.style.backgroundPosition).toBe('0px 0px')
+    act(() => { step(500) })
+    expect(el.style.backgroundPosition).toBe('-72px 0px')
+    act(() => { step(161) })
+    // The next frame tick wraps the looping segment back to its first frame.
+    expect(el.style.backgroundPosition).toBe('0px 0px')
+  })
+
   it('does not restart the frame loop when an equal-content decoration re-renders', () => {
     vi.spyOn(window, 'matchMedia').mockReturnValue({
       matches: false,
@@ -837,21 +959,41 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
       removeListener: () => {},
       dispatchEvent: () => false,
     })
-    vi.spyOn(performance, 'now').mockReturnValue(0)
+    let now = 0
+    vi.spyOn(performance, 'now').mockImplementation(() => now)
+    const timers: { at: number; callback: () => void }[] = []
+    let timerId = 0
+    const timerSpy = vi.spyOn(window, 'setTimeout').mockImplementation(((callback: () => void, delay = 0) => {
+      timers.push({ at: now + delay, callback })
+      return ++timerId
+    }) as typeof window.setTimeout)
+    const clearSpy = vi.spyOn(window, 'clearTimeout').mockImplementation(() => {})
     const frames: FrameRequestCallback[] = []
-    const rafSpy = vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation(callback => {
       frames.push(callback)
       return frames.length
     })
-    const cancelSpy = vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
+    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) }
+    const step = (ms: number): void => {
+      for (const callback of frames.splice(0)) callback(now)
+      now += ms
+      for (;;) {
+        const due = timers.filter(t => t.at <= now)
+        if (due.length === 0) break
+        for (const t of due) {
+          const idx = timers.indexOf(t)
+          if (idx >= 0) timers.splice(idx, 1)
+          t.callback()
+        }
+      }
+    }
     act(() => { step(161) })
     expect(ornament()!.style.backgroundPosition).toBe('-24px 0px')
-    const schedulesBefore = rafSpy.mock.calls.length
+    const schedulesBefore = timerSpy.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 = {
@@ -861,10 +1003,10 @@ describe('PetSprite status decoration (pet-center M5, #567)', () => {
       phases: { ...decoration.phases },
     }
     result.rerender(<PetSprite {...petProps({ definition, snapshot: { ...snapshot, bubble: '正在思考', phase: 'thinking', decoration: repolled } })} />)
-    act(() => { step(322) })
+    act(() => { step(161) })
     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)
+    expect(clearSpy).not.toHaveBeenCalled()
+    // One reschedule per frame tick; no effect restart added new timers.
+    expect(timerSpy.mock.calls.length).toBe(schedulesBefore + 1)
   })
 })

package/src/client/PetSprite.tsx

@@ -98,32 +98,38 @@ function StatusOrnament(props: { decoration: DecorationView; phase: ActivityPhas
     // tick would keep rescheduling a no-op rAF forever. Settle on the one
     // frame instead — same as the reduced-motion static hold.
     if (reduceMotion || segment.from === segment.to) return
-    let raf = 0
+    let timer = 0
     let index = segment.from
     let elapsed = 0
     let last = performance.now()
-    const tick = (ts: number): void => {
-      const delta = ts - last
-      last = ts
+    const tick = (): void => {
+      const now = performance.now()
+      const delta = now - last
+      last = now
       elapsed += delta
-      const duration = decoration.durations[index] ?? 160
+      const duration = decoration.durations[index] ?? 120
+      // The segment's frame rate (duration ms, typically 90-160) is far
+      // below the rAF cadence, so a 60fps loop would spend ~90% of its
+      // ticks doing nothing. Schedule by the remaining time to the next
+      // frame instead — the ornament wakes once per frame, not once per
+      // screen refresh. A late wake (background tab, jank) carries extra
+      // elapsed time, so catch up every due frame like the sprite loop.
       if (elapsed >= duration) {
-        elapsed = 0
-        if (index < segment.to) index += 1
-        else if (decoration.loop) index = segment.from
-        // Only advance the background when the frame actually changes:
-        // the segment's frame rate (duration ms, typically 90-160) is far
-        // below the rAF cadence, so writing the same position every frame
-        // would churn style recalculations for no visual change.
+        do {
+          elapsed -= duration
+          if (index < segment.to) index += 1
+          else if (decoration.loop) index = segment.from
+        } while (elapsed >= duration)
+        // Only advance the background when the frame actually changes.
         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)
+      timer = window.setTimeout(tick, Math.max(1, duration - elapsed))
     }
-    raf = requestAnimationFrame(tick)
-    return () => cancelAnimationFrame(raf)
+    timer = window.setTimeout(tick, 0)
+    return () => window.clearTimeout(timer)
   }, [shown, segmentKey, frameWidth, decoration.loop, durationsKey])
   if (!shown) return null
   return (

package/src/client/index.test.tsx

@@ -2,7 +2,11 @@
 /**
  * The global pet entry container opts into the L2 semantic attributes
  * (issue #506): the apply body mounts [data-dsh-pet-root] with
- * data-dsh-plugin="pet" so skins can target the pet subtree.
+ * data-dsh-plugin="pet" so skins can target the pet subtree. The same
+ * tests pin the fiber-lifecycle contract (issue #785): a hot-reloaded or
+ * re-injected bundle instance must never leave the previous React root,
+ * container, or settings subscription behind, so the page always holds
+ * exactly one [data-dsh-pet-root].
  */
 import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 // The npm SDK's client half is a closure-factory bundle for the GUI's
@@ -51,12 +55,24 @@ beforeAll(() => {
   document.documentElement.lang = 'zh'
 })
 
+/** A client root context with observable fiber disposal. */
+interface FakeClientLifecycle {
+  ctx: ClientContext
+  dispose(): void
+  settingsListenerCount(): number
+  emitSettings(): void
+}
+
+const activeLifecycles: FakeClientLifecycle[] = []
+
 afterEach(() => {
+  for (const lifecycle of activeLifecycles.splice(0).reverse()) lifecycle.dispose()
   document.body.replaceChildren()
 })
 
-/** A minimal client root context: ready settings scope, no-op slot system. */
-function fakeContext(): ClientContext {
+function fakeContext(): FakeClientLifecycle {
+  const disposers: (() => void)[] = []
+  const settingsListeners = new Set<() => void>()
   const scope = {
     getSnapshot: () => ({
       status: 'ready',
@@ -67,29 +83,120 @@ function fakeContext(): ClientContext {
       revision: 1,
       mode: 'host',
     }),
-    subscribe: () => () => {},
+    subscribe: (listener: () => void) => {
+      settingsListeners.add(listener)
+      return () => { settingsListeners.delete(listener) }
+    },
   }
-  return {
-    effect: (fn: () => unknown) => {
+  const ctx = {
+    effect: (fn: () => unknown, _label?: string) => {
       const dispose = fn()
-      return typeof dispose === 'function' ? dispose : () => {}
+      if (typeof dispose !== 'function') return () => {}
+      const cleanup = dispose as () => void
+      disposers.push(cleanup)
+      return cleanup
     },
     locale: { register: () => () => {} },
     get: () => undefined,
     settingsScope: { bind: () => scope },
     slots: {
-      inject: (_name: string, callback: () => () => void) => callback(),
+      // Cordis runs the factory when the slot mounts and its returned
+      // disposer when the fiber disposes; mirror that so slot content
+      // (settings card subscription) is cleaned with the fiber.
+      inject: (_name: string, callback: () => () => void) => {
+        const dispose = callback()
+        if (typeof dispose === 'function') disposers.push(dispose)
+        return dispose
+      },
       register: () => () => {},
     },
     sessions: undefined,
   } as unknown as ClientContext
+  let disposed = false
+  const lifecycle: FakeClientLifecycle = {
+    ctx,
+    dispose: () => {
+      if (disposed) return
+      disposed = true
+      for (const dispose of disposers.splice(0).reverse()) dispose()
+    },
+    settingsListenerCount: () => settingsListeners.size,
+    emitSettings: () => {
+      for (const listener of settingsListeners) listener()
+    },
+  }
+  activeLifecycles.push(lifecycle)
+  return lifecycle
 }
 
-describe('pet client apply L2 semantic attributes (#506)', () => {
-  it('mounts the pet root container with data-dsh-plugin="pet"', () => {
-    apply(fakeContext())
+describe('pet client apply', () => {
+  it('mounts the pet root container with the L2 data-dsh-plugin attribute (#506)', () => {
+    apply(fakeContext().ctx)
     const root = document.body.querySelector('[data-dsh-pet-root]')
     expect(root).not.toBeNull()
     expect(root!.getAttribute('data-dsh-plugin')).toBe('pet')
   })
+
+  it('keeps one global pet root when two client factories overlap (#785)', () => {
+    const first = fakeContext()
+    apply(first.ctx)
+    const firstContainer = document.body.querySelector('[data-dsh-pet-root]')
+    expect(firstContainer).not.toBeNull()
+
+    // A rebuilt bundle re-applies while the first fiber is still draining.
+    const second = fakeContext()
+    apply(second.ctx)
+
+    const roots = document.body.querySelectorAll('[data-dsh-pet-root]')
+    expect(roots).toHaveLength(1)
+    expect(roots[0]).not.toBe(firstContainer)
+    expect(firstContainer!.isConnected).toBe(false)
+
+    // The first instance must not resurrect its own root.
+    first.emitSettings()
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(1)
+
+    // The first fiber draining later stays a no-op.
+    first.dispose()
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(1)
+  })
+
+  it('tears down root, container, and settings subscription on fiber disposal (#785)', () => {
+    const lifecycle = fakeContext()
+    apply(lifecycle.ctx)
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(1)
+    // The settings card controller subscribes to the same scope as the UI
+    // sync, so at least the sync listener is present while the fiber lives.
+    expect(lifecycle.settingsListenerCount()).toBeGreaterThan(0)
+
+    lifecycle.dispose()
+
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(0)
+    expect(lifecycle.settingsListenerCount()).toBe(0)
+  })
+
+  it('re-applies cleanly after disposal so a hot reload keeps one pet (#785)', () => {
+    const first = fakeContext()
+    apply(first.ctx)
+    first.dispose()
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(0)
+
+    const second = fakeContext()
+    apply(second.ctx)
+    expect(document.body.querySelectorAll('[data-dsh-pet-root]')).toHaveLength(1)
+  })
+
+  it('sweeps stale containers left behind by instances without a teardown slot (#785)', () => {
+    // A container from a bundle build that predates the teardown registry:
+    // nothing registered a teardown, so only the mount-path sweep can clear it.
+    const stale = document.createElement('div')
+    stale.dataset.dshPetRoot = ''
+    document.body.appendChild(stale)
+
+    apply(fakeContext().ctx)
+
+    const roots = document.body.querySelectorAll('[data-dsh-pet-root]')
+    expect(roots).toHaveLength(1)
+    expect(stale.isConnected).toBe(false)
+  })
 })

package/src/client/index.ts

@@ -28,6 +28,7 @@ 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 { registerPetUiTeardown, takeoverPetUiTeardown } from './ui-teardown.ts'
 import { PetSettingsSection, PetSettingsCardController, type PetSettings } from './PetSettingsCard.tsx'
 import { NS, en, zh, t } from './locales.ts'
 
@@ -139,9 +140,22 @@ export function apply(ctx: ClientContext): void {
 
   // The global pet entry, its store, and the poll loop live while the plugin
   // is enabled; toggling the setting off hides the pet and stops polling.
+  // 'uiDead' marks a terminal teardown (takeover by a later bundle instance
+  // or fiber disposal): a taken-over or disposed instance must never remount
+  // from a late settings callback (issue #785).
   let disposeUi: (() => void) | undefined
+  let clearUiTeardown: (() => void) | undefined
+  let uiDead = false
+  const killUi = (): void => {
+    if (uiDead) return
+    uiDead = true
+    clearUiTeardown?.()
+    clearUiTeardown = undefined
+    disposeUi?.()
+    disposeUi = undefined
+  }
   const syncUi = (): void => {
-    if (enabled() && disposeUi === undefined) {
+    if (!uiDead && enabled() && disposeUi === undefined) {
       // ONE store instance for the whole app, owned by this apply body. The
       // pet is host-global (state/display/interactions are /api/pet/*
       // endpoints with no session dimension), so the slot system's per-session
@@ -296,6 +310,17 @@ export function apply(ctx: ClientContext): void {
       // The entry therefore mounts straight onto document.body via a single
       // React root for the page lifetime: PetSprite portals itself to body
       // when visible, and the hidden-state summon button is fixed-positioned.
+      //
+      // Cross-instance single-mount guard (issue #785): take over the
+      // page-global slot first — the previous bundle instance's fiber may
+      // still be draining during a client reload, so unmount its React root
+      // and remove its container — then sweep containers left behind by
+      // instances that predate the teardown registry, so this mount is the
+      // page's only [data-dsh-pet-root].
+      takeoverPetUiTeardown()
+      for (const stale of Array.from(document.querySelectorAll('div[data-dsh-pet-root]'))) {
+        stale.remove()
+      }
       const container = document.createElement('div')
       container.dataset.dshPetRoot = ''
       container.dataset.dshPlugin = 'pet'
@@ -303,17 +328,40 @@ export function apply(ctx: ClientContext): void {
       const petRoot = createRoot(container)
       petRoot.render(createElement(PetDockEntry, { ...injected(), t }))
 
+      let uiGone = false
       disposeUi = () => {
+        if (uiGone) return
+        uiGone = true
+        clearUiTeardown?.()
+        clearUiTeardown = undefined
         petRoot.unmount()
         container.remove()
         disposePoll()
         disposeUi = undefined
       }
-    } else if (!enabled() && disposeUi !== undefined) {
+      // The slot teardown is the takeover hook a later apply body runs; it
+      // marks this instance terminal so a late settings callback from the
+      // still-draining instance cannot remount a second pet.
+      clearUiTeardown = registerPetUiTeardown(() => {
+        uiDead = true
+        disposeUi?.()
+      })
+    } else if (!uiDead && !enabled() && disposeUi !== undefined) {
       disposeUi()
       disposeUi = undefined
     }
   }
-  settingsScope.subscribe(syncUi)
+  // The settings subscription and the pet UI lifetime follow the fiber
+  // (issue #785): disposal drops the subscription and tears the UI down
+  // (terminal), so a hot-reloaded or re-injected bundle never leaves the
+  // previous React root, container, or poll loop behind on document.body.
+  const unsubscribeSettings = settingsScope.subscribe(syncUi)
+  ctx.effect(
+    () => () => {
+      unsubscribeSettings()
+      killUi()
+    },
+    'pet: client lifecycle',
+  )
   syncUi()
 }

package/src/client/ui-teardown.ts

@@ -0,0 +1,47 @@
+/**
+ * Cross-bundle-instance teardown slot for the page-global pet root
+ * (issue #785).
+ *
+ * A client bundle swap (HMR rebuilt frame, plugin update, duplicate
+ * injection) runs a new apply body while the previous instance's fiber
+ * may still be draining. Module state does not survive the swap, so a
+ * closure guard only sees one apply body and the previous instance's
+ * container keeps sitting on document.body: the page shows two pets
+ * until a full refresh. The slot rides globalThis (which does survive)
+ * so a re-apply can find the previous instance and unmount its React
+ * root cleanly before mounting its own; the previous fiber's later
+ * disposal stays a no-op through the idempotent teardowns.
+ */
+
+const SLOT = Symbol.for('dsh-pet.client-ui-teardown')
+
+interface TeardownSlot {
+  [SLOT]?: (() => void) | undefined
+}
+
+/**
+ * Claim the page-global pet UI slot with the current instance's teardown
+ * (React root unmount + container removal + poll stop).
+ * @param teardown - what a later instance runs to take the slot over.
+ * @returns a disposer that clears the slot when the current instance's
+ * UI is torn down (settings toggle, takeover, or fiber disposal).
+ */
+export function registerPetUiTeardown(teardown: () => void): () => void {
+  const slot = globalThis as TeardownSlot
+  slot[SLOT] = teardown
+  return () => {
+    if (slot[SLOT] === teardown) slot[SLOT] = undefined
+  }
+}
+
+/**
+ * Run the previous instance's teardown if one is registered, so the
+ * re-applying instance becomes the sole owner of the page-global pet
+ * root. No-op when the previous fiber already tore down cleanly.
+ */
+export function takeoverPetUiTeardown(): void {
+  const slot = globalThis as TeardownSlot
+  const teardown = slot[SLOT]
+  slot[SLOT] = undefined
+  teardown?.()
+}