@linxin666/dsh-pet 0.1.19 → 0.1.20

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: 75de064887be4289018547fba722851afd98dd5a
-README.zh.md: 9e396eca9b5a47425aeee972ec7a95a7e7da81ac
+README.md: b8705d67cb561b581ecfad2d644e6d70e17cf6b1
+README.zh.md: fb5bc5846a273a667c0f72adac1ecc1c9e0d5130

package/README.md

@@ -23,8 +23,8 @@ Re-implemented from the pet feature of the Codex desktop app, as an official DSH
 | Dragging | Hold and drag the pet to reposition; position persisted |
 | Hide/Summon | Hover panel 隐藏 (Hide); after hiding, a 召唤{name} (Summon {name}) button appears |
 | Witty remarks | Built-in remark library (10 lines per event) plus per-pet custom lines from a manifest remarks block — community PRs give their pet its own voice |
-| Status bubbles | Each concurrently active session gets its own bubble, stacked above the pet (up to 12); transient interaction feedback temporarily takes priority |
-| Multi-session activity | The pet is host-global: the most recent meaningful event drives the sprite animation while every active session reports its own state in a separate bubble; completed turns from every session contribute affinity and treats |
+| Status bubbles | Each concurrently active top-level session gets its own bubble, stacked above the pet (up to 12); subagent sessions report through their spawning conversation and never occupy a bubble of their own; click a bubble to jump to its session; transient interaction feedback temporarily takes priority |
+| Multi-session activity | The pet is host-global: the most recent meaningful event drives the sprite animation while every active top-level session reports its own state in a separate bubble; completed turns from every session (subagents included) contribute affinity and treats |
 
 ## Pet contract
 
