@linxin666/dsh-pet 0.1.1

package/src/state.ts

@@ -0,0 +1,156 @@
+/**
+ * Pet state machine — pure, clock-injected. Maps the DSH `activity/status`
+ * phase vocabulary (session events) onto the 9-state Codex pet
+ * animation contract, plus the session lifecycle transitions the web UI
+ * exposes (turn end celebration, no-session idle).
+ *
+ * The machine is deliberately dumb: it holds the last input phase, the
+ * animation decision, and a one-shot "celebration" window after `done` so the
+ * pet visibly jumps before settling back to idle. Everything here is a pure
+ * function of (input, nowMs); persistence and RPC live in the service.
+ * @module @linxin666/dsh-pet/state
+ */
+
+/** The DSH `activity/status` phase vocabulary (wire contract of session events). */
+export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
+
+/** The Codex-compatible 9-state animation contract (spritesheet rows). */
+export type PetAnimation =
+  | 'idle'
+  | 'running-right'
+  | 'running-left'
+  | 'waving'
+  | 'jumping'
+  | 'failed'
+  | 'waiting'
+  | 'running'
+  | 'review'
+
+/** One input snapshot consumed by the machine. */
+export interface PetStateInput {
+  /** Current activity/status phase of the active session. */
+  phase: ActivityPhase
+  /** Human-readable status line (plain text). */
+  line?: string
+  /** Playful phrase from the activity tracker, when any. */
+  phrase?: string
+}
+
+/** Animation decision plus the copy the pet should show. */
+export interface PetStateSnapshot {
+  /** Which animation track to play. */
+  animation: PetAnimation
+  /** Optional status bubble copy (line or phrase), shown while active. */
+  bubble?: string
+  /** Wall-clock ms this animation started (client can sync loops). */
+  animationStartedAt: number
+  /** Raw phase, for debugging and client-side rendering decisions. */
+  phase: ActivityPhase
+  /** True when there is an active session (pet mounted). */
+  sessionActive: boolean
+}
+
+/** Machine configuration. */
+export interface PetStateConfig {
+  /** Celebration window after `done` before settling to idle, ms (default 2400). */
+  celebrateMs: number
+}
+
+export const defaultPetStateConfig: PetStateConfig = { celebrateMs: 2400 }
+
+/**
+ * Map one activity phase onto the animation contract.
+ * - thinking / tool → `running` (focused work), with `running-right` as the
+ *   side-alternating variant the client may use for tool activity.
+ * - waiting → `waiting` (expectant pose, needs user input).
+ * - done → `jumping` (celebration), then back to `idle` after the window.
+ * - idle → `idle` (calm breathing loop).
+ * `failed` has no DSH phase source yet; the machine keeps the mapping table
+ * so a future error event can light it up.
+ */
+export function animationForPhase(phase: ActivityPhase): PetAnimation {
+  switch (phase) {
+    case 'thinking': return 'running'
+    case 'tool': return 'running-right'
+    case 'waiting': return 'waiting'
+    case 'done': return 'jumping'
+    case 'idle': return 'idle'
+  }
+}
+
+/** The spritesheet row index for one animation track. */
+export function rowOf(animation: PetAnimation): number {
+  const rows: Record<PetAnimation, number> = {
+    'idle': 0,
+    'running-right': 1,
+    'running-left': 2,
+    'waving': 3,
+    'jumping': 4,
+    'failed': 5,
+    'waiting': 6,
+    'running': 7,
+    'review': 8,
+  }
+  return rows[animation]
+}
+
+/**
+ * PetStateMachine — one instance per host process. Holds only the latest
+ * input snapshot and the celebration timing; no storage, no side effects.
+ */
+export class PetStateMachine {
+  private phase: ActivityPhase = 'idle'
+  private line: string | undefined
+  private phrase: string | undefined
+  private sessionActive = false
+  private doneAt: number | undefined
+
+  constructor(
+    private readonly config: PetStateConfig = defaultPetStateConfig,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /** Consume one `activity/status` session event. */
+  onActivityStatus(input: PetStateInput): void {
+    this.phase = input.phase
+    this.line = input.line
+    this.phrase = input.phrase
+    if (input.phase === 'done') this.doneAt = this.now()
+  }
+
+  /** A session became the active one (or a fresh session started). */
+  onSessionActive(): void {
+    this.sessionActive = true
+  }
+
+  /** The active session was disposed (or none left). */
+  onSessionDisposed(): void {
+    this.sessionActive = false
+    this.phase = 'idle'
+    this.line = undefined
+    this.phrase = undefined
+    this.doneAt = 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'
+      }
+    }
+    const bubble = this.phrase ?? this.line
+    return {
+      animation,
+      ...(bubble === undefined ? {} : { bubble }),
+      animationStartedAt: nowMs,
+      phase: this.phase,
+      sessionActive: this.sessionActive,
+    }
+  }
+}

