@linxin666/dsh-pet 0.1.15 → 0.1.16

package/lib/types/registry.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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
+ * 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
+ *      (highest precedence).
+ *
+ * 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
+ * per-track rhythm all fall back to the hatch-pet contract defaults, and the
+ * whale-girl manifest overrides its own durations.
+ * @module @linxin666/dsh-pet/registry
+ */
+import type { PetAnimation } from './state.ts';
+/** Fixed row order of the 9-state animation contract. */
+export declare const PET_ROW_ORDER: readonly PetAnimation[];
+/** Atlas cell size in px. */
+export interface PetCell {
+    width: number;
+    height: number;
+}
+/** Atlas cell size in px (Codex/hatch-pet contract). */
+export declare const DEFAULT_PET_CELL: PetCell;
+/** Columns per row (max frames per track). */
+export declare const DEFAULT_PET_COLUMNS = 8;
+/** Rows in the atlas (fixed by the animation contract). */
+export declare const DEFAULT_PET_ROW_COUNT = 9;
+/**
+ * Per-row used-column counts from the hatch-pet contract table. Manifests
+ * that carry no 'frames' field (the Codex custom-pet shape) resolve here.
+ */
+export declare const DEFAULT_FRAME_COUNTS: readonly number[];
+/** Absolute package root, resolved from a module URL (lib/ or src/). */
+export declare function petPackageRoot(importMetaUrl: string): string;
+/** Resolve the hatch-pet custom pets directory (CODEX_HOME or ~/.codex). */
+export declare function codexPetsDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/** One animation track as served to the browser half. */
+export interface PetTrackDef {
+    /** Frame indices (columns) played in order. */
+    frames: number[];
+    /** Per-frame duration in ms; same length as frames. */
+    durations: number[];
+    /** Whether the track loops; a non-looping track holds its last frame. */
+    loop: boolean;
+    /** Track to switch to after a non-looping track finishes. */
+    fallback?: PetAnimation;
+}
+/** Default per-track rhythm (hatch-pet contract table). */
+export declare const DEFAULT_TRACK_PATTERNS: Record<PetAnimation, {
+    durations: number[];
+    loop: boolean;
+    fallback?: PetAnimation;
+}>;
+/** Manifest shape a pet directory (or 'PetConfig.pets' entry) declares. */
+export interface PetManifest {
+    /** Unique pet id, lowercase kebab-case. */
+    id: string;
+    /** Human-readable display name (settings selector, panel header). */
+    displayName: string;
+    /** One-line description. */
+    description?: string;
+    /** Atlas path relative to the manifest's directory. */
+    spritesheetPath: string;
+    /** Atlas cell size; defaults to the Codex contract 192x208. */
+    cell?: {
+        width?: number;
+        height?: number;
+    };
+    /** Columns per row; defaults to 8. */
+    columns?: number;
+    /**
+     * Per-row frame counts (9 entries, row order above). Manifests that omit
+     * it resolve the hatch-pet contract table.
+     */
+    frames?: number[];
+    /** Optional per-track rhythm overrides; omitted tracks use the defaults. */
+    tracks?: Partial<Record<PetAnimation, PetTrackOverride>>;
+}
+/** Per-track rhythm overrides a manifest may carry. */
+export interface PetTrackOverride {
+    /** Per-frame durations in ms (cycled to the row's frame count). */
+    durations?: number[];
+    /** Whether the track loops. */
+    loop?: boolean;
+    /** Track to switch to after a non-looping track finishes. */
+    fallback?: PetAnimation;
+}
+/** A normalized pet as served to the browser half. */
+export interface PetDefinition {
+    id: string;
+    displayName: string;
+    description: string;
+    /** Atlas cell size in px. */
+    cell: PetCell;
+    /** Columns per row. */
+    columns: number;
+    /** Per-row frame counts (length 9, row order above). */
+    rows: number[];
+    /** Fully resolved animation tracks (frames + durations + loop/fallback). */
+    tracks: Record<PetAnimation, PetTrackDef>;
+    /** Browser URL of the atlas (served by the host asset route). */
+    atlasUrl: string;
+    /** Browser URL of the manifest (served by the host asset route). */
+    manifestUrl: string;
+}
+/** A resolved pet plus its host-side file location. */
+export interface PetEntry extends PetDefinition {
+    /** Absolute directory holding the manifest and atlas. */
+    dir: string;
+    /** Atlas path relative to 'dir' (declared by the manifest). */
+    spritesheetPath: string;
+}
+/** Registry load result: resolved entries plus load warnings. */
+export interface PetRegistry {
+    entries: PetEntry[];
+    warnings: string[];
+    byId(id: string): PetEntry | undefined;
+    /** The pet an installation falls back to when the selection is unknown. */
+    defaultEntry(): PetEntry;
+}
+/** Registry sources. */
+export interface PetRegistryOptions {
+    /** Absolute package root whose 'assets/*' hold built-in pets. */
+    packageRoot: string;
+    /** Asset route prefix the browser URLs are built under. */
+    assetPrefix?: string;
+    /** Custom pet directory (defaults to '${CODEX_HOME:-~/.codex}/pets'). */
+    petsDir?: string;
+    /** Extra manifest entries composed by the embedding application. */
+    extra?: readonly PetManifest[];
+}
+/**
+ * Normalize one parsed manifest into a renderable pet entry, or undefined
+ * (with a warning recorded) when the manifest violates the contract.
+ */
+export declare function resolvePetManifest(raw: unknown, dir: string, options?: {
+    assetPrefix?: string;
+    warnings?: string[];
+}): PetEntry | undefined;
+/**
+ * Load the pet registry: built-in 'assets/*' first, then the hatch-pet
+ * custom pets directory, then composed 'extra' manifests (each later source
+ * overrides an earlier one on id collision). The registry never throws on a
+ * bad manifest: it skips it and records a warning.
+ */
+export declare function loadPetRegistry(options: PetRegistryOptions): PetRegistry;
+/** Strip host-only fields, leaving the client-visible definition. */
+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

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

