@linxin666/dsh-pet 0.1.14 → 0.1.16

package/lib/types/client/spritesheet.js

@@ -1,40 +1,12 @@
 /**
- * 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`.
+ * Spritesheet geometry helpers — parameterized by the pet definition the
+ * host serves over '/api/pet/pets', so the browser half renders any registry
+ * entry without per-pet code. The per-track tables (frames, durations, loop,
+ * fallback) also come from the registry; these helpers only place frames,
+ * guard track lengths, and map the fixed 9-row animation contract.
  * @module @linxin666/dsh-pet/client/spritesheet
  */
-/** 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;
-/**
- * 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 = {
-    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). */
+/** Row index of one animation track (the fixed 9-row contract). */
 export function rowOfTrack(animation) {
     const rows = {
         idle: 0,
@@ -56,61 +28,21 @@ export function rowOfTrack(animation) {
  * atlas coordinates here would drift each frame by the scale factor and
  * render torn/overlapping frames.
  */
-export function framePosition(row, col, scale = 1) {
-    return { x: -col * FRAME_WIDTH * scale, y: -row * FRAME_HEIGHT * scale };
+export function framePosition(cell, columns, row, col, scale = 1) {
+    return { x: -col * cell.width * scale, y: -row * cell.height * scale };
 }
 /** Total duration of one track, ms. */
 export function trackDuration(track) {
     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) {
-    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 = [];
-    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.
+ * Trim a track to the actual frame count of its row (the manifest's per-row
+ * counts are authoritative; this is a last-line guard against a definition
+ * whose row count disagrees with its track table). A row with 0 detected
+ * frames degrades to the first frame so the pet never renders blank.
  */
 export function trimTrack(track, frameCount) {
-    const n = Math.max(1, Math.min(frameCount, track.frames.length));
+    const n = Math.max(1, Math.min(frameCount, track.frames.length, track.durations.length));
     return {
         frames: track.frames.slice(0, n),
         durations: track.durations.slice(0, n),

package/lib/types/dsh-home.d.ts

@@ -0,0 +1,17 @@
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export declare function expandHome(path: string, home?: string): string;
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** Resolve the DSH home directory from the live environment. */
+export declare function dshHome(): string;
+//# sourceMappingURL=dsh-home.d.ts.map

package/lib/types/dsh-home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsh-home.d.ts","sourceRoot":"","sources":["../../src/dsh-home.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAKH,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAOrG;AAED,gEAAgE;AAChE,wBAAgB,OAAO,IAAI,MAAM,CAEhC"}

package/lib/types/dsh-home.js

@@ -0,0 +1,34 @@
+// Generated by scripts/sync-shared.mjs from shared/host/dsh-home.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * DSH_HOME resolution shared by the plugin family's Host halves: the
+ * environment override wins, the platform home fallback follows. Mirrors
+ * what dsh-pet and dsh-liangshen each used to implement locally.
+ */
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+export function expandHome(path, home = homedir()) {
+    if (path === '~')
+        return home;
+    if (path.startsWith('~/') || path.startsWith('~\\'))
+        return join(home, path.slice(2));
+    return path;
+}
+/**
+ * Resolve the DSH home directory.
+ * @param env - process environment to read DSH_HOME from.
+ * @param home - platform home directory fallback (test seam).
+ * @returns the absolute DSH home path.
+ */
+export function resolveDshHome(env = process.env, home = homedir()) {
+    const raw = env.DSH_HOME;
+    if (raw !== undefined && raw.trim() !== '') {
+        const expanded = expandHome(raw.trim(), home);
+        return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded);
+    }
+    return join(home, '.dsh');
+}
+/** Resolve the DSH home directory from the live environment. */
+export function dshHome() {
+    return resolveDshHome();
+}

package/lib/types/event-projection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Official session event projection — pure. Maps the durable DSH session
+ * vocabulary onto the pet's visual phases and carries an optional completed-
+ * turn reward for the ledger. Holds no state of its own; callers keep a
+ * {@link ProjectionRuntime} per session and feed events in arrival order.
+ * @module @linxin666/dsh-pet/event-projection
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { PetStateInput } from './state.ts';
+/** Runtime shape of the optional legacy activity event. */
+export interface ActivityStatusEventLike {
+    phase?: string;
+    line?: string;
+    phrase?: string;
+}
+/** Per-session facts needed to project the official event stream. */
+export interface ProjectionRuntime {
+    activeTools: Set<string>;
+    officialEventsSeen: boolean;
+    stepHadFailure: boolean;
+}
+/** One official event projection, optionally carrying a completed turn reward. */
+export interface PetActivityTransition {
+    input: PetStateInput;
+    completedTurn?: number;
+}
+/** Fresh projection runtime for a newly seen session. */
+export declare function emptyProjectionRuntime(): ProjectionRuntime;
+/** Whether a legacy phase is part of the pet's supported vocabulary. */
+export declare function isActivityPhase(phase: string): phase is PetStateInput['phase'];
+/**
+ * Project the durable DSH session vocabulary into the pet's visual phases.
+ * Unknown and log-only events do not disturb the last meaningful activity.
+ */
+export declare function projectOfficialEvent(event: SessionEvent, runtime: ProjectionRuntime): PetActivityTransition | undefined;
+//# sourceMappingURL=event-projection.d.ts.map

package/lib/types/event-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-projection.d.ts","sourceRoot":"","sources":["../../src/event-projection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,kBAAkB,EAAE,OAAO,CAAA;IAC3B,cAAc,EAAE,OAAO,CAAA;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,aAAa,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,yDAAyD;AACzD,wBAAgB,sBAAsB,IAAI,iBAAiB,CAE1D;AAQD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,CAE9E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,iBAAiB,GACzB,qBAAqB,GAAG,SAAS,CAyEnC"}

package/lib/types/event-projection.js

@@ -0,0 +1,98 @@
+/**
+ * Official session event projection — pure. Maps the durable DSH session
+ * vocabulary onto the pet's visual phases and carries an optional completed-
+ * turn reward for the ledger. Holds no state of its own; callers keep a
+ * {@link ProjectionRuntime} per session and feed events in arrival order.
+ * @module @linxin666/dsh-pet/event-projection
+ */
+/** Fresh projection runtime for a newly seen session. */
+export function emptyProjectionRuntime() {
+    return { activeTools: new Set(), officialEventsSeen: false, stepHadFailure: false };
+}
+/** Keep tool names readable inside the compact status bubble. */
+function displayToolName(name) {
+    const compact = name.replace(/\s+/g, ' ').trim() || '工具';
+    return compact.length <= 24 ? compact : `${compact.slice(0, 21)}...`;
+}
+/** Whether a legacy phase is part of the pet's supported vocabulary. */
+export function isActivityPhase(phase) {
+    return ['idle', 'waiting', 'thinking', 'tool', 'review', 'done', 'failed'].includes(phase);
+}
+/**
+ * Project the durable DSH session vocabulary into the pet's visual phases.
+ * Unknown and log-only events do not disturb the last meaningful activity.
+ */
+export function projectOfficialEvent(event, runtime) {
+    switch (event.type) {
+        case 'turn/start':
+            runtime.activeTools.clear();
+            runtime.stepHadFailure = false;
+            return { input: { phase: 'waiting', line: '准备开始' } };
+        case 'step/start':
+            runtime.activeTools.clear();
+            runtime.stepHadFailure = false;
+            return { input: { phase: 'waiting', line: '等待模型响应' } };
+        case 'assistant/chunk': {
+            const { chunk } = event.data;
+            if (chunk.type === 'reasoning-delta' && chunk.text.length > 0) {
+                return { input: { phase: 'thinking', line: '正在思考' } };
+            }
+            if (chunk.type === 'text-delta' && chunk.text.length > 0) {
+                return { input: { phase: 'review', line: '整理回复中' } };
+            }
+            return undefined;
+        }
+        case 'assistant/message':
+            return { input: { phase: 'review', line: '整理回复中' } };
+        case 'tool/call':
+            runtime.activeTools.add(String(event.data.callId));
+            return {
+                input: {
+                    phase: 'tool',
+                    line: `正在使用 ${displayToolName(event.data.name)}`,
+                },
+            };
+        case 'tool/result': {
+            const block = event.data.message.content[0];
+            runtime.activeTools.delete(String(event.data.message.source.callId));
+            runtime.stepHadFailure ||= event.data.error !== undefined || block.isError === true;
+            if (runtime.activeTools.size > 0) {
+                return {
+                    input: {
+                        phase: 'tool',
+                        line: `还有 ${runtime.activeTools.size} 个工具运行中`,
+                    },
+                };
+            }
+            return runtime.stepHadFailure
+                ? { input: { phase: 'failed', line: '工具执行失败' } }
+                : { input: { phase: 'thinking', line: '处理工具结果' } };
+        }
+        case 'turn/end': {
+            runtime.activeTools.clear();
+            switch (event.data.reason.kind) {
+                case 'completed':
+                    return {
+                        input: { phase: 'done', line: '完成啦' },
+                        completedTurn: event.data.turn,
+                    };
+                case 'error':
+                    return { input: { phase: 'failed', line: '执行失败' } };
+                case 'max-tokens':
+                    return { input: { phase: 'failed', line: '达到输出上限' } };
+                case 'interrupted':
+                    return { input: { phase: 'failed', line: '执行意外中断' } };
+                case 'blocked':
+                    return { input: { phase: 'waiting', line: '等待继续' } };
+                case 'aborted':
+                    return { input: { phase: 'idle', line: '已停止' } };
+                default:
+                    // TurnEndReasonMap is merge-extensible; a newer ending must not
+                    // leave the pet showing stale in-progress work.
+                    return { input: { phase: 'idle' } };
+            }
+        }
+        default:
+            return undefined;
+    }
+}

package/lib/types/index.d.ts

@@ -1,43 +1,56 @@
 /**
  * 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
  */
 import { Context } from '@deepseek-ai/cordis';
 import z from 'schemastery';
 import { type PetConfig } from './service.ts';
 export { PetService } from './service.ts';
-export type { PetConfig, PetInteractResult, PetStateView, } from './service.ts';
+export type { PetConfig, PetInteractResult, PetSettingsSection, 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 { DEFAULT_PET_ID, DEFAULT_PET_NAME, PET_NAME_MAX_LENGTH, 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';
+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, PET_API_PREFIX, PET_ASSET_PREFIX, } from './routes.ts';
 /** Stable cordis plugin name (matches cordis.patch.yml insert id). */
 export declare const name = "pet";
 /** Services required before the pet can mount its surfaces. */
 export declare const inject: string[];
-/** Settings section schema: the display fields and name the web settings surface edits. */
-export declare const PET_SETTINGS_SCHEMA: z<Schemastery.ObjectS<{
+/**
+ * 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 declare function makePetSettingsSchema(fallbackPetId: string): z<Schemastery.ObjectS<{
     visible: z<boolean, boolean>;
     size: z<number, number>;
     right: z<number, number>;
     bottom: z<number, number>;
-    name: z<string, string>;
+    petId: z<string, string>;
     enabled: z<boolean, boolean>;
 }>, Schemastery.ObjectT<{
     visible: z<boolean, boolean>;
     size: z<number, number>;
     right: z<number, number>;
     bottom: z<number, number>;
-    name: z<string, string>;
+    petId: z<string, string>;
     enabled: z<boolean, boolean>;
 }>>;
 /** Register the pet service and its API + asset routes on the context. */

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAG7C,OAAO,CAAC,MAAM,aAAa,CAAA;AAC3B,OAAO,EAAsC,KAAK,SAAS,EAA2B,MAAM,cAAc,CAAA;AAU1G,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,MAAM,GACP,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,GACN,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,EACb,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEhE,OAAO,EACL,aAAa,EACb,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAA;AAEpB,sEAAsE;AACtE,eAAO,MAAM,IAAI,QAAQ,CAAA;AAEzB,+DAA+D;AAC/D,eAAO,MAAM,MAAM,UAAgB,CAAA;AAEnC,2FAA2F;AAC3F,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;GAO9B,CAAA;AAEF,0EAA0E;AAC1E,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,SAAc,GAAG,IAAI,CAoDhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAG7C,OAAO,CAAC,MAAM,aAAa,CAAA;AAC3B,OAAO,EAAsC,KAAK,SAAS,EAA2B,MAAM,cAAc,CAAA;AAK1G,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,GACb,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,MAAM,GACP,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,KAAK,GACN,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,aAAa,EACb,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAChE,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,kBAAkB,GACnB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,aAAa,EACb,QAAQ,EACR,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAA;AAEpB,sEAAsE;AACtE,eAAO,MAAM,IAAI,QAAQ,CAAA;AAEzB,+DAA+D;AAC/D,eAAO,MAAM,MAAM,UAAgB,CAAA;AAEnC;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM;;;;;;;;;;;;;;IAS1D;AAED,0EAA0E;AAC1E,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,SAAc,GAAG,IAAI,CA+DhE"}

package/lib/types/index.js

@@ -1,61 +1,81 @@
 /**
  * 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
  */
 import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
 import z from 'schemastery';
 import { PetService, PET_SETTINGS_NAMESPACE } from "./service.js";
-import { makePetRoutes, petPackageRoot } from "./routes.js";
-import { DEFAULT_PET_NAME, DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN, PET_NAME_MAX_LENGTH, } from "./persist.js";
+import { makePetRoutes } from "./routes.js";
+import { loadPetRegistry, petPackageRoot } from "./registry.js";
+import { DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN } from "./persist.js";
 export { PetService } from "./service.js";
 export { AFFINITY_MAX, AFFINITY_RANKS, applyInteraction, applyTurnReward, emptyAffinity, rankOf, } from "./affinity.js";
 export { animationForPhase, PetStateMachine, rowOf, } from "./state.js";
 export { consumeTreat, defaultTreatConfig, emptyTreatLedger, settleTreatGrants, } from "./treats.js";
-export { defaultDisplayConfig, emptyPersist, loadPetPersist, petHomeDir, savePetPersist, } from "./persist.js";
-export { makePetRoutes, petPackageRoot, PET_API_PREFIX, PET_ASSET_PREFIX, } from "./routes.js";
+export { DEFAULT_PET_ID, DEFAULT_PET_NAME, PET_NAME_MAX_LENGTH, defaultDisplayConfig, emptyPersist, loadPetPersist, petHomeDir, savePetPersist, } from "./persist.js";
+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.js";
+export { makePetRoutes, PET_API_PREFIX, PET_ASSET_PREFIX, } from "./routes.js";
 /** 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),
-});
+/**
+ * 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) {
+    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, config = {}) {
-    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.
+    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 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 = () => base;
     const base = {
         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;
     const syncRoutes = () => {
         const enabled = current().enabled ?? true;
@@ -71,7 +91,7 @@ export function apply(ctx, config = {}) {
             disposeRoutes = undefined;
         }
     };
-    installSettingsSection(ctx, settingsNamespace(PET_SETTINGS_NAMESPACE), PET_SETTINGS_SCHEMA, base, {
+    installSettingsSection(ctx, settingsNamespace(PET_SETTINGS_NAMESPACE), makePetSettingsSchema(service.selectedPetId()), base, {
         setSource: (source) => { current = source; },
         onChange: () => {
             const section = current();

package/lib/types/ledger.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pet affinity economy (ledger) — composes the pure affinity and treats
+ * modules with the cooldown/dedup bookkeeping and emits updated persistence
+ * snapshots, marking dirty so the owning facade decides when to flush. Read
+ * paths (view) no longer settle the economy; settlements happen on explicit
+ * economic events: completed-turn rewards (official or legacy) and feeds.
+ * @module @linxin666/dsh-pet/ledger
+ */
+import { type AffinityConfig, type PetAffinityView, type PetInteraction } from './affinity.ts';
+import { type TreatConfig } from './treats.ts';
+import type { PetDisplayConfig, PetPersist } from './persist.ts';
+/** Tuning overrides for the affinity economy. */
+export interface LedgerConfig {
+    affinity?: Partial<AffinityConfig>;
+    treats?: Partial<TreatConfig>;
+}
+/** Result of one ledger interaction (the shape the pet RPC returns). */
+export interface LedgerInteractionResult {
+    /** Reaction copy bubble. */
+    reaction: string;
+    /** Points gained (0 when inside the cooldown). */
+    delta: number;
+    /** Full affinity snapshot (same shape as the state view). */
+    affinity: PetAffinityView;
+}
+/**
+ * Holds the current persistence snapshot and all economy bookkeeping. Every
+ * mutating call flags takeDirty so the facade persists exactly once per
+ * batch of changes; read methods (snapshot, affinityView) never write.
+ */
+export declare class PetLedger {
+    private readonly affinityConfig;
+    private readonly treatConfig;
+    private current;
+    /** Completed turns already rewarded, per session (turn numbers are per-session). */
+    private rewardedTurns;
+    private lastLegacyTurnRewardAt;
+    private dirty;
+    constructor(persist: PetPersist, config?: LedgerConfig);
+    /** Affinity cooldown/rank tuning (read-only). */
+    get affinity(): AffinityConfig;
+    /** The current persistence snapshot (trade a copy when mutating). */
+    get snapshot(): PetPersist;
+    /** Stock cap reported to clients. */
+    get treatMax(): number;
+    /** Consume the pending-write flag if any mutation occurred. */
+    takeDirty(): boolean;
+    /** Replace the display block (clamping stays a caller concern). */
+    setDisplay(display: PetDisplayConfig): void;
+    /** Replace the selected pet id (validation stays a caller concern). */
+    setPetId(petId: string): void;
+    /** Replace one pet's display name (validation stays a caller concern). */
+    setPetName(petId: string, name: string): void;
+    /**
+     * Settle the treat economy (work + time output since the last settlement).
+     * A zero-gain first settlement still starts the time clock (anchor write),
+     * which is how the 30-minute time output can ever accrue. Returns true when
+     * the in-memory ledger changed and should be persisted.
+     */
+    settleTreats(nowMs: number): boolean;
+    /**
+     * Award the completed-turn reward once per session+turn (idempotent) and
+     * run the treat settlement that work output feeds. Returns true when the
+     * snapshot changed.
+     */
+    rewardTurn(sessionId: string, turn: number, nowMs: number): boolean;
+    /** Preserve turn rewards for installations that only emit legacy activity. */
+    rewardLegacyTurn(nowMs: number): boolean;
+    private applyTurnReward;
+    /**
+     * Pet or feed the pet. Feeding settles first, then gates on the feed
+     * cooldown before spending stock — a feed inside the cooldown must not burn
+     * a treat for nothing.
+     */
+    interact(kind: PetInteraction, nowMs: number): LedgerInteractionResult;
+    /** Current affinity view for the RPC snapshot. */
+    affinityView(nowMs: number): PetAffinityView;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/lib/types/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEhE,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;CAC9B;AAED,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,6DAA6D;IAC7D,QAAQ,EAAE,eAAe,CAAA;CAC1B;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,OAAO,CAAY;IAC3B,oFAAoF;IACpF,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,sBAAsB,CAAI;IAClC,OAAO,CAAC,KAAK,CAAQ;gBAET,OAAO,EAAE,UAAU,EAAE,MAAM,GAAE,YAAiB;IAM1D,iDAAiD;IACjD,IAAI,QAAQ,IAAI,cAAc,CAE7B;IAED,qEAAqE;IACrE,IAAI,QAAQ,IAAI,UAAU,CAEzB;IAED,qCAAqC;IACrC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,+DAA+D;IAC/D,SAAS,IAAI,OAAO;IAMpB,mEAAmE;IACnE,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAK3C,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM7B,0EAA0E;IAC1E,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7C;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAapC;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IASnE,8EAA8E;IAC9E,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IASxC,OAAO,CAAC,eAAe;IASvB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB;IAyBtE,kDAAkD;IAClD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe;CAG7C"}