@linxin666/dsh-pet 0.3.20 → 0.3.21

package/src/client/gameplay-hud.tsx

@@ -25,6 +25,11 @@ export interface GameplayApi {
   setMode: (mode: 'work' | 'sleep' | null) => Promise<PetGameplayVerbResult>
   workTick: () => Promise<PetGameplayVerbResult>
   buy: (item: string) => Promise<PetGameplayVerbResult>
+  /**
+   * Persist the selected skin for the current pet (host-authoritative;
+   * `undefined` restores the pet's default look).
+   */
+  setSkin: (skin: string | undefined) => Promise<{ ok: boolean; error?: string }>
 }
 
 /**
@@ -37,6 +42,13 @@ export interface GameplayBus {
   setTrack?: (track?: string) => void
   /** Swap the pet's base idle track (skin switch); undefined restores default. */
   setIdleTrack?: (track?: string) => void
+  /**
+   * The base idle track the HUD wants right now, latched on the bus so a
+   * renderer that registers late (or remounts: hidden/summoned, StrictMode's
+   * double mount) still applies the restored skin instead of snapping back to
+   * the default look. Mutating it never requires a re-render.
+   */
+  idleTrack?: string
   tap?: (fx: number, fy: number) => void
   /**
    * Card open/close request from the chrome (the hover panel's 玩法 action):
@@ -70,6 +82,8 @@ export function GameplayHud(props: {
   const def = definition.gameplay
   const view = ui.snapshot?.gameplay
   const phase = ui.snapshot?.phase ?? 'idle'
+  // Host-persisted skin selection for this pet (undefined = default look).
+  const persistedSkin = ui.snapshot?.skin
 
   const [open, setOpen] = useState(false)
   const [page, setPage] = useState<HudPage>('root')
@@ -284,24 +298,32 @@ export function GameplayHud(props: {
 
   // Work loop: hold the work track, adjudicate one round per tick, play the
   // result track for its hold window, then resume. Leaving the mode
-  // releases the override so the phase mapping takes over.
+  // releases the override so the phase mapping takes over. A skin that
+  // declares gameplayTracks for the work states plays its own art instead.
   useEffect(() => {
     const work = def?.work
     if (def === undefined || work === undefined || view?.mode !== 'work') return undefined
-    bus.setTrack?.(work.state)
+    const skinGameplay = definition.frames2d?.skins?.find(skin => skin.id === skinIdRef.current)?.gameplayTracks
+    /** The state's track, swapped for the skin's override when it declares one. */
+    const trackOf = (state: string): string => skinGameplay?.[state] ?? state
+    bus.setTrack?.(trackOf(work.state))
     let resultTimer = 0
     const timer = window.setInterval(() => {
       if (busyRef.current) return
       busyRef.current = true
       void api.workTick().then((result) => {
         busyRef.current = false
+        // Leaving work mode while the adjudication is in flight drops the late
+        // result: writing it back would show work rewards and play the result
+        // track for a mode the user has already left (#1495).
+        if (modeRef.current !== 'work') return
         applyResult(result)
         if (result.ok !== true || result.outcome === undefined) return
-        const resultTrack = result.outcome === 'success' ? work.successState : work.failState
+        const resultTrack = trackOf(result.outcome === 'success' ? work.successState : work.failState)
         const hold = result.outcome === 'success' ? work.resultMs?.success ?? 1300 : work.resultMs?.fail ?? 1900
         bus.setTrack?.(resultTrack)
         resultTimer = window.setTimeout(() => {
-          if (modeRef.current === 'work') bus.setTrack?.(work.state)
+          if (modeRef.current === 'work') bus.setTrack?.(trackOf(work.state))
         }, hold)
       }, () => { busyRef.current = false })
     }, work.tickMs)
