@linxin666/dsh-pet 0.2.1 → 0.2.3

package/src/model3.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { collectModel3References, model3HitAreas, model3MotionGroups } from './model3.ts'
+
+/** Fixture mirroring the real Haru sample's FileReferences shape. */
+const HARU_LIKE = {
+  Version: 3,
+  FileReferences: {
+    Moc: 'haru.moc3',
+    Textures: ['haru.2048/texture_00.png', 'haru.2048/texture_01.png'],
+    Physics: 'haru.physics3.json',
+    Pose: 'haru.pose3.json',
+    DisplayInfo: 'haru.cdi3.json',
+    Expressions: [
+      { Name: 'f01', File: 'expressions/f01.exp3.json' },
+      { Name: 'f02', File: 'expressions/f02.exp3.json' },
+    ],
+    Motions: {
+      Idle: [{ File: 'motions/idle_00.motion3.json' }],
+      TapBody: [{ File: 'motions/tap_00.motion3.json' }, { File: 'motions/tap_01.motion3.json' }],
+    },
+    UserData: 'haru.userdata3.json',
+  },
+  Groups: [{ Name: 'EyeBlink' }, { Name: 'LipSync' }],
+  HitAreas: [{ Id: 'Head', Name: 'Head' }, { Id: 'Body', Name: 'Body' }],
+}
+
+describe('collectModel3References', () => {
+  it('collects the complete reference closure of the eight Cubism file families', () => {
+    const { references, errors } = collectModel3References(HARU_LIKE)
+    expect(errors).toEqual([])
+    expect(references).toEqual([
+      'expressions/f01.exp3.json',
+      'expressions/f02.exp3.json',
+      'haru.2048/texture_00.png',
+      'haru.2048/texture_01.png',
+      'haru.cdi3.json',
+      'haru.moc3',
+      'haru.physics3.json',
+      'haru.pose3.json',
+      'haru.userdata3.json',
+      'motions/idle_00.motion3.json',
+      'motions/tap_00.motion3.json',
+      'motions/tap_01.motion3.json',
+    ])
+  })
+  it('rejects unsafe references instead of collecting them', () => {
+    const bad = {
+      FileReferences: {
+        Moc: '../escape.moc3',
+        Textures: ['/abs/path.png', 'ok.png'],
+        Motions: { Idle: [{ File: 'https://evil.example/x.motion3.json' }] },
+      },
+    }
+    const { references, errors } = collectModel3References(bad)
+    expect(references).toEqual(['ok.png'])
+    expect(errors).toHaveLength(3)
+  })
+  it('tolerates missing optional families', () => {
+    const minimal = { FileReferences: { Moc: 'a.moc3', Textures: ['a.png'] } }
+    const { references, errors } = collectModel3References(minimal)
+    expect(errors).toEqual([])
+    expect(references).toEqual(['a.moc3', 'a.png'])
+  })
+  it('reports malformed model3 roots', () => {
+    expect(collectModel3References(null).errors.length).toBeGreaterThan(0)
+    expect(collectModel3References({}).errors.length).toBeGreaterThan(0)
+  })
+})
+
+describe('model3MotionGroups / model3HitAreas', () => {
+  it('reads motion groups and hit areas for diagnostics', () => {
+    expect(model3MotionGroups(HARU_LIKE)).toEqual(['Idle', 'TapBody'])
+    expect(model3HitAreas(HARU_LIKE)).toEqual(['Body', 'Head'])
+  })
+  it('returns empty lists for malformed models', () => {
+    expect(model3MotionGroups(null)).toEqual([])
+    expect(model3HitAreas({})).toEqual([])
+  })
+})

package/src/model3.ts

