@linxin666/dsh-pet 0.3.2 → 0.3.4

package/src/client/renderers/frames2d.ts

@@ -0,0 +1,216 @@
+/**
+ * frames2d renderer — plays the free-form named frame-sequence tracks of a
+ * frames2d pet (manifest v2 'frames2d' block). The pet center picks the
+ * track from the ActivityPhase stream (phase -> track map, idle fallback);
+ * the gameplay driver may force a track through the handle's setState
+ * override (drag/work/sleep/shop...), and a finished non-loop track settles
+ * into its fallback, releasing the override when the fallback matches the
+ * phase-mapped track. Rendering never throws: a broken track list degrades
+ * to the first decodable frame, and the 1.2 s stall watchdog re-kicks the
+ * playback chain after timer throttling.
+ * @module @linxin666/dsh-pet/client/renderers/frames2d
+ */
+
+import { PET_RENDERER_API_VERSION, type PetRenderer, type PetRendererContext, type PetRendererHandle } from '../../contracts/renderer.ts'
+import type { ActivityPhase } from '../../state.ts'
+
+/** One track as served inside the pet definition (browser URLs). */
+export interface Frames2dTrackConfig {
+  frames: string[]
+  durations: number[]
+  loop: boolean
+  fallback?: string
+}
+
+/** The frames2d block as served inside the pet definition. */
+export interface PetFrames2dConfig {
+  tracks: Record<string, Frames2dTrackConfig>
+  phases: Partial<Record<ActivityPhase, string>> & { idle: string }
+}
+
+export interface Frames2dRendererHandle extends PetRendererHandle {
+  /** Force a track id (gameplay override); undefined returns to phase mapping. */
+  setState(track: string | undefined): void
+  /** The track currently playing (diagnostics and tests). */
+  currentTrack(): string
+}
+
+/** Stall watchdog period: a looping track stuck longer re-kicks its chain. */
+const WATCHDOG_MS = 1200
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Fail-closed client-side validation of the served frames2d block. */
+function validateFrames2dConfig(config: unknown): PetFrames2dConfig {
+  if (!isRecord(config) || !isRecord(config.tracks) || !isRecord(config.phases)) {
+    throw new Error('frames2d config requires tracks and phases objects')
+  }
+  const tracks: Record<string, Frames2dTrackConfig> = {}
+  for (const [name, raw] of Object.entries(config.tracks)) {
+    if (!isRecord(raw) || !Array.isArray(raw.frames) || raw.frames.length === 0
+      || raw.frames.some(f => typeof f !== 'string' || f === '')
+      || !Array.isArray(raw.durations) || raw.durations.length !== raw.frames.length
+      || raw.durations.some(d => typeof d !== 'number' || !(d > 0))) {
+      throw new Error('frames2d track ' + JSON.stringify(name) + ' needs same-length frames/durations')
+    }
+    tracks[name] = {
+      frames: raw.frames as string[],
+      durations: raw.durations as number[],
+      loop: raw.loop !== false,
+      ...(typeof raw.fallback === 'string' ? { fallback: raw.fallback } : {}),
+    }
+  }
+  const phases = config.phases as Partial<Record<ActivityPhase, string>>
+  if (typeof phases.idle !== 'string' || tracks[phases.idle] === undefined) {
+    throw new Error('frames2d phases.idle must name an existing track')
+  }
+  return { tracks, phases: phases as PetFrames2dConfig['phases'] }
+}
+
+export const frames2dRenderer: PetRenderer<PetFrames2dConfig> = {
+  id: 'frames2d',
+  apiVersion: PET_RENDERER_API_VERSION,
+  validateConfig: validateFrames2dConfig,
+
+  mount(ctx: PetRendererContext, config: PetFrames2dConfig): Frames2dRendererHandle {
+    const reducedMotion = typeof window !== 'undefined'
+      && typeof window.matchMedia === 'function'
+      && window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
+    const img = document.createElement('img')
+    img.dataset.dshPetFrames2d = ctx.petId
+    img.alt = ''
+    img.draggable = false
+    img.style.width = '100%'
+    img.style.height = '100%'
+    img.style.objectFit = 'contain'
+    img.style.pointerEvents = 'none'
+    ctx.container.appendChild(img)
+
+    // Warm the browser cache for every frame up front (same-origin, small
+    // webp files); playback itself swaps img.src without React state.
+    for (const track of Object.values(config.tracks)) {
+      for (const url of track.frames) {
+        const pre = new Image()
+        pre.src = url
+      }
+    }
+
+    let disposed = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let watchdog: ReturnType<typeof setInterval> | undefined
+    let track: string = config.phases.idle
+    let frameIndex = 0
+    let lastAdvance = Date.now()
+    let override: string | undefined
+
+    const trackForPhase = (phase: ActivityPhase): string => {
+      const mapped = config.phases[phase]
+      return mapped !== undefined && config.tracks[mapped] !== undefined ? mapped : config.phases.idle
+    }
+
+    const show = (trackId: string, index: number): void => {
+      const def = config.tracks[trackId]
+      const url = def?.frames[index]
+      if (url !== undefined && img.getAttribute('src') !== url) img.src = url
+    }
+
+    const schedule = (ms: number): void => {
+      if (disposed) return
+      timer = setTimeout(tick, ms)
+    }
+
+    function tick(): void {
+      if (disposed) return
+      const def = config.tracks[track]
+      if (def === undefined || def.frames.length === 0) return
+      lastAdvance = Date.now()
+      const next = frameIndex + 1
+      if (next < def.frames.length) {
+        frameIndex = next
+        show(track, frameIndex)
+        schedule(def.durations[frameIndex] ?? 200)
+        return
+      }
+      if (def.loop) {
+        frameIndex = 0
+        show(track, frameIndex)
+        schedule(def.durations[frameIndex] ?? 200)
+        return
+      }
+      // Non-loop completion: settle into the fallback; when the fallback is
+      // what the phase map would play anyway, release the gameplay override.
+      const target = def.fallback !== undefined && config.tracks[def.fallback] !== undefined
+        ? def.fallback
+        : config.phases.idle
+      if (target === trackForPhase(ctx.phase.get())) override = undefined
+      play(target)
+    }
+
+    function play(trackId: string): void {
+      if (disposed) return
+      if (config.tracks[trackId] === undefined) trackId = config.phases.idle
+      if (timer !== undefined) clearTimeout(timer)
+      track = trackId
+      frameIndex = 0
+      lastAdvance = Date.now()
+      show(track, frameIndex)
+      if (reducedMotion) return
+      const def = config.tracks[track]!
+      schedule(def.durations[0] ?? 200)
+    }
+
+    const unsubscribe = ctx.phase.subscribe((phase) => {
+      if (override !== undefined) return
+      const target = trackForPhase(phase)
+      if (target !== track) play(target)
+    })
+
+    // Watchdog: a throttled-away timer (background tab) leaves the chain
+    // dead; re-kick when a looping track has not advanced on schedule.
+    if (!reducedMotion) {
+      watchdog = setInterval(() => {
+        if (disposed) return
+        const def = config.tracks[track]
+        if (def === undefined || !def.loop) return
+        const expected = (def.durations[frameIndex] ?? 200) + WATCHDOG_MS
+        if (Date.now() - lastAdvance > expected) tick()
+      }, WATCHDOG_MS)
+    }
+
+    play(track)
+
+    let disposedOnce = false
+    const dispose = (): void => {
+      if (disposedOnce) return
+      disposedOnce = true
+      disposed = true
+      unsubscribe()
+      if (timer !== undefined) clearTimeout(timer)
+      if (watchdog !== undefined) clearInterval(watchdog)
+      img.remove()
+    }
+    ctx.onCleanup(dispose)
+
+    return {
+      dispose,
+      setState(next: string | undefined): void {
+        if (disposed) return
+        if (next === undefined) {
+          override = undefined
+          const target = trackForPhase(ctx.phase.get())
+          if (target !== track) play(target)
+          return
+        }
+        if (config.tracks[next] === undefined) return
+        override = next
+        if (next !== track) play(next)
+      },
+      currentTrack(): string {
+        return track
+      },
+    }
+  },
+}