package/lib/types/registry.js

@@ -0,0 +1,276 @@
+/**
+ * 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
+ * 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
+ *      (highest precedence).
+ *
+ * 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
+ * per-track rhythm all fall back to the hatch-pet contract defaults, and the
+ * whale-girl manifest overrides its own durations.
+ * @module @linxin666/dsh-pet/registry
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Fixed row order of the 9-state animation contract. */
+export const PET_ROW_ORDER = [
+    'idle',
+    'running-right',
+    'running-left',
+    'waving',
+    'jumping',
+    'failed',
+    'waiting',
+    'running',
+    'review',
+];
+/** Atlas cell size in px (Codex/hatch-pet contract). */
+export const DEFAULT_PET_CELL = { width: 192, height: 208 };
+/** Columns per row (max frames per track). */
+export const DEFAULT_PET_COLUMNS = 8;
+/** Rows in the atlas (fixed by the animation contract). */
+export const DEFAULT_PET_ROW_COUNT = 9;
+/**
+ * Per-row used-column counts from the hatch-pet contract table. Manifests
+ * that carry no 'frames' field (the Codex custom-pet shape) resolve here.
+ */
+export const DEFAULT_FRAME_COUNTS = [6, 8, 8, 4, 5, 8, 6, 6, 6];
+/** Absolute package root, resolved from a module URL (lib/ or src/). */
+export function petPackageRoot(importMetaUrl) {
+    return fileURLToPath(new URL('../', importMetaUrl));
+}
+/** Resolve the hatch-pet custom pets directory (CODEX_HOME or ~/.codex). */
+export function codexPetsDir(env = process.env, home = homedir()) {
+    const raw = env.CODEX_HOME !== undefined && env.CODEX_HOME.trim() !== ''
+        ? env.CODEX_HOME.trim()
+        : join(home, '.codex');
+    const expanded = raw === '~'
+        ? home
+        : (raw.startsWith('~/') || raw.startsWith('~\\')) ? join(home, raw.slice(2)) : raw;
+    return join(expanded, 'pets');
+}
+/** Finite non-negative integer guard, else the fallback. */
+function finiteInt(value, fallback, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= max
+        ? value
+        : fallback;
+}
+/** Build the browser URL of one pet asset. */
+function assetUrl(prefix, id, file) {
+    const path = file.split('/').filter(segment => segment !== '').join('/');
+    return prefix + '/' + encodeURIComponent(id) + '/' + path;
+}
+/** Default per-track rhythm (hatch-pet contract table). */
+export const DEFAULT_TRACK_PATTERNS = {
+    idle: { durations: [280, 110, 110, 140, 140, 320], loop: true },
+    'running-right': { durations: [120, 120, 120, 120, 120, 120, 120, 220], loop: true },
+    'running-left': { durations: [120, 120, 120, 120, 120, 120, 120, 220], loop: true },
+    waving: { durations: [140, 140, 140, 280], loop: true },
+    jumping: { durations: [140, 140, 140, 140, 280], loop: false, fallback: 'idle' },
+    failed: { durations: [140, 140, 140, 140, 140, 140, 140, 240], loop: false, fallback: 'idle' },
+    waiting: { durations: [150, 150, 150, 150, 150, 260], loop: true },
+    running: { durations: [120, 120, 120, 120, 120, 220], loop: true },
+    review: { durations: [150, 150, 150, 150, 150, 280], loop: true },
+};
+/** Stable id charset: keeps asset URLs plain and filesystem-safe. */
+const PET_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+/** Safe path-segment charset for atlas files. */
+const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+const PET_NAME_MAX_LENGTH = 80;
+/**
+ * Normalize one parsed manifest into a renderable pet entry, or undefined
+ * (with a warning recorded) when the manifest violates the contract.
+ */
+export function resolvePetManifest(raw, dir, options = {}) {
+    const { assetPrefix = '/pet', warnings = [] } = options;
+    const warn = (message) => { warnings.push(message); };
+    if (typeof raw !== 'object' || raw === null) {
+        warn('manifest is not an object');
+        return undefined;
+    }
+    const source = raw;
+    const id = typeof source.id === 'string' ? source.id.trim() : '';
+    if (!PET_ID_PATTERN.test(id)) {
+        warn('manifest id ' + JSON.stringify(String(source.id)) + ' is not a lowercase kebab id');
+        return undefined;
+    }
+    const displayName = typeof source.displayName === 'string' && source.displayName.trim() !== ''
+        ? source.displayName.trim().slice(0, PET_NAME_MAX_LENGTH)
+        : id;
+    const description = typeof source.description === 'string'
+        ? source.description.trim()
+        : '';
+    const spritesheet = typeof source.spritesheetPath === 'string' && source.spritesheetPath.trim() !== ''
+        ? source.spritesheetPath.trim()
+        : 'spritesheet.webp';
+    const spritesheetPath = spritesheet.split('/').filter(segment => segment !== '');
+    if (spritesheetPath.length === 0
+        || isAbsolute(spritesheet)
+        || spritesheet.includes('\\')
+        || spritesheetPath.some(segment => segment === '..' || !PATH_SEGMENT_PATTERN.test(segment))) {
+        warn('manifest spritesheetPath ' + JSON.stringify(spritesheet) + ' is not a safe relative path');
+        return undefined;
+    }
+    const rawCell = (typeof source.cell === 'object' && source.cell !== null ? source.cell : {});
+    const cell = {
+        width: finiteInt(rawCell.width, DEFAULT_PET_CELL.width, 2048),
+        height: finiteInt(rawCell.height, DEFAULT_PET_CELL.height, 2048),
+    };
+    const columns = finiteInt(source.columns, DEFAULT_PET_COLUMNS, 32);
+    const rows = DEFAULT_FRAME_COUNTS.map((fallback, index) => {
+        const value = Array.isArray(source.frames) ? source.frames[index] : undefined;
+        return finiteInt(value, fallback, columns);
+    });
+    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 }),
+        };
+    }
+    return {
+        id,
+        displayName,
+        description,
+        cell,
+        columns,
+        rows,
+        tracks,
+        atlasUrl: assetUrl(assetPrefix, id, spritesheet),
+        manifestUrl: assetUrl(assetPrefix, id, 'pet.json'),
+        dir,
+        spritesheetPath: spritesheetPath.join('/'),
+    };
+}
+/** Scan one directory of pet folders; entries come back in name order. */
+function scanPetDir(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 manifestFile = join(dir, name, 'pet.json');
+        if (!existsSync(manifestFile))
+            continue;
+        const parsed = readPetJson(manifestFile, options.warnings);
+        if (parsed === undefined)
+            continue;
+        const entry = resolvePetManifest(parsed, join(dir, name), options);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    return entries;
+}
+/** Read and parse one manifest file; undefined (warning recorded) on failure. */
+function readPetJson(file, warnings) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        warnings?.push('skipping ' + file + ': ' + (error instanceof Error ? error.message : String(error)));
+        return undefined;
+    }
+}
+/**
+ * Load the pet registry: built-in 'assets/*' first, then the hatch-pet
+ * custom pets directory, then composed 'extra' manifests (each later source
+ * overrides an earlier one on id collision). The registry never throws on a
+ * bad manifest: it skips it and records a warning.
+ */
+export function loadPetRegistry(options) {
+    const { packageRoot, assetPrefix = '/pet' } = options;
+    const warnings = [];
+    const byId = new Map();
+    const builtinIds = new Set();
+    for (const entry of scanPetDir(join(packageRoot, 'assets'), { assetPrefix, warnings })) {
+        if (byId.has(entry.id)) {
+            warnings.push('duplicate built-in pet id ' + entry.id + '; the first one wins');
+            continue;
+        }
+        byId.set(entry.id, entry);
+        builtinIds.add(entry.id);
+    }
+    const petsDir = options.petsDir ?? codexPetsDir();
+    if (petsDir !== '') {
+        for (const entry of scanPetDir(petsDir, { assetPrefix, warnings })) {
+            if (byId.has(entry.id))
+                warnings.push('custom pet ' + entry.id + ' overrides the built-in one');
+            byId.set(entry.id, entry);
+        }
+    }
+    for (const manifest of options.extra ?? []) {
+        const dir = manifest.spritesheetPath === undefined || isAbsolute(manifest.spritesheetPath)
+            ? join(packageRoot, 'assets', 'extra')
+            : dirname(resolve(packageRoot, manifest.spritesheetPath));
+        const entry = resolvePetManifest(manifest, dir, { assetPrefix, warnings });
+        if (entry === undefined)
+            continue;
+        if (byId.has(entry.id))
+            warnings.push('composed pet ' + entry.id + ' overrides an earlier registration');
+        byId.set(entry.id, entry);
+    }
+    const entries = [...byId.values()];
+    return {
+        entries,
+        warnings,
+        byId: (id) => byId.get(id),
+        defaultEntry: () => entries.find(entry => builtinIds.has(entry.id)) ?? entries[0],
+    };
+}
+/** Strip host-only fields, leaving the client-visible definition. */
+export function petEntryView(entry) {
+    return {
+        id: entry.id,
+        displayName: entry.displayName,
+        description: entry.description,
+        cell: entry.cell,
+        columns: entry.columns,
+        rows: entry.rows,
+        tracks: entry.tracks,
+        atlasUrl: entry.atlasUrl,
+        manifestUrl: entry.manifestUrl,
+    };
+}
+/** The absolute file a pet's atlas resolves to (host asset route). */
+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