@@ -0,0 +1,91 @@
+/**
+ * Live2D .model3.json reference closure — the set of files a model declares
+ * (pet-center M2, issue #623). The host asset route only ever serves a pet's
+ * declared manifest, its declared primary assets, and this closure; the CLI
+ * validator reuses the same extractor so an install-time check proves the
+ * serving set is complete.
+ *
+ * Cubism file family: Moc (.moc3), Textures (images), Physics (.physics3.json),
+ * Pose (.pose3.json), DisplayInfo (.cdi3.json), Expressions[].File
+ * (.exp3.json), Motions.<group>[].File (.motion3.json), UserData
+ * (.userdata3.json). Every reference must be a safe manifest-relative path
+ * (safeManifestPath); unsafe entries make the model unloadable.
+ *
+ * Erasable-syntax-only: scripts/ import this under node strip-only mode.
+ * @module @linxin666/dsh-pet/model3
+ */
+
+import { safeManifestPath } from './manifest-v2.ts'
+
+/** Collect the safe relative paths one model3.json references. */
+export function collectModel3References(model3: unknown): { references: string[]; errors: string[] } {
+  const errors: string[] = []
+  if (typeof model3 !== 'object' || model3 === null) {
+    return { references: [], errors: ['model3.json is not an object'] }
+  }
+  const fileReferences = (model3 as Record<string, unknown>).FileReferences
+  if (typeof fileReferences !== 'object' || fileReferences === null) {
+    return { references: [], errors: ['model3.json has no FileReferences'] }
+  }
+  const refs = fileReferences as Record<string, unknown>
+  const collected = new Set<string>()
+  const push = (raw: unknown, field: string): void => {
+    const safe = safeManifestPath(raw)
+    if (safe === undefined) {
+      errors.push(field + ' is not a safe relative path: ' + JSON.stringify(String(raw)))
+      return
+    }
+    collected.add(safe)
+  }
+  if (refs.Moc !== undefined) push(refs.Moc, 'FileReferences.Moc')
+  if (Array.isArray(refs.Textures)) {
+    refs.Textures.forEach((texture, index) => push(texture, 'FileReferences.Textures[' + index + ']'))
+  }
+  for (const scalar of ['Physics', 'Pose', 'DisplayInfo', 'UserData'] as const) {
+    if (refs[scalar] !== undefined) push(refs[scalar], 'FileReferences.' + scalar)
+  }
+  if (Array.isArray(refs.Expressions)) {
+    refs.Expressions.forEach((expression, index) => {
+      const file = typeof expression === 'object' && expression !== null
+        ? (expression as Record<string, unknown>).File
+        : undefined
+      if (file !== undefined) push(file, 'FileReferences.Expressions[' + index + '].File')
+    })
+  }
+  if (typeof refs.Motions === 'object' && refs.Motions !== null) {
+    for (const [group, motions] of Object.entries(refs.Motions as Record<string, unknown>)) {
+      if (!Array.isArray(motions)) {
+        errors.push('FileReferences.Motions.' + group + ' is not an array')
+        continue
+      }
+      motions.forEach((motion, index) => {
+        const file = typeof motion === 'object' && motion !== null
+          ? (motion as Record<string, unknown>).File
+          : undefined
+        if (file !== undefined) push(file, 'FileReferences.Motions.' + group + '[' + index + '].File')
+      })
+    }
+  }
+  return { references: [...collected].sort(), errors }
+}
+
+/** The motion group names a model3.json declares (for CLI diagnostics). */
+export function model3MotionGroups(model3: unknown): string[] {
+  if (typeof model3 !== 'object' || model3 === null) return []
+  const fileReferences = (model3 as Record<string, unknown>).FileReferences
+  if (typeof fileReferences !== 'object' || fileReferences === null) return []
+  const motions = (fileReferences as Record<string, unknown>).Motions
+  if (typeof motions !== 'object' || motions === null) return []
+  return Object.keys(motions as Record<string, unknown>).sort()
+}
+
+/** The hit area names a model3.json declares (top-level HitAreas). */
+export function model3HitAreas(model3: unknown): string[] {
+  if (typeof model3 !== 'object' || model3 === null) return []
+  const hitAreas = (model3 as Record<string, unknown>).HitAreas
+  if (!Array.isArray(hitAreas)) return []
+  return hitAreas
+    .map(area => typeof area === 'object' && area !== null ? (area as Record<string, unknown>).Name : undefined)
+    .filter((name): name is string => typeof name === 'string')
+    .sort()
+}

