@linxin666/dsh-pet 0.3.2 → 0.3.4

package/src/http.ts

@@ -11,7 +11,7 @@
  * edit this shared source and re-run the sync instead of editing a copy.
  * Consumer code is migrated onto it in follow-up waves; no call site changes
  * belong in the same change as its introduction.
- * @module dsh-web-ui-shared/host/http
+ * @module dsh-web-shared/host/http
  */
 
 import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http'

package/src/index.ts

@@ -6,7 +6,7 @@
  * the package assets, the hatch-pet custom pets directory, and composed
  * config entries; adding a pet means dropping a manifest + atlas into one of
  * those sources, never touching host or client code. Install via
- * 'dsh plugin --profile web add link:<dsh-web-ui>/packages/dsh-pet'; the
+ * 'dsh plugin --profile web add link:<dsh-web>/packages/dsh-pet'; the
  * cordis.patch.yml inserts this plugin row.
  * @module @linxin666/dsh-pet
  */

package/src/ledger.test.ts

@@ -43,6 +43,22 @@ describe('PetLedger', () => {
     expect(ledger.takeDirty()).toBe(false)
   })
 
+  it('grants and spends gameplay treats through the shared stock, capped', () => {
+    const ledger = new PetLedger(emptyPersist())
+    expect(ledger.grantTreats(3)).toBe(true)
+    expect(ledger.snapshot.treats.treats).toBe(3)
+    // 3 + 19 exceeds the cap: the grant lands capped and counts as changed.
+    expect(ledger.grantTreats(19)).toBe(true)
+    expect(ledger.snapshot.treats.treats).toBe(defaultTreatConfig.maxTreats)
+    // Already at the cap: no change, no dirty write.
+    expect(ledger.grantTreats(5)).toBe(false)
+    expect(ledger.spendTreats(5)).toEqual({ ok: true })
+    expect(ledger.snapshot.treats.treats).toBe(defaultTreatConfig.maxTreats - 5)
+    expect(ledger.spendTreats(16)).toEqual({ ok: false })
+    expect(ledger.snapshot.treats.treats).toBe(defaultTreatConfig.maxTreats - 5)
+    expect(ledger.grantTreats(0)).toBe(false)
+  })
+
   it('feed consumes a treat and applies the feed reward', () => {
     const ledger = new PetLedger(emptyPersist())
     const n = 1_000_000

package/src/ledger.ts

@@ -24,6 +24,7 @@ import {
 } from './treats.ts'
 import { RemarkPicker, type PetRemarks } from './remarks.ts'
 import type { PetDisplayConfig, PetPersist } from './persist.ts'
+import type { PetGameplayState } from './gameplay.ts'
 
 /** Tuning overrides for the affinity economy. */
 export interface LedgerConfig {
@@ -109,6 +110,12 @@ export class PetLedger {
     this.dirty = true
   }
 
+  /** Replace one pet's gameplay state (validation/clamping stays a caller concern). */
+  setGameplay(petId: string, gameplay: PetGameplayState): void {
+    this.current = { ...this.current, gameplay: { ...this.current.gameplay, [petId]: gameplay } }
+    this.dirty = true
+  }
+
   /** Replace one pet's display name (validation stays a caller concern). */
   setPetName(petId: string, name: string): void {
     this.current = { ...this.current, names: { ...this.current.names, [petId]: name } }
@@ -142,6 +149,30 @@ export class PetLedger {
     return true
   }
 
+  /**
+   * Grant gameplay treats into the shared stock (capped by the treat cap).
+   * This is the unified gameplay currency (wallet removed): work rewards,
+   * passive income and lottery prizes land here so one balance feeds the
+   * shop and the feeding economy. Returns true when the snapshot changed.
+   */
+  grantTreats(amount: number): boolean {
+    if (amount <= 0) return false
+    const capped = Math.min(this.treatConfig.maxTreats, this.current.treats.treats + amount)
+    if (capped === this.current.treats.treats) return false
+    this.current = { ...this.current, treats: { ...this.current.treats, treats: capped } }
+    this.dirty = true
+    return true
+  }
+
+  /** Spend gameplay treats from the shared stock; refuses when unaffordable. */
+  spendTreats(amount: number): { ok: boolean } {
+    const stock = this.current.treats.treats
+    if (amount <= 0 || stock < amount) return { ok: false }
+    this.current = { ...this.current, treats: { ...this.current.treats, treats: stock - amount } }
+    this.dirty = true
+    return { ok: true }
+  }
+
   /**
    * Award the completed-turn reward once per session+turn (idempotent) and
    * run the treat settlement that work output feeds. Returns true when the

package/src/loopback.ts

@@ -8,7 +8,7 @@
  * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
  * remote-web-ui gate), localhost hostnames, plus the browser same-origin
  * markers (sec-fetch-site and Origin) for the request-level fence.
- * @module dsh-web-ui-shared/host/loopback
+ * @module dsh-web-shared/host/loopback
  */
 
 import type { IncomingMessage } from 'node:http'

package/src/manifest-v2.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, it } from 'vitest'
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import {
+  KNOWN_FRAMES2D,
+  KNOWN_FRAMES2D_TRACK,
   KNOWN_LIVE2D,
   KNOWN_SPRITE2D,
   KNOWN_TOP_LEVEL,
@@ -217,7 +219,130 @@ describe('parsePetManifest v2 fail-closed validation', () => {
 describe('constants', () => {
   it('locks the manifest version and renderer kinds', () => {
     expect(PET_MANIFEST_V2).toBe(2)
-    expect(PET_RENDERER_KINDS).toEqual(['sprite2d', 'live2d'])
+    expect(PET_RENDERER_KINDS).toEqual(['sprite2d', 'live2d', 'frames2d'])
+  })
+})
+
+/** Minimal valid v2 frames2d manifest (miku-style directory tracks). */
+function v2Frames2d(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    petManifestVersion: 2,
+    id: 'miku',
+    displayName: 'Miku',
+    license: 'MIT',
+    renderer: 'frames2d',
+    frames2d: {
+      dir: 'thumb',
+      tracks: {
+        idle: { loop: true },
+        happy: { frames: ['happy_1_300.webp', 'happy_2_320.webp'], frameMs: [300, 320], loop: false, fallback: 'idle' },
+      },
+      phases: { idle: 'idle', done: 'happy' },
+    },
+    ...overrides,
+  }
+}
+
+describe('parsePetManifest v2 frames2d', () => {
+  it('accepts a minimal valid frames2d manifest', () => {
+    const result = parsePetManifest(v2Frames2d(), 'mem')
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.manifest.renderer).toBe('frames2d')
+    expect(result.manifest.frames2d?.dir).toBe('thumb')
+    expect(Object.keys(result.manifest.frames2d?.tracks ?? {}).sort()).toEqual(['happy', 'idle'])
+    expect(result.manifest.frames2d?.phases).toEqual({ idle: 'idle', done: 'happy' })
+  })
+
+  it('requires the frames2d block, tracks and phases.idle', () => {
+    expect(parsePetManifest({ ...v2Frames2d(), frames2d: undefined }, 'mem').ok).toBe(false)
+    const noTracks = v2Frames2d()
+    delete (noTracks.frames2d as Record<string, unknown>).tracks
+    expect(parsePetManifest(noTracks, 'mem').ok).toBe(false)
+    const noPhases = v2Frames2d()
+    delete (noPhases.frames2d as Record<string, unknown>).phases
+    expect(parsePetManifest(noPhases, 'mem').ok).toBe(false)
+    const noIdle = v2Frames2d({ })
+    ;(noIdle.frames2d as Record<string, unknown>).phases = { done: 'happy' }
+    expect(parsePetManifest(noIdle, 'mem').ok).toBe(false)
+  })
+
+  it('rejects mixing renderer blocks', () => {
+    const mixed = v2Frames2d()
+    ;(mixed as Record<string, unknown>).sprite2d = { spritesheetPath: 'x.webp' }
+    expect(parsePetManifest(mixed, 'mem').ok).toBe(false)
+    const spriteWithFrames = v2Sprite()
+    ;(spriteWithFrames as Record<string, unknown>).frames2d = (v2Frames2d() as { frames2d: unknown }).frames2d
+    expect(parsePetManifest(spriteWithFrames, 'mem').ok).toBe(false)
+  })
+
+  it('rejects unknown block and track fields', () => {
+    const badBlock = v2Frames2d()
+    ;(badBlock.frames2d as Record<string, unknown>).blink = { state: 'idle' }
+    expect(parsePetManifest(badBlock, 'mem').ok).toBe(false)
+    const badTrack = v2Frames2d()
+    ;((badTrack.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).idle = { loop: true, path: 'thumb/idle' }
+    expect(parsePetManifest(badTrack, 'mem').ok).toBe(false)
+  })
+
+  it('rejects bad track names, dangling phases and dangling fallbacks', () => {
+    const badName = v2Frames2d()
+    ;((badName.frames2d as Record<string, unknown>).tracks as Record<string, unknown>)['Bad Name'] = {}
+    expect(parsePetManifest(badName, 'mem').ok).toBe(false)
+    const badPhase = v2Frames2d()
+    ;((badPhase.frames2d as Record<string, unknown>).phases as Record<string, unknown>).done = 'ghost'
+    expect(parsePetManifest(badPhase, 'mem').ok).toBe(false)
+    const badFallback = v2Frames2d()
+    ;(((badFallback.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).happy as Record<string, unknown>).fallback = 'ghost'
+    expect(parsePetManifest(badFallback, 'mem').ok).toBe(false)
+  })
+
+  it('rejects unknown activity phases in frames2d.phases', () => {
+    const bad = v2Frames2d()
+    ;((bad.frames2d as Record<string, unknown>).phases as Record<string, unknown>).sleeping = 'idle'
+    expect(parsePetManifest(bad, 'mem').ok).toBe(false)
+  })
+
+  it('rejects unsafe frame names and non-image extensions', () => {
+    const traversal = v2Frames2d()
+    ;(((traversal.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).happy as Record<string, unknown>).frames = ['../evil.webp']
+    expect(parsePetManifest(traversal, 'mem').ok).toBe(false)
+    const notImage = v2Frames2d()
+    ;(((notImage.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).happy as Record<string, unknown>).frames = ['payload.exe']
+    expect(parsePetManifest(notImage, 'mem').ok).toBe(false)
+  })
+
+  it('rejects frameMs without frames, length mismatch and out-of-range durations', () => {
+    const noFrames = v2Frames2d()
+    ;((noFrames.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).idle = { frameMs: [100] }
+    expect(parsePetManifest(noFrames, 'mem').ok).toBe(false)
+    const mismatch = v2Frames2d()
+    ;(((mismatch.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).happy as Record<string, unknown>).frameMs = [300]
+    expect(parsePetManifest(mismatch, 'mem').ok).toBe(false)
+    const tooSlow = v2Frames2d()
+    ;(((tooSlow.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).happy as Record<string, unknown>).frameMs = [300, 9000]
+    expect(parsePetManifest(tooSlow, 'mem').ok).toBe(false)
+  })
+
+  it('rejects oversized track and frame counts', () => {
+    const manyTracks: Record<string, unknown> = {}
+    for (let i = 0; i < 65; i++) manyTracks['t' + i] = { loop: true }
+    const big = v2Frames2d()
+    ;(big.frames2d as Record<string, unknown>).tracks = manyTracks
+    ;((big.frames2d as Record<string, unknown>).phases as Record<string, unknown>).idle = 't0'
+    expect(parsePetManifest(big, 'mem').ok).toBe(false)
+    const manyFrames = v2Frames2d()
+    ;(((manyFrames.frames2d as Record<string, unknown>).tracks as Record<string, unknown>).happy as Record<string, unknown>).frames = Array.from({ length: 65 }, (_, i) => 'f' + i + '.webp')
+    expect(parsePetManifest(manyFrames, 'mem').ok).toBe(false)
+  })
+
+  it('rejects an unsafe frames2d.dir and out-of-range defaultFrameMs', () => {
+    const badDir = v2Frames2d()
+    ;(badDir.frames2d as Record<string, unknown>).dir = '../elsewhere'
+    expect(parsePetManifest(badDir, 'mem').ok).toBe(false)
+    const badMs = v2Frames2d()
+    ;(badMs.frames2d as Record<string, unknown>).defaultFrameMs = 9000
+    expect(parsePetManifest(badMs, 'mem').ok).toBe(false)
   })
 })
 
@@ -242,6 +367,10 @@ describe('schema file drift lock', () => {
   it('locks the renderer block allow-lists', () => {
     expect(new Set(Object.keys(schema.properties.sprite2d?.properties ?? {}))).toEqual(KNOWN_SPRITE2D)
     expect(new Set(Object.keys(schema.properties.live2d?.properties ?? {}))).toEqual(KNOWN_LIVE2D)
+    expect(new Set(Object.keys(schema.properties.frames2d?.properties ?? {}))).toEqual(KNOWN_FRAMES2D)
+    const frames2d = schema.properties.frames2d as { properties?: Record<string, { additionalProperties?: { properties?: Record<string, unknown> } }> }
+    const trackProps = frames2d.properties?.tracks?.additionalProperties?.properties ?? {}
+    expect(new Set(Object.keys(trackProps))).toEqual(KNOWN_FRAMES2D_TRACK)
   })
 
   it('keeps the schema version const in sync', () => {

package/src/manifest-v2.ts

@@ -25,12 +25,13 @@
 
 import { isAbsolute } from 'node:path'
 import type { ActivityPhase, PetAnimation } from './state.ts'
+import { parseGameplayManifest, type PetGameplayManifest } from './gameplay.ts'
 
 /** Schema version this module validates. */
 export const PET_MANIFEST_V2 = 2 as const
 
 /** Renderer kinds the pet center knows how to dispatch (M1 §2). */
-export const PET_RENDERER_KINDS = ['sprite2d', 'live2d'] as const
+export const PET_RENDERER_KINDS = ['sprite2d', 'live2d', 'frames2d'] as const
 export type PetRendererKind = (typeof PET_RENDERER_KINDS)[number]
 
 /** The seven ActivityPhase semantics (pet-center owned; M1 §1). */
@@ -72,6 +73,35 @@ export interface PetManifestLive2d {
   lipSync?: boolean
 }
 
+/** One frames2d track: an ordered frame sequence plus its rhythm. */
+export interface PetManifestFrames2dTrack {
+  /** Explicit ordered frame file names inside <dir>/<track>/; omitted means "list the directory". */
+  frames?: string[]
+  /** Per-frame durations in ms, same length as frames; wins over filename-encoded ms. */
+  frameMs?: number[]
+  /** Loop the track (default true); false stops on the last frame, then enters fallback. */
+  loop?: boolean
+  /** Track entered when a non-loop track ends (default 'idle'). */
+  fallback?: string
+}
+
+/**
+ * frames2d renderer block: free-form named frame-sequence tracks laid out as
+ * <dir>/<track>/<frame>.webp, with phase-direct state selection (the live2d
+ * motions precedent). Frame durations resolve frameMs[i] > filename-encoded
+ * <base>_<index>_<ms> suffix > defaultFrameMs.
+ */
+export interface PetManifestFrames2d {
+  /** Frame root directory relative to the manifest directory (default '.'). */
+  dir?: string
+  /** Default per-frame duration in ms (default 200). */
+  defaultFrameMs?: number
+  /** Named tracks (1..64, kebab ids). */
+  tracks: Record<string, PetManifestFrames2dTrack>
+  /** ActivityPhase -> track name; idle is required, unmapped phases fall back to it. */
+  phases: Partial<Record<ActivityPhase, string>> & { idle: string }
+}
+
 /** Normalized v2 manifest the registry consumes. */
 export interface PetManifestV2 {
   petManifestVersion: typeof PET_MANIFEST_V2
@@ -86,6 +116,9 @@ export interface PetManifestV2 {
   renderer: PetRendererKind
   sprite2d?: PetManifestSprite2d
   live2d?: PetManifestLive2d
+  frames2d?: PetManifestFrames2d
+  /** Optional gameplay layer (frames2d pets only); fail-closed structure. */
+  gameplay?: PetGameplayManifest
   sequences?: Partial<Record<ActivityPhase, PetAnimation[]>>
   /** Pass-through for the registry's remarks normalizer (v1 shape). */
   remarks?: unknown
@@ -112,12 +145,17 @@ const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/
  */
 export const KNOWN_TOP_LEVEL = new Set([
   '$schema', 'petManifestVersion', 'id', 'displayName', 'description', 'version',
-  'author', 'license', 'homepage', 'renderer', 'sprite2d', 'live2d', 'sequences', 'remarks',
+  'author', 'license', 'homepage', 'renderer', 'sprite2d', 'live2d', 'frames2d', 'sequences', 'remarks',
+  'gameplay',
 ])
 /** sprite2d block field allow-list (drift-locked to the schema file). */
 export const KNOWN_SPRITE2D = new Set(['spritesheetPath', 'cell', 'columns', 'atlasRows', 'frames', 'tracks'])
 /** live2d block field allow-list (drift-locked to the schema file). */
 export const KNOWN_LIVE2D = new Set(['model', 'scale', 'translate', 'motions', 'expressions', 'hitAreas', 'lipSync'])
+/** frames2d block field allow-list (drift-locked to the schema file). */
+export const KNOWN_FRAMES2D = new Set(['dir', 'defaultFrameMs', 'tracks', 'phases'])
+/** frames2d track field allow-list (drift-locked to the schema file). */
+export const KNOWN_FRAMES2D_TRACK = new Set(['frames', 'frameMs', 'loop', 'fallback'])
 
 class Diagnostics {
   readonly list: PetManifestDiagnostic[] = []
@@ -293,6 +331,129 @@ function parseLive2dBlock(raw: unknown, diag: Diagnostics): PetManifestLive2d |
   return diag.hasErrors ? undefined : block
 }
 
+const FRAMES2D_TRACK_NAME = /^[a-z0-9][a-z0-9-]*$/
+const FRAMES2D_MAX_TRACKS = 64
+const FRAMES2D_MAX_FRAMES = 64
+const FRAMES2D_MIN_FRAME_MS = 16
+const FRAMES2D_MAX_FRAME_MS = 5_000
+const FRAMES2D_IMAGE_EXTENSIONS = new Set(['.webp', '.png', '.gif', '.jpg', '.jpeg'])
+
+/** Validate one frames2d track name (kebab id, at most 32 chars). */
+function validTrackName(name: string): boolean {
+  return name.length <= 32 && FRAMES2D_TRACK_NAME.test(name)
+}
+
+/** A frames2d frame entry is a single image file name inside the track directory. */
+function safeFrameName(raw: unknown): string | undefined {
+  if (typeof raw !== 'string' || raw.trim() === '') return undefined
+  const value = raw.trim()
+  if (value.includes('/') || value.includes('\\') || !PATH_SEGMENT_PATTERN.test(value)) return undefined
+  const dot = value.lastIndexOf('.')
+  if (dot <= 0) return undefined
+  if (!FRAMES2D_IMAGE_EXTENSIONS.has(value.slice(dot).toLowerCase())) return undefined
+  return value
+}
+
+function parseFrames2dTrack(raw: unknown, field: string, diag: Diagnostics): PetManifestFrames2dTrack | undefined {
+  if (!isRecord(raw)) {
+    diag.error(field + ' must be an object')
+    return undefined
+  }
+  const extra = unknownKeys(raw, KNOWN_FRAMES2D_TRACK)
+  if (extra.length > 0) diag.error(field + ': unknown field(s) ' + extra.map(k => JSON.stringify(k)).join(', '))
+  const track: PetManifestFrames2dTrack = {}
+  if (raw.frames !== undefined) {
+    if (!Array.isArray(raw.frames) || raw.frames.length === 0) {
+      diag.error(field + '.frames must be a non-empty array of frame file names')
+    } else if (raw.frames.length > FRAMES2D_MAX_FRAMES) {
+      diag.error(field + '.frames declares too many frames (' + raw.frames.length + ', max ' + FRAMES2D_MAX_FRAMES + ')')
+    } else {
+      const frames: string[] = []
+      for (const entry of raw.frames) {
+        const safe = safeFrameName(entry)
+        if (safe === undefined) diag.error(field + '.frames entry ' + JSON.stringify(String(entry)) + ' is not a safe image file name')
+        else frames.push(safe)
+      }
+      if (frames.length === (raw.frames as unknown[]).length) track.frames = frames
+    }
+  }
+  if (raw.frameMs !== undefined) {
+    if (!Array.isArray(raw.frameMs) || raw.frameMs.length === 0
+      || raw.frameMs.some(v => typeof v !== 'number' || !Number.isInteger(v) || v < FRAMES2D_MIN_FRAME_MS || v > FRAMES2D_MAX_FRAME_MS)) {
+      diag.error(field + '.frameMs must be a non-empty array of integer ms in [' + FRAMES2D_MIN_FRAME_MS + ', ' + FRAMES2D_MAX_FRAME_MS + ']')
+    } else if (track.frames === undefined) {
+      diag.error(field + '.frameMs requires a valid explicit frames list (directory tracks use filename-encoded ms or defaultFrameMs)')
+    } else if (raw.frameMs.length !== track.frames.length) {
+      diag.error(field + '.frameMs must have the same length as frames')
+    } else {
+      track.frameMs = raw.frameMs as number[]
+    }
+  }
+  if (raw.loop !== undefined) {
+    if (typeof raw.loop !== 'boolean') diag.error(field + '.loop must be a boolean')
+    else track.loop = raw.loop
+  }
+  if (raw.fallback !== undefined) {
+    if (typeof raw.fallback !== 'string' || !validTrackName(raw.fallback)) diag.error(field + '.fallback must be a track name')
+    else track.fallback = raw.fallback
+  }
+  return diag.hasErrors ? undefined : track
+}
+
+function parseFrames2dBlock(raw: unknown, diag: Diagnostics): PetManifestFrames2d | undefined {
+  if (!isRecord(raw)) {
+    diag.error('renderer frames2d requires a "frames2d" block object')
+    return undefined
+  }
+  const extra = unknownKeys(raw, KNOWN_FRAMES2D)
+  if (extra.length > 0) diag.error('frames2d: unknown field(s) ' + extra.map(k => JSON.stringify(k)).join(', '))
+  const block: PetManifestFrames2d = { tracks: {}, phases: { idle: '' } }
+  if (raw.dir !== undefined) {
+    const dir = safeManifestPath(raw.dir)
+    if (dir === undefined) diag.error('frames2d.dir must be a safe manifest-relative directory')
+    else block.dir = dir
+  }
+  if (raw.defaultFrameMs !== undefined) {
+    if (typeof raw.defaultFrameMs !== 'number' || !Number.isInteger(raw.defaultFrameMs) || raw.defaultFrameMs < FRAMES2D_MIN_FRAME_MS || raw.defaultFrameMs > FRAMES2D_MAX_FRAME_MS) {
+      diag.error('frames2d.defaultFrameMs must be an integer in [' + FRAMES2D_MIN_FRAME_MS + ', ' + FRAMES2D_MAX_FRAME_MS + ']')
+    } else block.defaultFrameMs = raw.defaultFrameMs
+  }
+  const tracks: Record<string, PetManifestFrames2dTrack> = {}
+  if (!isRecord(raw.tracks)) {
+    diag.error('frames2d.tracks is required and must be an object keyed by track name')
+  } else {
+    const entries = Object.entries(raw.tracks)
+    if (entries.length === 0) diag.error('frames2d.tracks must declare at least one track')
+    if (entries.length > FRAMES2D_MAX_TRACKS) diag.error('frames2d.tracks declares too many tracks (' + entries.length + ', max ' + FRAMES2D_MAX_TRACKS + ')')
+    for (const [name, value] of entries) {
+      if (!validTrackName(name)) {
+        diag.error('frames2d.tracks: invalid track name ' + JSON.stringify(name) + ' (lowercase kebab, at most 32 chars)')
+        continue
+      }
+      const track = parseFrames2dTrack(value, 'frames2d.tracks.' + name, diag)
+      if (track !== undefined) tracks[name] = track
+    }
+  }
+  block.tracks = tracks
+  const phases = parsePhaseStringMap(raw.phases, 'frames2d.phases', diag)
+  if (raw.phases === undefined) diag.error('frames2d.phases is required (at least an "idle" mapping)')
+  else if (phases !== undefined && phases.idle === undefined) diag.error('frames2d.phases.idle is required (unmapped phases fall back to it)')
+  const phasesValid = phases !== undefined && phases.idle !== undefined
+  if (phasesValid) block.phases = phases as PetManifestFrames2d['phases']
+  // Dangling references (phases/fallback) are structure: fail closed.
+  if (phasesValid) {
+    for (const [phase, target] of Object.entries(block.phases)) {
+      if (target !== undefined && tracks[target] === undefined) diag.error('frames2d.phases.' + phase + ' references unknown track ' + JSON.stringify(target))
+    }
+  }
+  for (const [name, track] of Object.entries(tracks)) {
+    if (track.fallback !== undefined && tracks[track.fallback] === undefined) {
+      diag.error('frames2d.tracks.' + name + '.fallback references unknown track ' + JSON.stringify(track.fallback))
+    }
+  }
+  return diag.hasErrors ? undefined : block
+}
+
 /** v1 compat read: map the legacy flat manifest onto the v2 sprite2d shape. */
 function compatV1(source: Record<string, unknown>, diag: Diagnostics): PetManifestV2 | undefined {
   const id = parseStringBlock(source, 'id', diag, true)
@@ -377,10 +538,28 @@ function parseV2(source: Record<string, unknown>, diag: Diagnostics): PetManifes
     const block = parseSprite2dBlock(source.sprite2d, diag)
     if (block !== undefined) manifest.sprite2d = block
     if (source.live2d !== undefined) diag.error('renderer sprite2d must not declare a live2d block')
+    if (source.frames2d !== undefined) diag.error('renderer sprite2d must not declare a frames2d block')
   } else if (renderer === 'live2d') {
     const block = parseLive2dBlock(source.live2d, diag)
     if (block !== undefined) manifest.live2d = block
     if (source.sprite2d !== undefined) diag.error('renderer live2d must not declare a sprite2d block')
+    if (source.frames2d !== undefined) diag.error('renderer live2d must not declare a frames2d block')
+  } else if (renderer === 'frames2d') {
+    const block = parseFrames2dBlock(source.frames2d, diag)
+    if (block !== undefined) manifest.frames2d = block
+    if (source.sprite2d !== undefined) diag.error('renderer frames2d must not declare a sprite2d block')
+    if (source.live2d !== undefined) diag.error('renderer frames2d must not declare a live2d block')
+  }
+  if (source.gameplay !== undefined) {
+    if (renderer !== 'frames2d') {
+      diag.error('gameplay currently requires renderer frames2d (its state references name frames2d tracks)')
+    } else {
+      const gameplay = parseGameplayManifest(source.gameplay, {
+        stateNames: new Set(Object.keys(manifest.frames2d?.tracks ?? {})),
+        error: (message) => diag.error('gameplay: ' + message),
+      })
+      if (gameplay !== undefined) manifest.gameplay = gameplay
+    }
   }
   const sequences = parseSequences(source.sequences, diag)
   if (sequences !== undefined) manifest.sequences = sequences

package/src/mount-once.ts

@@ -1,7 +1,7 @@
 // Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Host single-instance guard shared by the plugin family. The family bundle
- * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * (dsh-web-all / dsh-skins) namespaces every child row id (web-ui-*), so
  * the loader accepts a standalone install of the same package side by side;
  * without this guard the second instance would still re-register the same
  * webserver routes, tools, settings namespaces, and system-prompt sections
@@ -15,7 +15,7 @@
  * return value as the fiber disposer, so the unmarker is returned, not run.
  */
 
-const MOUNTED = Symbol.for('dsh-web-ui.mounted-plugins')
+const MOUNTED = Symbol.for('dsh-web.mounted-plugins')
 
 interface MountRegistry {
   [MOUNTED]?: Set<string>

package/src/persist.test.ts

@@ -52,6 +52,9 @@ describe('loadPetPersist', () => {
         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 },
+        gameplay: {
+          otter: { stats: { hunger: 55.5 }, currencies: { coins: 12 }, mode: 'work' as const, settledAt: 777 },
+        },
       }
       savePetPersist(data, dir)
       expect(loadPetPersist(dir)).toEqual(data)

package/src/persist.ts

@@ -10,6 +10,10 @@ import { join } from 'node:path'
 import { dshHome } from './dsh-home.ts'
 import { AFFINITY_MAX, emptyAffinity, type AffinityState } from './affinity.ts'
 import { defaultTreatConfig, emptyTreatLedger, type TreatLedger } from './treats.ts'
+import { DEFAULT_PET_ID, DEFAULT_PET_NAME } from './defaults.ts'
+import type { PetGameplayState } from './gameplay.ts'
+
+export { DEFAULT_PET_ID, DEFAULT_PET_NAME } from './defaults.ts'
 
 /** Display configuration the user can tweak. */
 export interface PetDisplayConfig {
@@ -48,14 +52,10 @@ export interface PetPersist {
   /** Treat (小鱼干) stock ledger. */
   treats: TreatLedger
   display: PetDisplayConfig
+  /** Per-pet gameplay state (stats/currencies/mode), keyed by pet id. */
+  gameplay: Record<string, PetGameplayState>
 }
 
-/** Pet id the legacy single-pet installs resolve to on migration. */
-export const DEFAULT_PET_ID = 'whale-girl'
-
-/** Default pet name (used only when a manifest carries no displayName). */
-export const DEFAULT_PET_NAME = '鲸鱼娘'
-
 /** Name constraints. */
 export const PET_NAME_MAX_LENGTH = 20
 
@@ -66,6 +66,7 @@ export function emptyPersist(): PetPersist {
     affinity: emptyAffinity(),
     treats: emptyTreatLedger(),
     display: { ...defaultDisplayConfig },
+    gameplay: {},
   }
 }
 
@@ -104,6 +105,41 @@ function clamp(value: number, max: number): number {
   return Math.min(max, Math.max(0, value))
 }
 
+/** Absolute numeric ceilings applied at load (manifest clamps refine these). */
+const GAMEPLAY_LOAD_STAT_CAP = 1_000_000
+const GAMEPLAY_LOAD_CURRENCY_CAP = 9_999_999
+
+/** Sanitize the persisted per-pet gameplay map. */
+function loadGameplay(parsed: PetPersistDocument): Record<string, PetGameplayState> {
+  const result: Record<string, PetGameplayState> = {}
+  if (typeof parsed.gameplay !== 'object' || parsed.gameplay === null) return result
+  for (const [petId, raw] of Object.entries(parsed.gameplay as Record<string, unknown>)) {
+    if (petId === '' || typeof raw !== 'object' || raw === null) continue
+    const record = raw as Partial<PetGameplayState>
+    const stats: Record<string, number> = {}
+    if (typeof record.stats === 'object' && record.stats !== null) {
+      for (const [key, value] of Object.entries(record.stats)) {
+        if (key === '' || typeof value !== 'number' || !Number.isFinite(value)) continue
+        stats[key] = Math.min(GAMEPLAY_LOAD_STAT_CAP, Math.max(0, value))
+      }
+    }
+    const currencies: Record<string, number> = {}
+    if (typeof record.currencies === 'object' && record.currencies !== null) {
+      for (const [key, value] of Object.entries(record.currencies)) {
+        if (key === '' || typeof value !== 'number' || !Number.isFinite(value)) continue
+        currencies[key] = Math.min(GAMEPLAY_LOAD_CURRENCY_CAP, Math.max(0, Math.floor(value)))
+      }
+    }
+    result[petId] = {
+      stats,
+      currencies,
+      mode: record.mode === 'work' || record.mode === 'sleep' ? record.mode : null,
+      settledAt: clamp(finiteNum(record.settledAt, 0), Number.MAX_SAFE_INTEGER),
+    }
+  }
+  return result
+}
+
 /** Load persisted state; missing or corrupt files fall back to defaults. */
 export function loadPetPersist(dir: string = petHomeDir()): PetPersist {
   try {
@@ -152,6 +188,7 @@ export function loadPetPersist(dir: string = petHomeDir()): PetPersist {
       affinity,
       treats,
       display,
+      gameplay: loadGameplay(parsed),
     }
   } catch {
     return emptyPersist()