@linxin666/dsh-pet 0.1.20 → 0.2.0

package/src/registry.test.ts

@@ -25,6 +25,7 @@ describe('resolvePetManifest', () => {
     expect(entry!.id).toBe('otter')
     expect(entry!.cell).toEqual(DEFAULT_PET_CELL)
     expect(entry!.columns).toBe(8)
+    expect(entry!.atlasRows).toBe(9)
     expect(entry!.rows).toEqual([...DEFAULT_FRAME_COUNTS])
     expect(entry!.atlasUrl).toBe('/pet/otter/spritesheet.webp')
     expect(entry!.manifestUrl).toBe('/pet/otter/pet.json')
@@ -37,6 +38,21 @@ describe('resolvePetManifest', () => {
     expect(entry!.tracks.running.loop).toBe(true)
   })
 
+  it('marks v2 (spriteVersionNumber 2) atlases with 11 rows', () => {
+    const entry = resolvePetManifest({
+      id: 'firefly',
+      displayName: 'Firefly',
+      spritesheetPath: 'spritesheet.webp',
+      spriteVersionNumber: 2,
+    }, join(tmpdir(), 'firefly'))
+    expect(entry).toBeDefined()
+    // v2 atlases carry 11 rows: the 9 animation rows plus 2 look rows.
+    expect(entry!.atlasRows).toBe(11)
+    // The 9 animation rows still resolve the hatch-pet contract.
+    expect(entry!.rows).toEqual([...DEFAULT_FRAME_COUNTS])
+    expect(entry!.tracks.idle.frames.length).toBe(entry!.rows[0])
+  })
+
   it('keeps the legacy whale-girl frame counts and its own durations', () => {
     const entry = resolvePetManifest({
       id: 'whale-girl',
@@ -51,6 +67,36 @@ describe('resolvePetManifest', () => {
     expect(entry!.tracks['running-right'].durations.length).toBe(8)
   })
 
+  it('normalizes valid per-scene animation sequences', () => {
+    const entry = resolvePetManifest({
+      id: 'whale-girl',
+      displayName: '鲸鱼娘',
+      spritesheetPath: 'spritesheet.webp',
+      sequences: {
+        thinking: ['running', 'running-right', 'running', 'running-left', 'waiting'],
+      },
+    }, join(tmpdir(), 'whale'))
+    expect(entry!.sequences).toEqual({
+      thinking: ['running', 'running-right', 'running', 'running-left', 'waiting'],
+    })
+  })
+
+  it('drops invalid or undersized per-scene animation sequences', () => {
+    const warnings: string[] = []
+    const entry = resolvePetManifest({
+      id: 'whale-girl',
+      displayName: '鲸鱼娘',
+      spritesheetPath: 'spritesheet.webp',
+      sequences: {
+        waiting: ['waiting', 'idle'],
+        thinking: ['running', 'bogus', 'running', 'running-left', 'waiting'],
+      },
+    }, join(tmpdir(), 'whale'), { warnings })
+    expect(entry!.sequences).toBeUndefined()
+    expect(warnings).toContain('manifest whale-girl: sequence waiting must contain at least 5 animations')
+    expect(warnings).toContain('manifest whale-girl: sequence thinking contains unknown animation "bogus"')
+  })
+
   it('cycles short override durations up to the row frame count', () => {
     const entry = resolvePetManifest({
       id: 'fox',
@@ -152,8 +198,9 @@ describe('loadPetRegistry', () => {
 
 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')
+    // Expected values join through the platform separator (POSIX on CI).
+    expect(codexPetsDir({ CODEX_HOME: '/opt/codex' }, '/home/user')).toBe(join('/opt/codex', 'pets'))
+    expect(codexPetsDir({ CODEX_HOME: '~/codex' }, '/home/user')).toBe(join('/home/user', 'codex', 'pets'))
+    expect(codexPetsDir({}, '/home/user')).toBe(join('/home/user', '.codex', 'pets'))
   })
 })

package/src/registry.ts

@@ -21,7 +21,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { PetAnimation } from './state.ts'
+import type { ActivityPhase, PetAnimation } from './state.ts'
 import { normalizePetRemarks, type PetRemarks, type PetRemarksManifest } from './remarks.ts'
 
 /** Fixed row order of the 9-state animation contract. */
@@ -135,6 +135,8 @@ export interface PetManifest {
   frames?: number[]
   /** Optional per-track rhythm overrides; omitted tracks use the defaults. */
   tracks?: Partial<Record<PetAnimation, PetTrackOverride>>
+  /** Optional per-scene track sequences; every declared sequence has at least 5 items. */
+  sequences?: Partial<Record<ActivityPhase, PetAnimation[]>>
   /**
    * Optional witty-remark overrides the pet speaks on interactions
    * (community contributions use this to give their pet its own voice).
@@ -165,8 +167,12 @@ export interface PetDefinition {
   columns: number
   /** Per-row frame counts (length 9, row order above). */
   rows: number[]
+  /** Total atlas rows (9 for v1, 11 for v2 look-row atlases). */
+  atlasRows: number
   /** Fully resolved animation tracks (frames + durations + loop/fallback). */
   tracks: Record<PetAnimation, PetTrackDef>
+  /** Validated per-scene track sequences; omitted scenes keep single-track playback. */
+  sequences?: Partial<Record<ActivityPhase, PetAnimation[]>>
   /** Browser URL of the atlas (served by the host asset route). */
   atlasUrl: string
   /** Browser URL of the manifest (served by the host asset route). */
@@ -209,6 +215,39 @@ const PET_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/
 /** Safe path-segment charset for atlas files. */
 const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/
 const PET_NAME_MAX_LENGTH = 80
+const PET_PHASES: readonly ActivityPhase[] = ['idle', 'waiting', 'thinking', 'tool', 'review', 'done', 'failed']
+
+/** Validate optional scene sequences without rejecting an otherwise usable pet. */
+function normalizeSequences(
+  raw: unknown,
+  id: string,
+  warn: (message: string) => void,
+): Partial<Record<ActivityPhase, PetAnimation[]>> | undefined {
+  if (raw === undefined) return undefined
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    warn('manifest ' + id + ': sequences must be an object keyed by activity phase')
+    return undefined
+  }
+  const sequences: Partial<Record<ActivityPhase, PetAnimation[]>> = {}
+  for (const [phase, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!PET_PHASES.includes(phase as ActivityPhase)) {
+      warn('manifest ' + id + ': unknown sequence phase ' + JSON.stringify(phase))
+      continue
+    }
+    if (!Array.isArray(value) || value.length < 5) {
+      warn('manifest ' + id + ': sequence ' + phase + ' must contain at least 5 animations')
+      continue
+    }
+    const unknownIndex = value.findIndex(animation => typeof animation !== 'string' || !PET_ROW_ORDER.includes(animation as PetAnimation))
+    if (unknownIndex !== -1) {
+      const unknown = value[unknownIndex]
+      warn('manifest ' + id + ': sequence ' + phase + ' contains unknown animation ' + JSON.stringify(unknown))
+      continue
+    }
+    sequences[phase as ActivityPhase] = value as PetAnimation[]
+  }
+  return Object.keys(sequences).length === 0 ? undefined : sequences
+}
 
 /**
  * Normalize one parsed manifest into a renderable pet entry, or undefined
@@ -256,11 +295,14 @@ export function resolvePetManifest(
     height: finiteInt(rawCell.height, DEFAULT_PET_CELL.height, 2048),
   }
   const columns = finiteInt(source.columns, DEFAULT_PET_COLUMNS, 32)
+  // v2 atlases (spriteVersionNumber 2) hold 11 rows: 9 animation rows + 2 look rows.
+  const atlasRowCount = source.spriteVersionNumber === 2 ? 11 : DEFAULT_PET_ROW_COUNT
   const rows = DEFAULT_FRAME_COUNTS.map((fallback, index) => {
     const value = Array.isArray(source.frames) ? source.frames[index] : undefined
     return finiteInt(value, fallback, columns)
   })
   const remarks = normalizePetRemarks(source.remarks, message => warn('manifest ' + id + ': ' + message))
+  const sequences = normalizeSequences(source.sequences, id, warn)
   const trackOverrides = (typeof source.tracks === 'object' && source.tracks !== null ? source.tracks : {}) as Partial<Record<PetAnimation, PetTrackOverride>>
   const tracks = {} as Record<PetAnimation, PetTrackDef>
   for (const [row, animation] of PET_ROW_ORDER.entries()) {
@@ -295,7 +337,9 @@ export function resolvePetManifest(
     cell,
     columns,
     rows,
+    atlasRows: atlasRowCount,
     tracks,
+    ...(sequences === undefined ? {} : { sequences }),
     atlasUrl: assetUrl(assetPrefix, id, spritesheet),
     manifestUrl: assetUrl(assetPrefix, id, 'pet.json'),
     dir,
@@ -393,7 +437,9 @@ export function petEntryView(entry: PetEntry): PetDefinition {
     cell: entry.cell,
     columns: entry.columns,
     rows: entry.rows,
+    atlasRows: entry.atlasRows,
     tracks: entry.tracks,
+    ...(entry.sequences === undefined ? {} : { sequences: entry.sequences }),
     atlasUrl: entry.atlasUrl,
     manifestUrl: entry.manifestUrl,
   }
@@ -408,5 +454,3 @@ export function petAtlasFile(entry: PetEntry): string {
 export function petDirAlias(entry: PetEntry): string {
   return basename(entry.dir)
 }
-
-

package/src/remarks.ts

@@ -174,4 +174,10 @@ export class RemarkPicker {
     this.counters.set(kind, index + 1)
     return pool[index]!
   }
+
+  /** Select a line from a stable external counter without changing local picker state. */
+  pickAt(kind: RemarkKind, count: number): string {
+    const pool = this.pools[kind]
+    return pool[Math.max(0, Math.floor(count)) % pool.length]!
+  }
 }

package/src/service.ts

@@ -44,6 +44,7 @@ import {
   type PetManifest,
   type PetRegistry,
 } from './registry.ts'
+import { WHISPER_TTL_MS } from './chatter.ts'
 import {
   defaultPetStateConfig,
   PetStateMachine,
@@ -152,6 +153,12 @@ export interface PetStateView {
     /** Stock cap. */
     max: number
   }
+  /**
+   * The display session's fresh inner whisper (碎碎念), when one is within
+   * its TTL — short inner-voice copy woken by the model's own output,
+   * rendered by the client as a distinct whisper bubble.
+   */
+  whisper?: string
 }
 
 /** Result of `pet.interact`. */
@@ -169,6 +176,13 @@ interface SessionActivity {
   machine: PetStateMachine
   /** The session's most recent meaningful input (for display fallback). */
   lastInput?: PetStateInput
+  /** Latest inner whisper woken by this session's model output (碎碎念). */
+  whisper?: {
+    /** Whisper copy. */
+    text: string
+    /** Epoch ms when it appeared (view-side TTL applies). */
+    at: number
+  }
 }
 
 /**
@@ -319,7 +333,7 @@ export class PetService extends Service {
           const transition = projectOfficialEvent(event, runtime)
           if (transition === undefined) return
           runtime.officialEventsSeen = true
-          this.applyActivity(session, transition.input)
+          this.applyActivity(session, transition.input, transition.whisper)
           if (transition.completedTurn !== undefined) {
             this.rewardTurn(String(session.id), transition.completedTurn)
           }
@@ -364,9 +378,10 @@ export class PetService extends Service {
    * the session becomes the host-global display session (most recent
    * meaningful event wins the sprite animation).
    */
-  private applyActivity(session: Session, input: PetStateInput): void {
+  private applyActivity(session: Session, input: PetStateInput, whisper?: string): void {
     const activity = this.activityOf(session)
     activity.lastInput = input
+    if (whisper !== undefined) activity.whisper = { text: whisper, at: Date.now() }
     activity.machine.onActivityStatus(input)
     activity.machine.onSessionActive()
     // Move to the tail so map order reads most-recent-last, then trim the
@@ -495,6 +510,15 @@ export class PetService extends Service {
         phase: perSession.phase,
       })
     }
+    // The display session's inner whisper rides the global view while fresh;
+    // an expired whisper simply stops appearing (the client's 2s poll drops it).
+    const displayActivity = this.displaySession === undefined
+      ? undefined
+      : this.sessionActivity.get(this.displaySession)
+    const whisper = displayActivity?.whisper
+    const freshWhisper = whisper !== undefined && Date.now() - whisper.at < WHISPER_TTL_MS
+      ? whisper.text
+      : undefined
     // Read-only: the ledger settles on economic events only, never on a read,
     // so polling the state cannot trigger pet.json writes.
     return {
@@ -503,6 +527,7 @@ export class PetService extends Service {
       phase: snapshot.phase,
       sessionActive: snapshot.sessionActive,
       sessions,
+      ...(freshWhisper === undefined ? {} : { whisper: freshWhisper }),
       affinity: this.ledger.affinityView(Date.now()),
       display: { ...this.ledger.snapshot.display },
       pet: {

package/src/state.test.ts

@@ -33,6 +33,19 @@ describe('PetStateMachine', () => {
     expect(machine.render().bubble).toBeUndefined()
   })
 
+  it('shows failure briefly, then clears its bubble', () => {
+    let now = 1_000_000
+    const machine = new PetStateMachine({ celebrateMs: 2400, failureMs: 2400 }, () => now)
+    machine.onSessionActive()
+    machine.onActivityStatus({ phase: 'failed', line: '执行失败' })
+    expect(machine.render()).toMatchObject({ animation: 'failed', bubble: '执行失败' })
+    now += 2399
+    expect(machine.render()).toMatchObject({ animation: 'failed', bubble: '执行失败' })
+    now += 1
+    expect(machine.render()).toMatchObject({ animation: 'idle' })
+    expect(machine.render().bubble).toBeUndefined()
+  })
+
   it('shows the phrase bubble when present, else the line', () => {
     const machine = new PetStateMachine(defaultPetStateConfig, () => 1_000)
     machine.onActivityStatus({ phase: 'thinking', phrase: '查资料中', line: 'tool: grep' })

package/src/state.ts

@@ -53,9 +53,11 @@ export interface PetStateSnapshot {
 export interface PetStateConfig {
   /** Celebration window after `done` before settling to idle, ms (default 2400). */
   celebrateMs: number
+  /** Failure display window before settling to idle, ms (default 2400). */
+  failureMs: number
 }
 
-export const defaultPetStateConfig: PetStateConfig = { celebrateMs: 2400 }
+export const defaultPetStateConfig: PetStateConfig = { celebrateMs: 2400, failureMs: 2400 }
 
 /**
  * Map one activity phase onto the animation contract.
@@ -63,7 +65,7 @@ export const defaultPetStateConfig: PetStateConfig = { celebrateMs: 2400 }
  * - review → `review` while answer text is streaming.
  * - waiting → `waiting` (expectant pose, needs user input).
  * - done → `jumping` (celebration), then back to `idle` after the window.
- * - failed → `failed` until another activity event arrives.
+ * - failed → `failed` briefly, then back to `idle`.
  * - idle → `idle` (calm breathing loop).
  */
 export function animationForPhase(phase: ActivityPhase): PetAnimation {
@@ -96,7 +98,7 @@ export function rowOf(animation: PetAnimation): number {
 
 /**
  * PetStateMachine — one instance per host process. Holds only the latest
- * input snapshot and the celebration timing; no storage, no side effects.
+ * input snapshot and terminal-state timing; no storage, no side effects.
  */
 export class PetStateMachine {
   private phase: ActivityPhase = 'idle'
@@ -104,18 +106,23 @@ export class PetStateMachine {
   private phrase: string | undefined
   private sessionActive = false
   private doneAt: number | undefined
+  private failedAt: number | undefined
+  private readonly config: PetStateConfig
 
   constructor(
-    private readonly config: PetStateConfig = defaultPetStateConfig,
+    config: Partial<PetStateConfig> = defaultPetStateConfig,
     private readonly now: () => number = Date.now,
-  ) {}
+  ) {
+    this.config = { ...defaultPetStateConfig, ...config }
+  }
 
   /** Consume one projected activity update. */
   onActivityStatus(input: PetStateInput): void {
     this.phase = input.phase
     this.line = input.line
     this.phrase = input.phrase
-    if (input.phase === 'done') this.doneAt = this.now()
+    this.doneAt = input.phase === 'done' ? this.now() : undefined
+    this.failedAt = input.phase === 'failed' ? this.now() : undefined
   }
 
   /** A session became the active one (or a fresh session started). */
@@ -130,24 +137,23 @@ export class PetStateMachine {
     this.line = undefined
     this.phrase = undefined
     this.doneAt = undefined
+    this.failedAt = undefined
   }
 
   /** Render the current animation decision. */
   render(): PetStateSnapshot {
     const nowMs = this.now()
     let animation = animationForPhase(this.phase)
-    // Celebration window: after `done`, jump for celebrateMs then settle idle.
-    if (this.phase === 'done' && this.doneAt !== undefined) {
-      if (nowMs - this.doneAt < this.config.celebrateMs) {
-        animation = 'jumping'
-      } else {
-        animation = 'idle'
-      }
-    }
-    // Settled sessions never bubble: idle (e.g. an aborted/stopped turn)
-    // and done past its celebration window both fall silent.
-    const settled = this.phase === 'idle'
-      || (this.phase === 'done' && this.doneAt !== undefined && nowMs - this.doneAt >= this.config.celebrateMs)
+    const doneSettled = this.phase === 'done'
+      && this.doneAt !== undefined
+      && nowMs - this.doneAt >= this.config.celebrateMs
+    const failedSettled = this.phase === 'failed'
+      && this.failedAt !== undefined
+      && nowMs - this.failedAt >= this.config.failureMs
+    if (doneSettled || failedSettled) animation = 'idle'
+    // Settled sessions never bubble: idle (e.g. an aborted/stopped turn),
+    // completed celebration expiry, and failed display expiry all fall silent.
+    const settled = this.phase === 'idle' || doneSettled || failedSettled
     const bubble = settled ? undefined : this.phrase ?? this.line
     return {
       animation,