@linxin666/dsh-pet 0.2.2 → 0.2.4

package/lib/types/registry.js

@@ -1,14 +1,24 @@
 /**
  * Pet registry — the multi-pet contract. One pet is a directory holding a
  * 'pet.json' manifest plus an atlas image; nothing else is required, and no
- * host or client code changes when a pet is added. The registry scans three
+ * host or client code changes when a pet is added. The registry scans four
  * sources, later sources overriding earlier ones on an id collision:
  *
  *   1. the package's own 'assets' subdirectories (built-in pets);
- *   2. '${CODEX_HOME:-~/.codex}/pets' subdirectories (hatch-pet custom pets);
- *   3. 'PetConfig.pets' manifests composed by the embedding application
+ *   2. '${CODEX_HOME:-~/.codex}/pets' subdirectories (hatch-pet custom pets,
+ *      legacy source kept readable);
+ *   3. '$DSH_HOME/pets' subdirectories (the pet-center user directory);
+ *   4. 'PetConfig.pets' manifests composed by the embedding application
  *      (highest precedence).
  *
+ * Manifests are parsed through manifest-v2 (pet-center M2, issue #623): v1
+ * manifests are compat-read as sprite2d, v2 manifests validate fail-closed,
+ * and structured diagnostics ride alongside the legacy warnings. Live2d
+ * entries (pet-center M3) list like any other pet: the entry carries the
+ * validated live2d block plus the model's reference closure (the servable
+ * set the asset route allows), and a model3.json that is unreadable or
+ * declares unsafe references rejects the entry with an error diagnostic.
+ *
  * The manifest follows the Codex/hatch-pet contract (8 columns x 9 rows of
  * 192x208 cells, the 9-state row order below). Legacy whale-girl manifests
  * that only carry 'frames' keep working: geometry, per-row frame counts and
@@ -16,11 +26,17 @@
  * whale-girl manifest overrides its own durations.
  * @module @linxin666/dsh-pet/registry
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, 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 { 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';
 /** Fixed row order of the 9-state animation contract. */
 export const PET_ROW_ORDER = [
     'idle',
@@ -115,6 +131,41 @@ function normalizeSequences(raw, id, warn) {
     }
     return Object.keys(sequences).length === 0 ? undefined : sequences;
 }
