@linxin666/dsh-pet 0.2.6 → 0.2.8

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?.()
+}

package/src/registry.test.ts

@@ -5,6 +5,8 @@ import { join } from 'node:path'
 import {
   DEFAULT_FRAME_COUNTS,
   DEFAULT_PET_CELL,
+  DEFAULT_TRACK_PATTERNS,
+  PET_ROW_ORDER,
   PET_SCAN_JSON_CAP,
   codexPetsDir,
   loadPetRegistry,
@@ -168,6 +170,18 @@ describe('loadPetRegistry', () => {
       readFileSync(petAtlasFile(registry.byId('whale-girl-refined')!)),
     )).toBe(false)
     expect(registry.defaultEntry().id).toBe('whale-girl')
+    // Both built-in whales and every override-free pet share the one slow
+    // global rhythm (user request: all pets were too fast at the legacy
+    // hatch-pet contract pace).
+    for (const track of PET_ROW_ORDER) {
+      expect(registry.byId('whale-girl')!.tracks[track].durations)
+        .toEqual(DEFAULT_TRACK_PATTERNS[track].durations)
+      expect(registry.byId('whale-girl-refined')!.tracks[track].durations)
+        .toEqual(DEFAULT_TRACK_PATTERNS[track].durations)
+    }
+    expect(DEFAULT_TRACK_PATTERNS.idle.durations[0]!).toBeGreaterThanOrEqual(500)
+    expect(DEFAULT_TRACK_PATTERNS['running-right'].durations[0]!).toBeGreaterThanOrEqual(300)
+    expect(DEFAULT_TRACK_PATTERNS.waving.durations[0]!).toBeGreaterThanOrEqual(450)
   })
 
   it('scans built-in assets, the custom pets dir, and composed extras with precedence', () => {

package/src/registry.ts

@@ -114,21 +114,25 @@ export interface PetTrackDef {
   fallback?: PetAnimation
 }
 
-/** Default per-track rhythm (hatch-pet contract table). */
+/**
+ * Default per-track rhythm — the shared slow baseline every sprite2d pet
+ * plays unless its manifest overrides a track (user request: all pets were
+ * too fast at the legacy hatch-pet contract pace).
+ */
 export const DEFAULT_TRACK_PATTERNS: Record<PetAnimation, {
   durations: number[]
   loop: boolean
   fallback?: PetAnimation
 }> = {
-  idle: { durations: [280, 110, 110, 140, 140, 320], loop: true },
-  'running-right': { durations: [120, 120, 120, 120, 120, 120, 120, 220], loop: true },
-  'running-left': { durations: [120, 120, 120, 120, 120, 120, 120, 220], loop: true },
-  waving: { durations: [140, 140, 140, 280], loop: true },
-  jumping: { durations: [140, 140, 140, 140, 280], loop: false, fallback: 'idle' },
-  failed: { durations: [140, 140, 140, 140, 140, 140, 140, 240], loop: false, fallback: 'idle' },
-  waiting: { durations: [150, 150, 150, 150, 150, 260], loop: true },
-  running: { durations: [120, 120, 120, 120, 120, 220], loop: true },
-  review: { durations: [150, 150, 150, 150, 150, 280], loop: true },
+  idle: { durations: [500, 500, 600, 500, 500, 600], loop: true },
+  'running-right': { durations: [300, 300, 300, 300, 300, 300, 300, 400], loop: true },
+  'running-left': { durations: [300, 300, 300, 300, 300, 300, 300, 400], loop: true },
+  waving: { durations: [450, 450, 450, 450], loop: true },
+  jumping: { durations: [400, 400, 400, 450, 450], loop: false, fallback: 'idle' },
+  failed: { durations: [550, 550, 550, 600, 650, 700, 550, 550], loop: false, fallback: 'idle' },
+  waiting: { durations: [550, 550, 600, 550, 550, 600], loop: true },
+  running: { durations: [330, 330, 330, 330, 330, 400], loop: true },
+  review: { durations: [650, 650, 650, 650, 650, 650], loop: true },
 }
 
 /** Manifest shape a pet directory (or 'PetConfig.pets' entry) declares. */