@@ -1,22 +1,22 @@
 /**
  * Pet HTTP routes — the browser half talks to the host through plain
- * same-origin JSON endpoints (`/api/pet/*`) and loads the whale-girl atlas
- * from `/pet/whale/*`. The `/plugins/` endpoint only serves client bundles
- * and RPC 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.
+ * same-origin JSON endpoints ('/api/pet/*') and loads pet assets from
+ * '/pet/<id>/*'. The '/plugins/' endpoint only serves client bundles and RPC
+ * 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.
  * @module @linxin666/dsh-pet/routes
  */
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { PetService } from './service.ts';
 /** Browser-facing base path of the pet API. */
 export declare const PET_API_PREFIX = "/api/pet";
-/** Browser-facing base path of the pet asset routes. */
-export declare const PET_ASSET_PREFIX = "/pet/whale";
-/** Absolute package root, resolved from this module's own location (lib/). */
-export declare function petPackageRoot(importMetaUrl: string): string;
-/** Build the full route family (API + assets) for one service + package root. */
+/** 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. */
 export declare function makePetRoutes(deps: {
     service: PetService;
-    packageRoot: string;
 }): 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;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAG9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAQ5C,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE5D;AAkFD,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,EAAE,CAuD5F"}
+{"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;AAI9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAuNtC,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"}