+/**
+ * Build the fully resolved animation tracks from the contract defaults plus
+ * optional per-track overrides. Shared by the sprite2d resolver and the
+ * live2d entry builder (which fills the sprite fields with contract
+ * defaults so the flat PetDefinition shape holds for every renderer).
+ */
+function buildTracks(rows, columns, trackOverrides, warn) {
+    const tracks = {};
+    for (const [row, animation] of PET_ROW_ORDER.entries()) {
+        const pattern = DEFAULT_TRACK_PATTERNS[animation];
+        const override = trackOverrides[animation];
+        const durations = Array.isArray(override?.durations) && override.durations.length > 0
+            ? override.durations.filter((value) => typeof value === 'number' && Number.isFinite(value) && value > 0)
+            : pattern.durations;
+        if (durations.length === 0) {
+            warn('track ' + animation + ' carries no usable durations');
+            return undefined;
+        }
+        const frameCount = Math.max(1, Math.min(rows[row], columns));
+        const sized = durations.length >= frameCount
+            ? durations.slice(0, frameCount)
+            : Array.from({ length: frameCount }, (_, index) => durations[index % durations.length]);
+        tracks[animation] = {
+            frames: Array.from({ length: frameCount }, (_, index) => index),
+            durations: sized,
+            loop: typeof override?.loop === 'boolean' ? override.loop : pattern.loop,
+            ...(override?.fallback === undefined
+                ? pattern.fallback === undefined ? {} : { fallback: pattern.fallback }
+                : PET_ROW_ORDER.includes(override.fallback)
+                    ? { fallback: override.fallback }
+                    : pattern.fallback === undefined ? {} : { fallback: pattern.fallback }),
+        };
+    }
+    return tracks;
+}
 /**
  * Normalize one parsed manifest into a renderable pet entry, or undefined
  * (with a warning recorded) when the manifest violates the contract.
@@ -164,36 +215,15 @@ export function resolvePetManifest(raw, dir, options = {}) {
     const remarks = normalizePetRemarks(source.remarks, message => warn('manifest ' + id + ': ' + message));
     const sequences = normalizeSequences(source.sequences, id, warn);
     const trackOverrides = (typeof source.tracks === 'object' && source.tracks !== null ? source.tracks : {});
-    const tracks = {};
-    for (const [row, animation] of PET_ROW_ORDER.entries()) {
-        const pattern = DEFAULT_TRACK_PATTERNS[animation];
-        const override = trackOverrides[animation];
-        const durations = Array.isArray(override?.durations) && override.durations.length > 0
-            ? override.durations.filter((value) => typeof value === 'number' && Number.isFinite(value) && value > 0)
-            : pattern.durations;
-        if (durations.length === 0) {
-            warn('manifest ' + id + ': track ' + animation + ' carries no usable durations');
-            return undefined;
-        }
-        const frameCount = Math.max(1, Math.min(rows[row], columns));
-        const sized = durations.length >= frameCount
-            ? durations.slice(0, frameCount)
-            : Array.from({ length: frameCount }, (_, index) => durations[index % durations.length]);
-        tracks[animation] = {
-            frames: Array.from({ length: frameCount }, (_, index) => index),
-            durations: sized,
-            loop: typeof override?.loop === 'boolean' ? override.loop : pattern.loop,
-            ...(override?.fallback === undefined
-                ? pattern.fallback === undefined ? {} : { fallback: pattern.fallback }
-                : PET_ROW_ORDER.includes(override.fallback)
-                    ? { fallback: override.fallback }
-                    : pattern.fallback === undefined ? {} : { fallback: pattern.fallback }),
-        };
-    }
+    const tracks = buildTracks(rows, columns, trackOverrides, message => warn('manifest ' + id + ': ' + message));
+    if (tracks === undefined)
+        return undefined;
+    const sheet = spritesheetPath.join('/');
     return {
         id,
         displayName,
         description,
+        renderer: 'sprite2d',
         cell,
         columns,
         rows,
@@ -203,7 +233,121 @@ export function resolvePetManifest(raw, dir, options = {}) {
         atlasUrl: assetUrl(assetPrefix, id, spritesheet),
         manifestUrl: assetUrl(assetPrefix, id, 'pet.json'),
         dir,
-        spritesheetPath: spritesheetPath.join('/'),
+        spritesheetPath: sheet,
+        servable: [sheet],
+        ...(remarks === undefined ? {} : { remarks }),
+    };
+}
+/**
+ * Adapt a validated v2 manifest's sprite2d block onto the legacy flat shape
+ * the established resolver consumes (pet-center M2 P2). The legacy resolver
+ * only expresses 9-row (default) and 11-row (spriteVersionNumber 2) atlases,
+ * so other atlasRows values are rejected here with a diagnostic.
+ */
+function flattenV2Sprite2d(manifest) {
+    const block = manifest.sprite2d;
+    if (block === undefined)
+        return undefined;
+    const legacy = {
+        id: manifest.id,
+        displayName: manifest.displayName,
+        spritesheetPath: block.spritesheetPath,
+    };
+    if (manifest.description !== undefined)
+        legacy.description = manifest.description;
+    if (block.cell !== undefined)
+        legacy.cell = block.cell;
+    if (block.columns !== undefined)
+        legacy.columns = block.columns;
+    if (block.frames !== undefined)
+        legacy.frames = block.frames;
+    if (block.tracks !== undefined)
+        legacy.tracks = block.tracks;
+    if (block.atlasRows !== undefined) {
+        if (block.atlasRows === 11)
+            legacy.spriteVersionNumber = 2;
+        else if (block.atlasRows !== DEFAULT_PET_ROW_COUNT)
+            return undefined;
+    }
+    if (manifest.sequences !== undefined)
+        legacy.sequences = manifest.sequences;
+    if (manifest.remarks !== undefined)
+        legacy.remarks = manifest.remarks;
+    return legacy;
+}
+/**
+ * Resolve a validated live2d manifest into a renderable entry (pet-center
+ * M3). The model3.json is read at scan time: its reference closure becomes
+ * the entry's servable set (the asset route's allow-list), and a model that
+ * is unreadable or declares unsafe references rejects the entry fail-closed
+ * with an error diagnostic. Closure files missing on disk warn but keep the
+ * entry listed — the client renderer's diagnostic card reports the broken
+ * render, matching the registry's never-throw philosophy (install-time
+ * strictness belongs to the CLI validator). The sprite fields carry contract
+ * defaults: the chrome sizes live2d pets off 'display.size', not the atlas.
+ */
+function resolveLive2dEntry(manifest, dir, options) {
+    const assetPrefix = options.assetPrefix ?? '/pet';
+    const record = (level, message) => {
+        options.diagnostics?.push({ level, source: dir, message });
+        options.warnings?.push(message);
+    };
+    const block = manifest.live2d;
+    if (block === undefined) {
+        record('error', 'pet ' + manifest.id + ': renderer live2d requires a live2d block');
+        return undefined;
+    }
+    let model3;
+    try {
+        model3 = JSON.parse(readFileSync(join(dir, block.model), 'utf8'));
+    }
+    catch (error) {
+        record('error', 'pet ' + manifest.id + ': live2d model ' + block.model + ' is not readable: '
+            + (error instanceof Error ? error.message : String(error)));
+        return undefined;
+    }
+    const { references, errors } = collectModel3References(model3);
+    if (errors.length > 0) {
+        for (const message of errors) {
+            record('error', 'pet ' + manifest.id + ': live2d model ' + block.model + ': ' + message);
+        }
+        return undefined;
+    }
+    for (const reference of references) {
+        if (!existsSync(join(dir, reference))) {
+            record('warning', 'pet ' + manifest.id + ': live2d closure file missing: ' + reference);
+        }
+    }
+    const tracks = buildTracks(DEFAULT_FRAME_COUNTS, DEFAULT_PET_COLUMNS, {}, message => record('warning', 'pet ' + manifest.id + ': ' + message));
+    if (tracks === undefined)
+        return undefined;
+    const remarks = normalizePetRemarks(manifest.remarks, message => record('warning', 'pet ' + manifest.id + ': ' + message));
+    const modelUrl = assetUrl(assetPrefix, manifest.id, block.model);
+    const live2d = {
+        modelUrl,
+        modelPath: block.model,
+        ...(block.scale === undefined ? {} : { scale: block.scale }),
+        ...(block.translate === undefined ? {} : { translate: block.translate }),
+        motions: block.motions,
+        ...(block.expressions === undefined ? {} : { expressions: block.expressions }),
+        ...(block.hitAreas === undefined ? {} : { hitAreas: block.hitAreas }),
+    };
+    return {
+        id: manifest.id,
+        displayName: manifest.displayName,
+        description: manifest.description ?? '',
+        renderer: 'live2d',
+        live2d,
+        cell: { ...DEFAULT_PET_CELL },
+        columns: DEFAULT_PET_COLUMNS,
+        rows: [...DEFAULT_FRAME_COUNTS],
+        atlasRows: DEFAULT_PET_ROW_COUNT,
+        tracks,
+        atlasUrl: modelUrl,
+        manifestUrl: assetUrl(assetPrefix, manifest.id, 'pet.json'),
+        dir,
+        spritesheetPath: block.model,
+        servable: [block.model, ...references],
         ...(remarks === undefined ? {} : { remarks }),
     };
 }
