@linxin666/dsh-pet 0.3.20 → 0.3.22

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)

package/src/ledger.test.ts

@@ -143,6 +143,25 @@ describe('PetLedger', () => {
     expect(ledger.takeDirty()).toBe(true)
   })
 
+  it('stores and clears the per-pet skin selection', () => {
+    const ledger = new PetLedger(emptyPersist())
+    expect(ledger.petSkin('jyn')).toBeUndefined()
+    ledger.setPetSkin('jyn', 'bingjing-gongzhu')
+    expect(ledger.petSkin('jyn')).toBe('bingjing-gongzhu')
+    expect(ledger.snapshot.skins).toEqual({ jyn: 'bingjing-gongzhu' })
+    expect(ledger.takeDirty()).toBe(true)
+    // Same value again: nothing changed, so no extra persist.
+    ledger.setPetSkin('jyn', 'bingjing-gongzhu')
+    expect(ledger.takeDirty()).toBe(false)
+    // undefined clears the entry back to the pet's default look.
+    ledger.setPetSkin('jyn', undefined)
+    expect(ledger.petSkin('jyn')).toBeUndefined()
+    expect(ledger.snapshot.skins).toEqual({})
+    expect(ledger.takeDirty()).toBe(true)
+    ledger.setPetSkin('jyn', undefined)
+    expect(ledger.takeDirty()).toBe(false)
+  })
+
   it('exposes the treat stock cap and display/pet/name setters', () => {
     const ledger = new PetLedger(emptyPersist())
     expect(ledger.treatMax).toBe(defaultTreatConfig.maxTreats)

package/src/ledger.ts

@@ -124,6 +124,30 @@ export class PetLedger {
     this.dirty = true
   }
 
+  /**
+   * Select one pet's frames2d skin; `undefined` clears the choice back to the
+   * pet's default look. Manifest validation stays a caller concern, exactly
+   * like setPetName's length check.
+   */
+  setPetSkin(petId: string, skinId: string | undefined): void {
+    const skins = this.current.skins
+    if (skinId === undefined) {
+      if (skins[petId] === undefined) return
+      const next = { ...skins }
+      delete next[petId]
+      this.current = { ...this.current, skins: next }
+    } else {
+      if (skins[petId] === skinId) return
+      this.current = { ...this.current, skins: { ...skins, [petId]: skinId } }
+    }
+    this.dirty = true
+  }
+
+  /** The persisted skin id for one pet (undefined = the pet's default look). */
+  petSkin(petId: string): string | undefined {
+    return this.current.skins[petId]
+  }
+
   /**
    * Swap the reaction pools to another pet's custom remarks (called on pet
    * selection). Slots the pet does not declare fall back to voice packs or built-ins.

package/src/persist.test.ts

@@ -49,6 +49,7 @@ describe('loadPetPersist', () => {
       const data = {
         petId: 'otter',
         names: { otter: '泡泡', 'whale-girl': '鲸鱼娘' },
+        skins: { otter: 'lanhainishang' },
         affinity: { ...emptyAffinity(), points: 42, pets: 3, feeds: 1, turns: 10 },
         treats: { ...emptyTreatLedger(), treats: 7, lastTreatGrantAt: 1234, turnsAtLastTreatGrant: 9 },
         display: { visible: false, size: 200, right: 10, bottom: 40 },
@@ -111,6 +112,18 @@ describe('loadPetPersist', () => {
     }
   })
 
+  it('sanitizes the per-pet skin map', () => {
+    const dir = tempDir()
+    try {
+      writeFileSync(join(dir, 'pet.json'), JSON.stringify({
+        skins: { otter: '  lanhainishang  ', blank: '   ', numeric: 7, '': 'x' },
+      }), 'utf8')
+      expect(loadPetPersist(dir).skins).toEqual({ otter: 'lanhainishang' })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
   it('clamps out-of-range and non-numeric fields', () => {
     const dir = tempDir()
     try {

package/src/persist.ts

@@ -48,6 +48,12 @@ export interface PetPersist {
    * to its manifest displayName, so only user renames are stored here.
    */
   names: Record<string, string>
+  /**
+   * Per-pet selected frames2d skin id (keyed by pet id). Skin ids are manifest
+   * data, so a stale entry (skin renamed or removed, pet swapped) is ignored
+   * when the state view is built instead of pinning an unresolvable track.
+   */
+  skins: Record<string, string>
   affinity: AffinityState
   /** Treat (小鱼干) stock ledger. */
   treats: TreatLedger
@@ -63,6 +69,7 @@ export function emptyPersist(): PetPersist {
   return {
     petId: DEFAULT_PET_ID,
     names: {},
+    skins: {},
     affinity: emptyAffinity(),
     treats: emptyTreatLedger(),
     display: { ...defaultDisplayConfig },
@@ -100,6 +107,19 @@ function loadPetNames(parsed: PetPersistDocument): Record<string, string> {
   return names
 }
 
+/** Sanitize the per-pet skin selection map (string keys, non-empty trimmed values). */
+function loadPetSkins(parsed: PetPersistDocument): Record<string, string> {
+  const skins: Record<string, string> = {}
+  if (typeof parsed.skins !== 'object' || parsed.skins === null) return skins
+  for (const [id, value] of Object.entries(parsed.skins as Record<string, unknown>)) {
+    if (id === '' || typeof value !== 'string') continue
+    const skin = value.trim()
+    if (skin === '') continue
+    skins[id] = skin
+  }
+  return skins
+}
+
 /** Clamp one count/score into [0, max]. */
 function clamp(value: number, max: number): number {
   return Math.min(max, Math.max(0, value))
@@ -130,12 +150,19 @@ function loadGameplay(parsed: PetPersistDocument): Record<string, PetGameplaySta
         currencies[key] = Math.min(GAMEPLAY_LOAD_CURRENCY_CAP, Math.max(0, Math.floor(value)))
       }
     }
-    result[petId] = {
+    const item: PetGameplayState = {
       stats,
       currencies,
       mode: record.mode === 'work' || record.mode === 'sleep' ? record.mode : null,
       settledAt: clamp(finiteNum(record.settledAt, 0), Number.MAX_SAFE_INTEGER),
     }
+    if (typeof record.incomeCarryMs === 'number' && Number.isFinite(record.incomeCarryMs)) {
+      item.incomeCarryMs = Math.max(0, record.incomeCarryMs)
+    }
+    if (typeof record.restoreCarryMs === 'number' && Number.isFinite(record.restoreCarryMs)) {
+      item.restoreCarryMs = Math.max(0, record.restoreCarryMs)
+    }
+    result[petId] = item
   }
   return result
 }
@@ -185,6 +212,7 @@ export function loadPetPersist(dir: string = petHomeDir()): PetPersist {
     return {
       petId,
       names,
+      skins: loadPetSkins(parsed),
       affinity,
       treats,
       display,

package/src/routes.ts

@@ -603,6 +603,11 @@ export function makePetRoutes(deps: { service: PetService; ctx: Context; assetCa
       if (typeof name !== 'string') return Promise.reject(new Error('invalid-name'))
       return service.setName(name)
     }),
+    postRoute(ctx, PET_API_PREFIX + '/set-skin', (body) => {
+      const skin = body.skin
+      if (skin !== undefined && typeof skin !== 'string') return Promise.reject(new Error('invalid-skin'))
+      return service.setSkin(skin === undefined || skin === '' ? undefined : skin)
+    }),
     postRoute(ctx, PET_API_PREFIX + '/set-pet', (body) => {
       const petId = body.petId
       if (typeof petId !== 'string') return Promise.reject(new Error('invalid-pet'))

package/src/service.ts

@@ -175,6 +175,12 @@ export interface PetStateView {
   }
   /** The selected pet's display name (user rename or manifest default). */
   name: string
+  /**
+   * The selected frames2d skin id for this pet (absent = the pet's default
+   * look). Persisted host-side, so a page reload or client restart restores
+   * the user's last choice instead of falling back to the default look.
+   */
+  skin?: string
   /** Treat (小鱼干) stock snapshot. */
   treats: {
     /** Stocked treats now. */
@@ -720,6 +726,36 @@ export class PetService extends Service {
     return { ok: true, display: this.ledger.snapshot.display }
   }
 
+  /**
+   * The persisted skin for one entry, when the manifest still declares it: a
+   * stale id (skin removed from the manifest, pet swapped) reads as "default"
+   * rather than pinning a track the browser half cannot resolve.
+   */
+  private persistedSkin(entry: NonNullable<PetRegistry['entries'][number]>): string | undefined {
+    const stored = this.ledger.petSkin(entry.id)
+    if (stored === undefined) return undefined
+    return entry.frames2d?.skins?.some(skin => skin.id === stored) === true ? stored : undefined
+  }
+
+  /**
+   * RPC: select the current pet's frames2d skin (`undefined` restores the
+   * pet's default look). The choice is stored per pet, so every later state
+   * view (reload, client restart, pet re-selection) serves it back.
+   */
+  async setSkin(skin: string | undefined): Promise<{ ok: true; skin?: string } | { ok: false; error: string }> {
+    const entry = this.activeEntry()
+    const declared = entry.frames2d?.skins ?? []
+    if (skin === undefined) {
+      this.ledger.setPetSkin(entry.id, undefined)
+      this.flush()
+      return { ok: true }
+    }
+    if (!declared.some(candidate => candidate.id === skin)) return { ok: false, error: 'unknown-skin' }
+    this.ledger.setPetSkin(entry.id, skin)
+    this.flush()
+    return { ok: true, skin }
+  }
+
   /** RPC: update display config (size / position). Values are clamped to whole pixels. */
   async setConfig(patch: Partial<PetDisplayConfig>): Promise<{ ok: true; display: PetDisplayConfig }> {
     const next = { ...this.ledger.snapshot.display, ...patch }
@@ -850,6 +886,7 @@ export class PetService extends Service {
     const announcement = this.announcement !== undefined && announcementFresh(this.announcement, Date.now())
       ? this.announcement
       : undefined
+    const skin = this.persistedSkin(entry)
     return {
       animation: snapshot.animation,
       ...(snapshot.bubble === undefined ? {} : { bubble: snapshot.bubble }),
@@ -866,6 +903,7 @@ export class PetService extends Service {
         description: entry.description,
       },
       name: this.petName(),
+      ...(skin === undefined ? {} : { skin }),
       treats: {
         stocked: this.ledger.snapshot.treats.treats,
         max: this.ledger.treatMax,