@linxin666/dsh-pet 0.1.1

package/src/client/spritesheet.ts

@@ -0,0 +1,138 @@
+/**
+ * Whale-girl spritesheet geometry and animation tracks.
+ *
+ * The atlas follows the Codex/hatch-pet contract: 8 columns × 9 rows of
+ * 192×208 cells (1536×1872 total), rows in this order:
+ *   0 idle, 1 running-right, 2 running-left, 3 waving, 4 jumping,
+ *   5 failed, 6 waiting, 7 running, 8 review
+ *
+ * Frame counts and per-frame durations are per-track definitions below; the
+ * whale-girl atlas is produced by the hatch-pet pipeline, so calibrate
+ * `TRACKS` against the actual run (`pet_request.json` frame counts) when the
+ * asset lands. Tracks that do not loop hand off to `fallback`.
+ * @module @linxin666/dsh-pet/client/spritesheet
+ */
+
+import type { PetAnimation } from '../state.ts'
+
+/** Atlas cell size in px (Codex contract). */
+export const FRAME_WIDTH = 192
+export const FRAME_HEIGHT = 208
+/** Columns per row (max frames per track). */
+export const FRAME_COLUMNS = 8
+
+/** One animation track: frame indices into the row + per-frame durations. */
+export interface TrackDef {
+  /** Frame indices (columns) played in order; must be < FRAME_COLUMNS. */
+  frames: readonly number[]
+  /** Per-frame duration in ms; same length as frames. */
+  durations: readonly number[]
+  /** Whether the track loops; a non-looping track hands off to fallback. */
+  loop: boolean
+  /** Track to play after a non-looping track finishes. */
+  fallback?: PetAnimation
+}
+
+/**
+ * Track definitions for the whale-girl. Durations are tuned for a soft,
+ * slow-healing feel (roughly 2.5× the earlier fast draft — the pet should
+ * breathe, not race); calibrate frame counts against the hatch-pet run when
+ * the asset lands (rows may carry 4–8 frames).
+ */
+export const TRACKS: Record<PetAnimation, TrackDef> = {
+  idle: { frames: [0, 1, 2, 3, 4, 5], durations: [400, 400, 500, 400, 400, 500], loop: true },
+  'running-right': { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [225, 225, 225, 225, 225, 225, 225, 225], loop: true },
+  'running-left': { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [225, 225, 225, 225, 225, 225, 225, 225], loop: true },
+  waving: { frames: [0, 1, 2, 3], durations: [350, 350, 350, 350], loop: true },
+  jumping: { frames: [0, 1, 2, 3, 4], durations: [300, 300, 300, 350, 350], loop: false, fallback: 'idle' },
+  failed: { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [450, 450, 450, 500, 550, 600, 450, 450], loop: false, fallback: 'idle' },
+  waiting: { frames: [0, 1, 2, 3, 4, 5], durations: [450, 450, 500, 450, 450, 500], loop: true },
+  running: { frames: [0, 1, 2, 3, 4, 5], durations: [250, 250, 250, 250, 250, 250], loop: true },
+  review: { frames: [0, 1, 2, 3, 4, 5], durations: [550, 550, 550, 550, 550, 550], loop: true },
+}
+
+/** Row index of one animation track (mirrors state.ts rowOf). */
+export function rowOfTrack(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]
+}
+
+/**
+ * Background-position (px) of one frame cell within the scaled atlas.
+ * The background image is scaled by `scale` (element size ÷ cell size), and
+ * background-position offsets are applied in SCALED coordinates — using raw
+ * atlas coordinates here would drift each frame by the scale factor and
+ * render torn/overlapping frames.
+ */
+export function framePosition(row: number, col: number, scale = 1): { x: number; y: number } {
+  return { x: -col * FRAME_WIDTH * scale, y: -row * FRAME_HEIGHT * scale }
+}
+
+/** Total duration of one track, ms. */
+export function trackDuration(track: TrackDef): number {
+  return track.durations.reduce((sum, d) => sum + d, 0)
+}
+
+/**
+ * Detect how many frames each row actually carries by scanning the decoded
+ * atlas for non-transparent cells (hatch-pet rows may hold 4–8 frames; the
+ * unused trailing cells are fully transparent). Rows whose every sample is
+ * transparent report 0.
+ * @param image - the fully decoded spritesheet (natural size 1536×1872).
+ * @returns per-row frame counts, length 9.
+ */
+export function detectFrameCounts(image: HTMLImageElement): number[] {
+  const canvas = document.createElement('canvas')
+  canvas.width = image.naturalWidth
+  canvas.height = image.naturalHeight
+  const ctx = canvas.getContext('2d')
+  if (ctx === null) return Array.from({ length: 9 }, () => FRAME_COLUMNS)
+  ctx.drawImage(image, 0, 0)
+  const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data
+  const counts: number[] = []
+  const stride = FRAME_COLUMNS * FRAME_WIDTH
+  const probeStep = 8
+  const margin = 12
+  for (let row = 0; row < 9; row++) {
+    let count = 0
+    for (let col = 0; col < FRAME_COLUMNS; col++) {
+      let hasContent = false
+      const x0 = col * FRAME_WIDTH
+      const y0 = row * FRAME_HEIGHT
+      for (let y = y0 + margin; y < y0 + FRAME_HEIGHT - margin && !hasContent; y += probeStep) {
+        for (let x = x0 + margin; x < x0 + FRAME_WIDTH - margin && !hasContent; x += probeStep) {
+          const idx = (y * stride + x) * 4
+          if ((data[idx + 3] ?? 0) > 8) hasContent = true
+        }
+      }
+      if (hasContent) count += 1
+    }
+    counts.push(count)
+  }
+  return counts
+}
+
+/**
+ * Trim a track to the actual frame count of its row. A row with 0 detected
+ * frames degrades to the first frame (the atlas is still loading or corrupt)
+ * so the pet never renders blank.
+ */
+export function trimTrack(track: TrackDef, frameCount: number): TrackDef {
+  const n = Math.max(1, Math.min(frameCount, track.frames.length))
+  return {
+    frames: track.frames.slice(0, n),
+    durations: track.durations.slice(0, n),
+    loop: track.loop,
+    ...(track.fallback === undefined ? {} : { fallback: track.fallback }),
+  }
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ * @module @linxin666/dsh-pet
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+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'
+
+export { PetService } from './service.ts'
+export type {
+  PetConfig,
+  PetInteractResult,
+  PetStateView,
+} from './service.ts'
+export {
+  AFFINITY_MAX,
+  AFFINITY_RANKS,
+  applyInteraction,
+  applyTurnReward,
+  emptyAffinity,
+  rankOf,
+} from './affinity.ts'
+export type {
+  AffinityConfig,
+  AffinityState,
+  InteractionOutcome,
+  PetInteraction,
+} from './affinity.ts'
+export {
+  animationForPhase,
+  PetStateMachine,
+  rowOf,
+} from './state.ts'
+export type {
+  ActivityPhase,
+  PetAnimation,
+  PetStateConfig,
+  PetStateInput,
+  PetStateSnapshot,
+} from './state.ts'
+export {
+  consumeTreat,
+  defaultTreatConfig,
+  emptyTreatLedger,
+  settleTreatGrants,
+} from './treats.ts'
+export type { TreatConfig, TreatLedger, TreatSettlement } from './treats.ts'
+export {
+  defaultDisplayConfig,
+  emptyPersist,
+  loadPetPersist,
+  petHomeDir,
+  savePetPersist,
+} from './persist.ts'
+export type { PetDisplayConfig, PetPersist } from './persist.ts'
+
+export {
+  makePetRoutes,
+  petPackageRoot,
+  PET_API_PREFIX,
+  PET_ASSET_PREFIX,
+} from './routes.ts'
+
+/** Stable cordis plugin name (matches cordis.patch.yml insert id). */
+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),
+})
+
+/** 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)
+
+  // 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.
+  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(),
+    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) })
+  let disposeRoutes: (() => void) | undefined
+  const syncRoutes = (): void => {
+    const enabled = current().enabled ?? true
+    if (disposeRoutes === undefined && enabled) {
+      disposeRoutes = ctx.effect(
+        () => {
+          const disposers = routes.map((route) => ctx.webServer.register(route))
+          return () => { for (const dispose of disposers) dispose() }
+        },
+        'pet: routes',
+      )
+    } else if (disposeRoutes !== undefined && !enabled) {
+      disposeRoutes()
+      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()
+    },
+  })
+  syncRoutes()
+}

package/src/invariant.ts

@@ -0,0 +1,40 @@
+/**
+ * Package invariants — cheap structural checks run at import time on the
+ * host side. Mirrors the pattern used by other dsh plugin packages.
+ * @module @linxin666/dsh-pet/invariant
+ */
+
+import { AFFINITY_MAX, AFFINITY_RANKS, defaultAffinityConfig } from './affinity.ts'
+import { animationForPhase } from './state.ts'
+import type { ActivityPhase } from './state.ts'
+
+/** Assert a condition; throws a descriptive Error when violated. */
+export function invariant(condition: unknown, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(`[dsh-pet] ${message}`)
+  }
+}
+
+/** Run every package invariant once; throws on the first violation. */
+export function runPetInvariants(): void {
+  invariant(AFFINITY_MAX > 0, 'AFFINITY_MAX must be positive')
+  invariant(
+    AFFINITY_RANKS.length > 0 && AFFINITY_RANKS[0]!.min === 0,
+    'AFFINITY_RANKS must start at 0',
+  )
+  invariant(defaultAffinityConfig.turnReward > 0, 'turnReward must be positive')
+  invariant(defaultAffinityConfig.feedCooldownMs > defaultAffinityConfig.petCooldownMs,
+    'feed cooldown must exceed pet cooldown')
+
+  // Every activity phase must map onto a known animation track.
+  const phases: readonly ActivityPhase[] = ['idle', 'waiting', 'thinking', 'tool', 'done']
+  for (const phase of phases) {
+    invariant(
+      ['idle', 'running', 'running-right', 'waiting', 'jumping'].includes(animationForPhase(phase)),
+      `phase ${phase} maps outside the animation contract`,
+    )
+  }
+}
+
+// Run once on import (host half only; cheap and side-effect free).
+runPetInvariants()

