@linxin666/dsh-pet 0.2.2 → 0.2.4

package/lib/types/routes.js

@@ -8,11 +8,12 @@
  * optional previews), so adding a pet never touches route wiring.
  * @module @linxin666/dsh-pet/routes
  */
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { petEntryView } from './registry.js';
+import { join, sep } from 'node:path';
+import { DECORATION_ASSET_PREFIX, petEntryView, petPackageRoot } from './registry.js';
 import { isLoopbackRequest } from './loopback.js';
+import { dshHome } from './dsh-home.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>/...'). */
@@ -20,6 +21,43 @@ export const PET_ASSET_PREFIX = '/pet';
 const MANIFEST_FILE = 'pet.json';
 const PREVIEW_DIR = 'previews';
 const PREVIEW_PATTERN = /^[A-Za-z0-9._-]+$/;
+/**
+ * Per-class size ceilings for served pet assets, in bytes (pet-center M2 P3,
+ * issue #623). Constants are tested directly; makePetRoutes accepts an
+ * override so tests can exercise the 413 path with tiny caps.
+ */
+export const PET_ASSET_CAPS = {
+    /** pet.json manifest. */
+    manifest: 64 * 1024,
+    /** Atlas, preview and Live2D texture imagery. */
+    image: 20 * 1024 * 1024,
+    /** Live2D model closure files (.moc3, motion/physics/expression JSON; M3). */
+    model: 32 * 1024 * 1024,
+};
+/** Imagery extensions classify into the image cap; everything else served from a closure is model-class. */
+const IMAGE_EXTENSIONS = new Set(['.webp', '.png', '.gif', '.jpg', '.jpeg']);
+/** Lowercased file extension ('' when none). */
+function extensionOf(file) {
+    const dot = file.lastIndexOf('.');
+    return dot < 0 ? '' : file.slice(dot).toLowerCase();
+}
+/**
+ * realpath containment: resolve both sides and require the candidate to stay
+ * inside the base directory. A pet directory (or an atlas/preview inside it)
+ * that is a symlink escaping its root is rejected, never followed.
+ */
+export function containedRealpath(base, candidate) {
+    try {
+        const realBase = realpathSync(base);
+        const realCandidate = realpathSync(candidate);
+        return realCandidate === realBase || realCandidate.startsWith(realBase + sep)
+            ? realCandidate
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const MIME_BY_EXT = {
     '.webp': 'image/webp',
     '.png': 'image/png',
@@ -133,10 +171,14 @@ function dirAliases(registry) {
 /**
  * The one asset handler behind the '/pet' prefix. Resolves the pet by id (or
  * legacy directory alias), then serves exactly the files a manifest declares:
- * pet.json, the declared spritesheet path, and optional 'previews/<name>'
- * media. Composed pets without a manifest file get a synthesized pet.json.
+ * pet.json, the entry's servable set (the sprite2d atlas, or the live2d
+ * model3.json plus its reference closure — pet-center M3), and optional
+ * 'previews/<name>' media. The servable match is an exact string comparison
+ * against scan-time normalized paths, so crafted '..' or '.' segments never
+ * match; containedRealpath stays as the second layer. Composed pets without
+ * a manifest file get a synthesized pet.json.
  */
-function assetHandler(registry) {
+function assetHandler(registry, caps) {
     const aliases = dirAliases(registry);
     return (req, res) => {
         if (!guard(req, res))
@@ -198,15 +240,15 @@ function assetHandler(registry) {
             if (file === undefined)
                 synthesized = true;
         }
-        else if (rest.length > 0 && rel === entry.spritesheetPath) {
-            file = join(entry.dir, entry.spritesheetPath);
+        else if (rest.length > 0 && entry.servable.includes(rel)) {
+            file = join(entry.dir, rel);
         }
         else if (rest.length === 2 && rest[0] === PREVIEW_DIR && PREVIEW_PATTERN.test(rest[1])) {
             const preview = join(entry.dir, PREVIEW_DIR, rest[1]);
             file = existsSync(preview) ? preview : undefined;
         }
         if (synthesized) {
-            const body = Buffer.from(JSON.stringify(petEntryView(entry), null, 2), 'utf8');
+            const body = Buffer.from(JSON.stringify(petEntryView(entry, registry.globalVoice), null, 2), 'utf8');
             res.writeHead(200, {
                 'content-type': 'application/json; charset=utf-8',
                 'content-length': String(body.byteLength),
@@ -224,7 +266,29 @@ function assetHandler(registry) {
             res.end();
             return;
         }
-        const resolved = file;
+        // realpath containment: a symlink escaping the pet directory is refused.
+        const resolved = containedRealpath(entry.dir, file);
+        if (resolved === undefined) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        // Enforce the size ceiling before the file is read into memory.
+        const cap = rest.length === 1 && rest[0] === MANIFEST_FILE
+            ? caps.manifest
+            : IMAGE_EXTENSIONS.has(extensionOf(rel)) ? caps.image : caps.model;
+        try {
+            if (statSync(resolved).size > cap) {
+                res.writeHead(413);
+                res.end();
+                return;
+            }
+        }
+        catch {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
         readFile(resolved).then((body) => {
             res.writeHead(200, {
                 'content-type': mimeFor(resolved),
@@ -242,12 +306,234 @@ function assetHandler(registry) {
         });
     };
 }
-/** Build the full route family (API + assets) for one service. */
+/** Browser-facing base path of the plugin runtime files (pet-center M3). */
+export const PET_RUNTIME_PREFIX = PET_API_PREFIX + '/runtime';
+/**
+ * The runtime files the route may serve, by exact name (no slashes, no
+ * user-controlled path segments, so traversal is structurally impossible):
+ * the user-supplied Cubism Core from the pet runtime directory (the plugin
+ * never bundles or downloads it — issue #623 M1 §0) and the plugin-shipped
+ * MIT vendor bundle from the package lib directory.
+ */
+const RUNTIME_FILES = {
+    'live2dcubismcore.min.js': { root: 'runtimeDir' },
+    'live2d-vendor.js': { root: 'vendorDir' },
+    'live2d-vendor.js.map': { root: 'vendorDir' },
+};
+/** Size ceiling for one runtime file (the Cubism Core is ~200 KB today). */
+export const PET_RUNTIME_CAP = 16 * 1024 * 1024;
+/**
+ * The runtime handler behind '/api/pet/runtime/<name>'. A missing file
+ * answers 404 with a JSON marker the client renderer turns into install
+ * guidance (the Cubism Core is user-supplied, so its absence is a normal
+ * state, not an error).
+ */
+function runtimeHandler(roots) {
+    return (req, res) => {
+        if (!guard(req, res))
+            return;
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405);
+            res.end();
+            return;
+        }
+        let pathname;
+        try {
+            pathname = new URL(req.url ?? '/', 'http://pet.local').pathname;
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const rest = pathname.slice(PET_RUNTIME_PREFIX.length).replace(/^\/+/, '');
+        let name;
+        try {
+            name = decodeURIComponent(rest);
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const spec = RUNTIME_FILES[name];
+        // Exact-name allow-list: anything with a path separator never matches.
+        if (spec === undefined) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const base = spec.root === 'runtimeDir' ? roots.runtimeDir : roots.vendorDir;
+        const file = join(base, name);
+        if (!existsSync(file)) {
+            json(res, 404, { ok: false, error: 'runtime-file-missing', file: name });
+            return;
+        }
+        const resolved = containedRealpath(base, file);
+        if (resolved === undefined) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        try {
+            if (statSync(resolved).size > PET_RUNTIME_CAP) {
+                res.writeHead(413);
+                res.end();
+                return;
+            }
+        }
+        catch {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        readFile(resolved).then((body) => {
+            res.writeHead(200, {
+                'content-type': name.endsWith('.map') ? 'application/json' : 'application/javascript; charset=utf-8',
+                'content-length': String(body.byteLength),
+                'cache-control': 'no-cache',
+            });
+            if (req.method === 'HEAD') {
+                res.end();
+                return;
+            }
+            res.end(body);
+        }, () => {
+            res.writeHead(404);
+            res.end();
+        });
+    };
+}
+/**
+ * The decoration asset handler behind '/api/pet/decoration/<id>/<file>'
+ * (pet-center M5, #567). Serves exactly the files a decoration descriptor
+ * declares — decoration.json and the PNG/WebP strip — by exact allow-list
+ * match, with realpath containment and the same size ceilings as pet
+ * assets. Crafted '..' or '.' segments never match the normalized closure.
+ */
+function decorationHandler(registry, caps) {
+    return (req, res) => {
+        if (!guard(req, res))
+            return;
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.writeHead(405);
+            res.end();
+            return;
+        }
+        let pathname;
+        try {
+            pathname = new URL(req.url ?? '/', 'http://pet.local').pathname;
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const segments = pathname.split('/').filter(segment => segment !== '');
+        const prefixSegments = DECORATION_ASSET_PREFIX.split('/').filter(segment => segment !== '');
+        if (segments.length < prefixSegments.length + 2) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        for (let i = 0; i < prefixSegments.length; i += 1) {
+            if (segments[i] !== prefixSegments[i]) {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+        }
+        let id;
+        try {
+            id = decodeURIComponent(segments[prefixSegments.length]);
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const entry = registry.decorationById?.(id);
+        if (entry === undefined) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const rest = [];
+        for (const segment of segments.slice(prefixSegments.length + 1)) {
+            let decoded;
+            try {
+                decoded = decodeURIComponent(segment);
+            }
+            catch {
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            rest.push(decoded);
+        }
+        const rel = rest.join('/');
+        if (!entry.servable.includes(rel)) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const file = join(entry.dir, rel);
+        const resolved = containedRealpath(entry.dir, file);
+        if (resolved === undefined) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        const cap = rel === 'decoration.json' ? caps.manifest : caps.image;
+        let stat;
+        try {
+            stat = statSync(resolved);
+            if (stat.size > cap) {
+                res.writeHead(413);
+                res.end();
+                return;
+            }
+        }
+        catch {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        // Weak ETag from size + mtime: 'no-cache' forces revalidation, and the
+        // validator lets repeat requests settle as 304 — the ornament remounts
+        // on whisper and display-session flips, and without a validator each
+        // remount would re-download the full strip body.
+        const etag = '"' + stat.size.toString(16) + '-' + Math.round(stat.mtimeMs).toString(16) + '"';
+        if (req.headers['if-none-match'] === etag) {
+            res.writeHead(304, { etag, 'cache-control': 'no-cache' });
+            res.end();
+            return;
+        }
+        readFile(resolved).then((body) => {
+            res.writeHead(200, {
+                'content-type': mimeFor(resolved),
+                'content-length': String(body.byteLength),
+                'cache-control': 'no-cache',
+                etag,
+            });
+            if (req.method === 'HEAD') {
+                res.end();
+                return;
+            }
+            res.end(body);
+        }, () => {
+            res.writeHead(404);
+            res.end();
+        });
+    };
+}
+/** Build the full route family (API + assets + runtime) for one service. */
 export function makePetRoutes(deps) {
     const { service } = deps;
     const apiRoutes = [
         getRoute(PET_API_PREFIX + '/state', () => service.state()),
         getRoute(PET_API_PREFIX + '/pets', () => service.pets()),
+        getRoute(PET_API_PREFIX + '/diagnostics', () => service.diagnostics()),
         postRoute(PET_API_PREFIX + '/interact', (body) => {
             const kind = body.kind;
             if (kind !== 'pet' && kind !== 'feed')
@@ -282,9 +568,22 @@ export function makePetRoutes(deps) {
     const assetRoute = {
         kind: 'prefix',
         path: PET_ASSET_PREFIX,
-        handler: assetHandler(service.registrySnapshot()),
+        handler: assetHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
+    };
+    const runtimeRoute = {
+        kind: 'prefix',
+        path: PET_RUNTIME_PREFIX,
+        handler: runtimeHandler({
+            runtimeDir: deps.runtimeDir ?? join(dshHome(), 'pets', '.runtime'),
+            vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), 'lib'),
+        }),
+    };
+    const decorationRoute = {
+        kind: 'prefix',
+        path: DECORATION_ASSET_PREFIX,
+        handler: decorationHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
     };
-    return [...apiRoutes, assetRoute];
+    return [...apiRoutes, assetRoute, runtimeRoute, decorationRoute];
 }
 // Re-exported for the package surface (the registry owns the definition now).
 export { petPackageRoot } from './registry.js';

package/lib/types/service.d.ts

@@ -16,7 +16,8 @@ import type { AffinityConfig, PetAffinityView, PetInteraction } from './affinity
 import type { TreatConfig } from './treats.ts';
 import { type LedgerInteractionResult } from './ledger.ts';
 import { type PetDisplayConfig } from './persist.ts';
-import { type PetDefinition, type PetManifest, type PetRegistry } from './registry.ts';
+import { type PetDefinition, type PetManifest, type PetRegistry, type PetRegistryDiagnostic } from './registry.ts';
+import type { DecorationView } from './contracts/status-decoration.ts';
 import { type PetStateConfig, type PetStateSnapshot } from './state.ts';
 /** Plugin configuration. */
 export interface PetConfig {
@@ -30,6 +31,8 @@ export interface PetConfig {
     persistDir?: string;
     /** Master switch for the plugin (browser half + host routes). */
     enabled?: boolean;
+    /** Status-decoration master switch (pet-center M5, #567); defaults to on. */
+    decorationEnabled?: boolean;
     /** Prebuilt registry (tests); defaults to scanning the package + user dirs. */
     registry?: PetRegistry;
     /** Extra manifest entries composed by the embedding application. */
@@ -55,6 +58,11 @@ export interface PetSettingsSection {
     bottom: number;
     /** Master switch for the plugin (browser half + host routes). */
     enabled?: boolean;
+    /**
+     * Status-decoration master switch (pet-center M5, #567). Defaults to on;
+     * the settings surface mirrors this field and can turn it off.
+     */
+    decorationEnabled?: boolean;
 }
 /** Settings namespace of the pet capability. Spelled here rather than imported: the browser half spells the same value. */
 export declare const PET_SETTINGS_NAMESPACE = "pet";
@@ -119,6 +127,12 @@ export interface PetStateView {
      * rendered by the client as a distinct whisper bubble.
      */
     whisper?: string;
+    /**
+     * The active status decoration (pet-center M5, #567), when the master
+     * switch is on and the default decoration entry exists. Absent means the
+     * browser half renders no ornament.
+     */
+    decoration?: DecorationView;
 }
 /** Result of `pet.interact`. */
 export type PetInteractResult = LedgerInteractionResult;
@@ -141,9 +155,17 @@ export declare class PetService extends Service {
     private readonly registry;
     private readonly persistDir;
     private enabled;
+    /** Status-decoration master switch (M5, #567); mirrored from settings. */
+    private decorationEnabled;
     private disposeActivity;
     /** Session whose most recent meaningful event currently drives the global pet. */
     private displaySession;
+    /**
+     * Effective voice-pack overrides for the currently selected pet (M4,
+     * #677). Cached per pet id; the registry is an immutable snapshot, so the
+     * global pack and each entry's pack cannot change behind the cache.
+     */
+    private voiceCache;
     /**
      * Per-session activity, most recent last (Map insertion order). Bounded by
      * MAX_SESSION_BUBBLES so a burst of sessions cannot grow it without bound;
@@ -151,6 +173,12 @@ export declare class PetService extends Service {
      */
     private readonly sessionActivity;
     constructor(ctx: Context, config?: PetConfig);
+    /**
+     * The draw-time voice-pool provider handed to every projection runtime.
+     * It re-resolves when the selected pet changes, so live engines re-voice
+     * on the next draw without being rebuilt (M4, #677).
+     */
+    private voicePools;
     /** Whether the pet service consumes session activity while enabled. */
     isEnabled(): boolean;
     /** RPC: current pet state snapshot. */
@@ -161,6 +189,15 @@ export declare class PetService extends Service {
     pets(): Promise<PetDefinition[]>;
     /** The loaded registry (the asset routes serve its entries). */
     registrySnapshot(): PetRegistry;
+    /** RPC: structured registry diagnostics (pet-center M2, issue #623). */
+    diagnostics(): Promise<{
+        diagnostics: PetRegistryDiagnostic[];
+    }>;
+    /**
+     * The active status decoration view (M5, #567): the default 'whale' entry
+     * (user directories override built-ins by id), gated by the master switch.
+     */
+    private activeDecoration;
     /** The selected pet's registry entry. */
     activeEntry(): NonNullable<PetRegistry['entries'][number]>;
     /** Currently selected pet id (persisted). */

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

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"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"}

package/lib/types/service.js

@@ -15,8 +15,9 @@ import { Service } from '@deepseek-ai/cordis';
 import { emptyProjectionRuntime, isActivityPhase, projectOfficialEvent, } from './event-projection.js';
 import { PetLedger } from './ledger.js';
 import { DEFAULT_PET_NAME, DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN, PET_NAME_MAX_LENGTH, loadPetPersist, petHomeDir, savePetPersist, } from './persist.js';
-import { loadPetRegistry, petEntryView, petPackageRoot, } from './registry.js';
+import { DEFAULT_DECORATION_ID, decorationView, loadPetRegistry, petEntryView, petPackageRoot, } from './registry.js';
 import { WHISPER_TTL_MS } from './chatter.js';
+import { mergeVoicePacks } from './voice-pack.js';
 import { defaultPetStateConfig, PetStateMachine, } from './state.js';
 /** Settings namespace of the pet capability. Spelled here rather than imported: the browser half spells the same value. */
 export const PET_SETTINGS_NAMESPACE = 'pet';
@@ -36,9 +37,17 @@ export class PetService extends Service {
     registry;
     persistDir;
     enabled;
+    /** Status-decoration master switch (M5, #567); mirrored from settings. */
+    decorationEnabled;
     disposeActivity;
     /** Session whose most recent meaningful event currently drives the global pet. */
     displaySession;
+    /**
+     * Effective voice-pack overrides for the currently selected pet (M4,
+     * #677). Cached per pet id; the registry is an immutable snapshot, so the
+     * global pack and each entry's pack cannot change behind the cache.
+     */
+    voiceCache;
     /**
      * Per-session activity, most recent last (Map insertion order). Bounded by
      * MAX_SESSION_BUBBLES so a burst of sessions cannot grow it without bound;
@@ -72,8 +81,25 @@ export class PetService extends Service {
         this.stateConfig = { ...defaultPetStateConfig, ...(config.state ?? {}) };
         this.machine = new PetStateMachine(this.stateConfig);
         this.enabled = config.enabled ?? true;
+        this.decorationEnabled = config.decorationEnabled ?? true;
         this.syncActivity();
     }
+    /**
+     * The draw-time voice-pool provider handed to every projection runtime.
+     * It re-resolves when the selected pet changes, so live engines re-voice
+     * on the next draw without being rebuilt (M4, #677).
+     */
+    voicePools() {
+        return () => {
+            const entry = this.activeEntry();
+            if (this.voiceCache !== undefined && this.voiceCache.petId === entry.id) {
+                return this.voiceCache.overrides;
+            }
+            const overrides = mergeVoicePacks(this.registry.globalVoice, entry.voice)?.overrides ?? {};
+            this.voiceCache = { petId: entry.id, overrides };
+            return overrides;
+        };
+    }
     /** Whether the pet service consumes session activity while enabled. */
     isEnabled() {
         return this.enabled;
@@ -88,12 +114,26 @@ export class PetService extends Service {
     }
     /** RPC: the registry entries the browser half renders and selects from. */
     async pets() {
-        return this.registry.entries.map(petEntryView);
+        return this.registry.entries.map(entry => petEntryView(entry, this.registry.globalVoice));
     }
     /** The loaded registry (the asset routes serve its entries). */
     registrySnapshot() {
         return this.registry;
     }
+    /** RPC: structured registry diagnostics (pet-center M2, issue #623). */
+    async diagnostics() {
+        return { diagnostics: this.registry.diagnostics };
+    }
+    /**
+     * The active status decoration view (M5, #567): the default 'whale' entry
+     * (user directories override built-ins by id), gated by the master switch.
+     */
+    activeDecoration() {
+        if (!this.decorationEnabled)
+            return undefined;
+        const entry = this.registry.decorationById?.(DEFAULT_DECORATION_ID);
+        return entry === undefined ? undefined : decorationView(entry);
+    }
     /** The selected pet's registry entry. */
     activeEntry() {
         return this.registry.byId(this.selectedPetId()) ?? this.registry.defaultEntry();
@@ -195,7 +235,7 @@ export class PetService extends Service {
         let activity = this.sessionActivity.get(session);
         if (activity === undefined) {
             activity = {
-                runtime: emptyProjectionRuntime(),
+                runtime: emptyProjectionRuntime(this.voicePools()),
                 machine: new PetStateMachine(this.stateConfig),
             };
             this.sessionActivity.set(session, activity);
@@ -273,6 +313,7 @@ export class PetService extends Service {
      * @param section - the resolved settings section.
      */
     applySettingsSection(section) {
+        this.decorationEnabled = section.decorationEnabled ?? true;
         const selected = typeof section.petId === 'string' ? this.registry.byId(section.petId) : undefined;
         if (selected !== undefined) {
             this.ledger.setPetId(selected.id);
@@ -351,6 +392,7 @@ export class PetService extends Service {
         const freshWhisper = whisper !== undefined && Date.now() - whisper.at < WHISPER_TTL_MS
             ? whisper.text
             : undefined;
+        const decoration = this.activeDecoration();
         // Read-only: the ledger settles on economic events only, never on a read,
         // so polling the state cannot trigger pet.json writes.
         return {
@@ -360,6 +402,7 @@ export class PetService extends Service {
             sessionActive: snapshot.sessionActive,
             sessions,
             ...(freshWhisper === undefined ? {} : { whisper: freshWhisper }),
+            ...(decoration === undefined ? {} : { decoration }),
             affinity: this.ledger.affinityView(Date.now()),
             display: { ...this.ledger.snapshot.display },
             pet: {