package/src/treats.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import {
+  consumeTreat,
+  defaultTreatConfig,
+  emptyTreatLedger,
+  settleTreatGrants,
+} from './treats.ts'
+
+describe('settleTreatGrants', () => {
+  it('grants one treat per turnsPerTreat completed turns', () => {
+    const ledger = { ...emptyTreatLedger(), turnsAtLastTreatGrant: 0 }
+    const s = settleTreatGrants(ledger, 6, 1_000, defaultTreatConfig)
+    expect(s.gained).toBe(2)
+    expect(s.ledger.treats).toBe(2)
+    expect(s.ledger.turnsAtLastTreatGrant).toBe(6)
+  })
+
+  it('grants time-output treats per elapsed period', () => {
+    const ledger = { ...emptyTreatLedger(), lastTreatGrantAt: 1_000 }
+    const s = settleTreatGrants(ledger, 0, 1_000 + 90 * 60_000, defaultTreatConfig)
+    expect(s.gained).toBe(3)
+    expect(s.ledger.treats).toBe(3)
+    expect(s.ledger.lastTreatGrantAt).toBe(1_000 + 90 * 60_000)
+  })
+
+  it('does not backfill time output before the first settlement', () => {
+    const ledger = emptyTreatLedger() // lastTreatGrantAt === 0
+    const s = settleTreatGrants(ledger, 0, 1_000 + 10 * 60 * 60_000, defaultTreatConfig)
+    expect(s.gained).toBe(0)
+    expect(s.ledger).toBe(ledger)
+  })
+
+  it('caps stocked treats at maxTreats', () => {
+    const ledger = { ...emptyTreatLedger(), treats: 19, lastTreatGrantAt: 1_000, turnsAtLastTreatGrant: 0 }
+    const s = settleTreatGrants(ledger, 6, 1_000 + 30 * 60_000, defaultTreatConfig)
+    expect(s.ledger.treats).toBe(defaultTreatConfig.maxTreats)
+  })
+
+  it('reports gained=0 and returns the same ledger when nothing is due', () => {
+    const ledger = { ...emptyTreatLedger(), treats: 5, lastTreatGrantAt: 1_000, turnsAtLastTreatGrant: 0 }
+    const s = settleTreatGrants(ledger, 2, 1_000 + 10_000, defaultTreatConfig)
+    expect(s.gained).toBe(0)
+    expect(s.ledger).toBe(ledger)
+  })
+
+  it('ignores a negative turns delta (corrupt persistence)', () => {
+    const ledger = { ...emptyTreatLedger(), turnsAtLastTreatGrant: 100, lastTreatGrantAt: 1_000 }
+    const s = settleTreatGrants(ledger, 50, 1_000, defaultTreatConfig)
+    expect(s.gained).toBe(0)
+  })
+
+  it('a continuously working user still earns time treats (work does not reset the time anchor)', () => {
+    // First settlement: 3 completed turns grant one work treat and start the
+    // time clock without touching the work anchor's independence.
+    let ledger = emptyTreatLedger()
+    const first = settleTreatGrants(ledger, 3, 1_000, defaultTreatConfig)
+    expect(first.gained).toBe(1)
+    ledger = first.ledger
+    // Keep working in 3-turn steps well under one time period: every work
+    // settlement must advance only the turn anchor, never the time anchor.
+    const stepMs = defaultTreatConfig.timeTreatMs / 100
+    for (let i = 0; i < 10; i++) {
+      const s = settleTreatGrants(ledger, 3 + ((i + 1) * 3), 1_000 + ((i + 1) * stepMs), defaultTreatConfig)
+      expect(s.gained).toBe(1)
+      expect(s.ledger.lastTreatGrantAt).toBe(1_000)
+      ledger = s.ledger
+    }
+    // After a full time period elapses (past the anchored start), the time
+    // source finally grants, proving work settlements never reset the clock.
+    const late = settleTreatGrants(ledger, ledger.turnsAtLastTreatGrant, 1_000 + defaultTreatConfig.timeTreatMs, defaultTreatConfig)
+    expect(late.gained).toBe(1)
+    expect(late.ledger.lastTreatGrantAt).toBe(1_000 + defaultTreatConfig.timeTreatMs)
+  })
+})
+
+describe('consumeTreat', () => {
+  it('consumes one treat when stocked', () => {
+    const r = consumeTreat({ ...emptyTreatLedger(), treats: 2 })
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.ledger.treats).toBe(1)
+  })
+
+  it('refuses when the stock is empty', () => {
+    expect(consumeTreat(emptyTreatLedger()).ok).toBe(false)
+  })
+})