@@ -227,9 +371,33 @@ function scanPetDir(dir, options) {
         const parsed = readPetJson(manifestFile, options.warnings);
         if (parsed === undefined)
             continue;
-        const entry = resolvePetManifest(parsed, join(dir, name), options);
-        if (entry !== undefined)
-            entries.push(entry);
+        const entryDir = join(dir, name);
+        const verdict = parsePetManifest(parsed, entryDir);
+        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;
+        let entry;
+        if (verdict.manifest.renderer === 'live2d') {
+            entry = resolveLive2dEntry(verdict.manifest, entryDir, options);
+        }
+        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);
+        }
+        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;
 }
@@ -243,6 +411,136 @@ 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';
+/**
+ * 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 });
+        }
+        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
@@ -252,9 +550,10 @@ function readPetJson(file, warnings) {
 export function loadPetRegistry(options) {
     const { packageRoot, assetPrefix = '/pet' } = options;
     const warnings = [];
+    const diagnostics = [];
     const byId = new Map();
     const builtinIds = new Set();
-    for (const entry of scanPetDir(join(packageRoot, 'assets'), { assetPrefix, warnings })) {
+    for (const entry of scanPetDir(join(packageRoot, 'assets'), { assetPrefix, warnings, diagnostics })) {
         if (byId.has(entry.id)) {
             warnings.push('duplicate built-in pet id ' + entry.id + '; the first one wins');
             continue;
@@ -264,12 +563,24 @@ export function loadPetRegistry(options) {
     }
     const petsDir = options.petsDir ?? codexPetsDir();
     if (petsDir !== '') {
-        for (const entry of scanPetDir(petsDir, { assetPrefix, warnings })) {
+        for (const entry of scanPetDir(petsDir, { assetPrefix, warnings, diagnostics })) {
             if (byId.has(entry.id))
                 warnings.push('custom pet ' + entry.id + ' overrides the built-in one');
             byId.set(entry.id, entry);
         }
     }
+    // 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;
         const dir = raw === undefined || isAbsolute(raw)
@@ -289,20 +600,65 @@ 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),
     };
 }
-/** Strip host-only fields, leaving the client-visible definition. */
-export function petEntryView(entry) {
+/** 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. 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,
         description: entry.description,
+        renderer: entry.renderer,
+        ...(entry.live2d === undefined ? {} : { live2d: entry.live2d }),
         cell: entry.cell,
         columns: entry.columns,
         rows: entry.rows,
@@ -311,6 +667,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

@@ -14,9 +14,46 @@ import type { PetService } from './service.ts';
 export declare const PET_API_PREFIX = "/api/pet";
 /** Browser-facing base path of the pet asset routes ('/pet/<id>/...'). */
 export declare const PET_ASSET_PREFIX = "/pet";
-/** Build the full route family (API + assets) for one service. */
+/**
+ * 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 declare const PET_ASSET_CAPS: {
+    /** pet.json manifest. */
+    readonly manifest: number;
+    /** Atlas, preview and Live2D texture imagery. */
+    readonly image: number;
+    /** Live2D model closure files (.moc3, motion/physics/expression JSON; M3). */
+    readonly model: number;
+};
+/** Size-cap profile the asset route enforces (test seam). */
+export interface PetAssetCaps {
+    manifest: number;
+    image: number;
+    model: number;
+}
+/**
+ * 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 declare function containedRealpath(base: string, candidate: string): string | undefined;
+/** Browser-facing base path of the plugin runtime files (pet-center M3). */
+export declare const PET_RUNTIME_PREFIX: string;
+/** Size ceiling for one runtime file (the Cubism Core is ~200 KB today). */
+export declare const PET_RUNTIME_CAP: number;
+/** Runtime file roots (test seam; defaults resolve from the environment). */
+export interface PetRuntimeRoots {
+    /** User-supplied runtime directory (defaults to '$DSH_HOME/pets/.runtime'). */
+    runtimeDir?: string;
+    /** Plugin vendor bundle directory (defaults to the package 'lib'). */
+    vendorDir?: string;
+}
+/** Build the full route family (API + assets + runtime) for one service. */
 export declare function makePetRoutes(deps: {
     service: PetService;
-}): WebRoute[];
+    assetCaps?: PetAssetCaps;
+} & PetRuntimeRoots): WebRoute[];
 export { petPackageRoot } from './registry.ts';
 //# sourceMappingURL=routes.d.ts.map

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;AAK9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAiOtC,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAA;CAAE,GAAG,QAAQ,EAAE,CAwCvE;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}
+{"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;AAwMD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAwDnH;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}