@linxin666/dsh-pet 0.2.2 → 0.2.3

package/lib/types/client/renderers/live2d/runtime.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Live2D runtime loading (pet-center M3) — the two scripts a live2d mount
+ * needs, fetched lazily through the plugin's own runtime route: the
+ * user-supplied Cubism Core (proprietary; the plugin never bundles or
+ * downloads it — issue #623 M1 §0) and the plugin-shipped MIT vendor bundle
+ * (pixi.js + untitled-pixi-live2d-engine). Each loads at most once per page;
+ * concurrent mounts share the in-flight promise, and a failure is cached as
+ * 'absent' so a broken install stops retrying the network every mount.
+ *
+ * The vendor surface below is the structural slice the renderer consumes;
+ * the real objects come from 'window.__dshPetLive2d' (lib/live2d-vendor.js),
+ * so this module never imports pixi — the client bundle stays lean.
+ * @module @linxin666/dsh-pet/client/renderers/live2d/runtime
+ */
+/** The pixi Application slice the renderer uses. */
+export interface Live2dVendorApp {
+    canvas: HTMLCanvasElement;
+    stage: {
+        addChild(child: unknown): unknown;
+    };
+    renderer: {
+        readonly width: number;
+        readonly height: number;
+    };
+    init(options: Record<string, unknown>): Promise<void>;
+    destroy(removeView?: boolean, options?: Record<string, unknown>): void;
+}
+/** The Live2DModel slice the renderer uses. */
+export interface Live2dVendorModel {
+    anchor: {
+        set(x: number, y?: number): void;
+    };
+    position: {
+        set(x: number, y: number): void;
+    };
+    scale: {
+        set(x: number, y?: number): void;
+    };
+    readonly width: number;
+    readonly height: number;
+    internalModel: {
+        settings: {
+            motions?: Record<string, unknown[]>;
+            hitAreas?: readonly {
+                Name?: string;
+            }[];
+        };
+    };
+    motion(group: string, index?: number): Promise<unknown>;
+    expression(name?: string): unknown;
+    hitTest(x: number, y: number): string[];
+    on(event: string, fn: () => void): unknown;
+}
+/** The vendor bundle global (window.__dshPetLive2d). */
+export interface Live2dVendor {
+    Application: new () => Live2dVendorApp;
+    extensions: {
+        add(...items: unknown[]): void;
+    };
+    Live2DPlugin: unknown;
+    configureCubismSDK(options: Record<string, unknown>): void;
+    Live2DModel: {
+        from(source: string, options?: Record<string, unknown>): Promise<Live2dVendorModel>;
+    };
+}
+declare global {
+    interface Window {
+        Live2DCubismCore?: unknown;
+        __dshPetLive2d?: Live2dVendor;
+    }
+}
+/** Injects one classic script tag; resolves on load, rejects on error. */
+type ScriptInjector = (src: string) => Promise<void>;
+/** Test seam: swap the network for a stub injector. */
+export interface Live2dRuntimeProbe {
+    inject?: ScriptInjector;
+}
+/**
+ * Ensure the Cubism Core global exists, injecting the runtime-route script
+ * once when absent. Resolves false when the user has not installed the core
+ * (a normal state — the renderer turns it into install guidance).
+ */
+export declare function ensureCubismCore(probe?: Live2dRuntimeProbe): Promise<boolean>;
+/** Ensure the plugin vendor bundle global exists (same caching discipline). */
+export declare function ensureLive2dVendor(probe?: Live2dRuntimeProbe): Promise<Live2dVendor | undefined>;
+/** Reset the cached script promises (tests). */
+export declare function resetLive2dRuntime(): void;
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/client/renderers/live2d/runtime.d.ts.map

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

package/lib/types/client/renderers/live2d/runtime.js

@@ -0,0 +1,63 @@
+/**
+ * Live2D runtime loading (pet-center M3) — the two scripts a live2d mount
+ * needs, fetched lazily through the plugin's own runtime route: the
+ * user-supplied Cubism Core (proprietary; the plugin never bundles or
+ * downloads it — issue #623 M1 §0) and the plugin-shipped MIT vendor bundle
+ * (pixi.js + untitled-pixi-live2d-engine). Each loads at most once per page;
+ * concurrent mounts share the in-flight promise, and a failure is cached as
+ * 'absent' so a broken install stops retrying the network every mount.
+ *
+ * The vendor surface below is the structural slice the renderer consumes;
+ * the real objects come from 'window.__dshPetLive2d' (lib/live2d-vendor.js),
+ * so this module never imports pixi — the client bundle stays lean.
+ * @module @linxin666/dsh-pet/client/renderers/live2d/runtime
+ */
+/** Runtime file URLs the host serves ('/api/pet/runtime/<name>', M3-2). */
+const CORE_URL = '/api/pet/runtime/live2dcubismcore.min.js';
+const VENDOR_URL = '/api/pet/runtime/live2d-vendor.js';
+const defaultInjector = (src) => new Promise((resolve, reject) => {
+    const tag = document.createElement('script');
+    tag.src = src;
+    tag.onload = () => resolve();
+    tag.onerror = () => reject(new Error('script failed to load: ' + src));
+    document.head.appendChild(tag);
+});
+let corePromise;
+let vendorPromise;
+/**
+ * Ensure the Cubism Core global exists, injecting the runtime-route script
+ * once when absent. Resolves false when the user has not installed the core
+ * (a normal state — the renderer turns it into install guidance).
+ */
+export function ensureCubismCore(probe = {}) {
+    if (typeof window !== 'undefined' && window.Live2DCubismCore !== undefined)
+        return Promise.resolve(true);
+    if (probe.inject !== undefined) {
+        return probe.inject(CORE_URL)
+            .then(() => typeof window !== 'undefined' && window.Live2DCubismCore !== undefined)
+            .catch(() => false);
+    }
+    corePromise ??= defaultInjector(CORE_URL)
+        .then(() => typeof window !== 'undefined' && window.Live2DCubismCore !== undefined)
+        .catch(() => false);
+    return corePromise;
+}
+/** Ensure the plugin vendor bundle global exists (same caching discipline). */
+export function ensureLive2dVendor(probe = {}) {
+    if (typeof window !== 'undefined' && window.__dshPetLive2d !== undefined)
+        return Promise.resolve(window.__dshPetLive2d);
+    if (probe.inject !== undefined) {
+        return probe.inject(VENDOR_URL)
+            .then(() => typeof window !== 'undefined' ? window.__dshPetLive2d : undefined)
+            .catch(() => undefined);
+    }
+    vendorPromise ??= defaultInjector(VENDOR_URL)
+        .then(() => typeof window !== 'undefined' ? window.__dshPetLive2d : undefined)
+        .catch(() => undefined);
+    return vendorPromise;
+}
+/** Reset the cached script promises (tests). */
+export function resetLive2dRuntime() {
+    corePromise = undefined;
+    vendorPromise = undefined;
+}

package/lib/types/client/renderers/live2d/vendor-entry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Live2D vendor bundle entry (pet-center M3) — builds pixi.js plus the
+ * untitled-pixi-live2d-engine Cubism stack into lib/live2d-vendor.js, an IIFE
+ * exposing 'window.__dshPetLive2d'. The sprite-only client bundle never pays
+ * for this stack: the live2d renderer lazy-loads the vendor file through the
+ * plugin's own runtime route, after the user-supplied Cubism Core script
+ * ('window.Live2DCubismCore') is already present.
+ *
+ * Redistribution: pixi.js and untitled-pixi-live2d-engine are MIT-licensed
+ * and may ship inside this plugin; the proprietary Cubism Core is NEVER
+ * bundled (issue #623, milestone M1 §0).
+ */
+export { Application, Point, extensions } from 'pixi.js';
+export { configureCubismSDK, Live2DModel, Live2DPlugin } from 'untitled-pixi-live2d-engine/cubism';
+//# sourceMappingURL=vendor-entry.d.ts.map

package/lib/types/client/renderers/live2d/vendor-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vendor-entry.d.ts","sourceRoot":"","sources":["../../../../../src/client/renderers/live2d/vendor-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA"}

package/lib/types/client/renderers/live2d/vendor-entry.js

@@ -0,0 +1,14 @@
+/**
+ * Live2D vendor bundle entry (pet-center M3) — builds pixi.js plus the
+ * untitled-pixi-live2d-engine Cubism stack into lib/live2d-vendor.js, an IIFE
+ * exposing 'window.__dshPetLive2d'. The sprite-only client bundle never pays
+ * for this stack: the live2d renderer lazy-loads the vendor file through the
+ * plugin's own runtime route, after the user-supplied Cubism Core script
+ * ('window.Live2DCubismCore') is already present.
+ *
+ * Redistribution: pixi.js and untitled-pixi-live2d-engine are MIT-licensed
+ * and may ship inside this plugin; the proprietary Cubism Core is NEVER
+ * bundled (issue #623, milestone M1 §0).
+ */
+export { Application, Point, extensions } from 'pixi.js';
+export { configureCubismSDK, Live2DModel, Live2DPlugin } from 'untitled-pixi-live2d-engine/cubism';

package/lib/types/client/renderers/live2d.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Live2D renderer (pet-center M3, issue #623) — mounts a Cubism model into
+ * the center-owned container through the lazy vendor stack. The mount call
+ * itself is synchronous per the renderer contract: the boot (core script →
+ * vendor script → pixi → model) continues asynchronously and reports fatal
+ * failures through the handle's error sink, so the React bridge can render
+ * localized guidance. Disposing mid-boot is race-safe.
+ *
+ * Interaction model: the center chrome owns the affinity economy (its click
+ * handler fires the pet interaction exactly like sprite2d); this renderer's
+ * 'tap' affordance only drives the model's hit-area motion feedback. The
+ * contract's interact write-back stays available for future standalone
+ * mounts and is intentionally not invoked here.
+ *
+ * Motion mapping: manifests map ActivityPhases to motion GROUP names; every
+ * unmapped phase (and any mapped-but-absent group) falls back to the idle
+ * group — official sample models only ship Idle/TapBody, so the fallback is
+ * mandatory. Groups with multiple motions pick a random entry, and a tap
+ * that hits a declared hit area plays the conventional 'TapBody' group,
+ * returning to the phase's group when the tap motion finishes.
+ * @module @linxin666/dsh-pet/client/renderers/live2d
+ */
+import type { ActivityPhase } from '../../state.ts';
+import { type PetRenderer, type PetRendererHandle } from '../../contracts/renderer.ts';
+/** Renderer config: the client-visible live2d block (fail-closed validated). */
+export interface PetLive2dConfig {
+    modelUrl: string;
+    scale?: number;
+    translate?: {
+        x?: number;
+        y?: number;
+    };
+    motions: Partial<Record<ActivityPhase, string>> & {
+        idle: string;
+    };
+    expressions?: Partial<Record<ActivityPhase, string>>;
+    hitAreas?: string[];
+}
+/** Fatal mount failure codes the bridge localizes. */
+export type Live2dErrorCode = 'core-missing' | 'vendor-missing' | 'load-failed';
+/** The live2d activation handle: contract dispose plus tap + error sink. */
+export interface Live2dRendererHandle extends PetRendererHandle {
+    /** Forward a chrome tap in container coordinates; plays the hit motion. */
+    tap(x: number, y: number): void;
+    /** Subscribe to fatal mount errors (at most one fires per activation). */
+    onError(listener: (code: Live2dErrorCode) => void): void;
+}
+/** Reset module state (tests). */
+export declare function resetLive2dRenderer(): void;
+/** The live2d renderer implementation. */
+export declare const live2dRenderer: PetRenderer<PetLive2dConfig>;
+//# sourceMappingURL=live2d.d.ts.map

package/lib/types/client/renderers/live2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live2d.d.ts","sourceRoot":"","sources":["../../../../src/client/renderers/live2d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAA;AASpC,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACtC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAClE,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAA;IACpD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,gBAAgB,GAAG,aAAa,CAAA;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,2EAA2E;IAC3E,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAA;CACzD;AAeD,kCAAkC;AAClC,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAcD,0CAA0C;AAC1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,eAAe,CA+HvD,CAAA"}

package/lib/types/client/renderers/live2d.js

@@ -0,0 +1,180 @@
+/**
+ * Live2D renderer (pet-center M3, issue #623) — mounts a Cubism model into
+ * the center-owned container through the lazy vendor stack. The mount call
+ * itself is synchronous per the renderer contract: the boot (core script →
+ * vendor script → pixi → model) continues asynchronously and reports fatal
+ * failures through the handle's error sink, so the React bridge can render
+ * localized guidance. Disposing mid-boot is race-safe.
+ *
+ * Interaction model: the center chrome owns the affinity economy (its click
+ * handler fires the pet interaction exactly like sprite2d); this renderer's
+ * 'tap' affordance only drives the model's hit-area motion feedback. The
+ * contract's interact write-back stays available for future standalone
+ * mounts and is intentionally not invoked here.
+ *
+ * Motion mapping: manifests map ActivityPhases to motion GROUP names; every
+ * unmapped phase (and any mapped-but-absent group) falls back to the idle
+ * group — official sample models only ship Idle/TapBody, so the fallback is
+ * mandatory. Groups with multiple motions pick a random entry, and a tap
+ * that hits a declared hit area plays the conventional 'TapBody' group,
+ * returning to the phase's group when the tap motion finishes.
+ * @module @linxin666/dsh-pet/client/renderers/live2d
+ */
+import { PET_RENDERER_API_VERSION, } from '../../contracts/renderer.js';
+import { ensureCubismCore, ensureLive2dVendor, } from './live2d/runtime.js';
+/** The de-facto tap-motion group of Cubism sample models. */
+const TAP_GROUP = 'TapBody';
+let vendorConfigured = false;
+/** Configure pixi extensions + the Cubism SDK once per page. */
+function configureOnce(vendor) {
+    if (vendorConfigured)
+        return;
+    vendorConfigured = true;
+    vendor.extensions.add(vendor.Live2DPlugin);
+    vendor.configureCubismSDK({ memorySizeMB: 32 });
+}
+/** Reset module state (tests). */
+export function resetLive2dRenderer() {
+    vendorConfigured = false;
+}
+/** Fail-closed config validation (contract: unknown manifest block in). */
+function validateLive2dConfig(config) {
+    if (typeof config !== 'object' || config === null)
+        throw new Error('live2d config is not an object');
+    const source = config;
+    if (typeof source.modelUrl !== 'string' || source.modelUrl === '')
+        throw new Error('live2d config modelUrl is required');
+    const motions = source.motions;
+    if (typeof motions !== 'object' || motions === null || typeof motions.idle !== 'string') {
+        throw new Error('live2d config motions.idle is required');
+    }
+    return config;
+}
+/** The live2d renderer implementation. */
+export const live2dRenderer = {
+    id: 'live2d',
+    apiVersion: PET_RENDERER_API_VERSION,
+    validateConfig: validateLive2dConfig,
+    mount(ctx, config) {
+        let disposed = false;
+        let app;
+        let model;
+        let errorListener;
+        let unsubscribe;
+        /** The motion group the current phase maps to (resume target after taps). */
+        let phaseGroup = config.motions.idle;
+        let tapPlaying = false;
+        const playGroup = (group) => {
+            if (model === undefined)
+                return;
+            const groups = model.internalModel.settings.motions ?? {};
+            const count = Array.isArray(groups[group]) ? groups[group].length : 0;
+            if (count === 0) {
+                // A mapped-but-absent group falls back to idle (never blank motion).
+                if (group !== config.motions.idle)
+                    playGroup(config.motions.idle);
+                return;
+            }
+            const index = count > 1 ? Math.floor(Math.random() * count) : 0;
+            void model.motion(group, index);
+        };
+        const applyPhase = (phase) => {
+            phaseGroup = config.motions[phase] ?? config.motions.idle;
+            playGroup(phaseGroup);
+            const expression = config.expressions?.[phase];
+            if (expression !== undefined && model !== undefined)
+                void model.expression(expression);
+        };
+        const boot = async () => {
+            if (!await ensureCubismCore()) {
+                if (!disposed)
+                    errorListener?.('core-missing');
+                return;
+            }
+            const vendor = await ensureLive2dVendor();
+            if (vendor === undefined) {
+                if (!disposed)
+                    errorListener?.('vendor-missing');
+                return;
+            }
+            configureOnce(vendor);
+            const pixiApp = new vendor.Application();
+            await pixiApp.init({
+                width: Math.max(1, ctx.container.clientWidth || 160),
+                height: Math.max(1, ctx.container.clientHeight || 174),
+                backgroundAlpha: 0,
+                antialias: true,
+                autoDensity: true,
+                preference: 'webgl',
+            });
+            if (disposed) {
+                pixiApp.destroy(true, { children: true });
+                return;
+            }
+            pixiApp.canvas.style.display = 'block';
+            pixiApp.canvas.style.width = '100%';
+            pixiApp.canvas.style.height = '100%';
+            ctx.container.appendChild(pixiApp.canvas);
+            const loaded = await vendor.Live2DModel.from(config.modelUrl, { autoHitTest: false, autoFocus: false });
+            if (disposed) {
+                pixiApp.destroy(true, { children: true });
+                return;
+            }
+            app = pixiApp;
+            model = loaded;
+            // Auto-fit the model into the container; the manifest scale multiplies
+            // the fit and translate offsets from the center anchor.
+            const fit = Math.min(pixiApp.renderer.width / Math.max(1, loaded.width), pixiApp.renderer.height / Math.max(1, loaded.height)) * 0.92;
+            loaded.scale.set(fit * (config.scale ?? 1));
+            loaded.anchor.set(0.5);
+            loaded.position.set(pixiApp.renderer.width / 2 + (config.translate?.x ?? 0), pixiApp.renderer.height / 2 + (config.translate?.y ?? 0));
+            pixiApp.stage.addChild(loaded);
+            // Resume the phase group once a tap motion finishes playing.
+            loaded.on('motionFinish', () => {
+                if (tapPlaying) {
+                    tapPlaying = false;
+                    playGroup(phaseGroup);
+                }
+            });
+            applyPhase(ctx.phase.get());
+            unsubscribe = ctx.phase.subscribe(applyPhase);
+        };
+        void boot().catch(() => {
+            if (!disposed)
+                errorListener?.('load-failed');
+        });
+        return {
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                unsubscribe?.();
+                model = undefined;
+                if (app !== undefined) {
+                    app.destroy(true, { children: true });
+                    app = undefined;
+                }
+            },
+            tap(x, y) {
+                const current = model;
+                if (disposed || current === undefined)
+                    return;
+                const hits = current.hitTest(x, y);
+                const allowed = config.hitAreas;
+                const hit = allowed === undefined ? hits.length > 0 : hits.some(name => allowed.includes(name));
+                if (!hit)
+                    return;
+                const groups = current.internalModel.settings.motions ?? {};
+                const group = groups[TAP_GROUP];
+                if (!Array.isArray(group) || group.length === 0)
+                    return;
+                tapPlaying = true;
+                const index = group.length > 1 ? Math.floor(Math.random() * group.length) : 0;
+                void current.motion(TAP_GROUP, index);
+            },
+            onError(listener) {
+                errorListener = listener;
+            },
+        };
+    },
+};

package/lib/types/client/renderers/registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Renderer registry — dispatches a manifest's renderer kind to its
+ * implementation (pet-center M2 P4, issue #623). Unknown kinds never blank
+ * the pet: a fallback card names the problem and reports the kinds this
+ * build actually supports.
+ * @module @linxin666/dsh-pet/client/renderers/registry
+ */
+import type { PetRenderer, PetRendererContext, PetRendererHandle } from '../../contracts/renderer.ts';
+/** Renderer dispatch table. */
+export declare class RendererRegistry {
+    private readonly renderers;
+    /** Register one renderer implementation (id wins on re-register). */
+    register(renderer: PetRenderer): void;
+    /** Whether a renderer kind is available in this build. */
+    has(id: string): boolean;
+    /** The registered renderer kinds (for diagnostics). */
+    kinds(): string[];
+    /** Remove every registration (tests; the client index registers once). */
+    clear(): void;
+    /**
+     * Mount a renderer for one activation. An unknown kind renders a clear
+     * diagnostic card into the container instead of failing silently.
+     */
+    mount(kind: string, ctx: PetRendererContext, config: unknown): PetRendererHandle;
+}
+/**
+ * The plugin-wide renderer registry. The client entry registers the
+ * built-in renderers at apply time; the renderer switch and the live2d
+ * bridge dispatch through this instance.
+ */
+export declare const defaultPetRendererRegistry: RendererRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/client/renderers/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAErG,+BAA+B;AAC/B,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAEpC;IAED,0DAA0D;IAC1D,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvB;IAED,uDAAuD;IACvD,KAAK,IAAI,MAAM,EAAE,CAEhB;IAED,0EAA0E;IAC1E,KAAK,IAAI,IAAI,CAEZ;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAW/E;CACF;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,kBAAyB,CAAA"}

package/lib/types/client/renderers/registry.js

@@ -0,0 +1,49 @@
+/**
+ * Renderer registry — dispatches a manifest's renderer kind to its
+ * implementation (pet-center M2 P4, issue #623). Unknown kinds never blank
+ * the pet: a fallback card names the problem and reports the kinds this
+ * build actually supports.
+ * @module @linxin666/dsh-pet/client/renderers/registry
+ */
+/** Renderer dispatch table. */
+export class RendererRegistry {
+    renderers = new Map();
+    /** Register one renderer implementation (id wins on re-register). */
+    register(renderer) {
+        this.renderers.set(renderer.id, renderer);
+    }
+    /** Whether a renderer kind is available in this build. */
+    has(id) {
+        return this.renderers.has(id);
+    }
+    /** The registered renderer kinds (for diagnostics). */
+    kinds() {
+        return [...this.renderers.keys()].sort();
+    }
+    /** Remove every registration (tests; the client index registers once). */
+    clear() {
+        this.renderers.clear();
+    }
+    /**
+     * Mount a renderer for one activation. An unknown kind renders a clear
+     * diagnostic card into the container instead of failing silently.
+     */
+    mount(kind, ctx, config) {
+        const renderer = this.renderers.get(kind);
+        if (renderer === undefined) {
+            const note = document.createElement('div');
+            note.dataset.dshPetRendererFallback = kind;
+            note.textContent = 'Pet renderer "' + kind + '" is not available in this build (supported: ' + this.kinds().join(', ') + ').';
+            ctx.container.appendChild(note);
+            ctx.onCleanup(() => note.remove());
+            return { dispose: () => note.remove() };
+        }
+        return renderer.mount(ctx, renderer.validateConfig(config));
+    }
+}
+/**
+ * The plugin-wide renderer registry. The client entry registers the
+ * built-in renderers at apply time; the renderer switch and the live2d
+ * bridge dispatch through this instance.
+ */
+export const defaultPetRendererRegistry = new RendererRegistry();

package/lib/types/contracts/renderer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Renderer contract — the seam between the pet center and its renderers
+ * (issue #623, milestone M2 P4). Renderers never see the DSH session, the
+ * registry, or the network: they receive exactly three capabilities — an
+ * asset base URL, the ActivityPhase stream, and the interaction write-back —
+ * inside a center-owned container. Every mount is a fresh activation whose
+ * cleanups must be idempotent.
+ *
+ * This contract only serves real consumers: sprite2d (existing) and live2d
+ * (M3). Speculative capabilities join only when a renderer actually needs
+ * them.
+ * @module @linxin666/dsh-pet/contracts/renderer
+ */
+import type { ActivityPhase } from '../state.ts';
+/** Contract version renderers declare against (independent of the manifest). */
+export declare const PET_RENDERER_API_VERSION = "x-org.linxin666.pet-center/v1alpha1";
+/** What the pet center hands a renderer on mount. */
+export interface PetRendererContext {
+    /** The selected pet's id. */
+    readonly petId: string;
+    /** Same-origin URL prefix of this pet's assets ('/pet/<id>'). */
+    readonly assetBase: string;
+    /** Center-owned mount root; renderers must not attach to document.body. */
+    readonly container: HTMLElement;
+    /** The ActivityPhase stream (pet-center owned; renderers subscribe). */
+    readonly phase: {
+        get(): ActivityPhase;
+        subscribe(listener: (phase: ActivityPhase) => void): () => void;
+    };
+    /** The single interaction write-back into the affinity economy. */
+    readonly interact: (kind: 'tap') => void;
+    /** Register an activation-scoped cleanup; run on dispose, idempotently. */
+    onCleanup(fn: () => void): void;
+}
+/** A mounted renderer activation. */
+export interface PetRendererHandle {
+    /** Tear the activation down; may be called 0/1/N times. */
+    dispose(): void;
+}
+/**
+ * One renderer implementation. validateConfig is fail-closed over the
+ * renderer-specific manifest block (schema v2 'sprite2d'/'live2d' blocks).
+ */
+export interface PetRenderer<Config = unknown> {
+    readonly id: string;
+    readonly apiVersion: string;
+    validateConfig(config: unknown): Config;
+    mount(ctx: PetRendererContext, config: Config): PetRendererHandle;
+}
+//# sourceMappingURL=renderer.d.ts.map

package/lib/types/contracts/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/contracts/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,wCAAwC,CAAA;AAE7E,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE;QACd,GAAG,IAAI,aAAa,CAAA;QACpB,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;KAChE,CAAA;IACD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,CAAA;IACxC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAChC;AAED,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,MAAM,GAAG,OAAO;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAA;IACvC,KAAK,CAAC,GAAG,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAClE"}

package/lib/types/contracts/renderer.js

@@ -0,0 +1,15 @@
+/**
+ * Renderer contract — the seam between the pet center and its renderers
+ * (issue #623, milestone M2 P4). Renderers never see the DSH session, the
+ * registry, or the network: they receive exactly three capabilities — an
+ * asset base URL, the ActivityPhase stream, and the interaction write-back —
+ * inside a center-owned container. Every mount is a fresh activation whose
+ * cleanups must be idempotent.
+ *
+ * This contract only serves real consumers: sprite2d (existing) and live2d
+ * (M3). Speculative capabilities join only when a renderer actually needs
+ * them.
+ * @module @linxin666/dsh-pet/contracts/renderer
+ */
+/** Contract version renderers declare against (independent of the manifest). */
+export const PET_RENDERER_API_VERSION = 'x-org.linxin666.pet-center/v1alpha1';