@@ -113,7 +113,7 @@ global React root (createRoot → document.body) <-- polling 2s -- pet-client (b
 - **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.
 - **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 session reports its stage in its own bubble (the state view's sessions list, capped at 12 most-recent). 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.
+- **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.
 - **Mount point**: `document.body` (global React root, always shown: no session / new session / mid-session — the old mount point `conversation.composer.dock` only rendered in an active session, hiding the pet in new sessions); the component uses `createPortal` internally to render the global floating layer.
 - **Rendering**: CSS sprite (background-position) per-frame animation; frame durations come from the served definition's tracks.
 - **Communication**: browser ↔ host over the same-origin `/api/pet/*` JSON endpoints (state/pets/interact/set-visible/set-config/set-name/set-pet); each pet's atlas loads from `/pet/<id>/<spritesheetPath>` — the plugin self-sufficiently provides its own API and assets (the same pattern as dsh-remote-web-ui's `/api/pair`).

package/README.zh.md

@@ -23,8 +23,8 @@
 | 拖动 | 按住拖动宠物换位置；位置持久化 |
 | 隐藏/召唤 | 悬浮面板 隐藏；隐藏后出现 召唤{name} 按钮 |
 | 妙语库 | 内置默认妙语库（每类事件 10 句）+ 宠物 manifest 的 remarks 块自定义台词——社区 PR 可以给自家宠物配上专属妙语 |
-| 状态气泡 | 并行会话各自一个气泡，在宠物头顶堆叠（最多 12 个）；瞬时互动反馈临时优先 |
-| 多会话活动 | 宠物是宿主全局的：最近一次有意义事件驱动精灵动画，同时每个活动会话用自己的气泡报告各自状态；每个会话完成的轮次都计入亲密度与小鱼干 |
+| 状态气泡 | 每个并行活动的顶层会话各自一个气泡，在宠物头顶堆叠（最多 12 个）；子代理会话借由其发起会话体现，不占用独立气泡；点击气泡跳转到对应会话；瞬时互动反馈临时优先 |
+| 多会话活动 | 宠物是宿主全局的：最近一次有意义事件驱动精灵动画，同时每个活动的顶层会话用自己的气泡报告各自状态；每个会话（含子代理）完成的轮次都计入亲密度与小鱼干 |
 
 ## 宠物契约
 
@@ -113,7 +113,7 @@ dsh-pet/
 - **状态来源**：宿主把官方 `turn/start`、`step/start`、`assistant/chunk`、`assistant/message`、`tool/call`、`tool/result`、`turn/end` 事件投影为 waiting/thinking/tool/review/done/failed 状态。可选兼容 `activity/status` 事件仍作为输入。
 - **注册表**：宿主把每份 manifest 归一化为完整渲染定义（几何、每行帧数、每轨时长），经 `/api/pet/pets` 下发；浏览器半区用该定义渲染任意条目，不携带任何宠物专属代码。
 - **选择与命名**：`petId` 存于设置命名空间；每只宠物的名字存于 `pet.json` 的 `names`，通过悬浮面板对当前宠物改名编辑。旧版安装的平铺 `name` 自动迁移到鲸鱼娘名下。
-- **多会话语义**：API 与浏览器挂载都是宿主全局的，不暴露前台会话身份。并行会话各自保留投影状态：最近一次有意义事件驱动精灵动画，同时每个活动会话在独立气泡里报告自己的阶段（state 视图的 sessions 列表，最多保留最近 12 个）。每个会话完成的轮次仍独立计奖；销毁会话移除它的气泡，销毁当前显示会话则回退到最近仍在活动的会话。
+- **多会话语义**：API 与浏览器挂载都是宿主全局的，不暴露前台会话身份。并行会话各自保留投影状态：最近一次有意义事件驱动精灵动画，同时每个活动的顶层会话在独立气泡里报告自己的阶段（state 视图的 sessions 列表，最多保留最近 12 个）。子代理会话仍参与动画、计奖与单一显示气泡，但不占独立气泡位——N 个对话不会变成"N + 子代理数"的气泡堆。每个会话完成的轮次仍独立计奖；销毁会话移除它的气泡，销毁当前显示会话则回退到最近仍在活动的会话。
 - **挂载点**：`document.body`（全局 React 根，始终显示：无会话 / 新会话 / 会话中都可见——旧挂载点 `conversation.composer.dock` 只在活动会话里渲染，新会话里宠物消失）；组件内部用 `createPortal` 渲染全局浮层。
 - **渲染**：CSS 精灵（background-position）逐帧动画；帧时长来自下发定义里的轨道表。
 - **通信**：浏览器 ↔ 宿主走同源 `/api/pet/*` JSON 端点（state/pets/interact/set-visible/set-config/set-name/set-pet）；每只宠物的图集从 `/pet/<id>/<spritesheetPath>` 加载——插件自给自足地提供自己的 API 与资源（与 dsh-remote-web-ui 的 `/api/pair` 同一模式）。

package/lib/client.js

@@ -62,21 +62,35 @@ window.__ModuleLoader__.load({
 			return n;
 		}
 		//#endregion
-		//#region src/client/spritesheet.ts
-		/** Row index of one animation track (the fixed 9-row contract). */
-		function rowOfTrack(animation) {
+		//#region src/state.ts
+		/** The spritesheet row index for one animation track. */
+		function rowOf(animation) {
 			return {
-				idle: 0,
+				"idle": 0,
 				"running-right": 1,
 				"running-left": 2,
-				waving: 3,
-				jumping: 4,
-				failed: 5,
-				waiting: 6,
-				running: 7,
-				review: 8
+				"waving": 3,
+				"jumping": 4,
+				"failed": 5,
+				"waiting": 6,
+				"running": 7,
+				"review": 8
 			}[animation];
 		}
+		//#endregion
+		//#region src/client/spritesheet.ts
+		/**
+		* Spritesheet geometry helpers — parameterized by the pet definition the
+		* host serves over '/api/pet/pets', so the browser half renders any registry
+		* entry without per-pet code. The per-track tables (frames, durations, loop,
+		* fallback) also come from the registry; these helpers only place frames,
+		* guard track lengths, and map the fixed 9-row animation contract.
+		* @module @linxin666/dsh-pet/client/spritesheet
+		*/
+		/** Row index of one animation track (the fixed 9-row contract). */
+		function rowOfTrack(animation) {
+			return rowOf(animation);
+		}
 		/**
 		* Background-position (px) of one frame cell within the scaled atlas.
 		* The background image is scaled by `scale` (element size ÷ cell size), and
@@ -107,7 +121,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:packages/dsh-pet/src/client/pet.module.css.mjs
-		const css$2 = ".kz2Bea_float{pointer-events:auto;-webkit-user-select:none;user-select:none;flex-direction:column;align-items:center;display:flex;position:fixed}.kz2Bea_sprite{image-rendering:auto;touch-action:none;position:relative}.kz2Bea_bubble{white-space:nowrap;color:#fff;pointer-events:none;border-radius:999px;margin-bottom:6px;padding:4px 10px;font-size:12px;line-height:1.4;animation:2.6s ease-out forwards kz2Bea_pet-bubble-pop;position:absolute;bottom:100%;box-shadow:0 2px 8px #00000040}.kz2Bea_bubblePet{background:#f472b6eb}.kz2Bea_bubbleFeed{background:#38bdf8eb}.kz2Bea_bubbleStatus{text-overflow:ellipsis;background:#0f172ae6;border:1px solid #7dd3fc80;max-width:min(280px,100vw - 24px);animation:none;overflow:hidden}.kz2Bea_bubbleStack{pointer-events:none;flex-direction:column;align-items:center;gap:4px;display:flex;position:absolute;bottom:100%}.kz2Bea_bubbleStack .kz2Bea_bubble{margin-bottom:0;position:relative;bottom:auto}@keyframes kz2Bea_pet-bubble-pop{0%{opacity:0;transform:translateY(6px)scale(.85)}15%{opacity:1;transform:translateY(0)scale(1.05)}25%{transform:translateY(0)scale(1)}75%{opacity:1}to{opacity:0;transform:translateY(-8px)scale(.95)}}.kz2Bea_panel{color:#e2e8f0;backdrop-filter:blur(6px);background:#0f172aeb;border:1px solid #94a3b859;border-radius:10px;flex-direction:column;gap:6px;min-width:132px;padding:8px 10px;font-size:12px;display:flex;position:absolute;bottom:100%;box-shadow:0 4px 16px #00000059}.kz2Bea_panel:after{content:\"\";height:14px;position:absolute;top:100%;left:0;right:0}.kz2Bea_rankRow{white-space:nowrap;justify-content:space-between;gap:10px;display:flex}.kz2Bea_nameCell{font-weight:600}.kz2Bea_renameRow{align-items:center;gap:6px;display:flex}.kz2Bea_nameInput{color:#e2e8f0;background:#1e293be6;border:1px solid #7dd3fc80;border-radius:6px;outline:none;flex:1;min-width:0;padding:3px 6px;font-size:12px}.kz2Bea_nameInput:focus{border-color:#38bdf8;box-shadow:0 0 0 2px #38bdf873}.kz2Bea_actions{gap:6px;display:flex}.kz2Bea_action{cursor:pointer;color:#0f172a;background:linear-gradient(#7dd3fc,#38bdf8);border:none;border-radius:6px;flex:1;padding:4px 8px;font-size:12px;transition:filter .12s,box-shadow .12s}.kz2Bea_action:hover{filter:brightness(1.08)}.kz2Bea_action:active{filter:brightness(.94)}.kz2Bea_action:focus-visible{outline:none;box-shadow:0 0 0 2px #38bdf8d9}.kz2Bea_summon{color:#7dd3fc;cursor:pointer;background:#0f172abf;border:1px dashed #7dd3fc99;border-radius:999px;padding:2px 10px;font-size:11px;transition:border-color .12s,color .12s,background .12s,box-shadow .12s}.kz2Bea_summon:hover{color:#bae6fd;background:#0f172ae6;border-color:#7dd3fcf2}.kz2Bea_summon:active{color:#7dd3fc;border-color:#7dd3fccc}.kz2Bea_summon:focus-visible{outline:none;box-shadow:0 0 0 2px #38bdf8d9}@media (prefers-reduced-motion:reduce){.kz2Bea_bubble{opacity:1;animation:none}.kz2Bea_action,.kz2Bea_summon{transition:none}}";
+		const css$2 = ".kz2Bea_float{pointer-events:auto;-webkit-user-select:none;user-select:none;flex-direction:column;align-items:center;display:flex;position:fixed}.kz2Bea_sprite{image-rendering:auto;touch-action:none;position:relative}.kz2Bea_bubble{white-space:nowrap;color:#fff;pointer-events:none;border-radius:999px;margin-bottom:6px;padding:4px 10px;font-size:12px;line-height:1.4;animation:2.6s ease-out forwards kz2Bea_pet-bubble-pop;position:absolute;bottom:100%;box-shadow:0 2px 8px #00000040}.kz2Bea_bubblePet{background:#f472b6eb}.kz2Bea_bubbleFeed{background:#38bdf8eb}.kz2Bea_bubbleStatus{text-overflow:ellipsis;background:#0f172ae6;border:1px solid #7dd3fc80;max-width:min(280px,100vw - 24px);animation:none;overflow:hidden}.kz2Bea_bubbleStack{pointer-events:auto;flex-direction:column;align-items:center;gap:4px;display:flex;position:absolute;bottom:100%}.kz2Bea_bubbleStack .kz2Bea_bubble{pointer-events:auto;margin-bottom:0;position:relative;bottom:auto}.kz2Bea_bubbleClickable{cursor:pointer;font:inherit;text-align:center;appearance:none;transition:filter .12s,box-shadow .12s}.kz2Bea_bubbleClickable:hover{filter:brightness(1.12)}.kz2Bea_bubbleClickable:focus-visible{outline:none;box-shadow:0 0 0 2px #38bdf8d9}@keyframes kz2Bea_pet-bubble-pop{0%{opacity:0;transform:translateY(6px)scale(.85)}15%{opacity:1;transform:translateY(0)scale(1.05)}25%{transform:translateY(0)scale(1)}75%{opacity:1}to{opacity:0;transform:translateY(-8px)scale(.95)}}.kz2Bea_panel{color:#e2e8f0;backdrop-filter:blur(6px);background:#0f172aeb;border:1px solid #94a3b859;border-radius:10px;flex-direction:column;gap:6px;min-width:132px;margin-right:8px;padding:8px 10px;font-size:12px;display:flex;position:absolute;bottom:0;right:100%;box-shadow:0 4px 16px #00000059}.kz2Bea_panel:after{content:\"\";width:14px;position:absolute;top:0;bottom:0;left:100%}.kz2Bea_rankRow{white-space:nowrap;justify-content:space-between;gap:10px;display:flex}.kz2Bea_nameCell{font-weight:600}.kz2Bea_renameRow{align-items:center;gap:6px;display:flex}.kz2Bea_nameInput{color:#e2e8f0;background:#1e293be6;border:1px solid #7dd3fc80;border-radius:6px;outline:none;flex:1;min-width:0;padding:3px 6px;font-size:12px}.kz2Bea_nameInput:focus{border-color:#38bdf8;box-shadow:0 0 0 2px #38bdf873}.kz2Bea_actions{gap:6px;display:flex}.kz2Bea_action{cursor:pointer;color:#0f172a;background:linear-gradient(#7dd3fc,#38bdf8);border:none;border-radius:6px;flex:1;padding:4px 8px;font-size:12px;transition:filter .12s,box-shadow .12s}.kz2Bea_action:hover{filter:brightness(1.08)}.kz2Bea_action:active{filter:brightness(.94)}.kz2Bea_action:focus-visible{outline:none;box-shadow:0 0 0 2px #38bdf8d9}.kz2Bea_summon{color:#7dd3fc;cursor:pointer;background:#0f172abf;border:1px dashed #7dd3fc99;border-radius:999px;padding:2px 10px;font-size:11px;transition:border-color .12s,color .12s,background .12s,box-shadow .12s}.kz2Bea_summon:hover{color:#bae6fd;background:#0f172ae6;border-color:#7dd3fcf2}.kz2Bea_summon:active{color:#7dd3fc;border-color:#7dd3fccc}.kz2Bea_summon:focus-visible{outline:none;box-shadow:0 0 0 2px #38bdf8d9}@media (prefers-reduced-motion:reduce){.kz2Bea_bubble{opacity:1;animation:none}.kz2Bea_action,.kz2Bea_summon{transition:none}}";
 		const tagId$2 = "@linxin666/dsh-pet/pet.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$2) + "]") === null) {
 			const tag = document.createElement("style");
@@ -120,6 +134,7 @@ window.__ModuleLoader__.load({
 			"action": "kz2Bea_action",
 			"actions": "kz2Bea_actions",
 			"bubble": "kz2Bea_bubble",
+			"bubbleClickable": "kz2Bea_bubbleClickable",
 			"bubbleFeed": "kz2Bea_bubbleFeed",
 			"bubblePet": "kz2Bea_bubblePet",
 			"bubbleStack": "kz2Bea_bubbleStack",
@@ -195,7 +210,8 @@ window.__ModuleLoader__.load({
 			(0, react.useEffect)(() => {
 				const reduceMotion = typeof window !== "undefined" && window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true;
 				const row = rowOfTrack(animation);
-				const leadCol = trimTrack(tracks[animation], rows[row] ?? tracks[animation].frames.length).frames[0];
+				const track = trimTrack(tracks[animation], rows[row] ?? tracks[animation].frames.length);
+				const leadCol = track.frames[0];
 				const lead = framePosition(cell, columns, row, leadCol, scaleRef.current);
 				if (spriteRef.current !== null) spriteRef.current.style.backgroundPosition = lead.x + "px " + lead.y + "px";
 				if (reduceMotion) return;
@@ -204,8 +220,6 @@ window.__ModuleLoader__.load({
 				const tick = (ts) => {
 					const delta = ts - last;
 					last = ts;
-					const row = rowOfTrack(animation);
-					const track = trimTrack(tracks[animation], rows[row] ?? tracks[animation].frames.length);
 					const st = frameRef.current;
 					if (st.track !== animation) {
 						st.track = animation;
@@ -290,7 +304,7 @@ window.__ModuleLoader__.load({
 			const spriteWidth = Math.round(cell.width * spriteScale);
 			const spriteHeight = Math.round(cell.height * spriteScale);
 			const sessionBubbles = snapshot?.sessions ?? [];
-			const statusBubble = feedback === null && !hovered && sessionBubbles.length === 0 ? snapshot?.bubble : void 0;
+			const statusBubble = feedback === null && sessionBubbles.length === 0 ? snapshot?.bubble : void 0;
 			const displayName = snapshot?.name ?? definition.displayName;
 			return (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				ref: floatRef,
@@ -337,12 +351,15 @@ window.__ModuleLoader__.load({
 						className: clsx(pet_module_css_default.bubble, feedback.kind === "feed" ? pet_module_css_default.bubbleFeed : pet_module_css_default.bubblePet),
 						children: feedback.text
 					}, feedback.at),
-					feedback === null && !hovered && sessionBubbles.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					feedback === null && sessionBubbles.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 						className: pet_module_css_default.bubbleStack,
-						role: "status",
-						"aria-live": "polite",
-						children: sessionBubbles.map((session) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: clsx(pet_module_css_default.bubble, pet_module_css_default.bubbleStatus),
+						children: sessionBubbles.map((session) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							type: "button",
+							className: clsx(pet_module_css_default.bubble, pet_module_css_default.bubbleStatus, pet_module_css_default.bubbleClickable),
+							title: props.t("pet.openSessionHint"),
+							onClick: () => {
+								props.onOpenSession(session.sessionId);
+							},
 							children: session.bubble
 						}, session.sessionId))
 					}),
@@ -481,6 +498,7 @@ window.__ModuleLoader__.load({
 					onHide: props.hide,
 					onDragEnd: props.dragEnd,
 					onRename: props.rename,
+					onOpenSession: props.openSession,
 					onFeedbackDone: props.feedbackDone,
 					t: props.t
 				})
@@ -1346,6 +1364,7 @@ window.__ModuleLoader__.load({
 			"pet.treats": "小鱼干 ×{n}",
 			"pet.state.loading": "宠物正在赶来…",
 			"pet.state.error": "宠物迷路了（连接失败）",
+			"pet.openSessionHint": "点击跳转到对应会话",
 			"settings.title": "宠物",
 			"settings.description": "选择宠物并调整它的显示布局。",
 			"settings.pet": "宠物",
@@ -1389,6 +1408,7 @@ window.__ModuleLoader__.load({
 			"pet.treats": "Treats ×{n}",
 			"pet.state.loading": "The pet is on its way…",
 			"pet.state.error": "The pet is lost (connection failed)",
+			"pet.openSessionHint": "Click to jump to this session",
 			"settings.title": "Pet",
 			"settings.description": "Pick a pet and tune its display layout.",
 			"settings.pet": "Pet",
@@ -1467,13 +1487,14 @@ window.__ModuleLoader__.load({
 		const POLL_MS = 2e3;
 		/** Settings namespace the pet settings card edits (the Host plugin registers it). */
 		const PET_SETTINGS_NS = "pet";
-		/** Required services. */
+		/** Required services (sessions powers bubble-to-session navigation). */
 		const inject = [
 			"slots",
 			"locale",
 			"connection",
 			"settingsScope",
-			"remote"
+			"remote",
+			"sessions"
 		];
 		/**
 		* Client plugin body: register dictionaries, mount the global pet entry and
@@ -1515,14 +1536,19 @@ window.__ModuleLoader__.load({
 					const setState = petStore.actions.setState;
 					const setFeedback = petStore.actions.setFeedback;
 					let petsLoaded = false;
+					let stateSeq = 0;
 					const pollNow = () => {
 						if (!petsLoaded) petApi.pets().then((list) => {
 							petsLoaded = true;
 							setPets(list);
 						}, () => {});
+						const seq = stateSeq + 1;
+						stateSeq = seq;
 						petApi.state().then((snapshot) => {
+							if (seq !== stateSeq) return;
 							setSnapshot(snapshot);
 						}, () => {
+							if (seq !== stateSeq) return;
 							setState("error", "pet.state transport error");
 						});
 					};
@@ -1550,9 +1576,15 @@ window.__ModuleLoader__.load({
 							document.removeEventListener("visibilitychange", onVisibility);
 						};
 					}, "pet: poll");
+					const sessions = ctx.sessions;
+					const openSession = (sessionId) => {
+						if (sessions.list.getSnapshot().byId[sessionId] === void 0) return;
+						sessions.open(sessionId);
+					};
 					const injected = () => ({
 						store: petStore,
 						ensure: pollNow,
+						openSession,
 						pet: () => {
 							petApi.interact("pet").then((result) => {
 								setFeedback({