@linxin666/dsh-pet 0.2.3 → 0.2.5

package/lib/types/registry.js

@@ -26,11 +26,15 @@
  * whale-girl manifest overrides its own durations.
  * @module @linxin666/dsh-pet/registry
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } 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';
+import { mergeVoicePacks, normalizeVoicePack } from './voice-pack.js';
+import { parseDecorationManifest } from './decoration.js';
+import { imageDimensions } from './image-dimensions.js';
+import { PET_DECORATION_API_VERSION } from './contracts/status-decoration.js';
 import { dshHome } from './dsh-home.js';
 import { parsePetManifest } from './manifest-v2.js';
 import { collectModel3References } from './model3.js';
@@ -376,22 +380,25 @@ function scanPetDir(dir, options) {
         }
         if (!verdict.ok)
             continue;
+        let entry;
         if (verdict.manifest.renderer === 'live2d') {
-            const entry = resolveLive2dEntry(verdict.manifest, entryDir, options);
-            if (entry !== undefined)
-                entries.push(entry);
-            continue;
+            entry = resolveLive2dEntry(verdict.manifest, entryDir, options);
         }
-        const legacy = flattenV2Sprite2d(verdict.manifest);
-        if (legacy === undefined) {
-            const note = 'pet ' + verdict.manifest.id + ': sprite2d.atlasRows only supports 9 or 11 under the v1 compat resolver';
-            options.diagnostics?.push({ level: 'error', source: entryDir, message: note });
-            options.warnings?.push(note);
-            continue;
+        else {
+            const legacy = flattenV2Sprite2d(verdict.manifest);
+            if (legacy === undefined) {
+                const note = 'pet ' + verdict.manifest.id + ': sprite2d.atlasRows only supports 9 or 11 under the v1 compat resolver';
+                options.diagnostics?.push({ level: 'error', source: entryDir, message: note });
+                options.warnings?.push(note);
+                continue;
+            }
+            entry = resolvePetManifest(legacy, entryDir, options);
         }
-        const entry = resolvePetManifest(legacy, entryDir, options);
-        if (entry !== undefined)
-            entries.push(entry);
+        if (entry === undefined)
+            continue;
+        // Optional voice pack (voice.json) — pure content, warn-and-drop (M4).
+        const voice = loadVoicePackFile(join(entryDir, 'voice.json'), options);
+        entries.push({ ...entry, ...(voice === undefined ? {} : { voice }) });
     }
     return entries;
 }
@@ -405,6 +412,177 @@ function readPetJson(file, warnings) {
         return undefined;
     }
 }