package/src/client/settings-card.module.css

@@ -24,6 +24,10 @@
 .header {
   appearance: none;
   width: 100%;
+  /* The suite does not force a global border-box, so width:100% + padding
+     would stretch the row 32px past the card and push the trailing pending
+     badge (last flex item) outside the card border. */
+  box-sizing: border-box;
   font: inherit;
   color: inherit;
   text-align: left;
@@ -44,6 +48,7 @@
 
 .headerStatic {
   width: 100%;
+  box-sizing: border-box;
   border-radius: 12px;
   align-items: center;
   gap: 12px;

package/src/client/settings-form.ts

@@ -320,7 +320,7 @@ export class CardForm<T> {
   /**
    * Write every staged edit, then re-seed from what the Host accepted.
    *
-   * When the scope carries the optional batch surface (the dsh-web-ui
+   * When the scope carries the optional batch surface (the dsh-web
    * bridge scope), every planned write rides one mutation so cross-field
    * validate hooks (baseURL+model) judge the batch as a unit instead of
    * deadlocking on per-field writes. Otherwise the per-field loop runs.

package/src/client/telemetry.ts

@@ -0,0 +1,105 @@
+// Generated by scripts/sync-shared.mjs from shared/client/telemetry.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Anonymous install telemetry shared by the DSH Web UI family plugins.
+ *
+ * Once per UTC day per browser, each wired plugin sends one heartbeat to
+ * the dsh-market edge API listing its package name (and version when known).
+ * The payload carries no conversation data and no identifiers beyond a random
+ * UUID generated in localStorage; the server hashes it with a deployment salt
+ * before storage and never persists IP addresses. Sends are fire-and-forget:
+ * failures stay silent and simply retry on a later mount or day. The system
+ * is documented in docs/telemetry.md.
+ */
+
+export type TelemetryChannel = 'market' | 'npm' | 'unknown'
+
+export interface TelemetryItem {
+  /** npm package name or asset id, e.g. "@linxin666/dsh-pet" or "skin:harbor". */
+  name: string
+  /** Installed version when known; omitted otherwise. */
+  version?: string
+  /** Install channel when determinable (market = Workshop install). */
+  channel?: TelemetryChannel
+}
+
+const VISITOR_KEY = 'dsh-web-ui-telemetry-visitor'
+const DAY_KEY_PREFIX = 'dsh-web-ui-telemetry-day:'
+const ENDPOINT = 'https://dsh-market.com/api/telemetry/event'
+
+// Baked into each client bundle by shared/tsdown.client.ts (the package's own
+// package.json version at build time). Undefined in dev/test builds.
+declare const __DSH_PKG_VERSION__: string | undefined
+
+/** The building package's version, when the bundle carries it. */
+function bakedVersion(): string | undefined {
+  try {
+    return typeof __DSH_PKG_VERSION__ === 'string' && __DSH_PKG_VERSION__ !== ''
+      ? __DSH_PKG_VERSION__
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Read or lazily create the anonymous visitor id; null when storage is unavailable. */
+function visitorId(): string | null {
+  try {
+    const existing = localStorage.getItem(VISITOR_KEY)
+    if (existing && /^[A-Za-z0-9_-]{16,64}$/.test(existing)) return existing
+    const fresh = crypto.randomUUID().replaceAll('-', '')
+    localStorage.setItem(VISITOR_KEY, fresh)
+    return fresh
+  } catch {
+    // Storage unavailable (privacy mode, sandboxed frame): report nothing.
+    return null
+  }
+}
+
+/** Drop stale per-day dedup keys so localStorage does not grow forever. */
+function pruneDayKeys(today: string): void {
+  try {
+    for (let index = localStorage.length - 1; index >= 0; index -= 1) {
+      const key = localStorage.key(index)
+      if (key !== null && key.startsWith(DAY_KEY_PREFIX) && key !== DAY_KEY_PREFIX + today) {
+        localStorage.removeItem(key)
+      }
+    }
+  } catch { /* best effort */ }
+}
+
+/**
+ * Fire the daily heartbeat for the given items at most once per UTC day per
+ * browser. Never throws and never blocks the caller. Items without an explicit
+ * version inherit the bundle's baked build version.
+ */
+export function reportDailyHeartbeat(items: readonly TelemetryItem[]): void {
+  try {
+    if (items.length === 0) return
+    const today = new Date().toISOString().slice(0, 10)
+    // Automation contexts (CDP-driven QA browsers, fresh isolated profiles)
+    // mint a new visitor id per run and would inflate instance counts.
+    if (navigator.webdriver) return
+    if (localStorage.getItem(DAY_KEY_PREFIX + today) !== null) return
+    const visitor = visitorId()
+    if (visitor === null) return
+    pruneDayKeys(today)
+    const payloadItems = items.map((item) => {
+      const out: Record<string, string> = { name: item.name }
+      const version = item.version ?? bakedVersion()
+      if (version !== undefined) out.version = version
+      if (item.channel !== undefined) out.channel = item.channel
+      return out
+    })
+    const body = JSON.stringify({ kind: 'heartbeat', visitor, items: payloadItems })
+    void fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body,
+      keepalive: true,
+    }).then((response) => {
+      // Mark the day only after an accepted send, so offline browsers retry
+      // on a later mount instead of going dark until tomorrow.
+      if (response.ok) localStorage.setItem(DAY_KEY_PREFIX + today, '1')
+    }).catch(() => { /* unreachable endpoint: stay silent */ })
+  } catch { /* never break the host UI over telemetry */ }
+}

package/src/defaults.ts

@@ -0,0 +1,7 @@
+/** Shared defaults used by registry selection and persisted-state migration. */
+
+/** Pet id that legacy single-pet installs and fresh registries resolve to. */
+export const DEFAULT_PET_ID = 'whale-girl'
+
+/** Default pet name used only when a manifest carries no displayName. */
+export const DEFAULT_PET_NAME = '鲸鱼娘'

package/src/dsh-home.ts

@@ -7,11 +7,14 @@
 
 import { homedir } from 'node:os'
 import { isAbsolute, join } from 'node:path'
+import { isAbsolute as posixIsAbsolute, join as posixJoin } from 'node:path/posix'
 
 /** Expand a leading ~ (or ~user) in a path, platform-style. */
 export function expandHome(path: string, home: string = homedir()): string {
+  const isPosix = home.startsWith('/')
+  const j = isPosix ? posixJoin : join
   if (path === '~') return home
-  if (path.startsWith('~/') || path.startsWith('~\\')) return join(home, path.slice(2))
+  if (path.startsWith('~/') || path.startsWith('~\\')) return j(home, path.slice(2))
   return path
 }
 
@@ -22,12 +25,15 @@ export function expandHome(path: string, home: string = homedir()): string {
  * @returns the absolute DSH home path.
  */
 export function resolveDshHome(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+  const isPosix = home.startsWith('/')
+  const j = isPosix ? posixJoin : join
+  const isAbs = isPosix ? posixIsAbsolute : isAbsolute
   const raw = env.DSH_HOME
   if (raw !== undefined && raw.trim() !== '') {
     const expanded = expandHome(raw.trim(), home)
-    return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded)
+    return isAbs(expanded) ? expanded : j(process.cwd(), expanded)
   }
-  return join(home, '.dsh')
+  return j(home, '.dsh')
 }
 
 /** Resolve the DSH home directory from the live environment. */

package/src/gameplay.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Gameplay tests — the manifest block (fail-closed structure, parsed through
+ * parsePetManifest) and the host engine (lazy settle, effects, rolls) with
+ * injected clock/rng for determinism.
+ */
+import { describe, expect, it } from 'vitest'
+import { parsePetManifest } from './manifest-v2.ts'
+import {
+  applyGameplayEffects,
+  clampGameplay,
+  drawLotteryTier,
+  initialGameplayState,
+  rollTouchBranch,
+  rollWorkOutcome,
+  settleGameplay,
+  touchZoneAt,
+  type PetGameplayManifest,
+} from './gameplay.ts'
+
+/** A miku-shaped frames2d manifest carrying the full gameplay block. */
+function mikuManifest(gameplay: Record<string, unknown>): Record<string, unknown> {
+  return {
+    petManifestVersion: 2,
+    id: 'miku',
+    displayName: 'Miku',
+    license: 'MIT',
+    renderer: 'frames2d',
+    frames2d: {
+      dir: 'thumb',
+      tracks: {
+        idle: {}, drag: {}, standup: {}, sleep: {}, work: {}, success: {}, fail: {},
+        happy: {}, shy: {}, flirty: {}, angry: {}, scratch: {}, blink1: {}, blink2: {}, eat: {}, shop: {},
+      },
+      phases: { idle: 'idle', done: 'success', failed: 'fail' },
+    },
+    gameplay,
+  }
+}
+
+const FULL_GAMEPLAY: Record<string, unknown> = {
+  idleDirector: {
+    intervalMs: 5000,
+    maxMiss: 2,
+    idleWeight: 40,
+    acts: [
+      { track: 'scratch', weight: 18 },
+      { track: 'blink1', weight: 9 },
+      { track: 'blink2', weight: 9 },
+      { track: 'eat', weight: 24 },
+    ],
+  },
+  stats: {
+    hunger: { max: 100, initial: 100, decayPerMinute: 1, workingDecayPerMinute: 5 },
+    mood: { max: 100, initial: 100, decayPerMinute: 0.5 },
+    energy: { max: 100, initial: 100, decayPerMinute: 0.25 },
+    affection: { max: 500, initial: 100, idleDecayPerMinute: 0.2 },
+  },
+  hitBox: { x0: 0.2, y0: 0.05, x1: 0.42, y1: 0.56 },
+  touch: {
+    zones: [
+      { name: 'head', y0: 0, y1: 0.55, branches: [{ probability: 0.05, effects: [{ stat: 'affection', amount: 5 }], state: 'happy', stateMs: 3000, phrases: ['hi'] }] },
+      { name: 'body', y0: 0.55, y1: 0.75, branches: [{ probability: 0.1, effects: [{ stat: 'affection', amount: 10 }], state: 'shy', stateMs: 3000 }] },
+      {
+        name: 'legs', y0: 0.75, y1: 1, branches: [
+          { probability: 0.1, effects: [{ stat: 'affection', amount: 30 }], state: 'flirty', stateMs: 3000 },
+          { probability: 0.9, effects: [{ stat: 'affection', amount: -5 }], state: 'angry', stateMs: 3000 },
+        ],
+      },
+    ],
+  },
+  work: {
+    state: 'work',
+    successState: 'success',
+    failState: 'fail',
+    tickMs: 10_000,
+    resultMs: { success: 1300, fail: 1900 },
+    successProbability: 0.5,
+    success: { effects: [{ currency: 'coins', amount: 3 }] },
+    fail: { effects: [{ currency: 'coins', amount: -1 }] },
+  },
+  sleep: { state: 'sleep', wakeState: 'standup', restore: { stat: 'energy', amount: 4, intervalMs: 30_000 } },
+  passiveIncome: { currency: 'coins', amount: 1, intervalMs: 60_000 },
+  shop: {
+    state: 'shop',
+    items: [
+      { id: 'food1', label: 'bread', price: 5, currency: 'coins', effects: [{ stat: 'hunger', amount: 40 }] },
+      { id: 'gamecoin', label: 'coin', price: 10, currency: 'coins', effects: [{ currency: 'gamecoins', amount: 1 }] },
+      {
+        id: 'lottery', label: 'ticket', price: 10, currency: 'gamecoins',
+        lottery: {
+          effects: [{ stat: 'hunger', amount: 10 }, { stat: 'mood', amount: 10 }, { stat: 'energy', amount: 10 }, { stat: 'affection', amount: 10 }],
+          tiers: [
+            { probability: 0.0001, prize: 1_000_000 },
+            { probability: 0.9836, prize: 50 },
+          ],
+        },
+      },
+    ],
+  },
+  dragState: 'drag',
+}
+
+describe('gameplay manifest', () => {
+  it('accepts the full miku-shaped block', () => {
+    const result = parsePetManifest(mikuManifest(FULL_GAMEPLAY), 'mem')
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const gameplay = result.manifest.gameplay!
+    expect(gameplay.idleDirector?.acts).toHaveLength(4)
+    expect(gameplay.stats?.affection?.max).toBe(500)
+    expect(gameplay.touch?.zones).toHaveLength(3)
+    expect(gameplay.work?.tickMs).toBe(10_000)
+    expect(gameplay.sleep?.restore).toEqual({ stat: 'energy', amount: 4, intervalMs: 30_000 })
+    expect(gameplay.shop?.items).toHaveLength(3)
+    expect(gameplay.dragState).toBe('drag')
+  })
+
+  it('rejects gameplay on non-frames2d renderers', () => {
+    const sprite = {
+      petManifestVersion: 2, id: 'cat', displayName: 'Cat', license: 'CC0-1.0',
+      renderer: 'sprite2d', sprite2d: { spritesheetPath: 'spritesheet.webp' },
+      gameplay: {},
+    }
+    const result = parsePetManifest(sprite, 'mem')
+    expect(result.ok).toBe(false)
+  })
+
+  it('rejects unknown fields and dangling references', () => {
+    expect(parsePetManifest(mikuManifest({ ...FULL_GAMEPLAY, casino: {} }), 'mem').ok).toBe(false)
+    const badStatRef = mikuManifest({ stats: { hunger: { max: 100 } }, shop: { items: [{ id: 'x', label: 'x', price: 1, currency: 'coins', effects: [{ stat: 'ghost', amount: 1 }] }] } })
+    expect(parsePetManifest(badStatRef, 'mem').ok).toBe(false)
+    const badTrackRef = mikuManifest({ work: { state: 'ghost', successState: 'success', failState: 'fail', tickMs: 1000, successProbability: 0.5 } })
+    expect(parsePetManifest(badTrackRef, 'mem').ok).toBe(false)
+  })
+
+  it('rejects probability sums above 1 and duplicate shop ids', () => {
+    const overTouch = mikuManifest({ touch: { zones: [{ name: 'z', y0: 0, y1: 1, branches: [{ probability: 0.6 }, { probability: 0.6 }] }] } })
+    expect(parsePetManifest(overTouch, 'mem').ok).toBe(false)
+    const dupShop = mikuManifest({ shop: { items: [
+      { id: 'a', label: 'a', price: 1, currency: 'c', effects: [{ currency: 'c', amount: 1 }] },
+      { id: 'a', label: 'b', price: 1, currency: 'c', effects: [{ currency: 'c', amount: 1 }] },
+    ] } })
+    expect(parsePetManifest(dupShop, 'mem').ok).toBe(false)
+  })
+
+  it('rejects a shop item with neither effects nor lottery', () => {
+    const bare = mikuManifest({ shop: { items: [{ id: 'a', label: 'a', price: 1, currency: 'coins' }] } })
+    expect(parsePetManifest(bare, 'mem').ok).toBe(false)
+  })
+
+  it('rejects bad ranges (tickMs, decay, zone slices, stateMs)', () => {
+    const badTick = mikuManifest({ work: { state: 'work', successState: 'success', failState: 'fail', tickMs: 50, successProbability: 0.5 } })
+    expect(parsePetManifest(badTick, 'mem').ok).toBe(false)
+    const badDecay = mikuManifest({ stats: { hunger: { max: 100, decayPerMinute: -1 } } })
+    expect(parsePetManifest(badDecay, 'mem').ok).toBe(false)
+    const badZone = mikuManifest({ touch: { zones: [{ name: 'z', y0: 0.8, y1: 0.2, branches: [{ probability: 1 }] }] } })
+    expect(parsePetManifest(badZone, 'mem').ok).toBe(false)
+  })
+})
+
+describe('gameplay engine', () => {
+  const manifest = parsePetManifest(mikuManifest(FULL_GAMEPLAY), 'mem')
+  if (!manifest.ok) throw new Error('fixture must parse')
+  const def = manifest.manifest.gameplay!
+
+  it('initializes stats at their declared initial (default max)', () => {
+    const state = initialGameplayState(def, 1000)
+    expect(state.stats).toEqual({ hunger: 100, mood: 100, energy: 100, affection: 100 })
+    expect(state.currencies).toEqual({})
+    expect(state.mode).toBeNull()
+  })
+
+  it('lazy-settles decay, passive income and sleep restore', () => {
+    const state = initialGameplayState(def, 0)
+    state.stats.hunger = 50
+    state.mode = 'sleep'
+    // 10 minutes pass with an active session: hunger -10 (1/min), mood -5,
+    // energy -2.5 then +20 sleep restore (10 x 30s ticks x 4), coins +10.
+    const changed = settleGameplay(state, def, 600_000, { sessionActive: true })
+    expect(changed).toBe(true)
+    expect(state.stats.hunger).toBe(40)
+    expect(state.stats.mood).toBe(95)
+    expect(state.stats.energy).toBe(100) // 97.5 + 20 clamped to max
+    expect(state.currencies.coins).toBe(10)
+    expect(state.settledAt).toBe(600_000)
+  })
+
+  it('applies the working decay variant while working and idle decay without a session', () => {
+    const state = initialGameplayState(def, 0)
+    state.mode = 'work'
+    settleGameplay(state, def, 60_000, { sessionActive: true })
+    expect(state.stats.hunger).toBe(95) // working: 5/min
+    const idle = initialGameplayState(def, 0)
+    settleGameplay(idle, def, 300_000, { sessionActive: false })
+    expect(idle.stats.affection).toBe(99) // idle decay 0.2/min over 5 min
+  })
+
+  it('clamps effects into stat max and currency floors', () => {
+    const state = initialGameplayState(def, 0)
+    applyGameplayEffects(state, def, [{ stat: 'affection', amount: 10_000 }, { currency: 'coins', amount: -5 }])
+    expect(state.stats.affection).toBe(500)
+    expect(state.currencies.coins).toBe(0)
+  })
+
+  it('rolls touch branches by cumulative probability with no-op mass', () => {
+    const zone = def.touch!.zones[0]! // head: 5% hit
+    expect(rollTouchBranch(zone, () => 0.04)?.state).toBe('happy')
+    expect(rollTouchBranch(zone, () => 0.5)).toBeUndefined()
+    const legs = def.touch!.zones[2]!
+    expect(rollTouchBranch(legs, () => 0.05)?.state).toBe('flirty')
+    expect(rollTouchBranch(legs, () => 0.5)?.state).toBe('angry')
+  })
+
+  it('rolls work outcomes and draws lottery tiers with fallthrough', () => {
+    expect(rollWorkOutcome(def.work!, () => 0.4)).toBe('success')
+    expect(rollWorkOutcome(def.work!, () => 0.6)).toBe('fail')
+    const lottery = def.shop!.items[2]!.lottery!
+    expect(drawLotteryTier(lottery, () => 0.00005).prize).toBe(1_000_000)
+    expect(drawLotteryTier(lottery, () => 0.5).prize).toBe(50)
+    // Sum < 1: the uncovered roll mass falls through to the last tier.
+    expect(drawLotteryTier(lottery, () => 0.9999).prize).toBe(50)
+  })
+
+  it('locates the touch zone for a hit-box fraction', () => {
+    expect(touchZoneAt(def.touch!, 0.3)?.name).toBe('head')
+    expect(touchZoneAt(def.touch!, 0.6)?.name).toBe('body')
+    expect(touchZoneAt(def.touch!, 0.9)?.name).toBe('legs')
+    expect(touchZoneAt(def.touch!, 0.55)?.name).toBe('body')
+  })
+
+  it('clamps gameplay state into declared maxima', () => {
+    const state = initialGameplayState(def, 0)
+    state.stats.hunger = 10_000
+    state.currencies.coins = 100_000_000
+    clampGameplay(state, def)
+    expect(state.stats.hunger).toBe(100)
+    expect(state.currencies.coins).toBe(9_999_999)
+  })
+})