@linxin666/dsh-pet 0.3.19 → 0.3.21

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   node scripts/verify-docs.mjs --write <dir>
-README.md: f19d0d949df444336ce190e997225d1c055f44f0
-README.zh.md: 6cfd8504d95081b9399f1dc132c6854228515879
+README.md: 8b92fda99dc04c8f95ff2e42bf39b42a6a4c1f6f
+README.zh.md: d684b6381a9515c6bc7cef55f418ab4e3ab7ee0c

package/README.md

@@ -289,7 +289,7 @@ global React root (createRoot → document.body) <-- polling 2s -- pet-client (b
                                        PetSprite floating layer (portal + rAF)
 ```
 
-- **Status source**: the host projects official `turn/start`, `step/start`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, and `turn/end` events into waiting/thinking/tool/review/done/failed states. Optional legacy `activity/status` events remain a compatibility input.
+- **Status source**: the host projects official `turn/start`, `step/start`, `assistant/message`, `tool/call`, `tool/result`, and `turn/end` events plus live `agent/assistant-stream` chunks into waiting/thinking/tool/review/done/failed states. Optional legacy `activity/status` events remain a compatibility input.
 - **Registry**: the host normalizes every manifest into a full render definition (geometry, per-row frame counts, per-track durations) and serves it over `/api/pet/pets`; the browser half renders any entry from that definition and carries no per-pet code.
 - **Selection & naming**: `petId` lives in the settings namespace; per-pet names live in `pet.json` under `names`, edited through the hover-panel rename of the active pet. Legacy installs migrate their flat `name` onto the whale girl.
 - **Multi-session semantics**: the API and browser mount are host-global and expose no foreground-session identity. Concurrent sessions each keep their own projected state: the most recent meaningful event drives the sprite animation, while every active TOP-LEVEL session reports its stage in its own bubble (the state view's sessions list, capped at 12 most-recent). Subagent children are tracked for animation, rewards, and the single display bubble but render no bubble of their own, so N conversations never multiply into an N-plus-subagents stack. Every session's completed turns are still rewarded independently; disposing a session removes its bubble, and disposing the display session falls back to the most recent remaining one.

package/README.zh.md

@@ -289,7 +289,7 @@ dsh-pet/
                                        PetSprite 浮层（portal + rAF）
 ```
 
-- **状态来源**：宿主把官方 `turn/start`、`step/start`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`turn/end` 事件投影为 waiting/thinking/tool/review/done/failed 状态。可选兼容 `activity/status` 事件仍作为输入。
+- **状态来源**：宿主把官方 `turn/start`、`step/start`、`assistant/message`、`tool/call`、`tool/result`、`turn/end` 事件与实时 `agent/assistant-stream` 增量投影为 waiting/thinking/tool/review/done/failed 状态。可选兼容 `activity/status` 事件仍作为输入。
 - **注册表**：宿主把每份 manifest 归一化为完整渲染定义（几何、每行帧数、每轨时长），经 `/api/pet/pets` 下发；浏览器半区用该定义渲染任意条目，不携带任何宠物专属代码。
 - **选择与命名**：`petId` 存于设置命名空间；每只宠物的名字存于 `pet.json` 的 `names`，通过悬浮面板对当前宠物改名编辑。旧版安装的平铺 `name` 自动迁移到鲸鱼娘名下。
 - **多会话语义**：API 与浏览器挂载都是宿主全局的，不暴露前台会话身份。并行会话各自保留投影状态：最近一次有意义事件驱动精灵动画，同时每个活动的顶层会话在独立气泡里报告自己的阶段（state 视图的 sessions 列表，最多保留最近 12 个）。子代理会话仍参与动画、计奖与单一显示气泡，但不占独立气泡位——N 个对话不会变成"N + 子代理数"的气泡堆。每个会话完成的轮次仍独立计奖；销毁会话移除它的气泡，销毁当前显示会话则回退到最近仍在活动的会话。

package/lib/client.js

@@ -75,6 +75,55 @@ window.__ModuleLoader__.load({
 			return previous !== null && JSON.stringify(previous) === JSON.stringify(next);
 		}
 		//#endregion
+		//#region src/client/work-tick-gate.ts
+		/**
+		* Page-wide work-tick gate for the pet's work mode. Hot reloads can leave
+		* several GameplayHud instances alive, each running its own work interval;
+		* without a shared gate every interval would call workTick and each stale call
+		* re-rolls, re-grants treats and re-plays the success/fail track, so the
+		* outcome appears to play several times per window. The gate accepts the first
+		* adjudication of a window and silently suppresses the duplicates that follow.
+		*
+		* The window is the active pet's own `gameplay.work.tickMs`, not a constant: a
+		* pet configured with a shorter cadence must actually adjudicate that often,
+		* while a fixed window would downgrade it without saying so (#1494).
+		* @module @linxin666/dsh-pet/client/work-tick-gate
+		*/
+		/** Window used when the active pet declares no work cadence. */
+		const DEFAULT_WORK_TICK_MS = 1e4;
+		/** Manifest bounds for `gameplay.work.tickMs` (src/gameplay.ts). */
+		const MIN_WORK_TICK_MS = 1e3;
+		const MAX_WORK_TICK_MS = 6e4;
+		/**
+		* The gate window for one pet: its configured cadence, clamped to the manifest's
+		* own bounds so a malformed registry entry cannot disable or flood the gate.
+		* @param tickMs - the active definition's `gameplay.work.tickMs`, when it has one.
+		* @returns the window in milliseconds.
+		*/
+		function workTickWindowMs(tickMs) {
+			if (typeof tickMs !== "number" || !Number.isFinite(tickMs)) return DEFAULT_WORK_TICK_MS;
+			return Math.min(MAX_WORK_TICK_MS, Math.max(MIN_WORK_TICK_MS, tickMs));
+		}
+		/**
+		* Create a gate.
+		* @param now - the clock, injectable so tests control the window.
+		* @returns the gate over that clock.
+		*/
+		function createWorkTickGate(now = Date.now) {
+			let lastAdjudicatedAt = 0;
+			return {
+				allow: (tickMs) => {
+					const at = now();
+					if (at - lastAdjudicatedAt < workTickWindowMs(tickMs)) return false;
+					lastAdjudicatedAt = at;
+					return true;
+				},
+				reset: () => {
+					lastAdjudicatedAt = 0;
+				}
+			};
+		}
+		//#endregion
 		//#region ../../node_modules/.pnpm/clsx@2.1.1/node_modules/clsx/dist/clsx.mjs
 		function r(e) {
 			var t, f, n = "";
@@ -1095,6 +1144,7 @@ window.__ModuleLoader__.load({
 					gameplayBus.setIdleTrack = (track) => {
 						handleRef.current?.setIdleTrack(track);
 					};
+					if (gameplayBus.idleTrack !== void 0) handle.setIdleTrack(gameplayBus.idleTrack);
 					cleanups.push(() => {
 						gameplayBus.setTrack = void 0;
 						gameplayBus.setIdleTrack = void 0;
@@ -1208,6 +1258,7 @@ window.__ModuleLoader__.load({
 			const def = definition.gameplay;
 			const view = ui.snapshot?.gameplay;
 			const phase = ui.snapshot?.phase ?? "idle";
+			const persistedSkin = ui.snapshot?.skin;
 			const [open, setOpen] = (0, react.useState)(false);
 			const [page, setPage] = (0, react.useState)("root");
 			const [skinId, setSkinId] = (0, react.useState)(void 0);
@@ -1400,20 +1451,24 @@ window.__ModuleLoader__.load({
 			(0, react.useEffect)(() => {
 				const work = def?.work;
 				if (def === void 0 || work === void 0 || view?.mode !== "work") return void 0;
-				bus.setTrack?.(work.state);
+				const skinGameplay = definition.frames2d?.skins?.find((skin) => skin.id === skinIdRef.current)?.gameplayTracks;
+				/** The state's track, swapped for the skin's override when it declares one. */
+				const trackOf = (state) => skinGameplay?.[state] ?? state;
+				bus.setTrack?.(trackOf(work.state));
 				let resultTimer = 0;
 				const timer = window.setInterval(() => {
 					if (busyRef.current) return;
 					busyRef.current = true;
 					api.workTick().then((result) => {
 						busyRef.current = false;
+						if (modeRef.current !== "work") return;
 						applyResult(result);
 						if (result.ok !== true || result.outcome === void 0) return;
-						const resultTrack = result.outcome === "success" ? work.successState : work.failState;
+						const resultTrack = trackOf(result.outcome === "success" ? work.successState : work.failState);
 						const hold = result.outcome === "success" ? work.resultMs?.success ?? 1300 : work.resultMs?.fail ?? 1900;
 						bus.setTrack?.(resultTrack);
 						resultTimer = window.setTimeout(() => {
-							if (modeRef.current === "work") bus.setTrack?.(work.state);
+							if (modeRef.current === "work") bus.setTrack?.(trackOf(work.state));
 						}, hold);
 					}, () => {
 						busyRef.current = false;
@@ -1427,7 +1482,8 @@ window.__ModuleLoader__.load({
 			}, [
 				definition.id,
 				def,
-				view?.mode
+				view?.mode,
+				skinId
 			]);
 			(0, react.useEffect)(() => {
 				const sleep = def?.sleep;
@@ -1464,10 +1520,32 @@ window.__ModuleLoader__.load({
 			const setMode = (next) => {
 				api.setMode(next).then(applyResult, () => void 0);
 			};
+			(0, react.useEffect)(() => {
+				setSkinId(persistedSkin);
+			}, [definition.id, persistedSkin]);
+			(0, react.useEffect)(() => {
+				const skin = definition.frames2d?.skins?.find((candidate) => candidate.id === skinId);
+				bus.idleTrack = skin?.idleTrack;
+				bus.setIdleTrack?.(skin?.idleTrack);
+			}, [
+				definition.id,
+				skinId,
+				persistedSkin
+			]);
 			const skins = definition.frames2d?.skins;
+			/** The base idle track one skin id resolves to (undefined = default look). */
+			const skinTrackOf = (id) => id === void 0 ? void 0 : definition.frames2d?.skins?.find((candidate) => candidate.id === id)?.idleTrack;
 			const selectSkin = (skin) => {
 				setSkinId(skin?.id);
 				bus.setIdleTrack?.(skin?.idleTrack);
+				const restore = () => {
+					setSkinId(persistedSkin);
+					bus.setIdleTrack?.(skinTrackOf(persistedSkin));
+				};
+				api.setSkin(skin?.id).then((result) => {
+					if (result.ok) return;
+					restore();
+				}, restore);
 			};
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				ref: hudRef,
@@ -2000,10 +2078,11 @@ window.__ModuleLoader__.load({
 		* Frame presentation has two modes picked once at mount by capability
 		* probing:
 		* - Canvas bitmap buffer (default where createImageBitmap/fetch/2D context
-		*   exist): every frame is decoded exactly once into an ImageBitmap during
-		*   the warm pass and drawn onto one <canvas> - steady-state playback issues
-		*   zero DOM mutations and zero re-decodes (measured hotspot: swapping
-		*   <img>.src per frame drove image decode + invalidation every tick).
+		*   exist): frames are decoded once into an ImageBitmap on demand, with a
+		*   bounded look-ahead window over the playing track, and drawn onto one
+		*   <canvas> - steady-state playback issues zero DOM mutations and zero
+		*   re-decodes (measured hotspot: swapping <img>.src per frame drove image
+		*   decode + invalidation every tick).
 		* - Classic <img> fallback (jsdom/tests or missing APIs): identical to the
 		*   historical behavior - cache-warm Image elements plus guarded src swaps,
 		*   so environments without modern decoding keep working unchanged.
@@ -2119,42 +2198,93 @@ window.__ModuleLoader__.load({
 				}
 				const decoding = /* @__PURE__ */ new Map();
 				const decodedAll = [];
-				const loadFrame = (url) => {
+				const FRAME_POOL_LIMIT = 8;
+				const frameQueue = [];
+				let activeFrames = 0;
+				const decodeFrame = async (url) => {
+					try {
+						const response = await fetch(url);
+						if (!response.ok) throw new Error("http " + response.status);
+						const bitmap = await createImageBitmap(await response.blob());
+						return {
+							source: bitmap,
+							width: bitmap.width,
+							height: bitmap.height
+						};
+					} catch {
+						return await new Promise((resolve) => {
+							try {
+								const pre = new Image();
+								pre.onload = () => {
+									resolve(pre.naturalWidth > 0 ? {
+										source: pre,
+										width: pre.naturalWidth,
+										height: pre.naturalHeight
+									} : void 0);
+								};
+								pre.onerror = () => resolve(void 0);
+								pre.src = url;
+							} catch {
+								resolve(void 0);
+							}
+						});
+					}
+				};
+				const pumpFrames = () => {
+					while (activeFrames < FRAME_POOL_LIMIT && frameQueue.length > 0) {
+						const queued = frameQueue.shift();
+						activeFrames += 1;
+						queued.release();
+					}
+				};
+				const loadFrame = (url, jump = false) => {
+					if (jump) {
+						const index = frameQueue.findIndex((queued) => queued.url === url);
+						if (index > 0) frameQueue.unshift(frameQueue.splice(index, 1)[0]);
+					}
 					const cached = decoding.get(url);
 					if (cached !== void 0) return cached;
-					const job = (async () => {
-						try {
-							const response = await fetch(url);
-							if (!response.ok) throw new Error("http " + response.status);
-							const bitmap = await createImageBitmap(await response.blob());
-							return {
-								source: bitmap,
-								width: bitmap.width,
-								height: bitmap.height
-							};
-						} catch {
-							return await new Promise((resolve) => {
-								try {
-									const pre = new Image();
-									pre.onload = () => {
-										resolve(pre.naturalWidth > 0 ? {
-											source: pre,
-											width: pre.naturalWidth,
-											height: pre.naturalHeight
-										} : void 0);
-									};
-									pre.onerror = () => resolve(void 0);
-									pre.src = url;
-								} catch {
-									resolve(void 0);
-								}
-							});
-						}
-					})();
+					let release;
+					const job = new Promise((resolve) => {
+						release = resolve;
+					}).then(() => disposed ? void 0 : decodeFrame(url));
+					job.then((frame) => {
+						if (frame === void 0) decoding.delete(url);
+					}, () => decoding.delete(url));
+					job.finally(() => {
+						activeFrames -= 1;
+						pumpFrames();
+					});
 					decoding.set(url, job);
 					decodedAll.push(job.then(() => void 0, () => void 0));
+					const entry = {
+						url,
+						release
+					};
+					if (jump) frameQueue.unshift(entry);
+					else frameQueue.push(entry);
+					pumpFrames();
 					return job;
 				};
+				/**
+				* Bounded look-ahead window: decode only the frames playback is about to
+				* need. The historical warm pass decoded every frame of every track up
+				* front - a shipped pet carries ~1.1k 512x683 frames, so that pass pulls
+				* tens of megabytes and retains every decoded bitmap for the life of the
+				* page. Prefetching the playing track's next frames keeps loops and phase
+				* switches warm while unplayed tracks (and every unselected skin's
+				* frames) stay on demand, where playback jumps the queue anyway.
+				*/
+				const PREFETCH_AHEAD = 12;
+				const prefetchAhead = (trackId, index) => {
+					const def = config.tracks[trackId];
+					if (def === void 0) return;
+					const end = Math.min(def.frames.length, index + 1 + PREFETCH_AHEAD);
+					for (let ahead = index + 1; ahead < end; ahead += 1) {
+						const url = def.frames[ahead];
+						if (url !== void 0) loadFrame(url);
+					}
+				};
 				let disposed = false;
 				let timer;
 				let watchdog;
@@ -2175,7 +2305,7 @@ window.__ModuleLoader__.load({
 				const paintCanvas = (url) => {
 					if (context2d === null || canvas === null) return;
 					const myToken = ++drawToken;
-					loadFrame(url).then((frame) => {
+					loadFrame(url, true).then((frame) => {
 						if (disposed || frame === void 0 || myToken !== drawToken) return;
 						if (lastDrawnUrl === url) return;
 						lastDrawnUrl = url;
@@ -2189,6 +2319,7 @@ window.__ModuleLoader__.load({
 				const show = (trackId, index) => {
 					const url = config.tracks[trackId]?.frames[index];
 					if (url === void 0) return;
+					prefetchAhead(trackId, index);
 					if (img !== null) {
 						if (img.getAttribute("src") !== url) img.src = url;
 						return;
@@ -2245,7 +2376,6 @@ window.__ModuleLoader__.load({
 					const expected = (def.durations[frameIndex] ?? 200) + WATCHDOG_MS;
 					if (Date.now() - lastAdvance > expected) tick();
 				}, WATCHDOG_MS);
-				for (const warmTrack of Object.values(config.tracks)) for (const warmUrl of warmTrack.frames) loadFrame(warmUrl);
 				play(track);
 				let disposedOnce = false;
 				const dispose = () => {
@@ -2255,6 +2385,7 @@ window.__ModuleLoader__.load({
 					unsubscribe();
 					if (timer !== void 0) clearTimeout(timer);
 					if (watchdog !== void 0) clearInterval(watchdog);
+					for (const queued of frameQueue.splice(0)) queued.release();
 					Promise.allSettled(decodedAll).then(() => {
 						for (const job of decoding.values()) job.then((frame) => {
 							try {
@@ -3619,7 +3750,7 @@ window.__ModuleLoader__.load({
 		/** The building package's version, when the bundle carries it. */
 		function bakedVersion() {
 			try {
-				return "0.3.19";
+				return "0.3.21";
 			} catch {
 				return;
 			}
@@ -3702,6 +3833,7 @@ window.__ModuleLoader__.load({
 			setConfig: (patch) => petFetch("/api/pet/set-config", patch),
 			setName: (name) => petFetch("/api/pet/set-name", { name }),
 			setPet: (petId) => petFetch("/api/pet/set-pet", { petId }),
+			setSkin: (skin) => petFetch("/api/pet/set-skin", skin === void 0 ? {} : { skin }),
 			gameplayTouch: (zone) => petFetch("/api/pet/gameplay/touch", zone === void 0 ? {} : { zone }),
 			gameplaySetMode: (mode) => petFetch("/api/pet/gameplay/mode", { mode }),
 			gameplayWorkTick: () => petFetch("/api/pet/gameplay/work-tick", {}),
@@ -3726,16 +3858,17 @@ window.__ModuleLoader__.load({
 		* first-level settings section.
 		* @param ctx - client root context.
 		*/
+		/** The page-wide work-tick gate; its window follows the active pet's cadence. */
+		const workTickGate = createWorkTickGate();
 		/**
-		* Module-wide work-tick throttle (ms). Hot reloads can leave several
-		* GameplayHud instances alive, each running its own 10s work interval;
-		* without a shared gate every interval would call workTick and each stale
-		* call re-rolls, re-grants treats and re-plays the success/fail track, so
-		* the outcome appears to play several times per window. This shared marker
-		* accepts the first adjudication of a window and silently suppresses the
-		* duplicates that follow. Reset when (re-)entering work mode.
+		* The work cadence the active pet declares, when its registry entry is known.
+		* @param store - the pet store holding the host snapshot and the registry list.
+		* @returns the configured `gameplay.work.tickMs`, or undefined when unknown.
 		*/
-		let lastWorkTickAt = 0;
+		function activeWorkTickMs(store) {
+			const state = store.getSnapshot();
+			return state.pets.find((entry) => entry.id === state.snapshot?.pet.id)?.gameplay?.work?.tickMs;
+		}
 		function apply(ctx) {
 			reportDailyHeartbeat([{ name: "@linxin666/dsh-pet" }]);
 			ctx.effect(() => {
@@ -3897,14 +4030,19 @@ window.__ModuleLoader__.load({
 						},
 						gameplay: {
 							touch: (zone) => petApi.gameplayTouch(zone),
+							setSkin: (skin) => petApi.setSkin(skin).then((result) => {
+								if (result.ok) pollNow();
+								return result;
+							}, () => ({
+								ok: false,
+								error: "transport"
+							})),
 							setMode: async (mode) => {
-								if (mode === "work") lastWorkTickAt = 0;
+								if (mode === "work") workTickGate.reset();
 								return petApi.gameplaySetMode(mode);
 							},
 							workTick: async () => {
-								const now = Date.now();
-								if (now - lastWorkTickAt < 8500) return { ok: true };
-								lastWorkTickAt = now;
+								if (!workTickGate.allow(activeWorkTickMs(petStore))) return { ok: true };
 								return petApi.gameplayWorkTick();
 							},
 							buy: (item) => petApi.gameplayBuy(item)