package/src/registry.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import {
@@ -8,6 +8,8 @@ import {
   codexPetsDir,
   loadPetRegistry,
   petAtlasFile,
+  petEntryView,
+  petPackageRoot,
   resolvePetManifest,
 } from './registry.ts'
 
@@ -147,6 +149,26 @@ describe('resolvePetManifest', () => {
 })
 
 describe('loadPetRegistry', () => {
+  it('ships the original and refined whale variants while keeping the original default', () => {
+    const registry = loadPetRegistry({
+      packageRoot: petPackageRoot(import.meta.url),
+      petsDir: '',
+      dshPetsDir: '',
+    })
+
+    expect(registry.entries.map(entry => entry.id)).toEqual([
+      'whale-girl',
+      'whale-girl-refined',
+    ])
+    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)
+    expect(readFileSync(petAtlasFile(registry.byId('whale-girl')!)).equals(
+      readFileSync(petAtlasFile(registry.byId('whale-girl-refined')!)),
+    )).toBe(false)
+    expect(registry.defaultEntry().id).toBe('whale-girl')
+  })
+
   it('scans built-in assets, the custom pets dir, and composed extras with precedence', () => {
     const root = tempDir()
     try {
@@ -164,7 +186,7 @@ describe('loadPetRegistry', () => {
       mkdirSync(join(petsDir, 'broken'), { recursive: true })
       writeFileSync(join(petsDir, 'broken', 'pet.json'), '{ not json', 'utf8')
 
-      const registry = loadPetRegistry({ packageRoot: root, petsDir })
+      const registry = loadPetRegistry({ packageRoot: root, petsDir, dshPetsDir: '' })
       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)
@@ -173,6 +195,7 @@ describe('loadPetRegistry', () => {
       const overridden = loadPetRegistry({
         packageRoot: root,
         petsDir,
+        dshPetsDir: '',
         extra: [{ id: 'whale-girl', displayName: '替换鲸', spritesheetPath: 'spritesheet.webp' }],
       })
       expect(overridden.byId('whale-girl')!.displayName).toBe('替换鲸')
@@ -191,6 +214,7 @@ describe('loadPetRegistry', () => {
       const registry = loadPetRegistry({
         packageRoot: root,
         petsDir: '',
+        dshPetsDir: '',
         extra: [{ id: 'otter', displayName: '水獭', spritesheetPath: 'pets/otter/spritesheet.webp' }],
       })
       const entry = registry.byId('otter')
@@ -216,7 +240,7 @@ describe('loadPetRegistry', () => {
       writeFileSync(join(petsDir, 'aardvark', 'pet.json'), JSON.stringify({
         id: 'aardvark', displayName: '土豚', spritesheetPath: 'spritesheet.webp',
       }), 'utf8')
-      const registry = loadPetRegistry({ packageRoot: join(root, 'no-assets'), petsDir })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'no-assets'), petsDir, dshPetsDir: '' })
       expect(registry.defaultEntry().id).toBe('aardvark')
     } finally {
       rmSync(root, { recursive: true, force: true })
@@ -232,3 +256,212 @@ describe('codexPetsDir', () => {
     expect(codexPetsDir({}, '/home/user')).toBe(join('/home/user', '.codex', 'pets'))
   })
 })
+
+describe('loadPetRegistry pet-center v2 (issue #623)', () => {
+  function writePet(dir: string, name: string, manifest: Record<string, unknown>): void {
+    mkdirSync(join(dir, name), { recursive: true })
+    writeFileSync(join(dir, name, 'pet.json'), JSON.stringify(manifest), 'utf8')
+    writeFileSync(join(dir, name, 'spritesheet.webp'), 'webp', 'utf8')
+  }
+
+  it('resolves a v2 sprite2d pet with the same geometry as its v1 twin', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      writePet(petsDir, 'v1pet', { id: 'twin-v1', displayName: 'Twin V1', frames: [1, 2, 3, 4, 5, 6, 7, 8, 9] })
+      writePet(petsDir, 'v2pet', {
+        petManifestVersion: 2, id: 'twin-v2', displayName: 'Twin V2', license: 'CC0-1.0',
+        renderer: 'sprite2d', sprite2d: { spritesheetPath: 'spritesheet.webp', frames: [1, 2, 3, 4, 5, 6, 7, 8, 9] },
+      })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      const v1 = registry.byId('twin-v1')!
+      const v2 = registry.byId('twin-v2')!
+      expect(v2.rows).toEqual(v1.rows)
+      expect(v2.tracks.idle.durations).toEqual(v1.tracks.idle.durations)
+      expect(registry.diagnostics.some(d => d.message.includes('v1 compat read'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('round-trips atlasRows 11 through the v1 compat resolver', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      writePet(petsDir, 'looky', {
+        petManifestVersion: 2, id: 'looky', displayName: 'Looky', license: 'CC0-1.0',
+        renderer: 'sprite2d', sprite2d: { spritesheetPath: 'spritesheet.webp', atlasRows: 11 },
+      })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('looky')?.atlasRows).toBe(11)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects atlasRows values the v1 compat resolver cannot express', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      writePet(petsDir, 'odd', {
+        petManifestVersion: 2, id: 'odd', displayName: 'Odd', license: 'CC0-1.0',
+        renderer: 'sprite2d', sprite2d: { spritesheetPath: 'spritesheet.webp', atlasRows: 7 },
+      })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('odd')).toBeUndefined()
+      expect(registry.diagnostics.some(d => d.level === 'error' && d.message.includes('atlasRows'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('lists live2d pets with the render block and the servable closure (M3)', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'haru', 'motions'), { recursive: true })
+      mkdirSync(join(petsDir, 'haru', 'textures'), { recursive: true })
+      writeFileSync(join(petsDir, 'haru', 'pet.json'), JSON.stringify({
+        petManifestVersion: 2, id: 'haru', displayName: 'Haru', license: 'Live2D-Sample',
+        renderer: 'live2d',
+        live2d: {
+          model: 'haru.model3.json',
+          scale: 1.2,
+          motions: { idle: 'Idle', thinking: 'TapBody' },
+          hitAreas: ['Head'],
+        },
+      }), 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'haru.model3.json'), JSON.stringify({
+        Version: 3,
+        FileReferences: {
+          Moc: 'haru.moc3',
+          Textures: ['textures/texture_00.png'],
+          Motions: { Idle: [{ File: 'motions/idle_00.motion3.json' }] },
+        },
+        HitAreas: [{ Name: 'Head', Id: 'HitAreaHead' }],
+      }), 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'haru.moc3'), 'moc', 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'textures', 'texture_00.png'), 'png', 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'motions', 'idle_00.motion3.json'), '{}', 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      const entry = registry.byId('haru')
+      expect(entry).toBeDefined()
+      expect(entry!.renderer).toBe('live2d')
+      expect(entry!.live2d).toBeDefined()
+      expect(entry!.live2d!.modelUrl).toBe('/pet/haru/haru.model3.json')
+      expect(entry!.live2d!.modelPath).toBe('haru.model3.json')
+      expect(entry!.live2d!.scale).toBe(1.2)
+      expect(entry!.live2d!.motions).toEqual({ idle: 'Idle', thinking: 'TapBody' })
+      expect(entry!.live2d!.hitAreas).toEqual(['Head'])
+      // The servable closure covers the model plus every referenced file.
+      expect(entry!.servable).toEqual([
+        'haru.model3.json', 'haru.moc3', 'motions/idle_00.motion3.json', 'textures/texture_00.png',
+      ])
+      // Sprite fields carry harmless contract defaults (chrome sizing only).
+      expect(entry!.cell).toEqual(DEFAULT_PET_CELL)
+      expect(entry!.rows).toEqual([...DEFAULT_FRAME_COUNTS])
+      expect(entry!.tracks.idle.frames.length).toBe(entry!.rows[0])
+      // The client-visible view keeps the live2d block, drops host paths.
+      const view = petEntryView(entry!)
+      expect(view.live2d!.modelPath).toBe('haru.model3.json')
+      expect('servable' in view).toBe(false)
+      expect('dir' in view).toBe(false)
+      // A healthy live2d entry records no diagnostics.
+      expect(registry.diagnostics.filter(d => d.message.includes('haru'))).toEqual([])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects live2d pets whose model3.json is unreadable', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      writePet(petsDir, 'haru', {
+        petManifestVersion: 2, id: 'haru', displayName: 'Haru', license: 'Live2D-Sample',
+        renderer: 'live2d', live2d: { model: 'haru.model3.json', motions: { idle: 'Idle' } },
+      })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('haru')).toBeUndefined()
+      expect(registry.diagnostics.some(d => d.level === 'error' && d.message.includes('not readable'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects live2d pets whose model3.json declares unsafe references', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'haru'), { recursive: true })
+      writeFileSync(join(petsDir, 'haru', 'pet.json'), JSON.stringify({
+        petManifestVersion: 2, id: 'haru', displayName: 'Haru', license: 'Live2D-Sample',
+        renderer: 'live2d', live2d: { model: 'haru.model3.json', motions: { idle: 'Idle' } },
+      }), 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'haru.model3.json'), JSON.stringify({
+        Version: 3,
+        FileReferences: { Moc: '../escape.moc3' },
+      }), 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('haru')).toBeUndefined()
+      expect(registry.diagnostics.some(d => d.level === 'error' && d.message.includes('not a safe relative path'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('warns on closure files missing on disk but keeps the live2d pet listed', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      mkdirSync(join(petsDir, 'haru'), { recursive: true })
+      writeFileSync(join(petsDir, 'haru', 'pet.json'), JSON.stringify({
+        petManifestVersion: 2, id: 'haru', displayName: 'Haru', license: 'Live2D-Sample',
+        renderer: 'live2d', live2d: { model: 'haru.model3.json', motions: { idle: 'Idle' } },
+      }), 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'haru.model3.json'), JSON.stringify({
+        Version: 3,
+        FileReferences: { Moc: 'haru.moc3', Textures: ['missing.png'] },
+      }), 'utf8')
+      writeFileSync(join(petsDir, 'haru', 'haru.moc3'), 'moc', 'utf8')
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('haru')).toBeDefined()
+      expect(registry.diagnostics.some(d => d.level === 'warning' && d.message.includes('closure file missing: missing.png'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('fails closed on v2 manifests with unknown fields', () => {
+    const root = tempDir()
+    try {
+      const petsDir = join(root, 'pets')
+      writePet(petsDir, 'surprise', {
+        petManifestVersion: 2, id: 'surprise', displayName: 'S', license: 'CC0-1.0',
+        renderer: 'sprite2d', sprite2d: { spritesheetPath: 'spritesheet.webp' }, sneaky: true,
+      })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir, dshPetsDir: '' })
+      expect(registry.byId('surprise')).toBeUndefined()
+      expect(registry.diagnostics.some(d => d.level === 'error' && d.message.includes('sneaky'))).toBe(true)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('ranks the DSH_HOME pets source above the legacy codex source', () => {
+    const root = tempDir()
+    try {
+      const legacy = join(root, 'legacy')
+      const dsh = join(root, 'dsh')
+      writePet(legacy, 'cat', { id: 'cat', displayName: 'Legacy Cat' })
+      writePet(dsh, 'cat', { id: 'cat', displayName: 'Home Cat' })
+      const registry = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir: legacy, dshPetsDir: dsh })
+      expect(registry.byId('cat')?.displayName).toBe('Home Cat')
+      // '' disables the source entirely.
+      const disabled = loadPetRegistry({ packageRoot: join(root, 'none'), petsDir: '', dshPetsDir: dsh })
+      expect(disabled.entries.map(e => e.id)).toEqual(['cat'])
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})