@linxin666/dsh-pet 0.2.2 → 0.2.3

package/src/registry.ts

@@ -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
@@ -23,6 +33,9 @@ import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { ActivityPhase, PetAnimation } from './state.ts'
 import { normalizePetRemarks, type PetRemarks, type PetRemarksManifest } from './remarks.ts'
+import { dshHome } from './dsh-home.ts'
+import { parsePetManifest, type PetManifestLive2d, type PetManifestV2, type PetRendererKind } from './manifest-v2.ts'
+import { collectModel3References } from './model3.ts'
 
 /** Fixed row order of the 9-state animation contract. */
 export const PET_ROW_ORDER: readonly PetAnimation[] = [
@@ -156,11 +169,33 @@ export interface PetTrackOverride {
   fallback?: PetAnimation
 }
 
+/** The live2d renderer block as served to the browser half (pet-center M3). */
+export interface PetLive2dDefinition {
+  /** Browser URL of the .model3.json (served by the host asset route). */
+  modelUrl: string
+  /** Manifest-relative model path (host route allow-list key). */
+  modelPath: string
+  /** Scale multiplier over the canvas auto-fit, (0, 10]. */
+  scale?: number
+  /** Model offset in canvas px from the center-bottom anchor. */
+  translate?: { x?: number; y?: number }
+  /** ActivityPhase -> motion group; unmapped phases fall back to idle. */
+  motions: Partial<Record<ActivityPhase, string>> & { idle: string }
+  /** Optional ActivityPhase -> expression name layered over the motion. */
+  expressions?: Partial<Record<ActivityPhase, string>>
+  /** Hit area names triggering the tap motion; defaults to every model HitArea. */
+  hitAreas?: string[]
+}
+
 /** A normalized pet as served to the browser half. */
 export interface PetDefinition {
   id: string
   displayName: string
   description: string
+  /** The renderer this entry mounts with (pet-center M2). */
+  renderer: PetRendererKind
+  /** Live2d render block; present exactly when renderer is 'live2d' (M3). */
+  live2d?: PetLive2dDefinition
   /** Atlas cell size in px. */
   cell: PetCell
   /** Columns per row. */
@@ -185,6 +220,12 @@ export interface PetEntry extends PetDefinition {
   dir: string
   /** Atlas path relative to 'dir' (declared by the manifest). */
   spritesheetPath: string
+  /**
+   * Manifest-relative files the asset route may serve beyond pet.json and
+   * 'previews/*' (pet-center M3): the sprite2d atlas, or the live2d model
+   * plus its model3.json reference closure.
+   */
+  servable: readonly string[]
   /** Normalized per-pet remark pools (manifest 'remarks'), when declared. */
   remarks?: PetRemarks
 }
@@ -193,11 +234,21 @@ export interface PetEntry extends PetDefinition {
 export interface PetRegistry {
   entries: PetEntry[]
   warnings: string[]
+  /** Structured diagnostics from the manifest-v2 parse (superset detail of warnings). */
+  diagnostics: PetRegistryDiagnostic[]
   byId(id: string): PetEntry | undefined
   /** The pet an installation falls back to when the selection is unknown. */
   defaultEntry(): PetEntry
 }
 
+/** One structured registry diagnostic (manifest-v2 era). */
+export interface PetRegistryDiagnostic {
+  level: 'error' | 'warning'
+  /** Where the diagnostic originates (directory or file). */
+  source: string
+  message: string
+}
+
 /** Registry sources. */
 export interface PetRegistryOptions {
   /** Absolute package root whose 'assets/*' hold built-in pets. */
@@ -206,6 +257,8 @@ export interface PetRegistryOptions {
   assetPrefix?: string
   /** Custom pet directory (defaults to '${CODEX_HOME:-~/.codex}/pets'). */
   petsDir?: string
+  /** Pet-center user directory (defaults to '$DSH_HOME/pets'; '' disables). */
+  dshPetsDir?: string
   /** Extra manifest entries composed by the embedding application. */
   extra?: readonly PetManifest[]
 }
@@ -249,6 +302,47 @@ function normalizeSequences(
   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: readonly number[],
+  columns: number,
+  trackOverrides: Partial<Record<PetAnimation, PetTrackOverride>>,
+  warn: (message: string) => void,
+): Record<PetAnimation, PetTrackDef> | undefined {
+  const tracks = {} as Record<PetAnimation, PetTrackDef>
+  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): value is number => 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.
@@ -304,36 +398,14 @@ export function resolvePetManifest(
   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 : {}) as Partial<Record<PetAnimation, PetTrackOverride>>
-  const tracks = {} as Record<PetAnimation, PetTrackDef>
-  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): value is number => 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' as const,
     cell,
     columns,
     rows,
@@ -343,13 +415,121 @@ export function resolvePetManifest(
     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: PetManifestV2): Record<string, unknown> | undefined {
+  const block = manifest.sprite2d
+  if (block === undefined) return undefined
+  const legacy: Record<string, unknown> = {
+    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: PetManifestV2,
+  dir: string,
+  options: { assetPrefix?: string; warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] },
+): PetEntry | undefined {
+  const assetPrefix = options.assetPrefix ?? '/pet'
+  const record = (level: 'error' | 'warning', message: string): void => {
+    options.diagnostics?.push({ level, source: dir, message })
+    options.warnings?.push(message)
+  }
+  const block = manifest.live2d as PetManifestLive2d | undefined
+  if (block === undefined) {
+    record('error', 'pet ' + manifest.id + ': renderer live2d requires a live2d block')
+    return undefined
+  }
+  let model3: unknown
+  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: PetLive2dDefinition = {
+    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' as const,
+    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 }),
   }
 }
 
 /** Scan one directory of pet folders; entries come back in name order. */
-function scanPetDir(dir: string, options: { assetPrefix?: string; warnings?: string[] }): PetEntry[] {
+function scanPetDir(dir: string, options: { assetPrefix?: string; warnings?: string[]; diagnostics?: PetRegistryDiagnostic[] }): PetEntry[] {
   if (!existsSync(dir)) return []
   let names: string[] = []
   try {
@@ -364,7 +544,26 @@ function scanPetDir(dir: string, options: { assetPrefix?: string; warnings?: str
     if (!existsSync(manifestFile)) continue
     const parsed = readPetJson(manifestFile, options.warnings)
     if (parsed === undefined) continue
-    const entry = resolvePetManifest(parsed, join(dir, name), options)
+    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
+    if (verdict.manifest.renderer === 'live2d') {
+      const entry = resolveLive2dEntry(verdict.manifest, entryDir, options)
+      if (entry !== undefined) entries.push(entry)
+      continue
+    }
+    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
+    }
+    const entry = resolvePetManifest(legacy, entryDir, options)
     if (entry !== undefined) entries.push(entry)
   }
   return entries
@@ -389,10 +588,11 @@ function readPetJson(file: string, warnings: string[] | undefined): unknown {
 export function loadPetRegistry(options: PetRegistryOptions): PetRegistry {
   const { packageRoot, assetPrefix = '/pet' } = options
   const warnings: string[] = []
+  const diagnostics: PetRegistryDiagnostic[] = []
   const byId = new Map<string, PetEntry>()
   const builtinIds = new Set<string>()
 
-  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
@@ -403,12 +603,21 @@ export function loadPetRegistry(options: PetRegistryOptions): PetRegistry {
 
   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')
+  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)
+    }
+  }
+
   for (const manifest of options.extra ?? []) {
     const raw = manifest.spritesheetPath
     const dir = raw === undefined || isAbsolute(raw)
@@ -431,6 +640,7 @@ export function loadPetRegistry(options: PetRegistryOptions): PetRegistry {
   return {
     entries,
     warnings,
+    diagnostics,
     byId: (id: string) => byId.get(id),
     defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0]!,
   }
@@ -442,6 +652,8 @@ export function petEntryView(entry: PetEntry): PetDefinition {
     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,

package/src/routes.ts

@@ -9,15 +9,16 @@
  * @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 { join, sep } from 'node:path'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import type { PetService } from './service.ts'
 import type { PetInteraction } from './affinity.ts'
-import { petEntryView, type PetEntry, type PetRegistry } from './registry.ts'
+import { petEntryView, petPackageRoot, type PetEntry, type PetRegistry } from './registry.ts'
 import { isLoopbackRequest } from './loopback.ts'
+import { dshHome } from './dsh-home.ts'
 
 /** Browser-facing base path of the pet API. */
 export const PET_API_PREFIX = '/api/pet'
@@ -29,6 +30,53 @@ 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,
+} as const
+
+/** Size-cap profile the asset route enforces (test seam). */
+export interface PetAssetCaps {
+  manifest: number
+  image: number
+  model: number
+}
+
+/** Imagery extensions classify into the image cap; everything else served from a closure is model-class. */
+const IMAGE_EXTENSIONS: ReadonlySet<string> = new Set(['.webp', '.png', '.gif', '.jpg', '.jpeg'])
+
+/** Lowercased file extension ('' when none). */
+function extensionOf(file: string): string {
+  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: string, candidate: string): string | undefined {
+  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: Readonly<Record<string, string>> = {
   '.webp': 'image/webp',
   '.png': 'image/png',
@@ -145,10 +193,14 @@ function dirAliases(registry: PetRegistry): Map<string, PetEntry> {
 /**
  * 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: PetRegistry): WebRoute['handler'] {
+function assetHandler(registry: PetRegistry, caps: PetAssetCaps): WebRoute['handler'] {
   const aliases = dirAliases(registry)
   return (req: IncomingMessage, res: ServerResponse): void => {
     if (!guard(req, res)) return
@@ -204,8 +256,8 @@ function assetHandler(registry: PetRegistry): WebRoute['handler'] {
       const manifestFile = join(entry.dir, MANIFEST_FILE)
       file = existsSync(manifestFile) ? manifestFile : undefined
       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
@@ -229,7 +281,28 @@ function assetHandler(registry: PetRegistry): WebRoute['handler'] {
       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),
@@ -248,12 +321,119 @@ function assetHandler(registry: PetRegistry): WebRoute['handler'] {
   }
 }
 
-/** Build the full route family (API + assets) for one service. */
-export function makePetRoutes(deps: { service: PetService }): WebRoute[] {
+/** 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: Readonly<Record<string, { root: 'runtimeDir' | 'vendorDir' }>> = {
+  '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
+
+/** 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
+}
+
+/**
+ * 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: { runtimeDir: string; vendorDir: string }): WebRoute['handler'] {
+  return (req: IncomingMessage, res: ServerResponse): void => {
+    if (!guard(req, res)) return
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    let pathname: string
+    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: string
+    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()
+    })
+  }
+}
+
+/** Build the full route family (API + assets + runtime) for one service. */
+export function makePetRoutes(deps: { service: PetService; assetCaps?: PetAssetCaps } & PetRuntimeRoots): WebRoute[] {
   const { service } = deps
   const apiRoutes: WebRoute[] = [
     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 as PetInteraction | undefined
       if (kind !== 'pet' && kind !== 'feed') return Promise.reject(new Error('invalid-kind'))
@@ -285,10 +465,19 @@ export function makePetRoutes(deps: { service: PetService }): WebRoute[] {
   const assetRoute: WebRoute = {
     kind: 'prefix',
     path: PET_ASSET_PREFIX,
-    handler: assetHandler(service.registrySnapshot()),
+    handler: assetHandler(service.registrySnapshot(), deps.assetCaps ?? PET_ASSET_CAPS),
+  }
+
+  const runtimeRoute: WebRoute = {
+    kind: 'prefix',
+    path: PET_RUNTIME_PREFIX,
+    handler: runtimeHandler({
+      runtimeDir: deps.runtimeDir ?? join(dshHome(), 'pets', '.runtime'),
+      vendorDir: deps.vendorDir ?? join(petPackageRoot(import.meta.url), 'lib'),
+    }),
   }
 
-  return [...apiRoutes, assetRoute]
+  return [...apiRoutes, assetRoute, runtimeRoute]
 }
 
 // Re-exported for the package surface (the registry owns the definition now).