package/src/treats.ts

@@ -0,0 +1,101 @@
+/**
+ * Treat (小鱼干) economy — pure, clock-injected. The pet's food comes from
+ * two sources, both tied to companionship:
+ *  - work output: every N completed turns grant one treat;
+ *  - time output: every T minutes of wall-clock time grant one treat.
+ * Feeding consumes one treat. Settlement is lazy: it runs whenever the host
+ * serves a state snapshot or an interaction, so there is no timer and no
+ * drift — elapsed periods are computed from the persisted last-grant marks.
+ * @module @linxin666/dsh-pet/treats
+ */
+
+/** Treat economy tuning. */
+export interface TreatConfig {
+  /** Completed turns per work-output treat. */
+  turnsPerTreat: number
+  /** Wall-clock ms per time-output treat. */
+  timeTreatMs: number
+  /** Hard cap on stocked treats. */
+  maxTreats: number
+}
+
+export const defaultTreatConfig: TreatConfig = {
+  turnsPerTreat: 3,
+  timeTreatMs: 30 * 60_000,
+  maxTreats: 20,
+}
+
+/** Treat ledger as persisted inside PetPersist. */
+export interface TreatLedger {
+  /** Current stocked treats (0..maxTreats). */
+  treats: number
+  /** Time-output anchor: epoch ms the wall-clock treat clock last advanced (0 = never started). */
+  lastTreatGrantAt: number
+  /** Work-output anchor: affinity turns counter at the last work-out settle. */
+  turnsAtLastTreatGrant: number
+}
+
+export function emptyTreatLedger(): TreatLedger {
+  return { treats: 0, lastTreatGrantAt: 0, turnsAtLastTreatGrant: 0 }
+}
+
+/** Outcome of one settlement pass. */
+export interface TreatSettlement {
+  /** Mutated ledger (caller persists it). */
+  ledger: TreatLedger
+  /** Treats gained in this pass (work + time). */
+  gained: number
+}
+
+function cap(treats: number, max: number): number {
+  return Math.min(max, Math.max(0, treats))
+}
+
+/**
+ * Settle treat grants from both sources against one ledger snapshot.
+ * Work output counts whole periods since the last work settlement
+ * (turnsDelta / turnsPerTreat) and advances only the work anchor;
+ * time output counts whole periods since the time anchor
+ * (`lastTreatGrantAt`) and advances only the time anchor. The two sources
+ * are independent so a continuously working user still earns time treats.
+ * 0 time history never backfills — the clock starts at the first settlement.
+ * Both sources are clamped by the stock cap.
+ */
+export function settleTreatGrants(
+  ledger: TreatLedger,
+  turns: number,
+  nowMs: number,
+  config: TreatConfig = defaultTreatConfig,
+): TreatSettlement {
+  const turnDelta = Math.max(0, turns - ledger.turnsAtLastTreatGrant)
+  const workGrants = Math.floor(turnDelta / config.turnsPerTreat)
+  // The time clock starts at the first settlement (no backfill of pre-first
+  // idle history); thereafter only time grants move it forward.
+  const timeAnchor = ledger.lastTreatGrantAt === 0 ? nowMs : ledger.lastTreatGrantAt
+  const timeGrants = Math.floor(Math.max(0, nowMs - timeAnchor) / config.timeTreatMs)
+  const gained = workGrants + timeGrants
+  if (gained <= 0) return { ledger, gained: 0 }
+  return {
+    ledger: {
+      treats: cap(ledger.treats + gained, config.maxTreats),
+      lastTreatGrantAt: timeGrants > 0
+        ? timeAnchor + timeGrants * config.timeTreatMs
+        : timeAnchor,
+      turnsAtLastTreatGrant: workGrants > 0
+        ? turns - (turnDelta % config.turnsPerTreat)
+        : ledger.turnsAtLastTreatGrant,
+    },
+    gained,
+  }
+}
+
+/**
+ * Consume one treat for a feed. Returns the outcome; a feed with no stocked
+ * treats is refused.
+ */
+export function consumeTreat(
+  ledger: TreatLedger,
+): { ok: true; ledger: TreatLedger } | { ok: false } {
+  if (ledger.treats <= 0) return { ok: false }
+  return { ok: true, ledger: { ...ledger, treats: ledger.treats - 1 } }
+}