package/src/persist.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { AFFINITY_MAX, emptyAffinity } from './affinity.ts'
+import { defaultTreatConfig, emptyTreatLedger } from './treats.ts'
+import {
+  DEFAULT_PET_NAME,
+  DISPLAY_INSET_MAX,
+  DISPLAY_SIZE_MAX,
+  DISPLAY_SIZE_MIN,
+  defaultDisplayConfig,
+  emptyPersist,
+  loadPetPersist,
+  savePetPersist,
+} from './persist.ts'
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), 'dsh-pet-test-'))
+}
+
+describe('loadPetPersist', () => {
+  it('falls back to defaults when the file is missing', () => {
+    const dir = tempDir()
+    try {
+      expect(loadPetPersist(dir)).toEqual(emptyPersist())
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('falls back to defaults on corrupt JSON', () => {
+    const dir = tempDir()
+    try {
+      writeFileSync(join(dir, 'pet.json'), '{ not json', 'utf8')
+      expect(loadPetPersist(dir)).toEqual(emptyPersist())
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('round-trips a saved persist file', () => {
+    const dir = tempDir()
+    try {
+      const data = {
+        name: '泡泡',
+        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 },
+      }
+      savePetPersist(data, dir)
+      expect(loadPetPersist(dir)).toEqual(data)
+    } 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: '   ',
+        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.affinity.points).toBe(AFFINITY_MAX)
+      expect(loaded.affinity.lastPetAt).toBe(0)
+      expect(loaded.affinity.lastFeedAt).toBe(0)
+      expect(loaded.affinity.pets).toBe(0)
+      expect(loaded.affinity.feeds).toBe(1.5) // finite numbers pass through
+      expect(loaded.treats.treats).toBe(defaultTreatConfig.maxTreats)
+      expect(loaded.treats.lastTreatGrantAt).toBe(0)
+      expect(loaded.display.visible).toBe(defaultDisplayConfig.visible)
+      expect(loaded.display.size).toBe(DISPLAY_SIZE_MIN) // -10 clamped to min
+      expect(loaded.display.right).toBe(DISPLAY_INSET_MAX) // 1e12 clamped to max
+      expect(loaded.display.bottom).toBe(20) // finite in-range passes through
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('clamps oversized display size to the max', () => {
+    const dir = tempDir()
+    try {
+      writeFileSync(join(dir, 'pet.json'), JSON.stringify({
+        display: { visible: true, size: 1e9, right: 0, bottom: 0 },
+      }), 'utf8')
+      expect(loadPetPersist(dir).display.size).toBe(DISPLAY_SIZE_MAX)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})

package/src/persist.ts

@@ -0,0 +1,128 @@
+/**
+ * Pet persistence — tiny JSON store for affinity + display config, written
+ * under $DSH_HOME (defaults to ~/.dsh) as `pet.json`. Deliberately minimal:
+ * one file, atomic rename write, tolerant read (corrupt file → defaults).
+ * @module @linxin666/dsh-pet/persist
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { AFFINITY_MAX, emptyAffinity, type AffinityState } from './affinity.ts'
+import { defaultTreatConfig, emptyTreatLedger, type TreatLedger } from './treats.ts'
+
+/** Display configuration the user can tweak. */
+export interface PetDisplayConfig {
+  /** Master switch. */
+  visible: boolean
+  /** Scale of the rendered pet in px (sprite cell height). */
+  size: number
+  /** Horizontal inset from the viewport right edge, px. */
+  right: number
+  /** Vertical inset from the viewport bottom edge, px. */
+  bottom: number
+}
+
+export const defaultDisplayConfig: PetDisplayConfig = {
+  visible: true,
+  size: 160,
+  right: 24,
+  bottom: 20,
+}
+
+/** Display value bounds (shared by load-time validation and setConfig). */
+export const DISPLAY_SIZE_MIN = 32
+export const DISPLAY_SIZE_MAX = 512
+export const DISPLAY_INSET_MAX = 10_000
+
+/** Everything persisted for the pet. */
+export interface PetPersist {
+  /** User-customizable pet display name. */
+  name: string
+  affinity: AffinityState
+  /** Treat (小鱼干) stock ledger. */
+  treats: TreatLedger
+  display: PetDisplayConfig
+}
+
+/** Default pet name (used until the user renames the pet). */
+export const DEFAULT_PET_NAME = '鲸鱼娘'
+
+/** Name constraints. */
+export const PET_NAME_MAX_LENGTH = 20
+
+export function emptyPersist(): PetPersist {
+  return {
+    name: DEFAULT_PET_NAME,
+    affinity: emptyAffinity(),
+    treats: emptyTreatLedger(),
+    display: { ...defaultDisplayConfig },
+  }
+}
+
+/** Resolve the persistence directory ($DSH_HOME or ~/.dsh). */
+export function petHomeDir(): string {
+  return process.env.DSH_HOME ?? join(homedir(), '.dsh')
+}
+
+/** Numeric field guard: finite numbers only, else the fallback. */
+function finiteNum(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}
+
+/** Clamp one count/score into [0, max]. */
+function clamp(value: number, max: number): number {
+  return Math.min(max, Math.max(0, value))
+}
+
+/** Load persisted state; missing or corrupt files fall back to defaults. */
+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 base = emptyPersist()
+    const rawAffinity = (parsed.affinity ?? {}) as Partial<AffinityState>
+    const affinity: AffinityState = {
+      points: clamp(finiteNum(rawAffinity.points, 0), AFFINITY_MAX),
+      lastPetAt: clamp(finiteNum(rawAffinity.lastPetAt, 0), Number.MAX_SAFE_INTEGER),
+      lastFeedAt: clamp(finiteNum(rawAffinity.lastFeedAt, 0), Number.MAX_SAFE_INTEGER),
+      pets: clamp(finiteNum(rawAffinity.pets, 0), Number.MAX_SAFE_INTEGER),
+      feeds: clamp(finiteNum(rawAffinity.feeds, 0), Number.MAX_SAFE_INTEGER),
+      turns: clamp(finiteNum(rawAffinity.turns, 0), Number.MAX_SAFE_INTEGER),
+    }
+    const rawTreats = (parsed.treats ?? {}) as Partial<TreatLedger>
+    const treats: TreatLedger = {
+      treats: clamp(finiteNum(rawTreats.treats, 0), defaultTreatConfig.maxTreats),
+      lastTreatGrantAt: clamp(finiteNum(rawTreats.lastTreatGrantAt, 0), Number.MAX_SAFE_INTEGER),
+      turnsAtLastTreatGrant: clamp(finiteNum(rawTreats.turnsAtLastTreatGrant, 0), Number.MAX_SAFE_INTEGER),
+    }
+    const rawDisplay = (parsed.display ?? {}) as Partial<PetDisplayConfig>
+    const display: PetDisplayConfig = {
+      visible: typeof rawDisplay.visible === 'boolean' ? rawDisplay.visible : base.display.visible,
+      // The settings schema requires whole pixels; drag positions are
+      // clamped but not integral, so round at the persistence boundary.
+      size: Math.round(Math.min(DISPLAY_SIZE_MAX, Math.max(DISPLAY_SIZE_MIN, finiteNum(rawDisplay.size, base.display.size)))),
+      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)),
+    }
+    return {
+      name: typeof parsed.name === 'string' && parsed.name.trim() !== ''
+        ? parsed.name
+        : base.name,
+      affinity,
+      treats,
+      display,
+    }
+  } catch {
+    return emptyPersist()
+  }
+}
+
+/** Atomically persist state (write temp + rename). */
+export function savePetPersist(data: PetPersist, dir: string = petHomeDir()): void {
+  mkdirSync(dir, { recursive: true })
+  const target = join(dir, 'pet.json')
+  const tmp = `${target}.tmp`
+  writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8')
+  renameSync(tmp, target)
+}