@@ -310,8 +332,8 @@ export function GameplayHud(props: {
       window.clearTimeout(resultTimer)
       bus.setTrack?.(undefined)
     }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- the loop keys on the mode value
-  }, [definition.id, def, view?.mode])
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- the loop keys on the mode and the selected skin
+  }, [definition.id, def, view?.mode, skinId])
 
   // Sleep loop: hold the sleep track; restore is host-side (lazy settle).
   // While a skin with a gameplayTracks.sleep override is selected, the skin's
@@ -352,10 +374,44 @@ export function GameplayHud(props: {
     void api.setMode(next).then(applyResult, () => undefined)
   }
 
+  // Skin selection is persisted host-side (per pet): re-seed the menu from
+  // every fresh state view, so a page reload or client restart keeps the last
+  // choice instead of snapping back to the default look.
+  useEffect(() => {
+    setSkinId(persistedSkin)
+  }, [definition.id, persistedSkin])
+
+  // Push the resolved base idle track into the renderer whenever the pet or
+  // the selection changes. The value is latched on the bus first: the visual
+  // may register later, or remount later (hidden/summoned), and reads the
+  // latch back on activation so a restored skin never falls back to default.
+  useEffect(() => {
+    const skin = definition.frames2d?.skins?.find(candidate => candidate.id === skinId)
+    bus.idleTrack = skin?.idleTrack
+    bus.setIdleTrack?.(skin?.idleTrack)
+    // persistedSkin rides the deps so the host's value also re-pushes on
+    // arrival (a renderer that mounted early still converges).
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- one push per selection
+  }, [definition.id, skinId, persistedSkin])
+
   const skins = definition.frames2d?.skins
+  /** The base idle track one skin id resolves to (undefined = default look). */
+  const skinTrackOf = (id: string | undefined): string | undefined =>
+    id === undefined ? undefined : definition.frames2d?.skins?.find(candidate => candidate.id === id)?.idleTrack
+
   const selectSkin = (skin: PetSkinDefinition | undefined): void => {
     setSkinId(skin?.id)
     bus.setIdleTrack?.(skin?.idleTrack)
+    // The host owns the choice: a refusal (unknown skin) restores both the
+    // menu highlight and the renderer to the value it still serves.
+    const restore = (): void => {
+      setSkinId(persistedSkin)
+      bus.setIdleTrack?.(skinTrackOf(persistedSkin))
+    }
+    void api.setSkin(skin?.id).then((result) => {
+      if (result.ok) return
+      restore()
+    }, restore)
   }
 
   return (

package/src/client/index.ts

@@ -32,6 +32,7 @@ import type { PetDefinition } from '../registry.ts'
 import { createElement } from 'react'
 import { createRoot } from 'react-dom/client'
 import { createPetStore, type PetStoreInstance } from './pet-store.ts'
+import { createWorkTickGate } from './work-tick-gate.ts'
 import { PetDockEntry, type PetInjected } from './PetDockEntry.tsx'
 import { defaultPetRendererRegistry } from './renderers/registry.ts'
 import { live2dRenderer } from './renderers/live2d.ts'
@@ -51,6 +52,7 @@ interface PetHttpApi {
   setConfig(patch: Partial<PetDisplayConfig>): Promise<{ ok: true; display: PetDisplayConfig }>
   setName(name: string): Promise<{ ok: true; name: string } | { ok: false; error: string }>
   setPet(petId: string): Promise<{ ok: true; petId: string } | { ok: false; error: string }>
+  setSkin(skin?: string): Promise<{ ok: boolean; error?: string; skin?: string }>
   gameplayTouch(zone?: string): Promise<PetGameplayVerbResult>
   gameplaySetMode(mode: 'work' | 'sleep' | null): Promise<PetGameplayVerbResult>
   gameplayWorkTick(): Promise<PetGameplayVerbResult>
@@ -82,6 +84,7 @@ const petApi: PetHttpApi = {
   setConfig: (patch) => petFetch('/api/pet/set-config', patch),
   setName: (name) => petFetch('/api/pet/set-name', { name }),
   setPet: (petId) => petFetch('/api/pet/set-pet', { petId }),
+  setSkin: (skin) => petFetch('/api/pet/set-skin', skin === undefined ? {} : { skin }),
   gameplayTouch: (zone) => petFetch('/api/pet/gameplay/touch', zone === undefined ? {} : { zone }),
   gameplaySetMode: (mode) => petFetch('/api/pet/gameplay/mode', { mode }),
   gameplayWorkTick: () => petFetch('/api/pet/gameplay/work-tick', {}),
@@ -123,16 +126,19 @@ declare module '@deepseek-ai/cordis' {
  * @param ctx - client root context.
  */
 
+/** The page-wide work-tick gate; its window follows the active pet's cadence. */
+const workTickGate = createWorkTickGate()
+
 /**
- * Module-wide work-tick throttle (ms). Hot reloads can leave several
- * GameplayHud instances alive, each running its own 10s work interval;
- * without a shared gate every interval would call workTick and each stale
- * call re-rolls, re-grants treats and re-plays the success/fail track, so
- * the outcome appears to play several times per window. This shared marker
- * accepts the first adjudication of a window and silently suppresses the
- * duplicates that follow. Reset when (re-)entering work mode.
+ * The work cadence the active pet declares, when its registry entry is known.
+ * @param store - the pet store holding the host snapshot and the registry list.
+ * @returns the configured `gameplay.work.tickMs`, or undefined when unknown.
  */
-let lastWorkTickAt = 0
+function activeWorkTickMs(store: PetStoreInstance): number | undefined {
+  const state = store.getSnapshot()
+  const definition = state.pets.find((entry) => entry.id === state.snapshot?.pet.id)
+  return definition?.gameplay?.work?.tickMs
+}
 
 export function apply(ctx: ClientContext): void {
   // Anonymous install heartbeat (docs/telemetry.md): one beat per browser per
@@ -371,18 +377,22 @@ export function apply(ctx: ClientContext): void {
         },
         gameplay: {
           touch: (zone) => petApi.gameplayTouch(zone),
+          setSkin: (skin) => petApi.setSkin(skin).then((result) => {
+            if (result.ok) pollNow()
+            return result
+          }, () => ({ ok: false, error: 'transport' })),
+          
           setMode: async (mode) => {
-            if (mode === 'work') lastWorkTickAt = 0
+            if (mode === 'work') workTickGate.reset()
             return petApi.gameplaySetMode(mode)
           },
           workTick: async () => {
             // One adjudication per tick window, page-wide: suppress stale
-            // duplicate intervals (HMR) re-playing the result track.
-            const now = Date.now()
-            if (now - lastWorkTickAt < 8500) {
+            // duplicate intervals (HMR) re-playing the result track. The window
+            // is the pet's own cadence, so a shorter tickMs is not downgraded.
+            if (!workTickGate.allow(activeWorkTickMs(petStore))) {
               return { ok: true } as PetGameplayVerbResult
             }
-            lastWorkTickAt = now
             return petApi.gameplayWorkTick()
           },
           buy: (item) => petApi.gameplayBuy(item),

package/src/client/pet.module.css

@@ -46,7 +46,7 @@
   background: rgba(3, 105, 161, 0.95);
 }
 
-/* 状态气泡：皮肤底色玻璃 + 皮肤描边微光 + 进场浮现。
+/* 状态气泡：虎鲸蓝黑渐变玻璃 + DeepSeek 蓝描边微光 + 进场浮现。
    碎碎念不再单独渲染第二只气泡，也不换色调，而是以 .bubbleWhisper
    接管这同一只气泡的文案，气泡栈内所有气泡共用同一片玻璃。 */
 .bubbleStatus {

package/src/client/renderers/Frames2dVisualMount.test.tsx

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+/**
+ * Frames2dVisualMount registration contract: the mount consumes the base idle
+ * the gameplay HUD latches on the bus. That covers a renderer which mounts
+ * after the HUD restored a skin from the host snapshot, and one that remounts
+ * later (hidden/summoned, StrictMode double mount) — the pet must repaint the
+ * selected skin instead of snapping back to the default look.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import type { PetDefinition } from '../../registry.ts'
+import { createDragStream } from '../drag-stream.ts'
+import type { GameplayBus } from '../gameplay-hud.tsx'
+import { t } from '../locales.ts'
+import { Frames2dVisualMount } from './Frames2dVisualMount.tsx'
+import { defaultPetRendererRegistry } from './registry.ts'
+
+function definition(): PetDefinition {
+  return {
+    id: 'miku',
+    displayName: 'Miku',
+    description: '',
+    renderer: 'frames2d',
+    cell: { width: 100, height: 100 },
+    columns: 8,
+    rows: [],
+    atlasUrl: '/pet/miku/atlas.webp',
+    manifestUrl: '/pet/miku/pet.json',
+    tracks: {} as PetDefinition['tracks'],
+    frames2d: {
+      tracks: {
+        idle: { frames: ['/pet/miku/idle_1.webp'], durations: [200], loop: true },
+        skin: { frames: ['/pet/miku/skin_1.webp'], durations: [200], loop: true },
+      },
+      phases: { idle: 'idle' },
+      skins: [{ id: 'skin', label: 'Skin', idleTrack: 'skin' }],
+    },
+  } as unknown as PetDefinition
+}
+
+function mountWith(bus: GameplayBus): { setIdleTrack: ReturnType<typeof vi.fn> } {
+  const handle = { dispose: vi.fn(), setState: vi.fn(), setIdleTrack: vi.fn(), currentTrack: () => 'idle' }
+  vi.spyOn(defaultPetRendererRegistry, 'mount')
+    .mockReturnValue(handle as unknown as ReturnType<typeof defaultPetRendererRegistry.mount>)
+  render(
+    <Frames2dVisualMount
+      definition={definition()}
+      phase="idle"
+      onPet={() => undefined}
+      drag={createDragStream()}
+      bus={bus}
+      t={t}
+    />,
+  )
+  return handle
+}
+
+describe('Frames2dVisualMount', () => {
+  afterEach(() => {
+    cleanup()
+    vi.restoreAllMocks()
+  })
+
+  it('applies the base idle the HUD latched before this mount (restored skin)', () => {
+    const handle = mountWith({ idleTrack: 'skin' })
+    expect(handle.setIdleTrack).toHaveBeenCalledWith('skin')
+  })
+
+  it('leaves the default look alone when no base idle is latched', () => {
+    const handle = mountWith({})
+    expect(handle.setIdleTrack).not.toHaveBeenCalled()
+  })
+})

package/src/client/renderers/Frames2dVisualMount.tsx

@@ -68,6 +68,10 @@ export function Frames2dVisualMount(props: {
       const gameplayBus = props.bus
       gameplayBus.setTrack = (track) => { handleRef.current?.setState(track) }
       gameplayBus.setIdleTrack = (track) => { handleRef.current?.setIdleTrack(track) }
+      // The HUD latches the wanted base idle (skin selection, restored from the
+      // host snapshot): apply it on activation, so a late or repeated mount
+      // never repaints the pet with the default look.
+      if (gameplayBus.idleTrack !== undefined) handle.setIdleTrack(gameplayBus.idleTrack)
       cleanups.push(() => {
         gameplayBus.setTrack = undefined
         gameplayBus.setIdleTrack = undefined

package/src/client/renderers/frames2d.test.ts

@@ -234,9 +234,9 @@ describe('frames2dRenderer canvas bitmap path', () => {
     expect(container.querySelector('canvas')).not.toBeNull()
     expect(container.querySelector('img')).toBeNull()
     await flush()
-    // Warm pass decoded every configured frame exactly once; the first frame
-    // of the idle track painted during mount.
-    expect(bitmaps.length).toBe(6)
+    // Only the playing track's look-ahead window decodes up front; unplayed
+    // tracks stay on demand. The idle track's first frame painted at mount.
+    expect(bitmaps.length).toBe(2)
     const paintsAtMount = draws
     expect(paintsAtMount).toBeGreaterThanOrEqual(1)
     vi.advanceTimersByTime(100)
@@ -277,7 +277,7 @@ describe('frames2dRenderer canvas bitmap path', () => {
     handle.dispose()
   })
 
-  it('drains the warm pass through a bounded fetch pool', async () => {
+  it('bounds the decode window to the pool plus the look-ahead, not the whole track', async () => {
     let inFlight = 0
     let peak = 0
     const gates: Array<() => void> = []
@@ -304,7 +304,39 @@ describe('frames2dRenderer canvas bitmap path', () => {
       await flush()
     }
     expect(peak).toBeLessThanOrEqual(8)
-    expect(bitmaps.length).toBe(24)
+    // Frame 0 plus the 12-frame look-ahead window; the remaining frames of the
+    // 24-frame track are never decoded up front.
+    expect(bitmaps.length).toBe(13)
+    handle.dispose()
+  })
+
+  it('leaves unplayed tracks and unselected skins to on-demand playback', async () => {
+    const fetched: string[] = []
+    vi.stubGlobal('fetch', vi.fn(async (input: unknown) => {
+      fetched.push(String(input))
+      return { ok: true, blob: async () => ({}) }
+    }))
+    const skinConfig: PetFrames2dConfig = {
+      tracks: {
+        idle: { frames: ['/pet/miku/idle/1.webp'], durations: [100], loop: true },
+        'skin-a-idle': { frames: ['/pet/miku/skin-a/1.webp', '/pet/miku/skin-a/2.webp'], durations: [100, 100], loop: true },
+        'skin-b-idle': { frames: ['/pet/miku/skin-b/1.webp'], durations: [100], loop: true },
+      },
+      phases: { idle: 'idle' },
+      skins: [
+        { id: 'a', label: 'A', idleTrack: 'skin-a-idle' },
+        { id: 'b', label: 'B', idleTrack: 'skin-b-idle' },
+      ],
+    }
+    const { ctx } = canvasSetup()
+    const handle = frames2dRenderer.mount(ctx, frames2dRenderer.validateConfig(skinConfig)) as Frames2dRendererHandle
+    await flush()
+    expect(fetched).toEqual(['/pet/miku/idle/1.webp'])
+    // Selecting a skin pulls only that skin's track.
+    handle.setIdleTrack('skin-a-idle')
+    await flush()
+    expect(fetched).toContain('/pet/miku/skin-a/1.webp')
+    expect(fetched).not.toContain('/pet/miku/skin-b/1.webp')
     handle.dispose()
   })
 
@@ -361,7 +393,7 @@ describe('frames2dRenderer canvas bitmap path', () => {
     vi.stubGlobal('Image', FailingImage)
     const { ctx } = canvasSetup()
     const handle = frames2dRenderer.mount(ctx, frames2dRenderer.validateConfig(CONFIG)) as Frames2dRendererHandle
-    // Warm pass fetches fail through the pool, resolve undefined and are
+    // Prefetch fetches fail through the pool, resolve undefined and are
     // dropped from the memo; nothing throws.
     await flush()
     const memoFetches = (fetch as ReturnType<typeof vi.fn>).mock.calls.length

package/src/client/renderers/frames2d.ts

@@ -12,10 +12,11 @@
  * Frame presentation has two modes picked once at mount by capability
  * probing:
  * - Canvas bitmap buffer (default where createImageBitmap/fetch/2D context
- *   exist): every frame is decoded exactly once into an ImageBitmap during
- *   the warm pass and drawn onto one <canvas> - steady-state playback issues
- *   zero DOM mutations and zero re-decodes (measured hotspot: swapping
- *   <img>.src per frame drove image decode + invalidation every tick).
+ *   exist): frames are decoded once into an ImageBitmap on demand, with a
+ *   bounded look-ahead window over the playing track, and drawn onto one
+ *   <canvas> - steady-state playback issues zero DOM mutations and zero
+ *   re-decodes (measured hotspot: swapping <img>.src per frame drove image
+ *   decode + invalidation every tick).
  * - Classic <img> fallback (jsdom/tests or missing APIs): identical to the
  *   historical behavior - cache-warm Image elements plus guarded src swaps,
  *   so environments without modern decoding keep working unchanged.
@@ -283,6 +284,27 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
       return job
     }
 
+    /**
+     * Bounded look-ahead window: decode only the frames playback is about to
+     * need. The historical warm pass decoded every frame of every track up
+     * front - a shipped pet carries ~1.1k 512x683 frames, so that pass pulls
+     * tens of megabytes and retains every decoded bitmap for the life of the
+     * page. Prefetching the playing track's next frames keeps loops and phase
+     * switches warm while unplayed tracks (and every unselected skin's
+     * frames) stay on demand, where playback jumps the queue anyway.
+     */
+    const PREFETCH_AHEAD = 12
+
+    const prefetchAhead = (trackId: string, index: number): void => {
+      const def = config.tracks[trackId]
+      if (def === undefined) return
+      const end = Math.min(def.frames.length, index + 1 + PREFETCH_AHEAD)
+      for (let ahead = index + 1; ahead < end; ahead += 1) {
+        const url = def.frames[ahead]
+        if (url !== undefined) void loadFrame(url)
+      }
+    }
+
     let disposed = false
     let timer: ReturnType<typeof setTimeout> | undefined
     let watchdog: ReturnType<typeof setInterval> | undefined
@@ -327,6 +349,7 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
       const def = config.tracks[trackId]
       const url = def?.frames[index]
       if (url === undefined) return
+      prefetchAhead(trackId, index)
       if (img !== null) {
         if (img.getAttribute('src') !== url) img.src = url
         return
@@ -400,21 +423,6 @@ export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
       }, WATCHDOG_MS)
     }
 
-    // Warm pass: decode every frame up front (tiny same-origin webp files)
-    // so loops and phase switches never wait on a first decode - same intent
-    // as the historical Image-cache warm loop, now feeding the decode cache.
-    // Phase-reachable tracks enqueue first so early switches never trail the
-    // full warm backlog; demand loads jump the queue regardless.
-    const warmTrackIds: string[] = [
-      ...new Set([...Object.values(config.phases), config.phases.idle]),
-    ]
-    for (const warmTrack of [...warmTrackIds, ...Object.keys(config.tracks)].map(
-      (id) => config.tracks[id],
-    )) {
-      if (warmTrack === undefined) continue
-      for (const warmUrl of warmTrack.frames) void loadFrame(warmUrl)
-    }
-
     play(track)
 
     let disposedOnce = false

package/src/client/work-tick-gate.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Work-tick gate tests: the window follows the configured cadence (clamped to
+ * the manifest bounds), one adjudication is admitted per window, and entering
+ * work mode re-arms the gate.
+ */
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_WORK_TICK_MS, createWorkTickGate, workTickWindowMs } from './work-tick-gate.ts'
+
+describe('workTickWindowMs', () => {
+  it('follows the configured cadence', () => {
+    expect(workTickWindowMs(2_000)).toBe(2_000)
+    expect(workTickWindowMs(10_000)).toBe(10_000)
+    expect(workTickWindowMs(60_000)).toBe(60_000)
+  })
+
+  it('clamps to the manifest bounds and defaults when absent', () => {
+    expect(workTickWindowMs(500)).toBe(1_000)
+    expect(workTickWindowMs(120_000)).toBe(60_000)
+    expect(workTickWindowMs(undefined)).toBe(DEFAULT_WORK_TICK_MS)
+    expect(workTickWindowMs(Number.NaN)).toBe(DEFAULT_WORK_TICK_MS)
+  })
+})
+
+describe('createWorkTickGate', () => {
+  it('admits one adjudication per configured window', () => {
+    let now = 1_000_000
+    const gate = createWorkTickGate(() => now)
+    expect(gate.allow(2_000)).toBe(true)
+    now += 1_999
+    expect(gate.allow(2_000)).toBe(false)
+    now += 1
+    expect(gate.allow(2_000)).toBe(true)
+  })
+
+  it('does not downgrade a pet whose cadence is shorter than the default', () => {
+    let now = 1_000_000
+    const gate = createWorkTickGate(() => now)
+    expect(gate.allow(2_000)).toBe(true)
+    for (let tick = 0; tick < 5; tick++) {
+      now += 2_000
+      expect(gate.allow(2_000)).toBe(true)
+    }
+  })
+
+  it('arms immediately after a reset (work mode entry)', () => {
+    let now = 1_000_000
+    const gate = createWorkTickGate(() => now)
+    expect(gate.allow(10_000)).toBe(true)
+    expect(gate.allow(10_000)).toBe(false)
+    gate.reset()
+    expect(gate.allow(10_000)).toBe(true)
+  })
+})

package/src/client/work-tick-gate.ts

@@ -0,0 +1,63 @@
+/**
+ * Page-wide work-tick gate for the pet's work mode. Hot reloads can leave
+ * several GameplayHud instances alive, each running its own work interval;
+ * without a shared gate every interval would call workTick and each stale call
+ * re-rolls, re-grants treats and re-plays the success/fail track, so the
+ * outcome appears to play several times per window. The gate accepts the first
+ * adjudication of a window and silently suppresses the duplicates that follow.
+ *
+ * The window is the active pet's own `gameplay.work.tickMs`, not a constant: a
+ * pet configured with a shorter cadence must actually adjudicate that often,
+ * while a fixed window would downgrade it without saying so (#1494).
+ * @module @linxin666/dsh-pet/client/work-tick-gate
+ */
+
+/** Window used when the active pet declares no work cadence. */
+export const DEFAULT_WORK_TICK_MS = 10_000
+
+/** Manifest bounds for `gameplay.work.tickMs` (src/gameplay.ts). */
+const MIN_WORK_TICK_MS = 1_000
+const MAX_WORK_TICK_MS = 60_000
+
+/**
+ * The gate window for one pet: its configured cadence, clamped to the manifest's
+ * own bounds so a malformed registry entry cannot disable or flood the gate.
+ * @param tickMs - the active definition's `gameplay.work.tickMs`, when it has one.
+ * @returns the window in milliseconds.
+ */
+export function workTickWindowMs(tickMs: number | undefined): number {
+  if (typeof tickMs !== 'number' || !Number.isFinite(tickMs)) return DEFAULT_WORK_TICK_MS
+  return Math.min(MAX_WORK_TICK_MS, Math.max(MIN_WORK_TICK_MS, tickMs))
+}
+
+/** The shared work-tick gate. */
+export interface WorkTickGate {
+  /**
+   * Admit one adjudication for the current window.
+   * @param tickMs - the active pet's configured work cadence.
+   * @returns true when this call may adjudicate, false for a duplicate.
+   */
+  allow: (tickMs: number | undefined) => boolean
+  /** Forget the last adjudication (used when work mode is entered). */
+  reset: () => void
+}
+
+/**
+ * Create a gate.
+ * @param now - the clock, injectable so tests control the window.
+ * @returns the gate over that clock.
+ */
+export function createWorkTickGate(now: () => number = Date.now): WorkTickGate {
+  let lastAdjudicatedAt = 0
+  return {
+    allow: (tickMs) => {
+      const at = now()
+      if (at - lastAdjudicatedAt < workTickWindowMs(tickMs)) return false
+      lastAdjudicatedAt = at
+      return true
+    },
+    reset: () => {
+      lastAdjudicatedAt = 0
+    },
+  }
+}

package/src/gameplay.test.ts

@@ -185,6 +185,42 @@ describe('gameplay engine', () => {
     expect(state.settledAt).toBe(600_000)
   })
 
+  it('preserves remainder carry across frequent polling intervals for passive income and sleep restore (#1478)', () => {
+    const state = initialGameplayState(def, 0)
+    state.stats.energy = 20
+    state.mode = 'sleep'
+    // Simulate 30 frequent settles every 2,000 ms (total 60,000 ms = 1 min).
+    // Passive income interval: 60,000 ms -> should grant 1 coin on 30th settle.
+    // Sleep restore interval: 30,000 ms (+4 energy each) -> should grant on 15th and 30th settle.
+    let now = 0
+    for (let i = 1; i <= 30; i++) {
+      now += 2_000
+      settleGameplay(state, def, now, { sessionActive: true })
+      if (i < 15) {
+        expect(state.stats.energy).toBeCloseTo(20 - (i * 2 / 60) * 0.25, 4)
+        expect(state.currencies.coins ?? 0).toBe(0)
+      } else if (i === 15) {
+        // At 30,000 ms: first sleep tick hits (+4 energy)
+        expect(state.stats.energy).toBeCloseTo(20 - 0.125 + 4, 4)
+        expect(state.currencies.coins ?? 0).toBe(0)
+      } else if (i < 30) {
+        expect(state.stats.energy).toBeCloseTo(20 - (i * 2 / 60) * 0.25 + 4, 4)
+        expect(state.currencies.coins ?? 0).toBe(0)
+      }
+    }
+    // At 60,000 ms (30th tick): second sleep tick hits (+4 energy = +8 total), passive income hits (+1 coin)
+    expect(state.stats.energy).toBeCloseTo(20 - 0.25 + 8, 4)
+    expect(state.currencies.coins).toBe(1)
+    expect(state.incomeCarryMs).toBe(0)
+    expect(state.restoreCarryMs).toBe(0)
+
+    // Leaving sleep mode clears restoreCarryMs
+    state.restoreCarryMs = 10_000
+    state.mode = null
+    settleGameplay(state, def, now + 1_000, { sessionActive: true })
+    expect(state.restoreCarryMs).toBe(0)
+  })
+
   it('applies the working decay variant while working and idle decay without a session', () => {
     const state = initialGameplayState(def, 0)
     state.mode = 'work'

package/src/gameplay.ts

@@ -572,6 +572,10 @@ export interface PetGameplayState {
   mode: 'work' | 'sleep' | null
   /** Epoch ms of the last lazy settle. */
   settledAt: number
+  /** Accumulated remainder ms towards the next passive income tick. */
+  incomeCarryMs?: number
+  /** Accumulated remainder ms towards the next sleep restore tick. */
+  restoreCarryMs?: number
 }
 
 /** Fresh state for one pet: stats at their initial (default max), no currency. */
@@ -624,7 +628,10 @@ export function settleGameplay(
     }
   }
   if (manifest.passiveIncome !== undefined) {
-    const ticks = Math.floor(elapsedMs / manifest.passiveIncome.intervalMs)
+    const incomeElapsed = elapsedMs + (state.incomeCarryMs ?? 0)
+    const interval = manifest.passiveIncome.intervalMs
+    const ticks = Math.floor(incomeElapsed / interval)
+    state.incomeCarryMs = incomeElapsed % interval
     if (ticks > 0) {
       const currency = manifest.passiveIncome.currency
       state.currencies[currency] = (state.currencies[currency] ?? 0) + ticks * manifest.passiveIncome.amount
@@ -632,12 +639,17 @@ export function settleGameplay(
     }
   }
   if (state.mode === 'sleep' && manifest.sleep !== undefined) {
-    const ticks = Math.floor(elapsedMs / manifest.sleep.restore.intervalMs)
+    const restoreElapsed = elapsedMs + (state.restoreCarryMs ?? 0)
+    const interval = manifest.sleep.restore.intervalMs
+    const ticks = Math.floor(restoreElapsed / interval)
+    state.restoreCarryMs = restoreElapsed % interval
     if (ticks > 0) {
       const stat = manifest.sleep.restore.stat
       state.stats[stat] = (state.stats[stat] ?? 0) + ticks * manifest.sleep.restore.amount
       changed = true
     }
+  } else {
+    state.restoreCarryMs = 0
   }
   state.settledAt = now
   clampGameplay(state, manifest)