@linxin666/dsh-pet 0.3.2 → 0.3.4

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

@@ -8,14 +8,27 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
  * diagnostic card instead of blanking.
  * @module @linxin666/dsh-pet/client/renderers/PetRendererSwitch
  */
-import { cloneElement, isValidElement } from 'react';
+import { cloneElement, isValidElement, useRef } from 'react';
+import { createDragStream } from "../drag-stream.js";
 import { defaultPetRendererRegistry } from "./registry.js";
 import { Live2dVisualMount } from "./live2d/Live2dVisualMount.js";
+import { Frames2dVisualMount } from "./Frames2dVisualMount.js";
 /** Dispatch one pet definition to its renderer; unknown kinds get a card. */
 export function PetRendererSwitch(props) {
     const renderer = props.definition.renderer ?? 'sprite2d';
+    // The frames2d drag stream lives one level up: the chrome (PetSprite)
+    // reports the gesture through onDraggingChange, the visual subscribes.
+    const dragRef = useRef(null);
+    if (dragRef.current === null || dragRef.current.id !== props.definition.id) {
+        dragRef.current = { id: props.definition.id, stream: createDragStream() };
+    }
+    const drag = props.drag ?? dragRef.current.stream;
     if (renderer === 'sprite2d')
         return _jsx(_Fragment, { children: props.children });
+    if (renderer === 'frames2d' && defaultPetRendererRegistry.has('frames2d') && isValidElement(props.children)) {
+        const visual = (_jsx(Frames2dVisualMount, { definition: props.definition, phase: props.phase, onPet: props.onPet, drag: drag, ...(props.bus === undefined ? {} : { bus: props.bus }), t: props.t }));
+        return cloneElement(props.children, { visual, onDraggingChange: (dragging) => drag.push(dragging) });
+    }
     if (renderer === 'live2d' && defaultPetRendererRegistry.has('live2d') && isValidElement(props.children)) {
         const visual = (_jsx(Live2dVisualMount, { definition: props.definition, phase: props.phase, onPet: props.onPet, t: props.t }));
         return cloneElement(props.children, { visual });

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

@@ -0,0 +1,36 @@
+/**
+ * frames2d renderer — plays the free-form named frame-sequence tracks of a
+ * frames2d pet (manifest v2 'frames2d' block). The pet center picks the
+ * track from the ActivityPhase stream (phase -> track map, idle fallback);
+ * the gameplay driver may force a track through the handle's setState
+ * override (drag/work/sleep/shop...), and a finished non-loop track settles
+ * into its fallback, releasing the override when the fallback matches the
+ * phase-mapped track. Rendering never throws: a broken track list degrades
+ * to the first decodable frame, and the 1.2 s stall watchdog re-kicks the
+ * playback chain after timer throttling.
+ * @module @linxin666/dsh-pet/client/renderers/frames2d
+ */
+import { type PetRenderer, type PetRendererHandle } from '../../contracts/renderer.ts';
+import type { ActivityPhase } from '../../state.ts';
+/** One track as served inside the pet definition (browser URLs). */
+export interface Frames2dTrackConfig {
+    frames: string[];
+    durations: number[];
+    loop: boolean;
+    fallback?: string;
+}
+/** The frames2d block as served inside the pet definition. */
+export interface PetFrames2dConfig {
+    tracks: Record<string, Frames2dTrackConfig>;
+    phases: Partial<Record<ActivityPhase, string>> & {
+        idle: string;
+    };
+}
+export interface Frames2dRendererHandle extends PetRendererHandle {
+    /** Force a track id (gameplay override); undefined returns to phase mapping. */
+    setState(track: string | undefined): void;
+    /** The track currently playing (diagnostics and tests). */
+    currentTrack(): string;
+}
+export declare const frames2dRenderer: PetRenderer<PetFrames2dConfig>;
+//# sourceMappingURL=frames2d.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frames2d.d.ts","sourceRoot":"","sources":["../../../../src/client/renderers/frames2d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA4B,KAAK,WAAW,EAA2B,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACzI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,IAAI,EAAE,OAAO,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;IAC3C,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAClE;AAED,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAA;IACzC,2DAA2D;IAC3D,YAAY,IAAI,MAAM,CAAA;CACvB;AAoCD,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,iBAAiB,CAgJ3D,CAAA"}

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

@@ -0,0 +1,196 @@
+/**
+ * frames2d renderer — plays the free-form named frame-sequence tracks of a
+ * frames2d pet (manifest v2 'frames2d' block). The pet center picks the
+ * track from the ActivityPhase stream (phase -> track map, idle fallback);
+ * the gameplay driver may force a track through the handle's setState
+ * override (drag/work/sleep/shop...), and a finished non-loop track settles
+ * into its fallback, releasing the override when the fallback matches the
+ * phase-mapped track. Rendering never throws: a broken track list degrades
+ * to the first decodable frame, and the 1.2 s stall watchdog re-kicks the
+ * playback chain after timer throttling.
+ * @module @linxin666/dsh-pet/client/renderers/frames2d
+ */
+import { PET_RENDERER_API_VERSION } from "../../contracts/renderer.js";
+/** Stall watchdog period: a looping track stuck longer re-kicks its chain. */
+const WATCHDOG_MS = 1200;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Fail-closed client-side validation of the served frames2d block. */
+function validateFrames2dConfig(config) {
+    if (!isRecord(config) || !isRecord(config.tracks) || !isRecord(config.phases)) {
+        throw new Error('frames2d config requires tracks and phases objects');
+    }
+    const tracks = {};
+    for (const [name, raw] of Object.entries(config.tracks)) {
+        if (!isRecord(raw) || !Array.isArray(raw.frames) || raw.frames.length === 0
+            || raw.frames.some(f => typeof f !== 'string' || f === '')
+            || !Array.isArray(raw.durations) || raw.durations.length !== raw.frames.length
+            || raw.durations.some(d => typeof d !== 'number' || !(d > 0))) {
+            throw new Error('frames2d track ' + JSON.stringify(name) + ' needs same-length frames/durations');
+        }
+        tracks[name] = {
+            frames: raw.frames,
+            durations: raw.durations,
+            loop: raw.loop !== false,
+            ...(typeof raw.fallback === 'string' ? { fallback: raw.fallback } : {}),
+        };
+    }
+    const phases = config.phases;
+    if (typeof phases.idle !== 'string' || tracks[phases.idle] === undefined) {
+        throw new Error('frames2d phases.idle must name an existing track');
+    }
+    return { tracks, phases: phases };
+}
+export const frames2dRenderer = {
+    id: 'frames2d',
+    apiVersion: PET_RENDERER_API_VERSION,
+    validateConfig: validateFrames2dConfig,
+    mount(ctx, config) {
+        const reducedMotion = typeof window !== 'undefined'
+            && typeof window.matchMedia === 'function'
+            && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        const img = document.createElement('img');
+        img.dataset.dshPetFrames2d = ctx.petId;
+        img.alt = '';
+        img.draggable = false;
+        img.style.width = '100%';
+        img.style.height = '100%';
+        img.style.objectFit = 'contain';
+        img.style.pointerEvents = 'none';
+        ctx.container.appendChild(img);
+        // Warm the browser cache for every frame up front (same-origin, small
+        // webp files); playback itself swaps img.src without React state.
+        for (const track of Object.values(config.tracks)) {
+            for (const url of track.frames) {
+                const pre = new Image();
+                pre.src = url;
+            }
+        }
+        let disposed = false;
+        let timer;
+        let watchdog;
+        let track = config.phases.idle;
+        let frameIndex = 0;
+        let lastAdvance = Date.now();
+        let override;
+        const trackForPhase = (phase) => {
+            const mapped = config.phases[phase];
+            return mapped !== undefined && config.tracks[mapped] !== undefined ? mapped : config.phases.idle;
+        };
+        const show = (trackId, index) => {
+            const def = config.tracks[trackId];
+            const url = def?.frames[index];
+            if (url !== undefined && img.getAttribute('src') !== url)
+                img.src = url;
+        };
+        const schedule = (ms) => {
+            if (disposed)
+                return;
+            timer = setTimeout(tick, ms);
+        };
+        function tick() {
+            if (disposed)
+                return;
+            const def = config.tracks[track];
+            if (def === undefined || def.frames.length === 0)
+                return;
+            lastAdvance = Date.now();
+            const next = frameIndex + 1;
+            if (next < def.frames.length) {
+                frameIndex = next;
+                show(track, frameIndex);
+                schedule(def.durations[frameIndex] ?? 200);
+                return;
+            }
+            if (def.loop) {
+                frameIndex = 0;
+                show(track, frameIndex);
+                schedule(def.durations[frameIndex] ?? 200);
+                return;
+            }
+            // Non-loop completion: settle into the fallback; when the fallback is
+            // what the phase map would play anyway, release the gameplay override.
+            const target = def.fallback !== undefined && config.tracks[def.fallback] !== undefined
+                ? def.fallback
+                : config.phases.idle;
+            if (target === trackForPhase(ctx.phase.get()))
+                override = undefined;
+            play(target);
+        }
+        function play(trackId) {
+            if (disposed)
+                return;
+            if (config.tracks[trackId] === undefined)
+                trackId = config.phases.idle;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            track = trackId;
+            frameIndex = 0;
+            lastAdvance = Date.now();
+            show(track, frameIndex);
+            if (reducedMotion)
+                return;
+            const def = config.tracks[track];
+            schedule(def.durations[0] ?? 200);
+        }
+        const unsubscribe = ctx.phase.subscribe((phase) => {
+            if (override !== undefined)
+                return;
+            const target = trackForPhase(phase);
+            if (target !== track)
+                play(target);
+        });
+        // Watchdog: a throttled-away timer (background tab) leaves the chain
+        // dead; re-kick when a looping track has not advanced on schedule.
+        if (!reducedMotion) {
+            watchdog = setInterval(() => {
+                if (disposed)
+                    return;
+                const def = config.tracks[track];
+                if (def === undefined || !def.loop)
+                    return;
+                const expected = (def.durations[frameIndex] ?? 200) + WATCHDOG_MS;
+                if (Date.now() - lastAdvance > expected)
+                    tick();
+            }, WATCHDOG_MS);
+        }
+        play(track);
+        let disposedOnce = false;
+        const dispose = () => {
+            if (disposedOnce)
+                return;
+            disposedOnce = true;
+            disposed = true;
+            unsubscribe();
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (watchdog !== undefined)
+                clearInterval(watchdog);
+            img.remove();
+        };
+        ctx.onCleanup(dispose);
+        return {
+            dispose,
+            setState(next) {
+                if (disposed)
+                    return;
+                if (next === undefined) {
+                    override = undefined;
+                    const target = trackForPhase(ctx.phase.get());
+                    if (target !== track)
+                        play(target);
+                    return;
+                }
+                if (config.tracks[next] === undefined)
+                    return;
+                override = next;
+                if (next !== track)
+                    play(next);
+            },
+            currentTrack() {
+                return track;
+            },
+        };
+    },
+};

package/lib/types/client/settings-form.d.ts

@@ -173,7 +173,7 @@ export declare class CardForm<T> {
     /**
      * Write every staged edit, then re-seed from what the Host accepted.
      *
-     * When the scope carries the optional batch surface (the dsh-web-ui
+     * When the scope carries the optional batch surface (the dsh-web
      * bridge scope), every planned write rides one mutation so cross-field
      * validate hooks (baseURL+model) judge the batch as a unit instead of
      * deadlocking on per-field writes. Otherwise the per-field loop runs.

package/lib/types/client/settings-form.js

@@ -170,7 +170,7 @@ export class CardForm {
     /**
      * Write every staged edit, then re-seed from what the Host accepted.
      *
-     * When the scope carries the optional batch surface (the dsh-web-ui
+     * When the scope carries the optional batch surface (the dsh-web
      * bridge scope), every planned write rides one mutation so cross-field
      * validate hooks (baseURL+model) judge the batch as a unit instead of
      * deadlocking on per-field writes. Otherwise the per-field loop runs.

package/lib/types/client/telemetry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Anonymous install telemetry shared by the DSH Web UI family plugins.
+ *
+ * Once per UTC day per browser, each wired plugin sends one heartbeat to
+ * the dsh-market edge API listing its package name (and version when known).
+ * The payload carries no conversation data and no identifiers beyond a random
+ * UUID generated in localStorage; the server hashes it with a deployment salt
+ * before storage and never persists IP addresses. Sends are fire-and-forget:
+ * failures stay silent and simply retry on a later mount or day. The system
+ * is documented in docs/telemetry.md.
+ */
+export type TelemetryChannel = 'market' | 'npm' | 'unknown';
+export interface TelemetryItem {
+    /** npm package name or asset id, e.g. "@linxin666/dsh-pet" or "skin:harbor". */
+    name: string;
+    /** Installed version when known; omitted otherwise. */
+    version?: string;
+    /** Install channel when determinable (market = Workshop install). */
+    channel?: TelemetryChannel;
+}
+/**
+ * Fire the daily heartbeat for the given items at most once per UTC day per
+ * browser. Never throws and never blocks the caller. Items without an explicit
+ * version inherit the bundle's baked build version.
+ */
+export declare function reportDailyHeartbeat(items: readonly TelemetryItem[]): void;
+//# sourceMappingURL=telemetry.d.ts.map

package/lib/types/client/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../../src/client/telemetry.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;AAE3D,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,OAAO,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AA+CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CA8B1E"}

package/lib/types/client/telemetry.js

@@ -0,0 +1,97 @@
+// Generated by scripts/sync-shared.mjs from shared/client/telemetry.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Anonymous install telemetry shared by the DSH Web UI family plugins.
+ *
+ * Once per UTC day per browser, each wired plugin sends one heartbeat to
+ * the dsh-market edge API listing its package name (and version when known).
+ * The payload carries no conversation data and no identifiers beyond a random
+ * UUID generated in localStorage; the server hashes it with a deployment salt
+ * before storage and never persists IP addresses. Sends are fire-and-forget:
+ * failures stay silent and simply retry on a later mount or day. The system
+ * is documented in docs/telemetry.md.
+ */
+const VISITOR_KEY = 'dsh-web-ui-telemetry-visitor';
+const DAY_KEY_PREFIX = 'dsh-web-ui-telemetry-day:';
+const ENDPOINT = 'https://dsh-market.com/api/telemetry/event';
+/** The building package's version, when the bundle carries it. */
+function bakedVersion() {
+    try {
+        return typeof __DSH_PKG_VERSION__ === 'string' && __DSH_PKG_VERSION__ !== ''
+            ? __DSH_PKG_VERSION__
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read or lazily create the anonymous visitor id; null when storage is unavailable. */
+function visitorId() {
+    try {
+        const existing = localStorage.getItem(VISITOR_KEY);
+        if (existing && /^[A-Za-z0-9_-]{16,64}$/.test(existing))
+            return existing;
+        const fresh = crypto.randomUUID().replaceAll('-', '');
+        localStorage.setItem(VISITOR_KEY, fresh);
+        return fresh;
+    }
+    catch {
+        // Storage unavailable (privacy mode, sandboxed frame): report nothing.
+        return null;
+    }
+}
+/** Drop stale per-day dedup keys so localStorage does not grow forever. */
+function pruneDayKeys(today) {
+    try {
+        for (let index = localStorage.length - 1; index >= 0; index -= 1) {
+            const key = localStorage.key(index);
+            if (key !== null && key.startsWith(DAY_KEY_PREFIX) && key !== DAY_KEY_PREFIX + today) {
+                localStorage.removeItem(key);
+            }
+        }
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Fire the daily heartbeat for the given items at most once per UTC day per
+ * browser. Never throws and never blocks the caller. Items without an explicit
+ * version inherit the bundle's baked build version.
+ */
+export function reportDailyHeartbeat(items) {
+    try {
+        if (items.length === 0)
+            return;
+        const today = new Date().toISOString().slice(0, 10);
+        // Automation contexts (CDP-driven QA browsers, fresh isolated profiles)
+        // mint a new visitor id per run and would inflate instance counts.
+        if (navigator.webdriver)
+            return;
+        if (localStorage.getItem(DAY_KEY_PREFIX + today) !== null)
+            return;
+        const visitor = visitorId();
+        if (visitor === null)
+            return;
+        pruneDayKeys(today);
+        const payloadItems = items.map((item) => {
+            const out = { name: item.name };
+            const version = item.version ?? bakedVersion();
+            if (version !== undefined)
+                out.version = version;
+            if (item.channel !== undefined)
+                out.channel = item.channel;
+            return out;
+        });
+        const body = JSON.stringify({ kind: 'heartbeat', visitor, items: payloadItems });
+        void fetch(ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body,
+            keepalive: true,
+        }).then((response) => {
+            // Mark the day only after an accepted send, so offline browsers retry
+            // on a later mount instead of going dark until tomorrow.
+            if (response.ok)
+                localStorage.setItem(DAY_KEY_PREFIX + today, '1');
+        }).catch(() => { });
+    }
+    catch { /* never break the host UI over telemetry */ }
+}

package/lib/types/defaults.d.ts

@@ -0,0 +1,6 @@
+/** Shared defaults used by registry selection and persisted-state migration. */
+/** Pet id that legacy single-pet installs and fresh registries resolve to. */
+export declare const DEFAULT_PET_ID = "whale-girl";
+/** Default pet name used only when a manifest carries no displayName. */
+export declare const DEFAULT_PET_NAME = "\u9CB8\u9C7C\u5A18";
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,8EAA8E;AAC9E,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,uBAAQ,CAAA"}

package/lib/types/defaults.js

@@ -0,0 +1,5 @@
+/** Shared defaults used by registry selection and persisted-state migration. */
+/** Pet id that legacy single-pet installs and fresh registries resolve to. */
+export const DEFAULT_PET_ID = 'whale-girl';
+/** Default pet name used only when a manifest carries no displayName. */
+export const DEFAULT_PET_NAME = '鲸鱼娘';

package/lib/types/dsh-home.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dsh-home.d.ts","sourceRoot":"","sources":["../../src/dsh-home.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAKH,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAOrG;AAED,gEAAgE;AAChE,wBAAgB,OAAO,IAAI,MAAM,CAEhC"}
+{"version":3,"file":"dsh-home.d.ts","sourceRoot":"","sources":["../../src/dsh-home.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAMH,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAMzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,GAAE,MAAkB,GAAG,MAAM,CAUrG;AAED,gEAAgE;AAChE,wBAAgB,OAAO,IAAI,MAAM,CAEhC"}

package/lib/types/dsh-home.js

@@ -6,12 +6,15 @@
  */
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
+import { isAbsolute as posixIsAbsolute, join as posixJoin } from 'node:path/posix';
 /** Expand a leading ~ (or ~user) in a path, platform-style. */
 export function expandHome(path, home = homedir()) {
+    const isPosix = home.startsWith('/');
+    const j = isPosix ? posixJoin : join;
     if (path === '~')
         return home;
     if (path.startsWith('~/') || path.startsWith('~\\'))
-        return join(home, path.slice(2));
+        return j(home, path.slice(2));
     return path;
 }
 /**
@@ -21,12 +24,15 @@ export function expandHome(path, home = homedir()) {
  * @returns the absolute DSH home path.
  */
 export function resolveDshHome(env = process.env, home = homedir()) {
+    const isPosix = home.startsWith('/');
+    const j = isPosix ? posixJoin : join;
+    const isAbs = isPosix ? posixIsAbsolute : isAbsolute;
     const raw = env.DSH_HOME;
     if (raw !== undefined && raw.trim() !== '') {
         const expanded = expandHome(raw.trim(), home);
-        return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded);
+        return isAbs(expanded) ? expanded : j(process.cwd(), expanded);
     }
-    return join(home, '.dsh');
+    return j(home, '.dsh');
 }
 /** Resolve the DSH home directory from the live environment. */
 export function dshHome() {

package/lib/types/gameplay.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Pet gameplay — the optional manifest 'gameplay' block and its host engine.
+ * The block layers an opt-in mini-game over any frames2d pet: decaying stat
+ * bars, currencies, a weighted idle director, touch zones, a work loop, a
+ * sleep loop, passive income and a shop (issue: miku-pet generalization).
+ *
+ * Discipline split matches manifest-v2: STRUCTURE is fail-closed (types,
+ * ranges, references into stats/tracks); the host engine is pure — every
+ * verb takes an explicit clock and rng so tests stay deterministic. Decay,
+ * passive income and sleep restore are lazy-settled on read (the treats.ts
+ * discipline): the host runs no timers for gameplay.
+ * @module @linxin666/dsh-pet/gameplay
+ */
+/** One gameplay effect: add amount to a declared stat or a currency. */
+export interface PetGameplayEffect {
+    stat?: string;
+    currency?: string;
+    amount: number;
+}
+/** One roll branch inside a touch zone; uncovered roll mass is a no-op. */
+export interface PetGameplayTouchBranch {
+    probability: number;
+    effects?: PetGameplayEffect[];
+    /** Track played on hit (held for stateMs, then the renderer settles). */
+    state?: string;
+    stateMs?: number;
+    /** Bubble phrase pool; one is picked on hit. */
+    phrases?: string[];
+}
+export interface PetGameplayTouchZone {
+    name: string;
+    /** Vertical slice of the hit box (fractions, y0 < y1). */
+    y0: number;
+    y1: number;
+    branches: PetGameplayTouchBranch[];
+}
+export interface PetGameplayStatDef {
+    max: number;
+    initial?: number;
+    decayPerMinute?: number;
+    /** Decay rate while the work mode is active (defaults to decayPerMinute). */
+    workingDecayPerMinute?: number;
+    /** Extra decay rate while no session is active. */
+    idleDecayPerMinute?: number;
+}
+export interface PetGameplayShopItem {
+    id: string;
+    label: string;
+    /** Optional frame path (manifest-relative) shown as the item icon. */
+    image?: string;
+    price: number;
+    currency: string;
+    effects?: PetGameplayEffect[];
+    lottery?: {
+        effects?: PetGameplayEffect[];
+        /** Default currency the prize is paid in (tiers may override). */
+        currency?: string;
+        tiers: {
+            probability: number;
+            prize: number;
+            currency?: string;
+        }[];
+    };
+}
+/** The validated manifest 'gameplay' block. */
+export interface PetGameplayManifest {
+    idleDirector?: {
+        intervalMs: number;
+        maxMiss: number;
+        idleWeight: number;
+        acts: {
+            track: string;
+            weight: number;
+            phrases?: string[];
+        }[];
+    };
+    stats?: Record<string, PetGameplayStatDef>;
+    /** Click hit box inside the sprite box (fractions). */
+    hitBox?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    touch?: {
+        zones: PetGameplayTouchZone[];
+        /** Plain-click effect while a touch animation holds (miku: mood +0..3). */
+        clickBoost?: {
+            stat: string;
+            min: number;
+            max: number;
+        };
+    };
+    work?: {
+        state: string;
+        successState: string;
+        failState: string;
+        tickMs: number;
+        /** Hold time of the result track before the next round. */
+        resultMs?: {
+            success: number;
+            fail: number;
+        };
+        successProbability: number;
+        success?: {
+            effects: PetGameplayEffect[];
+        };
+        fail?: {
+            effects: PetGameplayEffect[];
+        };
+    };
+    sleep?: {
+        state: string;
+        wakeState?: string;
+        restore: {
+            stat: string;
+            amount: number;
+            intervalMs: number;
+        };
+    };
+    passiveIncome?: {
+        currency: string;
+        amount: number;
+        intervalMs: number;
+    };
+    shop?: {
+        state?: string;
+        items: PetGameplayShopItem[];
+    };
+    /** Track played while the chrome reports dragging (default 'drag'). */
+    dragState?: string;
+    /** Track played once when a drag ends (miku: standup), before settling. */
+    dragEndState?: string;
+}
+export interface GameplayParseHooks {
+    /** State names the renderer can play (frames2d track ids). */
+    stateNames: ReadonlySet<string>;
+    error: (message: string) => void;
+}
+/**
+ * Validate the manifest 'gameplay' block (fail-closed). Only frames2d pets
+ * may declare gameplay today: every state reference checks against the
+ * declared track names.
+ */
+export declare function parseGameplayManifest(raw: unknown, hooks: GameplayParseHooks): PetGameplayManifest | undefined;
+/** Persisted per-pet gameplay state (pet.json 'gameplay' map values). */
+export interface PetGameplayState {
+    stats: Record<string, number>;
+    currencies: Record<string, number>;
+    mode: 'work' | 'sleep' | null;
+    /** Epoch ms of the last lazy settle. */
+    settledAt: number;
+}
+/** Fresh state for one pet: stats at their initial (default max), no currency. */
+export declare function initialGameplayState(manifest: PetGameplayManifest, now: number): PetGameplayState;
+/** Clamp one stat value into [0, max]; currencies into [0, CURRENCY_MAX]. */
+export declare function clampGameplay(state: PetGameplayState, manifest: PetGameplayManifest): void;
+/**
+ * Lazy settle: apply stat decay, passive income and sleep restore for the
+ * elapsed wall time since the last settle. Mirrors the treats.ts discipline
+ * (no host timers; read paths settle). Returns whether anything changed.
+ */
+export declare function settleGameplay(state: PetGameplayState, manifest: PetGameplayManifest, now: number, options: {
+    sessionActive: boolean;
+}): boolean;
+/** Apply one effect vector (touch/work/shop), clamped. */
+export declare function applyGameplayEffects(state: PetGameplayState, manifest: PetGameplayManifest, effects: readonly PetGameplayEffect[]): void;
+/** Roll one touch zone branch; undefined when the roll lands in no-op mass. */
+export declare function rollTouchBranch(zone: PetGameplayTouchZone, rng: () => number): PetGameplayTouchBranch | undefined;
+/** Roll one work tick outcome. */
+export declare function rollWorkOutcome(work: NonNullable<PetGameplayManifest['work']>, rng: () => number): 'success' | 'fail';
+/** Draw one lottery prize tier; uncovered mass falls through to the last tier. */
+export declare function drawLotteryTier(lottery: NonNullable<PetGameplayShopItem['lottery']>, rng: () => number): {
+    probability: number;
+    prize: number;
+    currency?: string;
+};
+/** The zone one normalized hit-box point lands in, if any. */
+export declare function touchZoneAt(touch: {
+    zones: PetGameplayTouchZone[];
+}, yFraction: number): PetGameplayTouchZone | undefined;
+//# sourceMappingURL=gameplay.d.ts.map

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

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