+/**
+ * Scan-time read ceiling for user-authored JSON descriptors (voice.json,
+ * .voice.json, decoration.json): the registry reads these synchronously at
+ * plugin startup, and a pathological file — multi-GB, or a FIFO/device
+ * symlink — must not hang or exhaust the host before the warn-and-drop
+ * discipline can apply (review-spd follow-up, pet-center M4/M5).
+ */
+export const PET_SCAN_JSON_CAP = 64 * 1024;
+/**
+ * Stat one scanned JSON descriptor with a regular-file + size guard, so a
+ * pathological user file is skipped with a warning instead of stalling or
+ * OOM-ing the host at startup. Returns the Stats, or undefined when the
+ * caller must skip the file (a warning was recorded).
+ */
+function guardedScannedJsonStat(file, options, what) {
+    let st;
+    try {
+        st = statSync(file);
+    }
+    catch {
+        return undefined;
+    }
+    const warn = (message) => {
+        options.warnings?.push(file + ': ' + message);
+        options.diagnostics?.push({ level: 'warning', source: file, message: file + ': ' + message });
+    };
+    if (!st.isFile()) {
+        warn(what + ' is not a regular file; ignored');
+        return undefined;
+    }
+    if (st.size > PET_SCAN_JSON_CAP) {
+        warn(what + ' exceeds the ' + PET_SCAN_JSON_CAP + '-byte scan ceiling; ignored');
+        return undefined;
+    }
+    return st;
+}
+/**
+ * Load and normalize one optional voice.json (pet-center M4). A missing
+ * file is silent; a broken file warns and drops. The pack is pure content,
+ * so every issue stays a warning — a bad voice.json never rejects a pet.
+ */
+function loadVoicePackFile(file, options) {
+    if (!existsSync(file))
+        return undefined;
+    if (guardedScannedJsonStat(file, options, 'voice pack') === undefined)
+        return undefined;
+    const warn = (message) => {
+        options.warnings?.push(file + ': ' + message);
+        options.diagnostics?.push({ level: 'warning', source: file, message: file + ': ' + message });
+    };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        warn('voice pack is not valid JSON; ignored: ' + (error instanceof Error ? error.message : String(error)));
+        return undefined;
+    }
+    return normalizeVoicePack(raw, warn);
+}
+/** Decoration asset URL prefix (served by the decoration route, M5). */
+export const DECORATION_ASSET_PREFIX = '/api/pet/decoration';
+/** Read the pixel dimensions of a decoration strip (PNG/WebP), if decodable. */
+function readImageDimensions(file) {
+    let header;
+    try {
+        // Only the header is needed for dimensions; cap the read so a huge or
+        // corrupt strip cannot balloon memory during the registry scan.
+        const fd = openSync(file, 'r');
+        try {
+            header = Buffer.alloc(64);
+            const read = readSync(fd, header, 0, header.length, 0);
+            if (read < 0)
+                return undefined;
+            header = header.subarray(0, read);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return imageDimensions(header);
+}
+/**
+ * Scan one directory of decoration folders ('decoration.json' + strip).
+ * Later scans override earlier ones on id collision; a bad descriptor warns
+ * and skips — the never-throw philosophy holds for decorations too (M5).
+ */
+function scanDecorationDir(dir, options) {
+    if (!existsSync(dir))
+        return [];
+    let names = [];
+    try {
+        names = readdirSync(dir).filter(name => !name.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+    names.sort();
+    const entries = [];
+    for (const name of names) {
+        const entryDir = join(dir, name);
+        const manifestFile = join(entryDir, 'decoration.json');
+        if (!existsSync(manifestFile))
+            continue;
+        if (guardedScannedJsonStat(manifestFile, options, 'decoration descriptor') === undefined)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(manifestFile, 'utf8'));
+        }
+        catch (error) {
+            const message = 'skipping ' + manifestFile + ': ' + (error instanceof Error ? error.message : String(error));
+            options.warnings?.push(message);
+            options.diagnostics?.push({ level: 'error', source: entryDir, message });
+            continue;
+        }
+        const verdict = parseDecorationManifest(raw, manifestFile);
+        for (const diagnostic of verdict.diagnostics) {
+            options.diagnostics?.push({ level: diagnostic.level, source: entryDir, message: diagnostic.message });
+            options.warnings?.push(diagnostic.message);
+        }
+        if (!verdict.ok)
+            continue;
+        const manifest = verdict.manifest;
+        // A missing strip keeps the entry listed (mirroring the live2d closure
+        // discipline) but earns a diagnostic: the ornament will silently render
+        // nothing, and the warning names the file to fix.
+        if (!existsSync(join(entryDir, manifest.entry))) {
+            const message = 'decoration ' + manifest.id + ': strip file missing: ' + manifest.entry;
+            options.warnings?.push(message);
+            options.diagnostics?.push({ level: 'warning', source: entryDir, message });
+        }
+        else {
+            // Geometry check: the client renders the strip as a single row of
+            // 'columns' frames (background-position advances by frame width only),
+            // so the strip must be exactly cell.width * columns wide and cell.height
+            // tall. A mismatched strip silently shows the wrong/partial frames —
+            // warn-and-keep, mirroring the missing-strip discipline (never throw).
+            const actual = readImageDimensions(join(entryDir, manifest.entry));
+            if (actual !== undefined) {
+                const expectedWidth = manifest.cell.width * manifest.columns;
+                if (actual.width !== expectedWidth || actual.height !== manifest.cell.height) {
+                    const message = 'decoration ' + manifest.id + ': strip ' + actual.width + 'x' + actual.height
+                        + ' does not match cell ' + manifest.cell.width + 'x' + manifest.cell.height + ' x ' + manifest.columns
+                        + ' columns (expected ' + expectedWidth + 'x' + manifest.cell.height + '); frames will render wrong';
+                    options.warnings?.push(message);
+                    options.diagnostics?.push({ level: 'warning', source: entryDir, message });
+                }
+            }
+        }
+        entries.push({
+            apiVersion: PET_DECORATION_API_VERSION,
+            id: manifest.id,
+            dir: entryDir,
+            entryPath: manifest.entry,
+            servable: ['decoration.json', manifest.entry],
+            license: manifest.license,
+            assetBase: DECORATION_ASSET_PREFIX + '/' + encodeURIComponent(manifest.id),
+            entryUrl: DECORATION_ASSET_PREFIX + '/' + encodeURIComponent(manifest.id) + '/' + manifest.entry,
+            cell: manifest.cell,
+            columns: manifest.columns,
+            durations: manifest.durations,
+            loop: manifest.loop,
+            phases: manifest.phases,
+        });
+    }
+    return entries;
+}
 /**
  * Load the pet registry: built-in 'assets/*' first, then the hatch-pet
  * custom pets directory, then composed 'extra' manifests (each later source
@@ -435,12 +613,15 @@ export function loadPetRegistry(options) {
     }
     // The pet-center user directory ranks above the legacy hatch-pet source.
     const dshPetsDir = options.dshPetsDir ?? join(dshHome(), 'pets');
+    let globalVoice;
     if (dshPetsDir !== '') {
         for (const entry of scanPetDir(dshPetsDir, { assetPrefix, warnings, diagnostics })) {
             if (byId.has(entry.id))
                 warnings.push('user pet ' + entry.id + ' overrides an earlier registration');
             byId.set(entry.id, entry);
         }
+        // The global voice override layers under every per-pet pack (M4, #677).
+        globalVoice = loadVoicePackFile(join(dshPetsDir, '.voice.json'), { warnings, diagnostics });
     }
     for (const manifest of options.extra ?? []) {
         const raw = manifest.spritesheetPath;
@@ -461,17 +642,59 @@ export function loadPetRegistry(options) {
             warnings.push('composed pet ' + entry.id + ' overrides an earlier registration');
         byId.set(entry.id, entry);
     }
+    // Status decorations (pet-center M5, #567): built-in entries first,
+    // then same-id user entries under '$DSH_HOME/pets/decorations' override.
+    const decorationById = new Map();
+    for (const entry of scanDecorationDir(join(packageRoot, 'assets', 'decorations'), { warnings, diagnostics })) {
+        decorationById.set(entry.id, entry);
+    }
+    if (dshPetsDir !== '') {
+        for (const entry of scanDecorationDir(join(dshPetsDir, 'decorations'), { warnings, diagnostics })) {
+            if (decorationById.has(entry.id)) {
+                warnings.push('user decoration ' + entry.id + ' overrides the built-in one');
+            }
+            decorationById.set(entry.id, entry);
+        }
+    }
     const entries = [...byId.values()];
+    const decorations = [...decorationById.values()];
     return {
         entries,
         warnings,
         diagnostics,
         byId: (id) => byId.get(id),
         defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0],
+        ...(globalVoice === undefined ? {} : { globalVoice }),
+        decorations,
+        decorationById: (id) => decorationById.get(id),
+    };
+}
+/** The built-in default decoration id (M5): the first reference ornament. */
+export const DEFAULT_DECORATION_ID = 'whale';
+/** Strip host-only fields, leaving the browser-visible decoration view. */
+export function decorationView(entry) {
+    return {
+        apiVersion: PET_DECORATION_API_VERSION,
+        id: entry.id,
+        assetBase: entry.assetBase,
+        entryUrl: entry.entryUrl,
+        cell: entry.cell,
+        columns: entry.columns,
+        durations: entry.durations,
+        loop: entry.loop,
+        phases: entry.phases,
     };
 }
-/** Strip host-only fields, leaving the client-visible definition. */
-export function petEntryView(entry) {
+/**
+ * Strip host-only fields, leaving the client-visible definition. When the
+ * registry carries a global voice pack, its panel chrome layers under the
+ * entry's own pack (per-slot merge, pet > global), mirroring the voice-pool
+ * layering (pet-center M4, issue #677).
+ */
+export function petEntryView(entry, globalVoice) {
+    const panel = globalVoice === undefined
+        ? entry.voice?.panel
+        : mergeVoicePacks(globalVoice, entry.voice)?.panel;
     return {
         id: entry.id,
         displayName: entry.displayName,
@@ -486,6 +709,7 @@ export function petEntryView(entry) {
         ...(entry.sequences === undefined ? {} : { sequences: entry.sequences }),
         atlasUrl: entry.atlasUrl,
         manifestUrl: entry.manifestUrl,
+        ...(panel === undefined ? {} : { panel }),
     };
 }
 /** The absolute file a pet's atlas resolves to (host asset route). */

package/lib/types/routes.d.ts

@@ -5,9 +5,13 @@
  * domains are platform-registered, so the pet serves its own API and media —
  * the same pattern as dsh-remote-web-ui's '/api/pair' family. The asset route
  * is one prefix registration serving every registry entry (manifest, atlas,
- * optional previews), so adding a pet never touches route wiring.
+ * optional previews), so adding a pet never touches route wiring. Both the
+ * JSON API, the asset prefix, and the Live2D runtime prefix are loopback-only
+ * by default; a live paired-device cookie is an extra allow path when
+ * remote-web-ui is loaded.
  * @module @linxin666/dsh-pet/routes
  */
+import type { Context } from '@deepseek-ai/cordis';
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { PetService } from './service.ts';
 /** Browser-facing base path of the pet API. */
@@ -53,6 +57,7 @@ export interface PetRuntimeRoots {
 /** Build the full route family (API + assets + runtime) for one service. */
 export declare function makePetRoutes(deps: {
     service: PetService;
+    ctx: Context;
     assetCaps?: PetAssetCaps;
 } & PetRuntimeRoots): WebRoute[];
 export { petPackageRoot } from './registry.ts';

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

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAM9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAMtC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,yBAAyB;aACzB,QAAQ;IACR,iDAAiD;aACjD,KAAK;IACL,8EAA8E;aAC9E,KAAK;CACG,CAAA;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrF;AAsPD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAA8B,CAAA;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAmB,CAAA;AAE/C,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAiFD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAkDnH;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAM9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAMtC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,yBAAyB;aACzB,QAAQ;IACR,iDAAiD;aACjD,KAAK;IACL,8EAA8E;aAC9E,KAAK;CACG,CAAA;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrF;AAsPD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAA8B,CAAA;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAmB,CAAA;AAE/C,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwMD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAwDjI;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}

package/lib/types/routes.js

@@ -5,14 +5,17 @@
  * domains are platform-registered, so the pet serves its own API and media —
  * the same pattern as dsh-remote-web-ui's '/api/pair' family. The asset route
  * is one prefix registration serving every registry entry (manifest, atlas,
- * optional previews), so adding a pet never touches route wiring.
+ * optional previews), so adding a pet never touches route wiring. Both the
+ * JSON API, the asset prefix, and the Live2D runtime prefix are loopback-only
+ * by default; a live paired-device cookie is an extra allow path when
+ * remote-web-ui is loaded.
  * @module @linxin666/dsh-pet/routes
  */
 import { existsSync, realpathSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
-import { petEntryView, petPackageRoot } from './registry.js';
-import { isLoopbackRequest } from './loopback.js';
+import { DECORATION_ASSET_PREFIX, petEntryView, petPackageRoot } from './registry.js';
+import { isPetAllowed } from './access.js';
 import { dshHome } from './dsh-home.js';
 /** Browser-facing base path of the pet API. */
 export const PET_API_PREFIX = '/api/pet';
@@ -114,20 +117,20 @@ function readJsonBody(req) {
         req.on('error', reject);
     });
 }
-/** Shared route fence: the browser UI is a loopback client; LAN hosts stay out. */
-function guard(req, res) {
-    if (isLoopbackRequest(req))
+/** Shared route fence: loopback always passes; a live paired-device cookie is an extra allow path. */
+function guard(ctx, req, res) {
+    if (isPetAllowed(ctx, req))
         return true;
     json(res, 403, { ok: false, error: 'forbidden: loopback-only' });
     return false;
 }
 /** Wrap one async service call as a GET JSON route. */
-function getRoute(path, run) {
+function getRoute(ctx, path, run) {
     return {
         kind: 'exact',
         path,
         handler: (req, res) => {
-            if (!guard(req, res))
+            if (!guard(ctx, req, res))
                 return;
             if (!requireMethod(req, res, 'GET'))
                 return;
@@ -138,12 +141,12 @@ function getRoute(path, run) {
     };
 }
 /** Wrap one async service call as a POST JSON route (body passed through). */
-function postRoute(path, run) {
+function postRoute(ctx, path, run) {
     return {
         kind: 'exact',
         path,
         handler: (req, res) => {
-            if (!guard(req, res))
+            if (!guard(ctx, req, res))
                 return Promise.resolve();
             if (!requireMethod(req, res, 'POST'))
                 return Promise.resolve();
@@ -178,10 +181,10 @@ function dirAliases(registry) {
  * match; containedRealpath stays as the second layer. Composed pets without
  * a manifest file get a synthesized pet.json.
  */
-function assetHandler(registry, caps) {
+function assetHandler(ctx, registry, caps) {
     const aliases = dirAliases(registry);
-    return (req, res) => {
-        if (!guard(req, res))
+    return ((req, res) => {
+        if (!guard(ctx, req, res))
             return;
         if (req.method !== 'GET' && req.method !== 'HEAD') {
             res.writeHead(405);
@@ -248,7 +251,7 @@ function assetHandler(registry, caps) {
             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),
@@ -289,7 +292,7 @@ function assetHandler(registry, caps) {
             res.end();
             return;
         }
-        readFile(resolved).then((body) => {
+        return readFile(resolved).then((body) => {
             res.writeHead(200, {
                 'content-type': mimeFor(resolved),
                 'content-length': String(body.byteLength),
@@ -304,7 +307,7 @@ function assetHandler(registry, caps) {
             res.writeHead(404);
             res.end();
         });
-    };
+    });
 }
 /** Browser-facing base path of the plugin runtime files (pet-center M3). */
 export const PET_RUNTIME_PREFIX = PET_API_PREFIX + '/runtime';
@@ -328,9 +331,9 @@ export const PET_RUNTIME_CAP = 16 * 1024 * 1024;
  * 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))
+function runtimeHandler(ctx, roots) {
+    return ((req, res) => {
+        if (!guard(ctx, req, res))
             return;
         if (req.method !== 'GET' && req.method !== 'HEAD') {
             res.writeHead(405);
@@ -387,7 +390,7 @@ function runtimeHandler(roots) {
             res.end();
             return;
         }
-        readFile(resolved).then((body) => {
+        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),
@@ -402,40 +405,163 @@ function runtimeHandler(roots) {
             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(ctx, registry, caps) {
+    return (req, res) => {
+        if (!guard(ctx, 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 { service, ctx } = 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) => {
+        getRoute(ctx, PET_API_PREFIX + '/state', () => service.state()),
+        getRoute(ctx, PET_API_PREFIX + '/pets', () => service.pets()),
+        getRoute(ctx, PET_API_PREFIX + '/diagnostics', () => service.diagnostics()),
+        postRoute(ctx, PET_API_PREFIX + '/interact', (body) => {
             const kind = body.kind;
             if (kind !== 'pet' && kind !== 'feed')
                 return Promise.reject(new Error('invalid-kind'));
             return service.interact(kind);
         }),
-        postRoute(PET_API_PREFIX + '/set-visible', (body) => {
+        postRoute(ctx, PET_API_PREFIX + '/set-visible', (body) => {
             const visible = body.visible;
             if (typeof visible !== 'boolean')
                 return Promise.reject(new Error('invalid-visible'));
             return service.setVisible(visible);
         }),
-        postRoute(PET_API_PREFIX + '/set-config', (body) => service.setConfig({
+        postRoute(ctx, PET_API_PREFIX + '/set-config', (body) => service.setConfig({
             ...(typeof body.size === 'number' ? { size: body.size } : {}),
             ...(typeof body.right === 'number' ? { right: body.right } : {}),
             ...(typeof body.bottom === 'number' ? { bottom: body.bottom } : {}),
             ...(typeof body.visible === 'boolean' ? { visible: body.visible } : {}),
         })),
-        postRoute(PET_API_PREFIX + '/set-name', (body) => {
+        postRoute(ctx, PET_API_PREFIX + '/set-name', (body) => {
             const name = body.name;
             if (typeof name !== 'string')
                 return Promise.reject(new Error('invalid-name'));
             return service.setName(name);
         }),
-        postRoute(PET_API_PREFIX + '/set-pet', (body) => {
+        postRoute(ctx, PET_API_PREFIX + '/set-pet', (body) => {
             const petId = body.petId;
             if (typeof petId !== 'string')
                 return Promise.reject(new Error('invalid-pet'));
@@ -445,17 +571,22 @@ export function makePetRoutes(deps) {
     const assetRoute = {
         kind: 'prefix',
         path: PET_ASSET_PREFIX,
-        handler: assetHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
+        handler: assetHandler(ctx, service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
     };
     const runtimeRoute = {
         kind: 'prefix',
         path: PET_RUNTIME_PREFIX,
-        handler: runtimeHandler({
+        handler: runtimeHandler(ctx, {
             runtimeDir: deps.runtimeDir ?? join(dshHome(), 'pets', '.runtime'),
             vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), 'lib'),
         }),
     };
-    return [...apiRoutes, assetRoute, runtimeRoute];
+    const decorationRoute = {
+        kind: 'prefix',
+        path: DECORATION_ASSET_PREFIX,
+        handler: decorationHandler(ctx, service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
+    };
+    return [...apiRoutes, assetRoute, runtimeRoute, decorationRoute];
 }
 // Re-exported for the package surface (the registry owns the definition now).
 export { petPackageRoot } from './registry.js';