@linxin666/dsh-pet 0.1.18 → 0.1.20

package/lib/types/index.js

@@ -12,17 +12,19 @@
  */
 import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
 import z from 'schemastery';
-import { PetService, PET_SETTINGS_NAMESPACE } from "./service.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 { 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";
+import { PetService, PET_SETTINGS_NAMESPACE } from './service.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';
+import { mountOnce } from './mount-once.js';
+export { PetService, MAX_SESSION_BUBBLES } 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 { BUILTIN_REMARKS, REMARK_KINDS, REMARK_LINE_MAX, REMARK_LINES_MAX, RemarkPicker, builtinRemark, normalizePetRemarks, } from './remarks.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. */
@@ -46,7 +48,8 @@ export function makePetSettingsSchema(fallbackPetId) {
     });
 }
 /** Register the pet service and its API + asset routes on the context. */
-export function apply(ctx, config = {}) {
+export const apply = mountOnce('@linxin666/dsh-pet', applyImpl);
+function applyImpl(ctx, config = {}) {
     const registry = config.registry
         ?? loadPetRegistry({
             packageRoot: petPackageRoot(import.meta.url),

package/lib/types/invariant.js

@@ -3,8 +3,8 @@
  * host side. Mirrors the pattern used by other dsh plugin packages.
  * @module @linxin666/dsh-pet/invariant
  */
-import { AFFINITY_MAX, AFFINITY_RANKS, defaultAffinityConfig } from "./affinity.js";
-import { animationForPhase } from "./state.js";
+import { AFFINITY_MAX, AFFINITY_RANKS, defaultAffinityConfig } from './affinity.js';
+import { animationForPhase } from './state.js';
 /** Assert a condition; throws a descriptive Error when violated. */
 export function invariant(condition, message) {
     if (!condition) {

package/lib/types/ledger.d.ts

@@ -8,11 +8,14 @@
  */
 import { type AffinityConfig, type PetAffinityView, type PetInteraction } from './affinity.ts';
 import { type TreatConfig } from './treats.ts';
+import { type PetRemarks } from './remarks.ts';
 import type { PetDisplayConfig, PetPersist } from './persist.ts';
 /** Tuning overrides for the affinity economy. */
 export interface LedgerConfig {
     affinity?: Partial<AffinityConfig>;
     treats?: Partial<TreatConfig>;
+    /** Per-pet remark pools for the selected pet (custom slots override built-ins). */
+    remarks?: PetRemarks;
 }
 /** Result of one ledger interaction (the shape the pet RPC returns). */
 export interface LedgerInteractionResult {
@@ -31,6 +34,8 @@ export interface LedgerInteractionResult {
 export declare class PetLedger {
     private readonly affinityConfig;
     private readonly treatConfig;
+    /** Round-robin reaction picker; rebuilt when the selected pet changes. */
+    private picker;
     private current;
     /** Completed turns already rewarded, per session (turn numbers are per-session). */
     private rewardedTurns;
@@ -45,16 +50,26 @@ export declare class PetLedger {
     get treatMax(): number;
     /** Consume the pending-write flag if any mutation occurred. */
     takeDirty(): boolean;
+    /**
+     * Drop a session's rewarded-turn bookkeeping once that session is disposed,
+     * so the per-session map does not grow without bound.
+     */
+    forgetSession(sessionId: string): void;
     /** 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;
+    /**
+     * Swap the reaction pools to another pet's custom remarks (called on pet
+     * selection). Slots the pet does not declare fall back to built-ins.
+     */
+    setRemarks(remarks?: PetRemarks): 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
+     * which is how the time output can ever accrue. Returns true when
      * the in-memory ledger changed and should be persisted.
      */
     settleTreats(nowMs: number): boolean;

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

@@ -1 +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"}
+{"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,EAAgB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AAC5D,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;IAC7B,mFAAmF;IACnF,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;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,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAY;IAC3B,oFAAoF;IACpF,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,sBAAsB,CAAI;IAClC,OAAO,CAAC,KAAK,CAAQ;IAErB,YAAY,OAAO,EAAE,UAAU,EAAE,MAAM,GAAE,YAAiB,EAKzD;IAED,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,CAInB;IAED;;;OAGG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAErC;IAED,mEAAmE;IACnE,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAG1C;IAED,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI5B;IAED,0EAA0E;IAC1E,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAG5C;IAED;;;OAGG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAErC;IAED;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAWnC;IAED;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOlE;IAED,8EAA8E;IAC9E,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOvC;IAED,OAAO,CAAC,eAAe;IASvB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,uBAAuB,CA8BrE;IAED,kDAAkD;IAClD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAE3C;CACF"}

package/lib/types/ledger.js

@@ -6,8 +6,9 @@
  * economic events: completed-turn rewards (official or legacy) and feeds.
  * @module @linxin666/dsh-pet/ledger
  */
-import { applyInteraction, affinityViewOf, applyTurnReward, defaultAffinityConfig, } from "./affinity.js";
-import { consumeTreat, defaultTreatConfig, settleTreatGrants, } from "./treats.js";
+import { applyInteraction, affinityViewOf, applyTurnReward, defaultAffinityConfig, } from './affinity.js';
+import { consumeTreat, defaultTreatConfig, settleTreatGrants, } from './treats.js';
+import { RemarkPicker } from './remarks.js';
 /**
  * Holds the current persistence snapshot and all economy bookkeeping. Every
  * mutating call flags takeDirty so the facade persists exactly once per
@@ -16,6 +17,8 @@ import { consumeTreat, defaultTreatConfig, settleTreatGrants, } from "./treats.j
 export class PetLedger {
     affinityConfig;
     treatConfig;
+    /** Round-robin reaction picker; rebuilt when the selected pet changes. */
+    picker;
     current;
     /** Completed turns already rewarded, per session (turn numbers are per-session). */
     rewardedTurns = new Map();
@@ -24,6 +27,7 @@ export class PetLedger {
     constructor(persist, config = {}) {
         this.affinityConfig = { ...defaultAffinityConfig, ...(config.affinity ?? {}) };
         this.treatConfig = { ...defaultTreatConfig, ...(config.treats ?? {}) };
+        this.picker = new RemarkPicker(config.remarks);
         this.current = persist;
     }
     /** Affinity cooldown/rank tuning (read-only). */
@@ -44,6 +48,13 @@ export class PetLedger {
         this.dirty = false;
         return was;
     }
+    /**
+     * Drop a session's rewarded-turn bookkeeping once that session is disposed,
+     * so the per-session map does not grow without bound.
+     */
+    forgetSession(sessionId) {
+        this.rewardedTurns.delete(sessionId);
+    }
     /** Replace the display block (clamping stays a caller concern). */
     setDisplay(display) {
         this.current = { ...this.current, display };
@@ -61,10 +72,17 @@ export class PetLedger {
         this.current = { ...this.current, names: { ...this.current.names, [petId]: name } };
         this.dirty = true;
     }
+    /**
+     * Swap the reaction pools to another pet's custom remarks (called on pet
+     * selection). Slots the pet does not declare fall back to built-ins.
+     */
+    setRemarks(remarks) {
+        this.picker = new RemarkPicker(remarks);
+    }
     /**
      * 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
+     * which is how the time output can ever accrue. Returns true when
      * the in-memory ledger changed and should be persisted.
      */
     settleTreats(nowMs) {
@@ -118,14 +136,17 @@ export class PetLedger {
         if (kind === 'feed')
             this.settleTreats(nowMs);
         const outcome = applyInteraction(this.current.affinity, kind, nowMs, this.affinityConfig);
+        // Reactions come from the picker pools (custom per-pet slots override
+        // the built-in library per slot); outcome.reaction stays the fallback
+        // copy for direct applyInteraction callers.
         if (kind === 'feed' && !outcome.accepted) {
-            return { reaction: outcome.reaction, delta: 0, affinity: this.affinityView(nowMs) };
+            return { reaction: this.picker.pick('feedCooldown'), delta: 0, affinity: this.affinityView(nowMs) };
         }
         if (kind === 'feed') {
             const consume = consumeTreat(this.current.treats);
             if (!consume.ok) {
                 return {
-                    reaction: '没有小鱼干了，多陪我工作一会儿吧～',
+                    reaction: this.picker.pick('noTreats'),
                     delta: 0,
                     affinity: this.affinityView(nowMs),
                 };
@@ -137,7 +158,11 @@ export class PetLedger {
             this.current = { ...this.current, affinity: outcome.affinity };
             this.dirty = true;
         }
-        return { reaction: outcome.reaction, delta: outcome.delta, affinity: this.affinityView(nowMs) };
+        return {
+            reaction: this.picker.pick(outcome.accepted ? kind : 'petCooldown'),
+            delta: outcome.delta,
+            affinity: this.affinityView(nowMs),
+        };
     }
     /** Current affinity view for the RPC snapshot. */
     affinityView(nowMs) {

package/lib/types/mount-once.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export declare function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T;
+//# sourceMappingURL=mount-once.d.ts.map

package/lib/types/mount-once.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-once.d.ts","sourceRoot":"","sources":["../../src/mount-once.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;GAcG;AAaH;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAW9F"}

package/lib/types/mount-once.js

@@ -0,0 +1,42 @@
+// Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+const MOUNTED = Symbol.for('dsh-web-ui.mounted-plugins');
+function mountedSet() {
+    const registry = globalThis;
+    return (registry[MOUNTED] ??= new Set());
+}
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export function mountOnce(packageName, fn) {
+    return ((...args) => {
+        const mounted = mountedSet();
+        if (mounted.has(packageName))
+            return;
+        mounted.add(packageName);
+        const ctx = args[0];
+        ctx?.effect?.(() => () => {
+            mounted.delete(packageName);
+        });
+        return fn(...args);
+    });
+}

package/lib/types/persist.js

@@ -6,9 +6,9 @@
  */
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { dshHome } from "./dsh-home.js";
-import { AFFINITY_MAX, emptyAffinity } from "./affinity.js";
-import { defaultTreatConfig, emptyTreatLedger } from "./treats.js";
+import { dshHome } from './dsh-home.js';
+import { AFFINITY_MAX, emptyAffinity } from './affinity.js';
+import { defaultTreatConfig, emptyTreatLedger } from './treats.js';
 export const defaultDisplayConfig = {
     visible: true,
     size: 160,

package/lib/types/registry.d.ts

@@ -17,6 +17,7 @@
  * @module @linxin666/dsh-pet/registry
  */
 import type { PetAnimation } from './state.ts';
+import { type PetRemarks, type PetRemarksManifest } from './remarks.ts';
 /** Fixed row order of the 9-state animation contract. */
 export declare const PET_ROW_ORDER: readonly PetAnimation[];
 /** Atlas cell size in px. */
@@ -80,6 +81,13 @@ export interface PetManifest {
     frames?: number[];
     /** Optional per-track rhythm overrides; omitted tracks use the defaults. */
     tracks?: Partial<Record<PetAnimation, PetTrackOverride>>;
+    /**
+     * Optional witty-remark overrides the pet speaks on interactions
+     * (community contributions use this to give their pet its own voice).
+     * Each slot accepts one line or a pool of lines; a slot replaces the
+     * built-in default pool for that slot only.
+     */
+    remarks?: PetRemarksManifest;
 }
 /** Per-track rhythm overrides a manifest may carry. */
 export interface PetTrackOverride {
@@ -114,6 +122,8 @@ export interface PetEntry extends PetDefinition {
     dir: string;
     /** Atlas path relative to 'dir' (declared by the manifest). */
     spritesheetPath: string;
+    /** Normalized per-pet remark pools (manifest 'remarks'), when declared. */
+    remarks?: PetRemarks;
 }
 /** Registry load result: resolved entries plus load warnings. */
 export interface PetRegistry {

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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAuB,KAAK,UAAU,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAE5F,yDAAyD;AACzD,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EAUhD,CAAA;AAED,6BAA6B;AAC7B,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,EAAE,OAAqC,CAAA;AACpE,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB,IAAI,CAAA;AACpC,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,IAAI,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAgC,CAAA;AAElF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAQnG;AAeD,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,uDAAuD;IACvD,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,yEAAyE;IACzE,IAAI,EAAE,OAAO,CAAA;IACb,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB;AAED,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,YAAY,EAAE;IACxD,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB,CAUA,CAAA;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAA;IACV,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAA;IACnB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAA;IACvB,+DAA+D;IAC/D,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAA;IACxD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;CAC7B;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,6BAA6B;IAC7B,IAAI,EAAE,OAAO,CAAA;IACb,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,wDAAwD;IACxD,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;IACzC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,uDAAuD;AACvD,MAAM,WAAW,QAAS,SAAQ,aAAa;IAC7C,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAA;IACX,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAA;IACvB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,QAAQ,EAAE,CAAA;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;IACtC,2EAA2E;IAC3E,YAAY,IAAI,QAAQ,CAAA;CACzB;AAED,wBAAwB;AACxB,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;CAC/B;AAQD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC1D,QAAQ,GAAG,SAAS,CAoFtB;AAkCD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAwCxE;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,aAAa,CAY3D;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEpD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAEnD"}

package/lib/types/registry.js

@@ -20,6 +20,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 { normalizePetRemarks } from './remarks.js';
 /** Fixed row order of the 9-state animation contract. */
 export const PET_ROW_ORDER = [
     'idle',
@@ -129,6 +130,7 @@ export function resolvePetManifest(raw, dir, options = {}) {
         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 trackOverrides = (typeof source.tracks === 'object' && source.tracks !== null ? source.tracks : {});
     const tracks = {};
     for (const [row, animation] of PET_ROW_ORDER.entries()) {
@@ -168,6 +170,7 @@ export function resolvePetManifest(raw, dir, options = {}) {
         manifestUrl: assetUrl(assetPrefix, id, 'pet.json'),
         dir,
         spritesheetPath: spritesheetPath.join('/'),
+        ...(remarks === undefined ? {} : { remarks }),
     };
 }
 /** Scan one directory of pet folders; entries come back in name order. */

package/lib/types/remarks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pet remark (reaction copy) library — pure. Reaction bubbles the pet speaks
+ * on interaction events come from two layers:
+ *  - the built-in default library below (a generous pool per event kind);
+ *  - per-pet custom lines declared in a manifest's 'remarks' block, which
+ *    community pet contributions (PRs) use to give their pet its own voice.
+ * A custom slot replaces the built-in pool for that slot only; the other
+ * slots keep the built-in lines. Picks cycle round-robin within a pool so
+ * repeated interactions stay varied while tests stay deterministic (no
+ * randomness, no clock).
+ * @module @linxin666/dsh-pet/remarks
+ */
+/** Interaction events a reaction line can accompany. */
+export type RemarkKind = 'pet' | 'petCooldown' | 'feed' | 'feedCooldown' | 'noTreats';
+/** Every remark slot, in a stable order. */
+export declare const REMARK_KINDS: readonly RemarkKind[];
+/** Per-pet remark overrides (normalized shape; each slot is a line pool). */
+export type PetRemarks = Partial<Record<RemarkKind, string[]>>;
+/** Raw manifest shape: each slot accepts one line or a pool of lines. */
+export type PetRemarksManifest = Partial<Record<RemarkKind, string | string[]>>;
+/** Longest accepted reaction line (characters, trimmed before slicing). */
+export declare const REMARK_LINE_MAX = 120;
+/** Longest accepted pool per slot. */
+export declare const REMARK_LINES_MAX = 64;
+/**
+ * Built-in default remark library. Every pool is plain zh copy in the
+ * whale-girl voice; the first line of each pool is the legacy reaction the
+ * plugin has always spoken, so existing installs and tests keep their
+ * wording while the pool adds variety. No emoji characters anywhere (the
+ * repo bans them); ～ is the whale-girl's signature.
+ */
+export declare const BUILTIN_REMARKS: Readonly<Record<RemarkKind, readonly string[]>>;
+/** The legacy first line of one kind (direct callers' fallback copy). */
+export declare function builtinRemark(kind: RemarkKind): string;
+/**
+ * Normalize a manifest 'remarks' block into per-kind line pools. Unknown
+ * slots and non-string entries are skipped with a warning; empty pools are
+ * dropped so the built-in library takes the slot. Returns undefined when no
+ * usable slot remains.
+ */
+export declare function normalizePetRemarks(raw: unknown, onWarning?: (message: string) => void): PetRemarks | undefined;
+/**
+ * Round-robin reaction picker over the effective pools (per-pet custom lines
+ * override the built-in pool per slot). Counters are per slot, so each slot
+ * cycles its own list independently and picks stay deterministic for tests.
+ */
+export declare class RemarkPicker {
+    private readonly counters;
+    private readonly pools;
+    constructor(overrides?: PetRemarks);
+    /** The effective pool for one slot (custom override or built-in). */
+    pool(kind: RemarkKind): readonly string[];
+    /** The next line for one slot (round-robin within its pool). */
+    pick(kind: RemarkKind): string;
+}
+//# sourceMappingURL=remarks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remarks.d.ts","sourceRoot":"","sources":["../../src/remarks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wDAAwD;AACxD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,aAAa,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CAAA;AAErF,4CAA4C;AAC5C,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAM7C,CAAA;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;AAE9D,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAA;AAE/E,2EAA2E;AAC3E,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC,CA6D3E,CAAA;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,OAAO,EACZ,SAAS,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,GAC9C,UAAU,GAAG,SAAS,CAyBxB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAE7D,YAAY,SAAS,CAAC,EAAE,UAAU,EAMjC;IAED,qEAAqE;IACrE,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAExC;IAED,gEAAgE;IAChE,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAK7B;CACF"}

package/lib/types/remarks.js

@@ -0,0 +1,157 @@
+/**
+ * Pet remark (reaction copy) library — pure. Reaction bubbles the pet speaks
+ * on interaction events come from two layers:
+ *  - the built-in default library below (a generous pool per event kind);
+ *  - per-pet custom lines declared in a manifest's 'remarks' block, which
+ *    community pet contributions (PRs) use to give their pet its own voice.
+ * A custom slot replaces the built-in pool for that slot only; the other
+ * slots keep the built-in lines. Picks cycle round-robin within a pool so
+ * repeated interactions stay varied while tests stay deterministic (no
+ * randomness, no clock).
+ * @module @linxin666/dsh-pet/remarks
+ */
+/** Every remark slot, in a stable order. */
+export const REMARK_KINDS = [
+    'pet',
+    'petCooldown',
+    'feed',
+    'feedCooldown',
+    'noTreats',
+];
+/** Longest accepted reaction line (characters, trimmed before slicing). */
+export const REMARK_LINE_MAX = 120;
+/** Longest accepted pool per slot. */
+export const REMARK_LINES_MAX = 64;
+/**
+ * Built-in default remark library. Every pool is plain zh copy in the
+ * whale-girl voice; the first line of each pool is the legacy reaction the
+ * plugin has always spoken, so existing installs and tests keep their
+ * wording while the pool adds variety. No emoji characters anywhere (the
+ * repo bans them); ～ is the whale-girl's signature.
+ */
+export const BUILTIN_REMARKS = {
+    pet: [
+        '咕噜咕噜～被摸摸好舒服！',
+        '再摸摸这里，痒痒的～',
+        '头顶温度刚刚好，安心～',
+        '被摸到耳朵啦，扑通扑通！',
+        '你的手掌好温暖，舍不得你走～',
+        '呼噜呼噜～就靠在这里不走了！',
+        '今天的摸头也收货成功！',
+        '蹭蹭你的手心，这是回礼～',
+        '多摸摸我，亲密度会涨哦！',
+        '闭眼享受中，请勿打扰～',
+    ],
+    petCooldown: [
+        '摸过头啦，让鲸鱼娘歇口气～',
+        '羽毛都快被摸秃啦，缓一缓～',
+        '呼……先让我喘口气嘛！',
+        '再摸就要睡着了哦～',
+        '稍微休息一下，待会儿再摸～',
+        '头顶要冒烟啦，停一停！',
+        '我知道你喜欢我，但也要节制呀～',
+        '歇一歇，摸摸的手感会更好哦～',
+        '咕……等我回个蓝～',
+        '让我先消化一下刚才的爱！',
+    ],
+    feed: [
+        '呜哇！小鱼干好好吃！',
+        '咔嚓咔嚓，美味到尾巴打结～',
+        '这条小鱼干是刚晒好的，好香！',
+        '谢谢你，胃里暖暖的～',
+        '囤粮 +1，今天也有好好被爱！',
+        '好吃到想转圈圈～',
+        '小鱼干最好吃了，再来亿条！',
+        '饱餐一顿，马上满血复活～',
+        '这个味道，是幸福的味道！',
+        '吃完了还不忘舔舔爪子～',
+    ],
+    feedCooldown: [
+        '吃饱啦，晚点再喂～',
+        '肚子圆滚滚的，装不下啦～',
+        '再喂就要变成球啦！',
+        '让我慢慢消化这份心意～',
+        '小鱼干的香气还没散呢～',
+        '呼……满足得动不了了～',
+        '先散步一圈再吃下一顿！',
+        '肚皮已经鼓鼓的啦～',
+        '好吃是好吃，可也得节制呀～',
+        '等我饿了会告诉你哦～',
+    ],
+    noTreats: [
+        '没有小鱼干了，多陪我工作一会儿吧～',
+        '粮仓空空，陪我完成几轮任务就会有小鱼干啦～',
+        '小鱼干在路上啦，先一起加油工作！',
+        '嘴巴寂寞了……快去完成一轮任务！',
+        '陪我多工作一会儿，鱼干自动到账～',
+        '现在喂我也只会饿着肚子说谢谢哦～',
+        '粮仓见底啦，用几轮任务换一条鱼干吧～',
+        '饿着肚子等你完成下一轮任务～',
+        '小鱼干藏在你的工作里，去找找看！',
+        '先工作后干饭，我们的约定哦～',
+    ],
+};
+/** The legacy first line of one kind (direct callers' fallback copy). */
+export function builtinRemark(kind) {
+    return BUILTIN_REMARKS[kind][0];
+}
+/**
+ * Normalize a manifest 'remarks' block into per-kind line pools. Unknown
+ * slots and non-string entries are skipped with a warning; empty pools are
+ * dropped so the built-in library takes the slot. Returns undefined when no
+ * usable slot remains.
+ */
+export function normalizePetRemarks(raw, onWarning = () => { }) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        onWarning('remarks must be an object with pet/petCooldown/feed/feedCooldown/noTreats slots');
+        return undefined;
+    }
+    const remarks = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!REMARK_KINDS.includes(key)) {
+            onWarning('unknown remarks slot ' + JSON.stringify(key));
+            continue;
+        }
+        const lines = (Array.isArray(value) ? value : [value])
+            .filter((line) => typeof line === 'string')
+            .map(line => line.trim())
+            .filter(line => line !== '')
+            .slice(0, REMARK_LINES_MAX)
+            .map(line => line.slice(0, REMARK_LINE_MAX));
+        if (lines.length === 0) {
+            onWarning('remarks slot ' + key + ' carries no usable lines');
+            continue;
+        }
+        remarks[key] = lines;
+    }
+    return Object.keys(remarks).length === 0 ? undefined : remarks;
+}
+/**
+ * Round-robin reaction picker over the effective pools (per-pet custom lines
+ * override the built-in pool per slot). Counters are per slot, so each slot
+ * cycles its own list independently and picks stay deterministic for tests.
+ */
+export class RemarkPicker {
+    counters = new Map();
+    pools;
+    constructor(overrides) {
+        this.pools = {};
+        for (const kind of REMARK_KINDS) {
+            const custom = overrides?.[kind];
+            this.pools[kind] = custom !== undefined && custom.length > 0 ? custom : BUILTIN_REMARKS[kind];
+        }
+    }
+    /** The effective pool for one slot (custom override or built-in). */
+    pool(kind) {
+        return this.pools[kind];
+    }
+    /** The next line for one slot (round-robin within its pool). */
+    pick(kind) {
+        const pool = this.pools[kind];
+        const index = (this.counters.get(kind) ?? 0) % pool.length;
+        this.counters.set(kind, index + 1);
+        return pool[index];
+    }
+}

package/lib/types/routes.js

@@ -11,7 +11,7 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { petEntryView } from "./registry.js";
+import { petEntryView } from './registry.js';
 /** Browser-facing base path of the pet API. */
 export const PET_API_PREFIX = '/api/pet';
 /** Browser-facing base path of the pet asset routes ('/pet/<id>/...'). */
@@ -273,4 +273,4 @@ export function makePetRoutes(deps) {
     return [...apiRoutes, assetRoute];
 }
 // Re-exported for the package surface (the registry owns the definition now).
-export { petPackageRoot } from "./registry.js";
+export { petPackageRoot } from './registry.js';