@linxin666/dsh-pet 0.3.3 → 0.3.5

package/src/registry.test.ts

@@ -152,18 +152,185 @@ describe('resolvePetManifest', () => {
   })
 })
 
+describe('loadPetRegistry frames2d', () => {
+  /** Write a frames2d pet fixture: pet.json + thumb/<track>/<frame> files. */
+  function writeFrames2dPet(root: string, id: string, manifest: Record<string, unknown>, files: Record<string, string[]>): string {
+    const dir = join(root, 'assets', id)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'pet.json'), JSON.stringify({
+      petManifestVersion: 2,
+      id,
+      displayName: id,
+      license: 'MIT',
+      renderer: 'frames2d',
+      ...manifest,
+    }), 'utf8')
+    for (const [trackDir, frames] of Object.entries(files)) {
+      mkdirSync(join(dir, trackDir), { recursive: true })
+      for (const frame of frames) writeFileSync(join(dir, trackDir, frame), 'webp', 'utf8')
+    }
+    return dir
+  }
+
+  it('resolves directory-listed tracks with filename-encoded durations', () => {
+    const root = tempDir()
+    try {
+      writeFrames2dPet(root, 'miku', {
+        frames2d: {
+          dir: 'thumb',
+          tracks: { idle: { loop: true }, happy: { loop: false } },
+          phases: { idle: 'idle', done: 'happy' },
+        },
+      }, {
+        'thumb/idle': ['miku_1_200.webp', 'miku_2_260.webp'],
+        'thumb/happy': ['miku-happy_1_300.webp'],
+      })
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      const entry = registry.byId('miku')
+      expect(entry?.renderer).toBe('frames2d')
+      expect(entry?.frames2d?.phases).toEqual({ idle: 'idle', done: 'happy' })
+      expect(entry?.frames2d?.tracks.idle).toMatchObject({ loop: true, durations: [200, 260] })
+      expect(entry?.frames2d?.tracks.idle?.frames).toEqual([
+        '/pet/miku/thumb/idle/miku_1_200.webp',
+        '/pet/miku/thumb/idle/miku_2_260.webp',
+      ])
+      expect(entry?.frames2d?.tracks.happy).toMatchObject({ loop: false, fallback: 'idle', durations: [300] })
+      expect([...(entry?.servable ?? [])].sort()).toEqual([
+        'thumb/happy/miku-happy_1_300.webp',
+        'thumb/idle/miku_1_200.webp',
+        'thumb/idle/miku_2_260.webp',
+      ])
+      expect(entry?.atlasUrl).toBe('/pet/miku/thumb/idle/miku_1_200.webp')
+      // The browser view carries the frames2d block.
+      const view = petEntryView(entry!)
+      expect(view.frames2d?.tracks.idle?.frames).toHaveLength(2)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('orders directory-scanned frames by their trailing index (10+ frames)', () => {
+    const root = tempDir()
+    try {
+      const names = Array.from({ length: 12 }, (_, index) => 'miku-pet-eat' + String(index + 1) + '.webp')
+      writeFrames2dPet(root, 'miku', {
+        frames2d: { dir: 'thumb', tracks: { eat: { loop: false } }, phases: { idle: 'eat' } },
+      }, { 'thumb/eat': names })
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      const frames = registry.byId('miku')?.frames2d?.tracks.eat?.frames ?? []
+      expect(frames).toHaveLength(12)
+      expect(frames[1]).toBe('/pet/miku/thumb/eat/miku-pet-eat2.webp')
+      expect(frames[9]).toBe('/pet/miku/thumb/eat/miku-pet-eat10.webp')
+      expect(frames[11]).toBe('/pet/miku/thumb/eat/miku-pet-eat12.webp')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('honours explicit frames order and frameMs over filename-encoded durations', () => {
+    const root = tempDir()
+    try {
+      writeFrames2dPet(root, 'fox', {
+        frames2d: {
+          dir: 'thumb',
+          tracks: { idle: { frames: ['b_100.webp', 'a_100.webp'], frameMs: [111, 222], loop: true } },
+          phases: { idle: 'idle' },
+        },
+      }, { 'thumb/idle': ['a_100.webp', 'b_100.webp'] })
+      const entry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' }).byId('fox')
+      expect(entry?.frames2d?.tracks.idle?.frames).toEqual([
+        '/pet/fox/thumb/idle/b_100.webp',
+        '/pet/fox/thumb/idle/a_100.webp',
+      ])
+      expect(entry?.frames2d?.tracks.idle?.durations).toEqual([111, 222])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('drops an empty track and remaps its phases to idle with a warning', () => {
+    const root = tempDir()
+    try {
+      writeFrames2dPet(root, 'miku', {
+        frames2d: {
+          dir: 'thumb',
+          tracks: { idle: {}, work: {} },
+          phases: { idle: 'idle', thinking: 'work' },
+        },
+      }, { 'thumb/idle': ['miku_1_200.webp'] })
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      const entry = registry.byId('miku')
+      expect(entry?.frames2d?.tracks.work).toBeUndefined()
+      expect(entry?.frames2d?.phases.thinking).toBe('idle')
+      expect(registry.warnings.some(warning => warning.includes('work'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects the entry fail-closed when the idle track has no frames on disk', () => {
+    const root = tempDir()
+    try {
+      writeFrames2dPet(root, 'miku', {
+        frames2d: {
+          dir: 'thumb',
+          tracks: { idle: {}, happy: {} },
+          phases: { idle: 'idle', done: 'happy' },
+        },
+      }, { 'thumb/happy': ['miku_1_200.webp'] })
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      expect(registry.byId('miku')).toBeUndefined()
+      expect(registry.diagnostics.some(d => d.level === 'error' && d.message.includes('idle'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('warns and skips a missing explicit frame', () => {
+    const root = tempDir()
+    try {
+      writeFrames2dPet(root, 'miku', {
+        frames2d: {
+          dir: 'thumb',
+          tracks: { idle: { frames: ['a_100.webp', 'gone_100.webp'] } },
+          phases: { idle: 'idle' },
+        },
+      }, { 'thumb/idle': ['a_100.webp'] })
+      const registry = loadPetRegistry({ packageRoot: root, petsDir: '', dshPetsDir: '' })
+      const entry = registry.byId('miku')
+      expect(entry?.frames2d?.tracks.idle?.frames).toEqual(['/pet/miku/thumb/idle/a_100.webp'])
+      expect(registry.warnings.some(warning => warning.includes('gone_100.webp'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+
 describe('loadPetRegistry', () => {
-  it('ships the original and refined whale variants while keeping the original default', () => {
+  it('ships every built-in pet while keeping the original whale as default', () => {
     const registry = loadPetRegistry({
       packageRoot: petPackageRoot(import.meta.url),
       petsDir: '',
       dshPetsDir: '',
     })
 
+    // The repo checkout also resolves miku (frames2d gameplay pet) from
+    // assets/; the npm files whitelist excludes it (Workshop delivery), so
+    // npm installs see the three atlas pets until a Workshop install lands
+    // miku under $DSH_HOME/pets.
     expect(registry.entries.map(entry => entry.id)).toEqual([
+      'miku',
+      'ouo-neko',
       'whale-girl',
       'whale-girl-refined',
     ])
+    expect(registry.byId('ouo-neko')).toMatchObject({
+      displayName: 'OUO Neko',
+      atlasRows: 11,
+      columns: 8,
+      rows: [6, 8, 8, 4, 5, 8, 6, 6, 6],
+    })
+    expect(existsSync(petAtlasFile(registry.byId('ouo-neko')!))).toBe(true)
     expect(registry.byId('whale-girl')?.displayName).toBe('鲸鱼娘（原版）')
     expect(registry.byId('whale-girl-refined')?.displayName).toBe('鲸鱼娘（精致版）')
     expect(existsSync(petAtlasFile(registry.byId('whale-girl-refined')!))).toBe(true)

package/src/registry.ts

@@ -39,7 +39,9 @@ import { imageDimensions } from './image-dimensions.ts'
 import { PET_DECORATION_API_VERSION, type DecorationView } from './contracts/status-decoration.ts'
 import { dshHome } from './dsh-home.ts'
 import { parsePetManifest, type PetManifestLive2d, type PetManifestV2, type PetRendererKind } from './manifest-v2.ts'
+import type { PetGameplayManifest } from './gameplay.ts'
 import { collectModel3References } from './model3.ts'
+import { DEFAULT_PET_ID } from './defaults.ts'
 
 /** Fixed row order of the 9-state animation contract. */
 export const PET_ROW_ORDER: readonly PetAnimation[] = [
@@ -195,6 +197,26 @@ export interface PetLive2dDefinition {
   hitAreas?: string[]
 }
 
+/** One frames2d track as served to the browser half. */
+export interface PetFrames2dTrackView {
+  /** Browser URLs of the frames in play order. */
+  frames: string[]
+  /** Per-frame durations in ms; same length as frames. */
+  durations: number[]
+  /** Whether the track loops; a non-looping track ends into fallback. */
+  loop: boolean
+  /** Track entered when a non-looping track finishes (defaults to the idle track). */
+  fallback?: string
+}
+
+/** The frames2d renderer block as served to the browser half. */
+export interface PetFrames2dDefinition {
+  /** Named tracks keyed by track id. */
+  tracks: Record<string, PetFrames2dTrackView>
+  /** ActivityPhase -> track id; unmapped phases fall back to idle. */
+  phases: Partial<Record<ActivityPhase, string>> & { idle: string }
+}
+
 /** A normalized pet as served to the browser half. */
 export interface PetDefinition {
   id: string
@@ -204,6 +226,14 @@ export interface PetDefinition {
   renderer: PetRendererKind
   /** Live2d render block; present exactly when renderer is 'live2d' (M3). */
   live2d?: PetLive2dDefinition
+  /** Frames2d render block; present exactly when renderer is 'frames2d'. */
+  frames2d?: PetFrames2dDefinition
+  /**
+   * The pet's gameplay layer (miku-pet generalization), present when the
+   * manifest declares 'gameplay'. Shop item images are served as browser
+   * URLs; every other field is the validated manifest block verbatim.
+   */
+  gameplay?: PetGameplayManifest
   /** Atlas cell size in px. */
   cell: PetCell
   /** Columns per row. */
@@ -580,6 +610,168 @@ function resolveLive2dEntry(
   }
 }
 
+/** Filename-encoded frame duration tail ('<base>_<index>_<ms>.webp'). */
+const FRAMES2D_FILENAME_MS = /_(\d+)\.[^.]+$/
+/** Trailing frame index, allowing an optional '_<ms>' duration tail after it. */
+const FRAMES2D_FRAME_INDEX = /(\d+)(?:_\d+)?\.[^.]+$/
+/** Default per-frame duration when neither frameMs nor the filename encodes one. */
+const FRAMES2D_DEFAULT_FRAME_MS = 200
+/** Image extensions a frames2d track directory may list. */
+const FRAMES2D_IMAGE_EXTENSIONS = new Set(['.webp', '.png', '.gif', '.jpg', '.jpeg'])
+
+/**
+ * Resolve a validated frames2d manifest into a renderable entry. Track frame
+ * lists come from the manifest's explicit list or from listing
+ * '<dir>/<track>/' in filename order; durations resolve frameMs[i] >
+ * filename-encoded '_<ms>' tail > defaultFrameMs. Missing frames warn and
+ * skip (the live2d closure discipline); a track left with zero frames is
+ * dropped, and if the idle-mapped track ends up empty the entry is rejected
+ * fail-closed. The sprite fields carry contract defaults: the chrome sizes
+ * frames2d pets off 'display.size', not the atlas.
+ */
+function resolveFrames2dEntry(
+  manifest: PetManifestV2,
+  dir: string,
+  options: { assetPrefix?: string; warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] },
+): PetEntry | undefined {
+  const assetPrefix = options.assetPrefix ?? '/pet'
+  const record = (level: 'error' | 'warning', message: string): void => {
+    options.diagnostics?.push({ level, source: dir, message })
+    options.warnings?.push(message)
+  }
+  const block = manifest.frames2d
+  if (block === undefined) {
+    record('error', 'pet ' + manifest.id + ': renderer frames2d requires a frames2d block')
+    return undefined
+  }
+  const root = block.dir ?? '.'
+  const defaultMs = block.defaultFrameMs ?? FRAMES2D_DEFAULT_FRAME_MS
+  const idleTrack = block.phases.idle
+  const tracks: Record<string, PetFrames2dTrackView> = {}
+  const servable: string[] = []
+  const firstFrameRel: Record<string, string> = {}
+  for (const [name, track] of Object.entries(block.tracks)) {
+    const trackDir = root === '.' ? name : root + '/' + name
+    let relFrames: string[] = []
+    if (track.frames !== undefined) {
+      for (const frame of track.frames) {
+        const rel = trackDir + '/' + frame
+        if (!existsSync(join(dir, rel))) {
+          record('warning', 'pet ' + manifest.id + ': frames2d frame missing: ' + rel)
+          continue
+        }
+        relFrames.push(rel)
+      }
+    } else {
+      let files: string[] = []
+      try {
+        files = readdirSync(join(dir, trackDir)).filter(file => {
+          if (file.startsWith('.')) return false
+          const dot = file.lastIndexOf('.')
+          return dot > 0 && FRAMES2D_IMAGE_EXTENSIONS.has(file.slice(dot).toLowerCase())
+        })
+      } catch {
+        files = []
+      }
+      // Natural frame order: the trailing index (before any _<ms> duration
+      // suffix) sorts numerically, so 'eat10' comes after 'eat9' — plain
+      // lexicographic order would break any track with 10+ frames.
+      files.sort((a, b) => {
+        const ia = FRAMES2D_FRAME_INDEX.exec(a)?.[1]
+        const ib = FRAMES2D_FRAME_INDEX.exec(b)?.[1]
+        if (ia !== undefined && ib !== undefined && ia !== ib) return Number(ia) - Number(ib)
+        return a < b ? -1 : a > b ? 1 : 0
+      })
+      relFrames = files.map(file => trackDir + '/' + file)
+    }
+    if (relFrames.length === 0) {
+      record('warning', 'pet ' + manifest.id + ': frames2d track ' + JSON.stringify(name) + ' has no frames on disk; dropped')
+      continue
+    }
+    const durations = relFrames.map((rel, index) => {
+      if (track.frameMs !== undefined) return track.frameMs[index] ?? defaultMs
+      const match = FRAMES2D_FILENAME_MS.exec(rel)
+      if (match !== null) {
+        const ms = Number(match[1])
+        if (Number.isInteger(ms) && ms >= 16 && ms <= 5000) return ms
+      }
+      return defaultMs
+    })
+    const loop = track.loop ?? true
+    const view: PetFrames2dTrackView = {
+      frames: relFrames.map(rel => assetUrl(assetPrefix, manifest.id, rel)),
+      durations,
+      loop,
+      ...(loop ? {} : { fallback: track.fallback ?? idleTrack }),
+    }
+    tracks[name] = view
+    firstFrameRel[name] = relFrames[0]!
+    servable.push(...relFrames)
+  }
+  if (tracks[idleTrack] === undefined) {
+    record('error', 'pet ' + manifest.id + ': frames2d idle track ' + JSON.stringify(idleTrack) + ' has no frames on disk')
+    return undefined
+  }
+  const phases = { ...block.phases }
+  for (const [phase, target] of Object.entries(phases)) {
+    if (target !== undefined && tracks[target] === undefined) {
+      record('warning', 'pet ' + manifest.id + ': frames2d phase ' + phase + ' maps to dropped track ' + JSON.stringify(target) + '; using idle')
+      phases[phase as ActivityPhase] = idleTrack
+    }
+  }
+  const remarks = normalizePetRemarks(manifest.remarks, message => record('warning', 'pet ' + manifest.id + ': ' + message))
+  // Gameplay layer: shop item icons are manifest-relative frame paths —
+  // verify them, promote them to browser URLs, and add them to the servable
+  // allow-list so the asset route can serve them.
+  let gameplay: PetGameplayManifest | undefined
+  if (manifest.gameplay !== undefined) {
+    gameplay = manifest.gameplay
+    if (gameplay.shop !== undefined) {
+      const items = []
+      for (const item of gameplay.shop.items) {
+        if (item.image === undefined) {
+          items.push(item)
+          continue
+        }
+        if (!existsSync(join(dir, item.image))) {
+          record('warning', 'pet ' + manifest.id + ': gameplay shop item ' + item.id + ' image missing: ' + item.image)
+          const { image, ...rest } = item
+          items.push(rest)
+          continue
+        }
+        servable.push(item.image)
+        items.push({ ...item, image: assetUrl(assetPrefix, manifest.id, item.image) })
+      }
+      gameplay = { ...gameplay, shop: { ...gameplay.shop, items } }
+    }
+  }
+  const flatTracks = buildTracks(DEFAULT_FRAME_COUNTS, DEFAULT_PET_COLUMNS, {}, message => record('warning', 'pet ' + manifest.id + ': ' + message))
+  if (flatTracks === undefined) return undefined
+  // The render box comes from the first idle frame when decodable.
+  const firstAbs = join(dir, firstFrameRel[idleTrack]!)
+  const dims = existsSync(firstAbs) ? readImageDimensions(firstAbs) : undefined
+  const cell = dims !== undefined && dims.width >= 1 && dims.height >= 1 ? dims : { ...DEFAULT_PET_CELL }
+  return {
+    id: manifest.id,
+    displayName: manifest.displayName,
+    description: manifest.description ?? '',
+    renderer: 'frames2d' as const,
+    frames2d: { tracks, phases },
+    ...(gameplay === undefined ? {} : { gameplay }),
+    cell,
+    columns: DEFAULT_PET_COLUMNS,
+    rows: [...DEFAULT_FRAME_COUNTS],
+    atlasRows: DEFAULT_PET_ROW_COUNT,
+    tracks: flatTracks,
+    atlasUrl: tracks[idleTrack]!.frames[0]!,
+    manifestUrl: assetUrl(assetPrefix, manifest.id, 'pet.json'),
+    dir,
+    spritesheetPath: firstFrameRel[idleTrack]!,
+    servable,
+    ...(remarks === undefined ? {} : { remarks }),
+  }
+}
+
 /** Scan one directory of pet folders; entries come back in name order. */
 function scanPetDir(dir: string, options: { assetPrefix?: string; warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] }): PetEntry[] {
   if (!existsSync(dir)) return []
@@ -606,6 +798,8 @@ function scanPetDir(dir: string, options: { assetPrefix?: string; warnings?: str
     let entry: PetEntry | undefined
     if (verdict.manifest.renderer === 'live2d') {
       entry = resolveLive2dEntry(verdict.manifest, entryDir, options)
+    } else if (verdict.manifest.renderer === 'frames2d') {
+      entry = resolveFrames2dEntry(verdict.manifest, entryDir, options)
     } else {
       const legacy = flattenV2Sprite2d(verdict.manifest)
       if (legacy === undefined) {
@@ -907,7 +1101,9 @@ export function loadPetRegistry(options: PetRegistryOptions): PetRegistry {
     warnings,
     diagnostics,
     byId: (id: string) => byId.get(id),
-    defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0]!,
+    defaultEntry: () => entries.find(entry => (
+      entry.id === DEFAULT_PET_ID && builtinIds.has(entry.id)
+    )) ?? entries.find(entry => builtinIds.has(entry.id)) ?? entries[0]!,
     ...(globalVoice === undefined ? {} : { globalVoice }),
     decorations,
     decorationById: (id: string) => decorationById.get(id),
@@ -948,6 +1144,8 @@ export function petEntryView(entry: PetEntry, globalVoice?: VoicePack): PetDefin
     description: entry.description,
     renderer: entry.renderer,
     ...(entry.live2d === undefined ? {} : { live2d: entry.live2d }),
+    ...(entry.frames2d === undefined ? {} : { frames2d: entry.frames2d }),
+    ...(entry.gameplay === undefined ? {} : { gameplay: entry.gameplay }),
     cell: entry.cell,
     columns: entry.columns,
     rows: entry.rows,

package/src/routes.ts

@@ -112,15 +112,15 @@ function guard(ctx: Context, req: IncomingMessage, res: ServerResponse): boolean
   return false
 }
 
-/** Wrap one async service call as a GET JSON route. */
-function getRoute(ctx: Context, path: string, run: () => Promise<unknown>): WebRoute {
+/** Wrap one async service call as a GET JSON route (request passed through for query params). */
+function getRoute(ctx: Context, path: string, run: (req: IncomingMessage) => Promise<unknown>): WebRoute {
   return {
     kind: 'exact',
     path,
     handler: (req: IncomingMessage, res: ServerResponse): void => {
       if (!guard(ctx, req, res)) return
       if (!requireMethod(req, res, 'GET')) return
-      run().then((value) => writeJson(res, 200, value), (error) => {
+      run(req).then((value) => writeJson(res, 200, value), (error) => {
         writeJson(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) })
       })
     },
@@ -525,7 +525,12 @@ function decorationHandler(ctx: Context, registry: PetRegistry, caps: PetAssetCa
 export function makePetRoutes(deps: { service: PetService; ctx: Context; assetCaps?: PetAssetCaps } & PetRuntimeRoots): WebRoute[] {
   const { service, ctx } = deps
   const apiRoutes: WebRoute[] = [
-    getRoute(ctx, PET_API_PREFIX + '/state', () => service.state()),
+    getRoute(ctx, PET_API_PREFIX + '/state', (req) => {
+      // The browser half reports the GUI's current session id so the bubble
+      // stack can lead with the session the user is actually looking at.
+      const current = new URL(req.url ?? '/', 'http://pet.local').searchParams.get('current')
+      return service.state(current === null || current === '' ? undefined : current)
+    }),
     getRoute(ctx, PET_API_PREFIX + '/pets', () => service.pets()),
     getRoute(ctx, PET_API_PREFIX + '/diagnostics', () => service.diagnostics()),
     postRoute(ctx, PET_API_PREFIX + '/interact', (body) => {
@@ -554,6 +559,25 @@ export function makePetRoutes(deps: { service: PetService; ctx: Context; assetCa
       if (typeof petId !== 'string') return Promise.reject(new Error('invalid-pet'))
       return service.setPetId(petId)
     }),
+    // Gameplay verbs (miku-pet generalization): touch rolls a named zone's
+    // branch; the omitted-zone form is the plain-click boost during a touch
+    // animation. Mode/tick/buy drive the work, sleep and shop loops.
+    postRoute(ctx, PET_API_PREFIX + '/gameplay/touch', (body) => {
+      const zone = body.zone
+      if (zone !== undefined && typeof zone !== 'string') return Promise.reject(new Error('invalid-zone'))
+      return service.gameplayTouch(zone)
+    }),
+    postRoute(ctx, PET_API_PREFIX + '/gameplay/mode', (body) => {
+      const mode = body.mode
+      if (mode !== null && mode !== 'work' && mode !== 'sleep') return Promise.reject(new Error('invalid-mode'))
+      return service.gameplaySetMode(mode)
+    }),
+    postRoute(ctx, PET_API_PREFIX + '/gameplay/work-tick', () => service.gameplayWorkTick()),
+    postRoute(ctx, PET_API_PREFIX + '/gameplay/buy', (body) => {
+      const item = body.item
+      if (typeof item !== 'string') return Promise.reject(new Error('invalid-item'))
+      return service.gameplayBuy(item)
+    }),
   ]
 
   const assetRoute: WebRoute = {