@linxin666/dsh-pet 0.1.15 → 0.1.16

package/src/index.ts

@@ -1,9 +1,13 @@
 /**
  * dsh-pet host half — mounts the pet service and its HTTP routes. The
- * browser half (the `./client` entry) renders the whale-girl companion and
- * drives it through the same-origin `/api/pet/*` JSON endpoints plus the
- * `/pet/whale/*` media route. Install via `dsh plugin --profile web add
- * link:<dsh-web-ui>/packages/dsh-pet`; the cordis.patch.yml inserts this plugin row.
+ * browser half (the './client' entry) renders the selected pet and drives it
+ * through the same-origin '/api/pet/*' JSON endpoints plus the '/pet/<id>/*'
+ * media route. The host builds the multi-pet registry once at startup from
+ * 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
+ * cordis.patch.yml inserts this plugin row.
  * @module @linxin666/dsh-pet
  */
 
@@ -12,19 +16,15 @@ import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-sett
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import z from 'schemastery'
 import { PetService, PET_SETTINGS_NAMESPACE, type PetConfig, type PetSettingsSection } from './service.ts'
-import { makePetRoutes, petPackageRoot } from './routes.ts'
-import {
-  DEFAULT_PET_NAME,
-  DISPLAY_INSET_MAX,
-  DISPLAY_SIZE_MAX,
-  DISPLAY_SIZE_MIN,
-  PET_NAME_MAX_LENGTH,
-} from './persist.ts'
+import { makePetRoutes } from './routes.ts'
+import { loadPetRegistry, petPackageRoot } from './registry.ts'
+import { DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN } from './persist.ts'
 
 export { PetService } from './service.ts'
 export type {
   PetConfig,
   PetInteractResult,
+  PetSettingsSection,
   PetStateView,
 } from './service.ts'
 export {
@@ -61,6 +61,9 @@ export {
 } from './treats.ts'
 export type { TreatConfig, TreatLedger, TreatSettlement } from './treats.ts'
 export {
+  DEFAULT_PET_ID,
+  DEFAULT_PET_NAME,
+  PET_NAME_MAX_LENGTH,
   defaultDisplayConfig,
   emptyPersist,
   loadPetPersist,
@@ -68,10 +71,31 @@ export {
   savePetPersist,
 } from './persist.ts'
 export type { PetDisplayConfig, PetPersist } from './persist.ts'
+export {
+  DEFAULT_FRAME_COUNTS,
+  DEFAULT_PET_CELL,
+  DEFAULT_PET_COLUMNS,
+  DEFAULT_PET_ROW_COUNT,
+  DEFAULT_TRACK_PATTERNS,
+  PET_ROW_ORDER,
+  codexPetsDir,
+  loadPetRegistry,
+  petEntryView,
+  petPackageRoot,
+  resolvePetManifest,
+} from './registry.ts'
+export type {
+  PetDefinition,
+  PetEntry,
+  PetManifest,
+  PetRegistry,
+  PetRegistryOptions,
+  PetTrackDef,
+  PetTrackOverride,
+} from './registry.ts'
 
 export {
   makePetRoutes,
-  petPackageRoot,
   PET_API_PREFIX,
   PET_ASSET_PREFIX,
 } from './routes.ts'
@@ -82,43 +106,57 @@ export const name = 'pet'
 /** Services required before the pet can mount its surfaces. */
 export const inject = ['webServer']
 
-/** Settings section schema: the display fields and name the web settings surface edits. */
-export const PET_SETTINGS_SCHEMA = z.object({
-  visible: z.boolean().default(true),
-  size: z.number().step(1).min(DISPLAY_SIZE_MIN).max(DISPLAY_SIZE_MAX).default(160),
-  right: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(24),
-  bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
-  name: z.string().min(1).max(PET_NAME_MAX_LENGTH).pattern(/\S/).default(DEFAULT_PET_NAME),
-  enabled: z.boolean().default(true),
-})
+/**
+ * Settings section schema: pet selection and display fields the web settings
+ * surface edits. petId is a plain string on purpose: the service clamps the
+ * resolved value against the registry, so a stored selection that points at
+ * a removed pet cannot invalidate the section (a strict union would refuse
+ * the whole registration). The settings card renders the actual registry
+ * choices itself from '/api/pet/pets'.
+ */
+export function makePetSettingsSchema(fallbackPetId: string) {
+  return z.object({
+    visible: z.boolean().default(true),
+    size: z.number().step(1).min(DISPLAY_SIZE_MIN).max(DISPLAY_SIZE_MAX).default(160),
+    right: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(24),
+    bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
+    petId: z.string().default(fallbackPetId),
+    enabled: z.boolean().default(true),
+  })
+}
 
 /** Register the pet service and its API + asset routes on the context. */
 export function apply(ctx: Context, config: PetConfig = {}): void {
-  const service = new PetService(ctx, config)
+  const registry = config.registry
+    ?? loadPetRegistry({
+      packageRoot: petPackageRoot(import.meta.url),
+      ...(config.pets === undefined ? {} : { extra: config.pets }),
+    })
+  const service = new PetService(ctx, { ...config, registry })
 
-  // The settings surface edits the display config through the `pet`
-  // namespace. The composition `base` starts as the persisted pet.json
-  // values (clamped to schema bounds), so an empty user layer resolves to
-  // exactly what the pet already shows — a fresh deployment never
-  // overwrites a customized layout, and reset re-inherits it. Runtime drag
-  // interactions mirror back into the settings document through the service
-  // (see syncSettingsFromPet), keeping both views consistent.
+  // The settings surface edits the pet selection + display config through
+  // the 'pet' namespace. The composition 'base' starts as the persisted
+  // pet.json values (clamped to schema bounds), so an empty user layer
+  // resolves to exactly what the pet already shows — a fresh deployment
+  // never overwrites a customized layout, and reset re-inherits it. Runtime
+  // drag interactions mirror back into the settings document through the
+  // service (see syncSettingsFromPet), keeping both views consistent.
   let current: () => PetSettingsSection = () => base
   const base: PetSettingsSection = {
     visible: service.display().visible,
     size: service.display().size,
     right: service.display().right,
     bottom: service.display().bottom,
-    name: service.petName(),
+    petId: service.selectedPetId(),
     enabled: config.enabled ?? true,
   }
   // The browser half talks to the pet through same-origin JSON endpoints and
-  // loads the atlas from the pet's own media route (RPC domains are
-  // platform-registered, so the pet serves its own API — the same pattern as
-  // dsh-remote-web-ui's /api/pair family). The routes are registered while
-  // the plugin is enabled; toggling the setting off makes the pet API
-  // disappear until it is re-enabled.
-  const routes = makePetRoutes({ service, packageRoot: petPackageRoot(import.meta.url) })
+  // loads each pet's atlas from the registry's own media route (RPC domains
+  // are platform-registered, so the pet serves its own API — the same
+  // pattern as dsh-remote-web-ui's /api/pair family). The routes are
+  // registered while the plugin is enabled; toggling the setting off makes
+  // the pet API disappear until it is re-enabled.
+  const routes = makePetRoutes({ service })
   let disposeRoutes: (() => void) | undefined
   const syncRoutes = (): void => {
     const enabled = current().enabled ?? true
@@ -135,14 +173,20 @@ export function apply(ctx: Context, config: PetConfig = {}): void {
       disposeRoutes = undefined
     }
   }
-  installSettingsSection(ctx, settingsNamespace(PET_SETTINGS_NAMESPACE), PET_SETTINGS_SCHEMA, base, {
-    setSource: (source) => { current = source },
-    onChange: () => {
-      const section = current()
-      service.applySettingsSection(section)
-      service.setEnabled(section.enabled ?? true)
-      syncRoutes()
+  installSettingsSection(
+    ctx,
+    settingsNamespace(PET_SETTINGS_NAMESPACE),
+    makePetSettingsSchema(service.selectedPetId()),
+    base,
+    {
+      setSource: (source) => { current = source },
+      onChange: () => {
+        const section = current()
+        service.applySettingsSection(section)
+        service.setEnabled(section.enabled ?? true)
+        syncRoutes()
+      },
     },
-  })
+  )
   syncRoutes()
 }

package/src/ledger.test.ts

@@ -55,13 +55,15 @@ describe('PetLedger', () => {
     expect(ledger.takeDirty()).toBe(true)
   })
 
-  it('exposes the treat stock cap and display/name setters', () => {
+  it('exposes the treat stock cap and display/pet/name setters', () => {
     const ledger = new PetLedger(emptyPersist())
     expect(ledger.treatMax).toBe(defaultTreatConfig.maxTreats)
     ledger.setDisplay({ ...ledger.snapshot.display, visible: false })
-    ledger.setName('泡泡')
+    ledger.setPetId('otter')
+    ledger.setPetName('otter', '泡泡')
     expect(ledger.snapshot.display.visible).toBe(false)
-    expect(ledger.snapshot.name).toBe('泡泡')
+    expect(ledger.snapshot.petId).toBe('otter')
+    expect(ledger.snapshot.names).toEqual({ otter: '泡泡' })
     expect(ledger.takeDirty()).toBe(true)
   })
 })

package/src/ledger.ts

@@ -88,9 +88,16 @@ export class PetLedger {
     this.dirty = true
   }
 
-  /** Replace the pet display name (validation stays a caller concern). */
-  setName(name: string): void {
-    this.current = { ...this.current, name }
+  /** Replace the selected pet id (validation stays a caller concern). */
+  setPetId(petId: string): void {
+    if (this.current.petId === petId) return
+    this.current = { ...this.current, petId }
+    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 } }
     this.dirty = true
   }
 
@@ -161,7 +168,7 @@ export class PetLedger {
       const consume = consumeTreat(this.current.treats)
       if (!consume.ok) {
         return {
-          reaction: '没有小鱼干了，多陪鲸鱼娘工作一会儿吧～',
+          reaction: '没有小鱼干了，多陪我工作一会儿吧～',
           delta: 0,
           affinity: this.affinityView(nowMs),
         }

package/src/persist.test.ts

@@ -5,7 +5,7 @@ import { join } from 'node:path'
 import { AFFINITY_MAX, emptyAffinity } from './affinity.ts'
 import { defaultTreatConfig, emptyTreatLedger } from './treats.ts'
 import {
-  DEFAULT_PET_NAME,
+  DEFAULT_PET_ID,
   DISPLAY_INSET_MAX,
   DISPLAY_SIZE_MAX,
   DISPLAY_SIZE_MIN,
@@ -43,7 +43,8 @@ describe('loadPetPersist', () => {
     const dir = tempDir()
     try {
       const data = {
-        name: '泡泡',
+        petId: 'otter',
+        names: { otter: '泡泡', 'whale-girl': '鲸鱼娘' },
         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 },
@@ -55,17 +56,65 @@ describe('loadPetPersist', () => {
     }
   })
 
+  it('migrates the legacy flat name onto the legacy pet id', () => {
+    const dir = tempDir()
+    try {
+      writeFileSync(join(dir, 'pet.json'), JSON.stringify({
+        name: '泡泡',
+        affinity: { points: 5 },
+      }), 'utf8')
+      const loaded = loadPetPersist(dir)
+      expect(loaded.petId).toBe(DEFAULT_PET_ID)
+      expect(loaded.names).toEqual({ [DEFAULT_PET_ID]: '泡泡' })
+      expect(loaded.affinity.points).toBe(5)
+      expect(loaded.display).toEqual(defaultDisplayConfig)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('migrates the legacy flat name onto the persisted selection when both exist', () => {
+    const dir = tempDir()
+    try {
+      writeFileSync(join(dir, 'pet.json'), JSON.stringify({
+        petId: 'otter',
+        name: '水獭',
+      }), 'utf8')
+      const loaded = loadPetPersist(dir)
+      expect(loaded.petId).toBe('otter')
+      expect(loaded.names).toEqual({ otter: '水獭' })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps stored per-pet names when the legacy name is also present', () => {
+    const dir = tempDir()
+    try {
+      writeFileSync(join(dir, 'pet.json'), JSON.stringify({
+        name: '旧名字',
+        names: { [DEFAULT_PET_ID]: '新名字' },
+      }), 'utf8')
+      const loaded = loadPetPersist(dir)
+      expect(loaded.names[DEFAULT_PET_ID]).toBe('新名字')
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
   it('clamps out-of-range and non-numeric fields', () => {
     const dir = tempDir()
     try {
       writeFileSync(join(dir, 'pet.json'), JSON.stringify({
         name: '   ',
+        names: { bad: '  ' },
         affinity: { points: 9999, lastPetAt: -5, lastFeedAt: 'x', pets: -1, feeds: 1.5, turns: 0 },
         treats: { treats: 150, lastTreatGrantAt: -1, turnsAtLastTreatGrant: 0 },
         display: { visible: 'yes', size: -10, right: 1e12, bottom: 20 },
       }), 'utf8')
       const loaded = loadPetPersist(dir)
-      expect(loaded.name).toBe(DEFAULT_PET_NAME)
+      expect(loaded.petId).toBe(DEFAULT_PET_ID)
+      expect(loaded.names).toEqual({})
       expect(loaded.affinity.points).toBe(AFFINITY_MAX)
       expect(loaded.affinity.lastPetAt).toBe(0)
       expect(loaded.affinity.lastFeedAt).toBe(0)

package/src/persist.ts

@@ -37,15 +37,23 @@ export const DISPLAY_INSET_MAX = 10_000
 
 /** Everything persisted for the pet. */
 export interface PetPersist {
-  /** User-customizable pet display name. */
-  name: string
+  /** Selected pet id (a registry entry; clamped at service startup). */
+  petId: string
+  /**
+   * Per-pet display names keyed by pet id. A pet without an entry falls back
+   * to its manifest displayName, so only user renames are stored here.
+   */
+  names: Record<string, string>
   affinity: AffinityState
   /** Treat (小鱼干) stock ledger. */
   treats: TreatLedger
   display: PetDisplayConfig
 }
 
-/** Default pet name (used until the user renames the pet). */
+/** 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. */
@@ -53,7 +61,8 @@ export const PET_NAME_MAX_LENGTH = 20
 
 export function emptyPersist(): PetPersist {
   return {
-    name: DEFAULT_PET_NAME,
+    petId: DEFAULT_PET_ID,
+    names: {},
     affinity: emptyAffinity(),
     treats: emptyTreatLedger(),
     display: { ...defaultDisplayConfig },
@@ -74,6 +83,22 @@ function finiteNum(value: unknown, fallback: number): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : fallback
 }
 
+/** A persisted document from any schema era (legacy carried a flat `name`). */
+type PetPersistDocument = Partial<PetPersist> & { name?: unknown }
+
+/** Sanitize the per-pet names map (string keys, non-empty trimmed values). */
+function loadPetNames(parsed: PetPersistDocument): Record<string, string> {
+  const names: Record<string, string> = {}
+  if (typeof parsed.names !== 'object' || parsed.names === null) return names
+  for (const [id, value] of Object.entries(parsed.names as Record<string, unknown>)) {
+    if (id === '' || typeof value !== 'string') continue
+    const name = value.trim()
+    if (name === '') continue
+    names[id] = name.slice(0, PET_NAME_MAX_LENGTH)
+  }
+  return names
+}
+
 /** Clamp one count/score into [0, max]. */
 function clamp(value: number, max: number): number {
   return Math.min(max, Math.max(0, value))
@@ -83,7 +108,7 @@ function clamp(value: number, max: number): number {
 export function loadPetPersist(dir: string = petHomeDir()): PetPersist {
   try {
     const raw = readFileSync(join(dir, 'pet.json'), 'utf8')
-    const parsed = JSON.parse(raw) as Partial<PetPersist>
+    const parsed = JSON.parse(raw) as PetPersistDocument
     const base = emptyPersist()
     const rawAffinity = (parsed.affinity ?? {}) as Partial<AffinityState>
     const affinity: AffinityState = {
@@ -109,10 +134,19 @@ export function loadPetPersist(dir: string = petHomeDir()): PetPersist {
       right: Math.round(clamp(finiteNum(rawDisplay.right, base.display.right), DISPLAY_INSET_MAX)),
       bottom: Math.round(clamp(finiteNum(rawDisplay.bottom, base.display.bottom), DISPLAY_INSET_MAX)),
     }
+    const petId = typeof parsed.petId === 'string' && parsed.petId.trim() !== ''
+      ? parsed.petId.trim()
+      : base.petId
+    const names = loadPetNames(parsed)
+    // Legacy migration: pre-registry installs persisted one flat `name`
+    // field. Move it onto the selected pet (the legacy whale-girl unless the
+    // file already names another pet) so renames survive the upgrade.
+    if (typeof parsed.name === 'string' && parsed.name.trim() !== '' && names[petId] === undefined) {
+      names[petId] = parsed.name.trim().slice(0, PET_NAME_MAX_LENGTH)
+    }
     return {
-      name: typeof parsed.name === 'string' && parsed.name.trim() !== ''
-        ? parsed.name
-        : base.name,
+      petId,
+      names,
       affinity,
       treats,
       display,

package/src/registry.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  DEFAULT_FRAME_COUNTS,
+  DEFAULT_PET_CELL,
+  codexPetsDir,
+  loadPetRegistry,
+  resolvePetManifest,
+} from './registry.ts'
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), 'dsh-pet-registry-'))
+}
+
+describe('resolvePetManifest', () => {
+  it('resolves a bare Codex manifest onto the hatch-pet contract defaults', () => {
+    const entry = resolvePetManifest({
+      id: 'otter',
+      displayName: '水獭',
+      spritesheetPath: 'spritesheet.webp',
+    }, join(tmpdir(), 'otter'))
+    expect(entry).toBeDefined()
+    expect(entry!.id).toBe('otter')
+    expect(entry!.cell).toEqual(DEFAULT_PET_CELL)
+    expect(entry!.columns).toBe(8)
+    expect(entry!.rows).toEqual([...DEFAULT_FRAME_COUNTS])
+    expect(entry!.atlasUrl).toBe('/pet/otter/spritesheet.webp')
+    expect(entry!.manifestUrl).toBe('/pet/otter/pet.json')
+    // Every track's frames/durations line up with its row count.
+    expect(entry!.tracks.idle.frames.length).toBe(entry!.rows[0])
+    expect(entry!.tracks.idle.durations.length).toBe(entry!.rows[0])
+    expect(entry!.tracks.jumping.loop).toBe(false)
+    expect(entry!.tracks.jumping.fallback).toBe('idle')
+    expect(entry!.tracks.failed.loop).toBe(false)
+    expect(entry!.tracks.running.loop).toBe(true)
+  })
+
+  it('keeps the legacy whale-girl frame counts and its own durations', () => {
+    const entry = resolvePetManifest({
+      id: 'whale-girl',
+      displayName: '鲸鱼娘',
+      spritesheetPath: 'spritesheet.webp',
+      frames: [6, 8, 8, 4, 5, 8, 6, 6, 6],
+      tracks: { idle: { durations: [400, 400, 500, 400, 400, 500] } },
+    }, join(tmpdir(), 'whale'))
+    expect(entry!.rows).toEqual([6, 8, 8, 4, 5, 8, 6, 6, 6])
+    expect(entry!.tracks.idle.durations).toEqual([400, 400, 500, 400, 400, 500])
+    // Non-overridden tracks keep the contract rhythm.
+    expect(entry!.tracks['running-right'].durations.length).toBe(8)
+  })
+
+  it('cycles short override durations up to the row frame count', () => {
+    const entry = resolvePetManifest({
+      id: 'fox',
+      displayName: '狐狸',
+      spritesheetPath: 'atlas.png',
+      frames: [4, 4, 4, 4, 4, 4, 4, 4, 4],
+      tracks: { idle: { durations: [200, 300] } },
+    }, join(tmpdir(), 'fox'))
+    expect(entry!.tracks.idle.durations).toEqual([200, 300, 200, 300])
+    expect(entry!.tracks.idle.frames).toEqual([0, 1, 2, 3])
+  })
+
+  it('rejects unsafe ids and spritesheet paths with warnings', () => {
+    const warnings: string[] = []
+    expect(resolvePetManifest({ id: 'Bad Id', displayName: 'x', spritesheetPath: 'a.webp' }, '/tmp', { warnings })).toBeUndefined()
+    expect(resolvePetManifest({ id: 'ok', displayName: 'x', spritesheetPath: '../etc/passwd' }, '/tmp', { warnings })).toBeUndefined()
+    expect(resolvePetManifest({ id: 'ok', displayName: 'x', spritesheetPath: '/absolute.webp' }, '/tmp', { warnings })).toBeUndefined()
+    expect(warnings.length).toBe(3)
+  })
+})
+
+describe('loadPetRegistry', () => {
+  it('scans built-in assets, the custom pets dir, and composed extras with precedence', () => {
+    const root = tempDir()
+    try {
+      const assets = join(root, 'assets')
+      mkdirSync(join(assets, 'whale'), { recursive: true })
+      writeFileSync(join(assets, 'whale', 'pet.json'), JSON.stringify({
+        id: 'whale-girl', displayName: '鲸鱼娘', spritesheetPath: 'spritesheet.webp',
+      }), 'utf8')
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'otter'), { recursive: true })
+      writeFileSync(join(petsDir, 'otter', 'pet.json'), JSON.stringify({
+        id: 'otter', displayName: '水獭', spritesheetPath: 'spritesheet.webp',
+      }), 'utf8')
+      // A broken manifest is skipped with a warning, never thrown.
+      mkdirSync(join(petsDir, 'broken'), { recursive: true })
+      writeFileSync(join(petsDir, 'broken', 'pet.json'), '{ not json', 'utf8')
+
+      const registry = loadPetRegistry({ packageRoot: root, petsDir })
+      expect(registry.entries.map(entry => entry.id)).toEqual(['whale-girl', 'otter'])
+      expect(registry.defaultEntry().id).toBe('whale-girl')
+      expect(registry.warnings.some(warning => warning.includes('broken'))).toBe(true)
+
+      // A composed extra with the same id overrides the earlier sources.
+      const overridden = loadPetRegistry({
+        packageRoot: root,
+        petsDir,
+        extra: [{ id: 'whale-girl', displayName: '替换鲸', spritesheetPath: 'spritesheet.webp' }],
+      })
+      expect(overridden.byId('whale-girl')!.displayName).toBe('替换鲸')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('defaults to the built-in pet even when custom pets sort first', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'aardvark'), { recursive: true })
+      writeFileSync(join(petsDir, 'aardvark', 'pet.json'), JSON.stringify({
+        id: 'aardvark', displayName: '土豚', spritesheetPath: 'spritesheet.webp',
+      }), 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'no-assets'), petsDir })
+      expect(registry.defaultEntry().id).toBe('aardvark')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('codexPetsDir', () => {
+  it('honors CODEX_HOME and expands a leading tilde', () => {
+    expect(codexPetsDir({ CODEX_HOME: '/opt/codex' }, '/home/user')).toBe('/opt/codex/pets')
+    expect(codexPetsDir({ CODEX_HOME: '~/codex' }, '/home/user')).toBe('/home/user/codex/pets')
+    expect(codexPetsDir({}, '/home/user')).toBe('/home/user/.codex/pets')
+  })
+})