@linxin666/dsh-pet 0.2.1 → 0.2.3

package/lib/types/registry.d.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
@@ -18,6 +28,7 @@
  */
 import type { ActivityPhase, PetAnimation } from './state.ts';
 import { type PetRemarks, type PetRemarksManifest } from './remarks.ts';
+import { type PetRendererKind } from './manifest-v2.ts';
 /** Fixed row order of the 9-state animation contract. */
 export declare const PET_ROW_ORDER: readonly PetAnimation[];
 /** Atlas cell size in px. */
@@ -100,11 +111,37 @@ export interface PetTrackOverride {
     /** Track to switch to after a non-looping track finishes. */
     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. */
@@ -128,6 +165,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;
 }
@@ -135,10 +178,19 @@ 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. */
@@ -147,6 +199,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[];
 }
@@ -169,6 +223,4 @@ export declare function loadPetRegistry(options: PetRegistryOptions): PetRegistr
 export declare function petEntryView(entry: PetEntry): PetDefinition;
 /** The absolute file a pet's atlas resolves to (host asset route). */
 export declare function petAtlasFile(entry: PetEntry): string;
-/** The directory basename of one entry (legacy asset URL alias, e.g. whale). */
-export declare function petDirAlias(entry: PetEntry): string;
 //# sourceMappingURL=registry.d.ts.map

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

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

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
@@ -21,6 +31,9 @@ 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 { 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 +128,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 +212,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 +230,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,7 +368,28 @@ function scanPetDir(dir, options) {
         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);
     }
@@ -252,9 +414,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 +427,21 @@ 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');
+    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)
@@ -293,6 +465,7 @@ export function loadPetRegistry(options) {
     return {
         entries,
         warnings,
+        diagnostics,
         byId: (id) => byId.get(id),
         defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0],
     };
@@ -303,6 +476,8 @@ export function petEntryView(entry) {
         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,
@@ -317,7 +492,3 @@ export function petEntryView(entry) {
 export function petAtlasFile(entry) {
     return join(entry.dir, entry.spritesheetPath);
 }
-/** The directory basename of one entry (legacy asset URL alias, e.g. whale). */
-export function petDirAlias(entry) {
-    return basename(entry.dir);
-}

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;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"}