From 5d18fb7b02254287660e718f9afa767d8ddd8bf1 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 16:57:17 +0800
Subject: [PATCH 01/19] feat(desktop-shell-ball): add bubble message feed
 contract

---
 .../features/shell-ball/shellBall.bubble.ts   | 14 ++++++
 .../shell-ball/shellBall.contract.test.ts     | 48 +++++++++++++++++++
 .../shell-ball/shellBall.windowSync.ts        |  5 ++
 3 files changed, 67 insertions(+)
 create mode 100644 apps/desktop/src/features/shell-ball/shellBall.bubble.ts

diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
new file mode 100644
index 000000000..ad6fcf187
--- /dev/null
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -0,0 +1,14 @@
+export type ShellBallBubbleMessageRole = "assistant" | "user" | "system";
+
+export type ShellBallBubbleMessageFreshnessHint = "fresh" | "stale";
+
+export type ShellBallBubbleMessageMotionHint = "pulse" | "settle";
+
+export type ShellBallBubbleMessage = {
+  id: string;
+  role: ShellBallBubbleMessageRole;
+  text: string;
+  createdAt: string;
+  freshnessHint?: ShellBallBubbleMessageFreshnessHint;
+  motionHint?: ShellBallBubbleMessageMotionHint;
+};
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index a150cadd6..b52f65e7d 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -53,6 +53,7 @@ import {
   getShellBallHelperWindowVisibility,
   shellBallWindowSyncEvents,
 } from "./shellBall.windowSync";
+import type { ShellBallBubbleMessage } from "./shellBall.bubble";
 import {
   SHELL_BALL_WINDOW_GAP_PX,
   SHELL_BALL_WINDOW_SAFE_MARGIN_PX,
@@ -1042,12 +1043,32 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
       visualState: "voice_locked",
       inputValue: "draft",
       voicePreview: "lock",
+      bubbleMessages: [
+        {
+          id: "msg-1",
+          role: "assistant",
+          text: "Still listening.",
+          createdAt: "2026-04-11T10:00:00.000Z",
+          freshnessHint: "fresh",
+          motionHint: "pulse",
+        },
+      ],
     }),
     {
       visualState: "voice_locked",
       inputBarMode: "voice",
       inputValue: "draft",
       voicePreview: "lock",
+      bubbleMessages: [
+        {
+          id: "msg-1",
+          role: "assistant",
+          text: "Still listening.",
+          createdAt: "2026-04-11T10:00:00.000Z",
+          freshnessHint: "fresh",
+          motionHint: "pulse",
+        },
+      ],
       visibility: {
         bubble: true,
         input: true,
@@ -1056,6 +1077,33 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
   );
 });
 
+test("shell-ball bubble message contract supports local bubble feed hints", () => {
+  const bubbleMessage: ShellBallBubbleMessage = {
+    id: "msg-local-1",
+    role: "user",
+    text: "Open the dashboard.",
+    createdAt: "2026-04-11T10:00:00.000Z",
+    freshnessHint: "stale",
+    motionHint: "settle",
+  };
+
+  assert.deepEqual(bubbleMessage, {
+    id: "msg-local-1",
+    role: "user",
+    text: "Open the dashboard.",
+    createdAt: "2026-04-11T10:00:00.000Z",
+    freshnessHint: "stale",
+    motionHint: "settle",
+  });
+
+  assert.deepEqual(createShellBallWindowSnapshot({
+    visualState: "idle",
+    inputValue: "",
+    voicePreview: null,
+    bubbleMessages: [],
+  }).bubbleMessages, []);
+});
+
 test("shell-ball window metrics compute safe frames and helper anchors", () => {
   assert.equal(SHELL_BALL_WINDOW_GAP_PX, 12);
   assert.equal(SHELL_BALL_WINDOW_SAFE_MARGIN_PX, 12);
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index 3c3aabbf2..8cae776a2 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -1,3 +1,4 @@
+import type { ShellBallBubbleMessage } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import { getShellBallInputBarMode } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
@@ -26,6 +27,7 @@ export type ShellBallWindowSnapshot = {
   inputBarMode: ShellBallInputBarMode;
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
+  bubbleMessages: ShellBallBubbleMessage[];
   visibility: ShellBallHelperWindowVisibility;
 };
 
@@ -79,12 +81,14 @@ export function createShellBallWindowSnapshot(input: {
   visualState: ShellBallVisualState;
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
+  bubbleMessages?: ShellBallBubbleMessage[];
 }): ShellBallWindowSnapshot {
   return {
     visualState: input.visualState,
     inputBarMode: getShellBallInputBarMode(input.visualState),
     inputValue: input.inputValue,
     voicePreview: input.voicePreview,
+    bubbleMessages: input.bubbleMessages ?? [],
     visibility: getShellBallHelperWindowVisibility(input.visualState),
   };
 }
@@ -94,5 +98,6 @@ export function createDefaultShellBallWindowSnapshot(): ShellBallWindowSnapshot
     visualState: "idle",
     inputValue: "",
     voicePreview: null,
+    bubbleMessages: [],
   });
 }

From 2da1079aa04efa85d2b8cef75680113f01954954 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 16:58:51 +0800
Subject: [PATCH 02/19] fix(desktop-shell-ball): align bubble message roles

---
 apps/desktop/src/features/shell-ball/shellBall.bubble.ts      | 2 +-
 .../src/features/shell-ball/shellBall.contract.test.ts        | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
index ad6fcf187..a01909af7 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -1,4 +1,4 @@
-export type ShellBallBubbleMessageRole = "assistant" | "user" | "system";
+export type ShellBallBubbleMessageRole = "user" | "agent";
 
 export type ShellBallBubbleMessageFreshnessHint = "fresh" | "stale";
 
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index b52f65e7d..c5b42d7ed 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -1046,7 +1046,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
       bubbleMessages: [
         {
           id: "msg-1",
-          role: "assistant",
+          role: "agent",
           text: "Still listening.",
           createdAt: "2026-04-11T10:00:00.000Z",
           freshnessHint: "fresh",
@@ -1062,7 +1062,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
       bubbleMessages: [
         {
           id: "msg-1",
-          role: "assistant",
+          role: "agent",
           text: "Still listening.",
           createdAt: "2026-04-11T10:00:00.000Z",
           freshnessHint: "fresh",

From cb45e060e4bcade54b02ce77e754e12a8aefd5a4 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:02:46 +0800
Subject: [PATCH 03/19] fix(desktop-shell-ball): copy bubble snapshot messages

---
 .../features/shell-ball/shellBall.bubble.ts   |  4 ++
 .../shell-ball/shellBall.contract.test.ts     | 51 +++++++++++++++++++
 .../shell-ball/shellBall.windowSync.ts        |  3 +-
 3 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
index a01909af7..894e509ec 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -12,3 +12,7 @@ export type ShellBallBubbleMessage = {
   freshnessHint?: ShellBallBubbleMessageFreshnessHint;
   motionHint?: ShellBallBubbleMessageMotionHint;
 };
+
+export function cloneShellBallBubbleMessages(messages: ShellBallBubbleMessage[]): ShellBallBubbleMessage[] {
+  return [...messages];
+}
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index c5b42d7ed..71ee137cb 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -1102,6 +1102,57 @@ test("shell-ball bubble message contract supports local bubble feed hints", () =
     voicePreview: null,
     bubbleMessages: [],
   }).bubbleMessages, []);
+
+  const minimalBubbleMessage: ShellBallBubbleMessage = {
+    id: "msg-local-2",
+    role: "agent",
+    text: "On it.",
+    createdAt: "2026-04-11T10:01:00.000Z",
+  };
+
+  assert.deepEqual(minimalBubbleMessage, {
+    id: "msg-local-2",
+    role: "agent",
+    text: "On it.",
+    createdAt: "2026-04-11T10:01:00.000Z",
+  });
+});
+
+test("shell-ball window snapshot copies bubble message arrays defensively", () => {
+  const sourceMessages: ShellBallBubbleMessage[] = [
+    {
+      id: "msg-copy-1",
+      role: "agent",
+      text: "Drafting update.",
+      createdAt: "2026-04-11T10:02:00.000Z",
+    },
+  ];
+
+  const snapshot = createShellBallWindowSnapshot({
+    visualState: "hover_input",
+    inputValue: "draft",
+    voicePreview: null,
+    bubbleMessages: sourceMessages,
+  });
+
+  assert.notEqual(snapshot.bubbleMessages, sourceMessages);
+  assert.deepEqual(snapshot.bubbleMessages, sourceMessages);
+
+  sourceMessages.push({
+    id: "msg-copy-2",
+    role: "user",
+    text: "Keep going.",
+    createdAt: "2026-04-11T10:03:00.000Z",
+  });
+
+  assert.deepEqual(snapshot.bubbleMessages, [
+    {
+      id: "msg-copy-1",
+      role: "agent",
+      text: "Drafting update.",
+      createdAt: "2026-04-11T10:02:00.000Z",
+    },
+  ]);
 });
 
 test("shell-ball window metrics compute safe frames and helper anchors", () => {
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index 8cae776a2..af413b6f8 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -1,3 +1,4 @@
+import { cloneShellBallBubbleMessages } from "./shellBall.bubble";
 import type { ShellBallBubbleMessage } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import { getShellBallInputBarMode } from "./shellBall.interaction";
@@ -88,7 +89,7 @@ export function createShellBallWindowSnapshot(input: {
     inputBarMode: getShellBallInputBarMode(input.visualState),
     inputValue: input.inputValue,
     voicePreview: input.voicePreview,
-    bubbleMessages: input.bubbleMessages ?? [],
+    bubbleMessages: cloneShellBallBubbleMessages(input.bubbleMessages ?? []),
     visibility: getShellBallHelperWindowVisibility(input.visualState),
   };
 }

From b1e6855f666a91d767366e025277623f5e79cedc Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:07:05 +0800
Subject: [PATCH 04/19] feat(desktop-shell-ball): sync bubble messages to
 helper window

---
 .../shell-ball/ShellBallBubbleWindow.tsx      |   2 +-
 .../components/ShellBallBubbleZone.tsx        |   2 +
 .../shell-ball/shellBall.contract.test.ts     | 171 ++++++++++++++++++
 .../shell-ball/useShellBallCoordinator.ts     |  17 ++
 4 files changed, 191 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
index 7cbc29c71..68626afdc 100644
--- a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
+++ b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
@@ -17,7 +17,7 @@ export function ShellBallBubbleWindow({ visualState }: ShellBallBubbleWindowProp
 
   return (
     <div ref={rootRef} className="shell-ball-window shell-ball-window--bubble" aria-label="Shell-ball bubble window">
-      <ShellBallBubbleZone visualState={resolvedVisualState} />
+      <ShellBallBubbleZone visualState={resolvedVisualState} bubbleMessages={snapshot.bubbleMessages} />
     </div>
   );
 }
diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
index ed67a0821..c40e9ca22 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
@@ -1,7 +1,9 @@
+import type { ShellBallBubbleMessage } from "../shellBall.bubble";
 import type { ShellBallVisualState } from "../shellBall.types";
 
 type ShellBallBubbleZoneProps = {
   visualState: ShellBallVisualState;
+  bubbleMessages?: ShellBallBubbleMessage[];
 };
 
 export function ShellBallBubbleZone({ visualState }: ShellBallBubbleZoneProps) {
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 71ee137cb..7075135ab 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -363,6 +363,47 @@ function withDesktopAliasRuntime<T>(callback: () => T) {
   }
 }
 
+function withShellBallModuleRuntime<T>(
+  moduleRelativePath: string,
+  mocks: Record<string, unknown>,
+  callback: (moduleExports: Record<string, unknown>) => T,
+) {
+  const NodeModule = require("node:module") as any;
+  const originalLoad = NodeModule._load;
+  const modulePath = resolve(desktopRoot, "src/features/shell-ball", moduleRelativePath);
+  const source = readFileSync(modulePath, "utf8");
+  const transpiledModule = { exports: {} as Record<string, unknown> };
+  const transpiled = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.ReactJSX,
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.ES2020,
+      esModuleInterop: true,
+    },
+    fileName: modulePath,
+  });
+  const moduleFactory = new Function("require", "module", "exports", transpiled.outputText) as (
+    require: NodeRequire,
+    module: { exports: Record<string, unknown> },
+    exports: Record<string, unknown>,
+  ) => void;
+
+  NodeModule._load = function loadShellBallModule(request: string, parent: unknown, isMain: boolean) {
+    if (request in mocks) {
+      return mocks[request];
+    }
+
+    return originalLoad(request, parent, isMain);
+  };
+
+  try {
+    moduleFactory(require, transpiledModule, transpiledModule.exports);
+    return callback(transpiledModule.exports);
+  } finally {
+    NodeModule._load = originalLoad;
+  }
+}
+
 function withTrayControllerRuntime<T>(
   openOrFocusDesktopWindow: (label: "dashboard" | "control-panel") => Promise<string>,
   callback: (mod: { openControlPanelFromTray: () => Promise<string>; calls: Array<"dashboard" | "control-panel"> }) => Promise<T> | T,
@@ -1927,6 +1968,136 @@ test("shell-ball bubble window owns the bubble zone rendering", () => {
   assert.doesNotMatch(markup, /shell-ball-input-bar/);
 });
 
+test("shell-ball coordinator snapshots carry shell-ball-local bubble messages", () => {
+  const { useShellBallCoordinator } = withShellBallModuleRuntime("useShellBallCoordinator.ts", {
+    react: {
+      useEffect() {},
+      useMemo<T>(factory: () => T) {
+        return factory();
+      },
+      useRef<T>(value: T) {
+        return { current: value };
+      },
+      useState<T>(value: T) {
+        return [typeof value === "function" ? (value as () => T)() : value, () => {}] as const;
+      },
+    },
+    "@tauri-apps/api/window": {
+      getCurrentWindow() {
+        return { label: shellBallWindowLabels.bubble };
+      },
+    },
+    "../../platform/shellBallWindowController": {
+      shellBallWindowLabels,
+    },
+    "./shellBall.windowSync": require(resolve(desktopRoot, ".cache/shell-ball-tests/features/shell-ball/shellBall.windowSync.js")),
+  }, (moduleExports) => moduleExports as { useShellBallCoordinator: typeof import("./useShellBallCoordinator").useShellBallCoordinator });
+
+  const { snapshot } = useShellBallCoordinator({
+    visualState: "hover_input",
+    inputValue: "draft",
+    voicePreview: null,
+    setInputValue: () => {},
+    onRegionEnter: () => {},
+    onRegionLeave: () => {},
+    onInputFocusChange: () => {},
+    onSubmitText: () => {},
+    onAttachFile: () => {},
+    onPrimaryClick: () => {},
+  });
+
+  assert.ok(Array.isArray(snapshot.bubbleMessages));
+  assert.ok(snapshot.bubbleMessages.length > 0);
+});
+
+test("shell-ball bubble window resolves bubble messages from the helper-window snapshot", () => {
+  const helperSnapshot = createShellBallWindowSnapshot({
+    visualState: "processing",
+    inputValue: "",
+    voicePreview: null,
+    bubbleMessages: [
+      {
+        id: "msg-helper-1",
+        role: "agent",
+        text: "Drafting your update.",
+        createdAt: "2026-04-11T10:04:00.000Z",
+      },
+    ],
+  });
+  let capturedProps: Record<string, unknown> | null = null;
+
+  const { ShellBallBubbleWindow: RuntimeShellBallBubbleWindow } = withShellBallModuleRuntime("ShellBallBubbleWindow.tsx", {
+    react: require("react"),
+    "./useShellBallCoordinator": {
+      useShellBallHelperWindowSnapshot() {
+        return helperSnapshot;
+      },
+    },
+    "./useShellBallWindowMetrics": {
+      useShellBallWindowMetrics() {
+        return { rootRef: null };
+      },
+    },
+    "./components/ShellBallBubbleZone": {
+      ShellBallBubbleZone(props: Record<string, unknown>) {
+        capturedProps = props;
+        return createElement("section", { className: "shell-ball-bubble-zone-stub" });
+      },
+    },
+  }, (moduleExports) => moduleExports as { ShellBallBubbleWindow: typeof import("./ShellBallBubbleWindow").ShellBallBubbleWindow });
+
+  renderToStaticMarkup(createElement(RuntimeShellBallBubbleWindow, null));
+
+  assert.deepEqual(capturedProps, {
+    visualState: "processing",
+    bubbleMessages: helperSnapshot.bubbleMessages,
+  });
+});
+
+test("shell-ball bubble window does not depend on only visualState to render its body", () => {
+  const helperSnapshot = createShellBallWindowSnapshot({
+    visualState: "idle",
+    inputValue: "",
+    voicePreview: null,
+    bubbleMessages: [
+      {
+        id: "msg-helper-2",
+        role: "user",
+        text: "Open the dashboard.",
+        createdAt: "2026-04-11T10:05:00.000Z",
+      },
+    ],
+  });
+  let capturedProps: Record<string, unknown> | null = null;
+
+  const { ShellBallBubbleWindow: RuntimeShellBallBubbleWindow } = withShellBallModuleRuntime("ShellBallBubbleWindow.tsx", {
+    react: require("react"),
+    "./useShellBallCoordinator": {
+      useShellBallHelperWindowSnapshot() {
+        return helperSnapshot;
+      },
+    },
+    "./useShellBallWindowMetrics": {
+      useShellBallWindowMetrics() {
+        return { rootRef: null };
+      },
+    },
+    "./components/ShellBallBubbleZone": {
+      ShellBallBubbleZone(props: Record<string, unknown>) {
+        capturedProps = props;
+        return createElement("section", { className: "shell-ball-bubble-zone-stub" });
+      },
+    },
+  }, (moduleExports) => moduleExports as { ShellBallBubbleWindow: typeof import("./ShellBallBubbleWindow").ShellBallBubbleWindow });
+
+  renderToStaticMarkup(createElement(RuntimeShellBallBubbleWindow, { visualState: "voice_locked" }));
+
+  assert.deepEqual(capturedProps, {
+    visualState: "voice_locked",
+    bubbleMessages: helperSnapshot.bubbleMessages,
+  });
+});
+
 test("shell-ball input window owns the input rendering", () => {
   const markup = renderToStaticMarkup(
     createElement(ShellBallInputWindow, {
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index c6eea7c78..d71f43acf 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { shellBallWindowLabels } from "../../platform/shellBallWindowController";
+import type { ShellBallBubbleMessage } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
 import {
@@ -33,6 +34,21 @@ type ShellBallHelperSnapshotInput = {
   role: ShellBallHelperWindowRole;
 };
 
+const SHELL_BALL_LOCAL_BUBBLE_MESSAGES: ShellBallBubbleMessage[] = [
+  {
+    id: "shell-ball-local-agent-1",
+    role: "agent",
+    text: "Drafting your update.",
+    createdAt: "2026-04-11T10:04:00.000Z",
+  },
+  {
+    id: "shell-ball-local-user-1",
+    role: "user",
+    text: "Open the dashboard.",
+    createdAt: "2026-04-11T10:05:00.000Z",
+  },
+];
+
 export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
   const snapshot = useMemo(
     () =>
@@ -40,6 +56,7 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
         visualState: input.visualState,
         inputValue: input.inputValue,
         voicePreview: input.voicePreview,
+        bubbleMessages: SHELL_BALL_LOCAL_BUBBLE_MESSAGES,
       }),
     [input.inputValue, input.visualState, input.voicePreview],
   );

From 927971b28bb3cea394ee3e02847660e4bb652f83 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:10:28 +0800
Subject: [PATCH 05/19] feat(desktop-shell-ball): render bubble message list

---
 .../components/ShellBallBubbleMessage.tsx     | 18 +++++++++++
 .../components/ShellBallBubbleZone.tsx        | 12 ++++---
 .../shell-ball/shellBall.contract.test.ts     | 32 +++++++++++++++++++
 3 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx

diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
new file mode 100644
index 000000000..1f6bf81f2
--- /dev/null
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
@@ -0,0 +1,18 @@
+import type { ShellBallBubbleMessage as ShellBallBubbleMessageModel } from "../shellBall.bubble";
+
+type ShellBallBubbleMessageProps = {
+  message: ShellBallBubbleMessageModel;
+};
+
+export function ShellBallBubbleMessage({ message }: ShellBallBubbleMessageProps) {
+  return (
+    <div
+      className={`shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--${message.role}`}
+      data-role={message.role}
+    >
+      <div className={`shell-ball-bubble-message shell-ball-bubble-message--${message.role}`} data-message-id={message.id}>
+        <p className="shell-ball-bubble-message__text">{message.text}</p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
index c40e9ca22..109378736 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
@@ -1,16 +1,20 @@
 import type { ShellBallBubbleMessage } from "../shellBall.bubble";
 import type { ShellBallVisualState } from "../shellBall.types";
+import { ShellBallBubbleMessage as ShellBallBubbleMessageView } from "./ShellBallBubbleMessage";
 
 type ShellBallBubbleZoneProps = {
   visualState: ShellBallVisualState;
   bubbleMessages?: ShellBallBubbleMessage[];
 };
 
-export function ShellBallBubbleZone({ visualState }: ShellBallBubbleZoneProps) {
+export function ShellBallBubbleZone({ visualState, bubbleMessages = [] }: ShellBallBubbleZoneProps) {
   return (
-    <section className="shell-ball-bubble-zone" data-state={visualState} aria-hidden="true">
-      <div className="shell-ball-bubble-zone__shell" />
-      <div className="shell-ball-bubble-zone__shell shell-ball-bubble-zone__shell--secondary" />
+    <section className="shell-ball-bubble-zone" data-state={visualState}>
+      <div className="shell-ball-bubble-zone__scroll">
+        {bubbleMessages.map((message) => (
+          <ShellBallBubbleMessageView key={message.id} message={message} />
+        ))}
+      </div>
     </section>
   );
 }
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 7075135ab..b5dcc8171 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -32,6 +32,7 @@ import { ShellBallBubbleWindow } from "./ShellBallBubbleWindow";
 import { ShellBallDevLayer } from "./ShellBallDevLayer";
 import { ShellBallInputWindow } from "./ShellBallInputWindow";
 import { ShellBallMascot } from "./components/ShellBallMascot";
+import { ShellBallBubbleZone } from "./components/ShellBallBubbleZone";
 import { getShellBallMascotHotspotGestureAction } from "./components/ShellBallMascot";
 import { getShellBallMascotPointerPhaseAction } from "./components/ShellBallMascot";
 import { shouldStartShellBallMascotWindowDrag } from "./components/ShellBallMascot";
@@ -2098,6 +2099,37 @@ test("shell-ball bubble window does not depend on only visualState to render its
   });
 });
 
+test("shell-ball bubble zone renders a real message list without placeholder chrome", () => {
+  const markup = renderToStaticMarkup(
+    createElement(ShellBallBubbleZone, {
+      visualState: "processing",
+      bubbleMessages: [
+        {
+          id: "msg-agent-1",
+          role: "agent",
+          text: "I found the latest dashboard status.",
+          createdAt: "2026-04-11T10:06:00.000Z",
+        },
+        {
+          id: "msg-user-1",
+          role: "user",
+          text: "Open it for me.",
+          createdAt: "2026-04-11T10:06:05.000Z",
+        },
+      ] satisfies ShellBallBubbleMessage[],
+    }),
+  );
+
+  assert.match(markup, /I found the latest dashboard status\./);
+  assert.match(markup, /Open it for me\./);
+  assert.match(markup, /shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--agent/);
+  assert.match(markup, /shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--user/);
+  assert.doesNotMatch(markup, /shell-ball-bubble-zone__shell/);
+  assert.doesNotMatch(markup, /<header/);
+  assert.doesNotMatch(markup, /<input/);
+  assert.doesNotMatch(markup, /toolbar/i);
+});
+
 test("shell-ball input window owns the input rendering", () => {
   const markup = renderToStaticMarkup(
     createElement(ShellBallInputWindow, {

From 8664b4bfa8134e0270da47f1bd50bcb4ad99d269 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:15:37 +0800
Subject: [PATCH 06/19] feat(desktop-shell-ball): style transparent bubble
 history window

---
 .../components/ShellBallBubbleZone.tsx        |   9 +-
 .../shell-ball/shellBall.contract.test.ts     |  33 +++++
 .../src/features/shell-ball/shellBall.css     | 125 ++++++++++++------
 3 files changed, 127 insertions(+), 40 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
index 109378736..ad9b648f4 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
@@ -12,7 +12,14 @@ export function ShellBallBubbleZone({ visualState, bubbleMessages = [] }: ShellB
     <section className="shell-ball-bubble-zone" data-state={visualState}>
       <div className="shell-ball-bubble-zone__scroll">
         {bubbleMessages.map((message) => (
-          <ShellBallBubbleMessageView key={message.id} message={message} />
+          <div
+            key={message.id}
+            className="shell-ball-bubble-zone__message-entry"
+            data-freshness={message.freshnessHint ?? "stale"}
+            data-motion={message.motionHint ?? "settle"}
+          >
+            <ShellBallBubbleMessageView message={message} />
+          </div>
         ))}
       </div>
     </section>
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index b5dcc8171..e87dadf68 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -2130,6 +2130,39 @@ test("shell-ball bubble zone renders a real message list without placeholder chr
   assert.doesNotMatch(markup, /toolbar/i);
 });
 
+test("shell-ball bubble window styles stay transparent, faded, and motion-ready", () => {
+  const shellBallStyles = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.css"), "utf8");
+  const markup = renderToStaticMarkup(
+    createElement(ShellBallBubbleZone, {
+      visualState: "processing",
+      bubbleMessages: [
+        {
+          id: "msg-style-1",
+          role: "agent",
+          text: "Draft ready.",
+          createdAt: "2026-04-11T10:07:00.000Z",
+          freshnessHint: "fresh",
+          motionHint: "settle",
+        },
+      ] satisfies ShellBallBubbleMessage[],
+    }),
+  );
+
+  assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*background:\s*transparent;/);
+  assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*border:\s*0;/);
+  assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*box-shadow:\s*none;/);
+  assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*scrollbar-width:\s*none;/);
+  assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll::-webkit-scrollbar\s*\{[\s\S]*display:\s*none;/);
+  assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*mask-image:\s*linear-gradient\(/);
+  assert.match(shellBallStyles, /@keyframes shell-ball-bubble-message-enter/);
+  assert.match(
+    shellBallStyles,
+    /\.shell-ball-bubble-zone__message-entry\[data-freshness="fresh"\]\[data-motion="settle"\]\s*\{[\s\S]*animation:\s*shell-ball-bubble-message-enter/,
+  );
+  assert.match(markup, /data-freshness="fresh"/);
+  assert.match(markup, /data-motion="settle"/);
+});
+
 test("shell-ball input window owns the input rendering", () => {
   const markup = renderToStaticMarkup(
     createElement(ShellBallInputWindow, {
diff --git a/apps/desktop/src/features/shell-ball/shellBall.css b/apps/desktop/src/features/shell-ball/shellBall.css
index f1fbc2816..3915b5423 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.css
+++ b/apps/desktop/src/features/shell-ball/shellBall.css
@@ -4,6 +4,13 @@
   width: max-content;
 }
 
+.shell-ball-window--bubble {
+  background: transparent;
+  border: 0;
+  box-shadow: none;
+  padding: 0;
+}
+
 .shell-ball-surface {
   --shell-ball-paper: rgba(255, 251, 244, 0.88);
   --shell-ball-paper-strong: rgba(255, 253, 249, 0.96);
@@ -83,56 +90,81 @@
 
 .shell-ball-bubble-zone {
   --shell-ball-bubble-accent: rgba(106, 145, 200, 0.18);
-  align-items: end;
+  align-items: stretch;
   display: grid;
-  justify-items: center;
+  justify-items: stretch;
   min-height: clamp(5.25rem, 12vw, 8.5rem);
-  padding: 0.4rem 0.25rem 0;
-  pointer-events: none;
+  padding: 0;
+  pointer-events: auto;
   position: relative;
-  width: max-content;
+  width: min(22rem, calc(100vw - 1rem));
 }
 
 .shell-ball-bubble-zone::before {
-  background: linear-gradient(180deg, rgba(255, 255, 255, 0.26), rgba(255, 255, 255, 0));
-  border-radius: 999px;
-  content: "";
-  filter: blur(16px);
-  height: clamp(2.8rem, 7vw, 4.2rem);
-  inset: auto 14% 0;
-  opacity: 0.75;
-  position: absolute;
+  content: none;
 }
 
-.shell-ball-bubble-zone__shell {
-  background:
-    linear-gradient(180deg, rgba(255, 255, 255, 0.54), rgba(255, 255, 255, 0.14)),
-    rgba(255, 251, 245, 0.2);
-  border: 1px dashed rgba(138, 125, 106, 0.22);
-  border-radius: 999px;
-  box-shadow:
-    0 18px 34px -30px rgba(82, 74, 62, 0.28),
-    0 1px 0 rgba(255, 255, 255, 0.54) inset;
-  height: clamp(2.4rem, 5vw, 3.2rem);
-  opacity: 0.72;
-  position: relative;
-  width: clamp(10rem, 18vw, 13rem);
+.shell-ball-bubble-zone__scroll {
+  display: grid;
+  gap: 0.5rem;
+  max-height: clamp(6.5rem, 28vh, 14rem);
+  overflow: hidden auto;
+  overscroll-behavior: contain;
+  padding: 0.85rem 0.2rem;
+  scrollbar-width: none;
+  -webkit-mask-image: linear-gradient(180deg, transparent 0, #000 12%, #000 88%, transparent 100%);
+  mask-image: linear-gradient(180deg, transparent 0, #000 12%, #000 88%, transparent 100%);
+  width: 100%;
 }
 
-.shell-ball-bubble-zone__shell::after {
-  background: linear-gradient(90deg, transparent, var(--shell-ball-bubble-accent), transparent);
-  border-radius: inherit;
-  content: "";
-  inset: 0.32rem;
-  opacity: 0.9;
-  position: absolute;
+.shell-ball-bubble-zone__scroll::-webkit-scrollbar {
+  display: none;
+}
+
+.shell-ball-bubble-zone__message-entry {
+  display: grid;
 }
 
-.shell-ball-bubble-zone__shell--secondary {
-  height: clamp(1.6rem, 3.5vw, 2rem);
-  margin-top: 0.65rem;
-  opacity: 0.5;
-  width: clamp(5rem, 9vw, 7rem);
+.shell-ball-bubble-zone__message-entry[data-freshness="fresh"][data-motion="settle"] {
+  animation: shell-ball-bubble-message-enter 220ms ease-out both;
+}
+
+.shell-ball-bubble-zone__message-row {
+  display: flex;
+  width: 100%;
+}
+
+.shell-ball-bubble-zone__message-row--agent {
+  justify-content: flex-start;
+}
+
+.shell-ball-bubble-zone__message-row--user {
+  justify-content: flex-end;
+}
+
+.shell-ball-bubble-message {
+  backdrop-filter: blur(12px);
+  border: 1px solid rgba(255, 255, 255, 0.32);
+  border-radius: 1.15rem;
+  box-shadow: 0 16px 28px -24px rgba(62, 56, 48, 0.34);
+  max-width: min(18rem, calc(100% - 2rem));
+  padding: 0.65rem 0.85rem;
+}
+
+.shell-ball-bubble-message--agent {
+  background: linear-gradient(180deg, rgba(255, 253, 249, 0.84), rgba(245, 238, 228, 0.7));
+}
+
+.shell-ball-bubble-message--user {
+  background: linear-gradient(180deg, rgba(125, 157, 200, 0.92), rgba(92, 123, 167, 0.86));
+  color: #f8fbff;
+}
+
+.shell-ball-bubble-message__text {
+  line-height: 1.45;
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
 }
 
 .shell-ball-bubble-zone[data-state="waiting_auth"] {
@@ -1030,6 +1062,18 @@
   }
 }
 
+@keyframes shell-ball-bubble-message-enter {
+  0% {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .shell-ball-mascot__float,
   .shell-ball-mascot__body-shell,
@@ -1049,7 +1093,9 @@
   .shell-ball-mascot__wing,
   .shell-ball-switcher__button,
   .shell-ball-input-bar,
-  .shell-ball-input-bar__action {
+  .shell-ball-input-bar__action,
+  .shell-ball-bubble-zone__message-entry[data-freshness="fresh"][data-motion="settle"] {
+    animation: none !important;
     transition-duration: 0.01ms;
   }
 
@@ -1087,6 +1133,7 @@
   .shell-ball-bubble-zone {
     min-height: 4.6rem;
     padding-inline: 0;
+    width: min(20rem, calc(100vw - 0.75rem));
   }
 
   .shell-ball-surface__body {

From b5def2ae04675fa2760c54a84297e5de2eb5bfa6 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:20:18 +0800
Subject: [PATCH 07/19] fix(desktop-shell-ball): tighten bubble style contract

---
 .../src/features/shell-ball/shellBall.bubble.ts    |  2 +-
 .../features/shell-ball/shellBall.contract.test.ts | 14 ++++++++++++--
 apps/desktop/src/features/shell-ball/shellBall.css |  5 +++--
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
index 894e509ec..49748e0a3 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -2,7 +2,7 @@ export type ShellBallBubbleMessageRole = "user" | "agent";
 
 export type ShellBallBubbleMessageFreshnessHint = "fresh" | "stale";
 
-export type ShellBallBubbleMessageMotionHint = "pulse" | "settle";
+export type ShellBallBubbleMessageMotionHint = "settle";
 
 export type ShellBallBubbleMessage = {
   id: string;
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index e87dadf68..fca56acc2 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -1092,7 +1092,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
           text: "Still listening.",
           createdAt: "2026-04-11T10:00:00.000Z",
           freshnessHint: "fresh",
-          motionHint: "pulse",
+          motionHint: "settle",
         },
       ],
     }),
@@ -1108,7 +1108,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
           text: "Still listening.",
           createdAt: "2026-04-11T10:00:00.000Z",
           freshnessHint: "fresh",
-          motionHint: "pulse",
+          motionHint: "settle",
         },
       ],
       visibility: {
@@ -1120,6 +1120,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
 });
 
 test("shell-ball bubble message contract supports local bubble feed hints", () => {
+  const bubbleContractSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.bubble.ts"), "utf8");
   const bubbleMessage: ShellBallBubbleMessage = {
     id: "msg-local-1",
     role: "user",
@@ -1137,6 +1138,7 @@ test("shell-ball bubble message contract supports local bubble feed hints", () =
     freshnessHint: "stale",
     motionHint: "settle",
   });
+  assert.doesNotMatch(bubbleContractSource, /"pulse"/);
 
   assert.deepEqual(createShellBallWindowSnapshot({
     visualState: "idle",
@@ -2124,7 +2126,12 @@ test("shell-ball bubble zone renders a real message list without placeholder chr
   assert.match(markup, /Open it for me\./);
   assert.match(markup, /shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--agent/);
   assert.match(markup, /shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--user/);
+  assert.match(
+    markup,
+    /<section class="shell-ball-bubble-zone" data-state="processing"><div class="shell-ball-bubble-zone__scroll"><div class="shell-ball-bubble-zone__message-entry"/,
+  );
   assert.doesNotMatch(markup, /shell-ball-bubble-zone__shell/);
+  assert.doesNotMatch(markup, /shell-ball-bubble-zone__panel|shell-ball-bubble-zone__frame|shell-ball-bubble-zone__card/);
   assert.doesNotMatch(markup, /<header/);
   assert.doesNotMatch(markup, /<input/);
   assert.doesNotMatch(markup, /toolbar/i);
@@ -2151,6 +2158,9 @@ test("shell-ball bubble window styles stay transparent, faded, and motion-ready"
   assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*background:\s*transparent;/);
   assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*border:\s*0;/);
   assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*box-shadow:\s*none;/);
+  assert.match(shellBallStyles, /--shell-ball-helper-width:\s*min\(22rem, calc\(100vw - 1rem\)\);/);
+  assert.match(shellBallStyles, /\.shell-ball-bubble-zone\s*\{[\s\S]*width:\s*var\(--shell-ball-helper-width\);/);
+  assert.match(shellBallStyles, /\.shell-ball-input-bar,\s*\.shell-ball-input-bar--hidden\s*\{[\s\S]*width:\s*var\(--shell-ball-helper-width\);/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*scrollbar-width:\s*none;/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll::-webkit-scrollbar\s*\{[\s\S]*display:\s*none;/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*mask-image:\s*linear-gradient\(/);
diff --git a/apps/desktop/src/features/shell-ball/shellBall.css b/apps/desktop/src/features/shell-ball/shellBall.css
index 3915b5423..e64d7a30e 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.css
+++ b/apps/desktop/src/features/shell-ball/shellBall.css
@@ -1,4 +1,5 @@
 .shell-ball-window {
+  --shell-ball-helper-width: min(22rem, calc(100vw - 1rem));
   display: grid;
   justify-items: center;
   width: max-content;
@@ -97,7 +98,7 @@
   padding: 0;
   pointer-events: auto;
   position: relative;
-  width: min(22rem, calc(100vw - 1rem));
+  width: var(--shell-ball-helper-width);
 }
 
 .shell-ball-bubble-zone::before {
@@ -208,7 +209,7 @@
 
 .shell-ball-input-bar,
 .shell-ball-input-bar--hidden {
-  width: min(22rem, calc(100vw - 1rem));
+  width: var(--shell-ball-helper-width);
 }
 
 .shell-ball-input-bar {

From 3cea33c5e13d93d347c649b75127d892457a327a Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:23:23 +0800
Subject: [PATCH 08/19] fix(desktop-shell-ball): unify helper width override

---
 .../src/features/shell-ball/shellBall.contract.test.ts     | 7 +++++++
 apps/desktop/src/features/shell-ball/shellBall.css         | 5 ++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index fca56acc2..039bc3cb3 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -2139,6 +2139,9 @@ test("shell-ball bubble zone renders a real message list without placeholder chr
 
 test("shell-ball bubble window styles stay transparent, faded, and motion-ready", () => {
   const shellBallStyles = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.css"), "utf8");
+  const mobileBubbleZoneBlock = shellBallStyles.match(
+    /@media \(max-width: 720px\)\s*\{[\s\S]*?(\.shell-ball-bubble-zone\s*\{[\s\S]*?\})/,
+  )?.[1] ?? "";
   const markup = renderToStaticMarkup(
     createElement(ShellBallBubbleZone, {
       visualState: "processing",
@@ -2159,8 +2162,12 @@ test("shell-ball bubble window styles stay transparent, faded, and motion-ready"
   assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*border:\s*0;/);
   assert.match(shellBallStyles, /\.shell-ball-window--bubble\s*\{[\s\S]*box-shadow:\s*none;/);
   assert.match(shellBallStyles, /--shell-ball-helper-width:\s*min\(22rem, calc\(100vw - 1rem\)\);/);
+  assert.match(shellBallStyles, /@media \(max-width: 720px\)\s*\{[\s\S]*--shell-ball-helper-width:\s*min\(20rem, calc\(100vw - 0\.75rem\)\);/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone\s*\{[\s\S]*width:\s*var\(--shell-ball-helper-width\);/);
   assert.match(shellBallStyles, /\.shell-ball-input-bar,\s*\.shell-ball-input-bar--hidden\s*\{[\s\S]*width:\s*var\(--shell-ball-helper-width\);/);
+  assert.match(mobileBubbleZoneBlock, /min-height:\s*4\.6rem;/);
+  assert.match(mobileBubbleZoneBlock, /padding-inline:\s*0;/);
+  assert.doesNotMatch(mobileBubbleZoneBlock, /width:/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*scrollbar-width:\s*none;/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll::-webkit-scrollbar\s*\{[\s\S]*display:\s*none;/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*mask-image:\s*linear-gradient\(/);
diff --git a/apps/desktop/src/features/shell-ball/shellBall.css b/apps/desktop/src/features/shell-ball/shellBall.css
index e64d7a30e..d889144da 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.css
+++ b/apps/desktop/src/features/shell-ball/shellBall.css
@@ -1127,6 +1127,10 @@
 }
 
 @media (max-width: 720px) {
+  .shell-ball-window {
+    --shell-ball-helper-width: min(20rem, calc(100vw - 0.75rem));
+  }
+
   .shell-ball-surface {
     padding: 0.75rem 0.55rem 0.9rem;
   }
@@ -1134,7 +1138,6 @@
   .shell-ball-bubble-zone {
     min-height: 4.6rem;
     padding-inline: 0;
-    width: min(20rem, calc(100vw - 0.75rem));
   }
 
   .shell-ball-surface__body {

From 43b4d79d75e8471469f93249317dd7f4ce17ee20 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:26:12 +0800
Subject: [PATCH 09/19] feat(desktop-shell-ball): add bubble window plan

---
 ...-ball-bubble-window-implementation-plan.md | 242 ++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 apps/desktop/docs/2026-04-11-shell-ball-bubble-window-implementation-plan.md

diff --git a/apps/desktop/docs/2026-04-11-shell-ball-bubble-window-implementation-plan.md b/apps/desktop/docs/2026-04-11-shell-ball-bubble-window-implementation-plan.md
new file mode 100644
index 000000000..896c7638a
--- /dev/null
+++ b/apps/desktop/docs/2026-04-11-shell-ball-bubble-window-implementation-plan.md
@@ -0,0 +1,242 @@
+# Shell-Ball Bubble Window Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Turn the shell-ball bubble window into a real transparent message stream that shows left/right chat bubbles, scrollable history, edge fade, and subtle new-message motion.
+
+**Architecture:** Keep the bubble window presentation-only and feed it with a shell-ball-local bubble message snapshot contract. The coordinator remains the source of truth for mock/live-ready bubble data, while the bubble window only renders the list, motion state, and scroll behavior without introducing protocol-layer coupling.
+
+**Tech Stack:** React 18, TypeScript, shell-ball window sync/coordinator layer, CSS animations, existing shell-ball contract test suite.
+
+---
+
+## File Map
+
+- Create: `apps/desktop/src/features/shell-ball/shellBall.bubble.ts`
+- Create: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.css`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+## Constraints
+
+- Bubble window only shows message bubbles; no title, caption, input bar, send area, card shell, border, backdrop panel, or window-level framing.
+- Bubble window background must remain transparent.
+- User messages align right; agent messages align left.
+- History scrolls upward; scrollbar stays hidden.
+- Top and bottom edges fade messages out with a transparent mask effect.
+- New messages enter with a light upward-float plus fade-in motion.
+- This iteration should be live-ready but still shell-ball-local: do not add `/packages/protocol` changes.
+
+### Task 1: Define Bubble Message Feed Contract
+
+**Files:**
+- Create: `apps/desktop/src/features/shell-ball/shellBall.bubble.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing contract test**
+
+Add tests asserting that the shell-ball bubble feed exposes a live-ready message model with:
+- `id`
+- `role` as `user` or `agent`
+- `text`
+- `createdAt`
+- an optional freshness/motion hint for new-message animation
+
+Also assert that the window snapshot shape includes a `bubbleMessages` array.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because no bubble feed contract exists yet.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `apps/desktop/src/features/shell-ball/shellBall.bubble.ts` with:
+- `ShellBallBubbleMessageRole`
+- `ShellBallBubbleMessage`
+- `createShellBallBubbleMessages(...)` or equivalent shell-ball-local mock/live-ready feed helper
+
+Update `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts` so the snapshot type includes `bubbleMessages`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for the bubble feed contract.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/shellBall.bubble.ts apps/desktop/src/features/shell-ball/shellBall.windowSync.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): add bubble message feed contract"
+```
+
+### Task 2: Feed Bubble Messages Through the Coordinator
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing contract test**
+
+Add tests asserting that:
+- the coordinator snapshot now carries `bubbleMessages`
+- `ShellBallBubbleWindow` resolves messages from the helper-window snapshot
+- the bubble window no longer depends on only `visualState` to render its body
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because the coordinator and bubble window do not move message arrays yet.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Update `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts` to include a shell-ball-local bubble message feed in every snapshot.
+
+Update `apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx` to read `snapshot.bubbleMessages` and pass them into the bubble zone.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for coordinator/bubble-window snapshot coverage.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): sync bubble messages to helper window"
+```
+
+### Task 3: Replace the Placeholder Bubble Zone With a Real Message List
+
+**Files:**
+- Create: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing render test**
+
+Add tests asserting that:
+- bubble zone renders message items instead of placeholder shells
+- `agent` messages align left
+- `user` messages align right
+- no title/input/toolbar text is rendered
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because the bubble zone still renders placeholder ellipses.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx` for one message bubble.
+
+Refactor `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx` to:
+- render a transparent scroll container
+- render only message bubbles
+- align left/right by `role`
+- remove the two placeholder shell bars
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for real message-list rendering.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): render bubble message list"
+```
+
+### Task 4: Style the Bubble Window for Transparent History, Hidden Scrollbars, Edge Fade, and New-Message Motion
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.css`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing style contract test**
+
+Add tests asserting that the bubble styles provide:
+- transparent container with no panel/card chrome
+- hidden scrollbars
+- top/bottom fade mask or equivalent edge fade treatment
+- new-message motion classes/data attributes for slight upward-float + fade-in
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because the current bubble CSS still targets placeholder shells.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Update `apps/desktop/src/features/shell-ball/shellBall.css` so the bubble window:
+- stays transparent
+- has no outer box/border/panel
+- hides scrollbars
+- applies a top/bottom fade mask
+- animates new messages with a light upward-float + fade-in
+
+Keep the motion subtle and preserve window sizing behavior.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for the bubble-window style contract.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/shellBall.css apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): style transparent bubble history window"
+```
+
+### Task 5: Verify Bubble Window Behavior End-to-End
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: Run shell-ball tests**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS.
+
+- [ ] **Step 2: Run typecheck**
+
+Run: `pnpm --dir apps/desktop typecheck`
+Expected: PASS.
+
+- [ ] **Step 3: Run build**
+
+Run: `pnpm --dir apps/desktop build`
+Expected: PASS.
+
+- [ ] **Step 4: Run the desktop app manually**
+
+Run: `pnpm --dir apps/desktop exec tauri dev`
+
+Expected:
+- bubble window shows only message bubbles
+- bubble background remains fully transparent
+- user bubbles are right-aligned
+- agent bubbles are left-aligned
+- older messages scroll upward
+- scrollbar stays hidden
+- top/bottom edges fade overflowing history
+- new incoming message uses subtle upward-float + fade-in
+
+- [ ] **Step 5: Commit only if manual verification required a follow-up fix**
+
+Run: `git status --short`
+Expected: clean working tree; if not, commit with:
+
+```bash
+git add <fixed-files>
+git commit -m "feat(desktop-shell-ball): polish bubble window motion and history"
+```

From 9d1966593962ef05f0d8b25dbda3a40b34ccf498 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 17:33:13 +0800
Subject: [PATCH 10/19] fix(desktop-shell-ball): anchor bubble feed to latest

---
 .../components/ShellBallBubbleZone.tsx        | 15 ++++-
 .../features/shell-ball/shellBall.bubble.ts   |  2 +-
 .../shell-ball/shellBall.contract.test.ts     | 67 +++++++++++++++++++
 .../src/features/shell-ball/shellBall.css     |  6 ++
 .../shell-ball/useShellBallCoordinator.ts     |  2 +
 5 files changed, 90 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
index ad9b648f4..afbd95db8 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
@@ -1,3 +1,4 @@
+import { useEffect, useRef } from "react";
 import type { ShellBallBubbleMessage } from "../shellBall.bubble";
 import type { ShellBallVisualState } from "../shellBall.types";
 import { ShellBallBubbleMessage as ShellBallBubbleMessageView } from "./ShellBallBubbleMessage";
@@ -8,9 +9,20 @@ type ShellBallBubbleZoneProps = {
 };
 
 export function ShellBallBubbleZone({ visualState, bubbleMessages = [] }: ShellBallBubbleZoneProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const scrollElement = scrollRef.current;
+    if (scrollElement === null) {
+      return;
+    }
+
+    scrollElement.scrollTop = scrollElement.scrollHeight;
+  }, [bubbleMessages]);
+
   return (
     <section className="shell-ball-bubble-zone" data-state={visualState}>
-      <div className="shell-ball-bubble-zone__scroll">
+      <div ref={scrollRef} className="shell-ball-bubble-zone__scroll">
         {bubbleMessages.map((message) => (
           <div
             key={message.id}
@@ -21,6 +33,7 @@ export function ShellBallBubbleZone({ visualState, bubbleMessages = [] }: ShellB
             <ShellBallBubbleMessageView message={message} />
           </div>
         ))}
+        <div className="shell-ball-bubble-zone__bottom-anchor" aria-hidden="true" />
       </div>
     </section>
   );
diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
index 49748e0a3..bb61e652b 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -14,5 +14,5 @@ export type ShellBallBubbleMessage = {
 };
 
 export function cloneShellBallBubbleMessages(messages: ShellBallBubbleMessage[]): ShellBallBubbleMessage[] {
-  return [...messages];
+  return messages.map((message) => ({ ...message }));
 }
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 039bc3cb3..339ac09ee 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -55,6 +55,7 @@ import {
   shellBallWindowSyncEvents,
 } from "./shellBall.windowSync";
 import type { ShellBallBubbleMessage } from "./shellBall.bubble";
+import { cloneShellBallBubbleMessages } from "./shellBall.bubble";
 import {
   SHELL_BALL_WINDOW_GAP_PX,
   SHELL_BALL_WINDOW_SAFE_MARGIN_PX,
@@ -1160,6 +1161,11 @@ test("shell-ball bubble message contract supports local bubble feed hints", () =
     text: "On it.",
     createdAt: "2026-04-11T10:01:00.000Z",
   });
+
+  assert.deepEqual(
+    cloneShellBallBubbleMessages([minimalBubbleMessage]),
+    [minimalBubbleMessage],
+  );
 });
 
 test("shell-ball window snapshot copies bubble message arrays defensively", () => {
@@ -1180,8 +1186,20 @@ test("shell-ball window snapshot copies bubble message arrays defensively", () =
   });
 
   assert.notEqual(snapshot.bubbleMessages, sourceMessages);
+  assert.notEqual(snapshot.bubbleMessages[0], sourceMessages[0]);
   assert.deepEqual(snapshot.bubbleMessages, sourceMessages);
 
+  sourceMessages[0].text = "Changed after snapshot.";
+
+  assert.deepEqual(snapshot.bubbleMessages, [
+    {
+      id: "msg-copy-1",
+      role: "agent",
+      text: "Drafting update.",
+      createdAt: "2026-04-11T10:02:00.000Z",
+    },
+  ]);
+
   sourceMessages.push({
     id: "msg-copy-2",
     role: "user",
@@ -2011,6 +2029,52 @@ test("shell-ball coordinator snapshots carry shell-ball-local bubble messages",
 
   assert.ok(Array.isArray(snapshot.bubbleMessages));
   assert.ok(snapshot.bubbleMessages.length > 0);
+  assert.equal(snapshot.bubbleMessages.at(-1)?.freshnessHint, "fresh");
+  assert.equal(snapshot.bubbleMessages.at(-1)?.motionHint, "settle");
+});
+
+test("shell-ball bubble zone keeps the latest message visible on feed updates", () => {
+  const effects: Array<() => void> = [];
+  const scrollElement = {
+    scrollHeight: 184,
+    scrollTop: 0,
+  };
+  const refs = [
+    { current: scrollElement },
+  ];
+
+  const { ShellBallBubbleZone: RuntimeShellBallBubbleZone } = withShellBallModuleRuntime("components/ShellBallBubbleZone.tsx", {
+    react: {
+      ...require("react"),
+      useEffect(callback: () => void) {
+        effects.push(callback);
+      },
+      useRef<T>() {
+        return refs.shift() as { current: T };
+      },
+    },
+    "./ShellBallBubbleMessage": {
+      ShellBallBubbleMessage() {
+        return null;
+      },
+    },
+  }, (moduleExports) => moduleExports as { ShellBallBubbleZone: typeof import("./components/ShellBallBubbleZone").ShellBallBubbleZone });
+
+  RuntimeShellBallBubbleZone({
+    visualState: "processing",
+    bubbleMessages: [
+      {
+        id: "msg-scroll-1",
+        role: "agent",
+        text: "Newest status.",
+        createdAt: "2026-04-11T10:08:00.000Z",
+      },
+    ],
+  });
+
+  assert.equal(effects.length, 1);
+  effects[0]?.();
+  assert.equal(scrollElement.scrollTop, scrollElement.scrollHeight);
 });
 
 test("shell-ball bubble window resolves bubble messages from the helper-window snapshot", () => {
@@ -2164,11 +2228,13 @@ test("shell-ball bubble window styles stay transparent, faded, and motion-ready"
   assert.match(shellBallStyles, /--shell-ball-helper-width:\s*min\(22rem, calc\(100vw - 1rem\)\);/);
   assert.match(shellBallStyles, /@media \(max-width: 720px\)\s*\{[\s\S]*--shell-ball-helper-width:\s*min\(20rem, calc\(100vw - 0\.75rem\)\);/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone\s*\{[\s\S]*width:\s*var\(--shell-ball-helper-width\);/);
+  assert.match(shellBallStyles, /\.shell-ball-bubble-zone\s*\{[\s\S]*overflow:\s*hidden;/);
   assert.match(shellBallStyles, /\.shell-ball-input-bar,\s*\.shell-ball-input-bar--hidden\s*\{[\s\S]*width:\s*var\(--shell-ball-helper-width\);/);
   assert.match(mobileBubbleZoneBlock, /min-height:\s*4\.6rem;/);
   assert.match(mobileBubbleZoneBlock, /padding-inline:\s*0;/);
   assert.doesNotMatch(mobileBubbleZoneBlock, /width:/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*scrollbar-width:\s*none;/);
+  assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*align-content:\s*end;/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll::-webkit-scrollbar\s*\{[\s\S]*display:\s*none;/);
   assert.match(shellBallStyles, /\.shell-ball-bubble-zone__scroll\s*\{[\s\S]*mask-image:\s*linear-gradient\(/);
   assert.match(shellBallStyles, /@keyframes shell-ball-bubble-message-enter/);
@@ -2178,6 +2244,7 @@ test("shell-ball bubble window styles stay transparent, faded, and motion-ready"
   );
   assert.match(markup, /data-freshness="fresh"/);
   assert.match(markup, /data-motion="settle"/);
+  assert.match(markup, /shell-ball-bubble-zone__bottom-anchor/);
 });
 
 test("shell-ball input window owns the input rendering", () => {
diff --git a/apps/desktop/src/features/shell-ball/shellBall.css b/apps/desktop/src/features/shell-ball/shellBall.css
index d889144da..bc0eac5e2 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.css
+++ b/apps/desktop/src/features/shell-ball/shellBall.css
@@ -95,6 +95,7 @@
   display: grid;
   justify-items: stretch;
   min-height: clamp(5.25rem, 12vw, 8.5rem);
+  overflow: hidden;
   padding: 0;
   pointer-events: auto;
   position: relative;
@@ -106,6 +107,7 @@
 }
 
 .shell-ball-bubble-zone__scroll {
+  align-content: end;
   display: grid;
   gap: 0.5rem;
   max-height: clamp(6.5rem, 28vh, 14rem);
@@ -126,6 +128,10 @@
   display: grid;
 }
 
+.shell-ball-bubble-zone__bottom-anchor {
+  block-size: 0;
+}
+
 .shell-ball-bubble-zone__message-entry[data-freshness="fresh"][data-motion="settle"] {
   animation: shell-ball-bubble-message-enter 220ms ease-out both;
 }
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index d71f43acf..944bfcf47 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -46,6 +46,8 @@ const SHELL_BALL_LOCAL_BUBBLE_MESSAGES: ShellBallBubbleMessage[] = [
     role: "user",
     text: "Open the dashboard.",
     createdAt: "2026-04-11T10:05:00.000Z",
+    freshnessHint: "fresh",
+    motionHint: "settle",
   },
 ];
 

From 31a8382bc94f8c814905574dd104928453c5ae3a Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 19:17:36 +0800
Subject: [PATCH 11/19] feat(desktop-shell-ball): align bubble items to
 protocol payloads

---
 .../features/shell-ball/shellBall.bubble.ts   |  36 +--
 .../shell-ball/shellBall.contract.test.ts     | 225 +++++++++++++-----
 .../shell-ball/shellBall.windowSync.ts        |  31 ++-
 .../shell-ball/shellBallBubbleDesktop.ts      |  94 ++++++++
 .../shell-ball/test-stubs/protocol.ts         |  12 +
 5 files changed, 309 insertions(+), 89 deletions(-)
 create mode 100644 apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts

diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
index bb61e652b..62aee71b5 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -1,18 +1,20 @@
-export type ShellBallBubbleMessageRole = "user" | "agent";
+export type {
+  ShellBallBubbleDesktopFreshnessHint,
+  ShellBallBubbleDesktopMotionHint,
+  ShellBallBubbleDesktopLifecycleState,
+  ShellBallBubbleDesktopState,
+  ShellBallBubbleItem,
+  ShellBallBubbleRole,
+  ShellBallLegacyBubbleMessage as ShellBallBubbleMessage,
+} from "./shellBallBubbleDesktop";
 
-export type ShellBallBubbleMessageFreshnessHint = "fresh" | "stale";
-
-export type ShellBallBubbleMessageMotionHint = "settle";
-
-export type ShellBallBubbleMessage = {
-  id: string;
-  role: ShellBallBubbleMessageRole;
-  text: string;
-  createdAt: string;
-  freshnessHint?: ShellBallBubbleMessageFreshnessHint;
-  motionHint?: ShellBallBubbleMessageMotionHint;
-};
-
-export function cloneShellBallBubbleMessages(messages: ShellBallBubbleMessage[]): ShellBallBubbleMessage[] {
-  return messages.map((message) => ({ ...message }));
-}
+export {
+  cloneShellBallBubbleDesktopState,
+  cloneShellBallBubbleItem,
+  cloneShellBallBubbleItems,
+  cloneShellBallBubbleMessages,
+  createLegacyShellBallBubbleMessage,
+  createLegacyShellBallBubbleMessages,
+  createShellBallBubbleItemFromLegacyMessage,
+  createShellBallBubbleItemsFromLegacyMessages,
+} from "./shellBallBubbleDesktop";
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 339ac09ee..9052f35a9 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -54,8 +54,8 @@ import {
   getShellBallHelperWindowVisibility,
   shellBallWindowSyncEvents,
 } from "./shellBall.windowSync";
-import type { ShellBallBubbleMessage } from "./shellBall.bubble";
-import { cloneShellBallBubbleMessages } from "./shellBall.bubble";
+import type { ShellBallBubbleItem, ShellBallBubbleMessage } from "./shellBall.bubble";
+import { cloneShellBallBubbleItems } from "./shellBall.bubble";
 import {
   SHELL_BALL_WINDOW_GAP_PX,
   SHELL_BALL_WINDOW_SAFE_MARGIN_PX,
@@ -1086,14 +1086,23 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
       visualState: "voice_locked",
       inputValue: "draft",
       voicePreview: "lock",
-      bubbleMessages: [
+      bubbleItems: [
         {
-          id: "msg-1",
+          bubble: {
+            bubble_id: "bubble-1",
+            task_id: "task-1",
+            type: "status",
+            text: "Still listening.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:00:00.000Z",
+          },
           role: "agent",
-          text: "Still listening.",
-          createdAt: "2026-04-11T10:00:00.000Z",
-          freshnessHint: "fresh",
-          motionHint: "settle",
+          desktop: {
+            lifecycleState: "visible",
+            freshnessHint: "fresh",
+            motionHint: "settle",
+          },
         },
       ],
     }),
@@ -1102,14 +1111,23 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
       inputBarMode: "voice",
       inputValue: "draft",
       voicePreview: "lock",
-      bubbleMessages: [
+      bubbleItems: [
         {
-          id: "msg-1",
+          bubble: {
+            bubble_id: "bubble-1",
+            task_id: "task-1",
+            type: "status",
+            text: "Still listening.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:00:00.000Z",
+          },
           role: "agent",
-          text: "Still listening.",
-          createdAt: "2026-04-11T10:00:00.000Z",
-          freshnessHint: "fresh",
-          motionHint: "settle",
+          desktop: {
+            lifecycleState: "visible",
+            freshnessHint: "fresh",
+            motionHint: "settle",
+          },
         },
       ],
       visibility: {
@@ -1120,61 +1138,108 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
   );
 });
 
-test("shell-ball bubble message contract supports local bubble feed hints", () => {
+test("shell-ball bubble item contract wraps protocol payload and keeps desktop-only state local", () => {
   const bubbleContractSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.bubble.ts"), "utf8");
-  const bubbleMessage: ShellBallBubbleMessage = {
-    id: "msg-local-1",
+  const bubbleItem: ShellBallBubbleItem = {
+    bubble: {
+      bubble_id: "bubble-local-1",
+      task_id: "task-local-1",
+      type: "result",
+      text: "Open the dashboard.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:00:00.000Z",
+    },
     role: "user",
-    text: "Open the dashboard.",
-    createdAt: "2026-04-11T10:00:00.000Z",
-    freshnessHint: "stale",
-    motionHint: "settle",
+    desktop: {
+      lifecycleState: "hidden",
+      freshnessHint: "stale",
+      motionHint: "settle",
+    },
   };
 
-  assert.deepEqual(bubbleMessage, {
-    id: "msg-local-1",
+  assert.deepEqual(bubbleItem, {
+    bubble: {
+      bubble_id: "bubble-local-1",
+      task_id: "task-local-1",
+      type: "result",
+      text: "Open the dashboard.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:00:00.000Z",
+    },
     role: "user",
-    text: "Open the dashboard.",
-    createdAt: "2026-04-11T10:00:00.000Z",
-    freshnessHint: "stale",
-    motionHint: "settle",
+    desktop: {
+      lifecycleState: "hidden",
+      freshnessHint: "stale",
+      motionHint: "settle",
+    },
   });
+  assert.equal("role" in bubbleItem.bubble, false);
+  assert.equal("desktop" in bubbleItem.bubble, false);
   assert.doesNotMatch(bubbleContractSource, /"pulse"/);
 
   assert.deepEqual(createShellBallWindowSnapshot({
     visualState: "idle",
     inputValue: "",
     voicePreview: null,
-    bubbleMessages: [],
-  }).bubbleMessages, []);
-
-  const minimalBubbleMessage: ShellBallBubbleMessage = {
-    id: "msg-local-2",
+    bubbleItems: [],
+  }).bubbleItems, []);
+
+  const minimalBubbleItem: ShellBallBubbleItem = {
+    bubble: {
+      bubble_id: "bubble-local-2",
+      task_id: "task-local-2",
+      type: "status",
+      text: "On it.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:01:00.000Z",
+    },
     role: "agent",
-    text: "On it.",
-    createdAt: "2026-04-11T10:01:00.000Z",
+    desktop: {
+      lifecycleState: "visible",
+    },
   };
 
-  assert.deepEqual(minimalBubbleMessage, {
-    id: "msg-local-2",
+  assert.deepEqual(minimalBubbleItem, {
+    bubble: {
+      bubble_id: "bubble-local-2",
+      task_id: "task-local-2",
+      type: "status",
+      text: "On it.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:01:00.000Z",
+    },
     role: "agent",
-    text: "On it.",
-    createdAt: "2026-04-11T10:01:00.000Z",
+    desktop: {
+      lifecycleState: "visible",
+    },
   });
 
   assert.deepEqual(
-    cloneShellBallBubbleMessages([minimalBubbleMessage]),
-    [minimalBubbleMessage],
+    cloneShellBallBubbleItems([minimalBubbleItem]),
+    [minimalBubbleItem],
   );
 });
 
-test("shell-ball window snapshot copies bubble message arrays defensively", () => {
-  const sourceMessages: ShellBallBubbleMessage[] = [
+test("shell-ball window snapshot copies bubble item arrays defensively", () => {
+  const sourceItems: ShellBallBubbleItem[] = [
     {
-      id: "msg-copy-1",
+      bubble: {
+        bubble_id: "bubble-copy-1",
+        task_id: "task-copy-1",
+        type: "status",
+        text: "Drafting update.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:02:00.000Z",
+      },
       role: "agent",
-      text: "Drafting update.",
-      createdAt: "2026-04-11T10:02:00.000Z",
+      desktop: {
+        lifecycleState: "visible",
+      },
     },
   ];
 
@@ -1182,37 +1247,64 @@ test("shell-ball window snapshot copies bubble message arrays defensively", () =
     visualState: "hover_input",
     inputValue: "draft",
     voicePreview: null,
-    bubbleMessages: sourceMessages,
+    bubbleItems: sourceItems,
   });
 
-  assert.notEqual(snapshot.bubbleMessages, sourceMessages);
-  assert.notEqual(snapshot.bubbleMessages[0], sourceMessages[0]);
-  assert.deepEqual(snapshot.bubbleMessages, sourceMessages);
+  assert.notEqual(snapshot.bubbleItems, sourceItems);
+  assert.notEqual(snapshot.bubbleItems[0], sourceItems[0]);
+  assert.deepEqual(snapshot.bubbleItems, sourceItems);
 
-  sourceMessages[0].text = "Changed after snapshot.";
+  sourceItems[0].bubble.text = "Changed after snapshot.";
 
-  assert.deepEqual(snapshot.bubbleMessages, [
+  assert.deepEqual(snapshot.bubbleItems, [
     {
-      id: "msg-copy-1",
+      bubble: {
+        bubble_id: "bubble-copy-1",
+        task_id: "task-copy-1",
+        type: "status",
+        text: "Drafting update.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:02:00.000Z",
+      },
       role: "agent",
-      text: "Drafting update.",
-      createdAt: "2026-04-11T10:02:00.000Z",
+      desktop: {
+        lifecycleState: "visible",
+      },
     },
   ]);
 
-  sourceMessages.push({
-    id: "msg-copy-2",
+  sourceItems.push({
+    bubble: {
+      bubble_id: "bubble-copy-2",
+      task_id: "task-copy-2",
+      type: "result",
+      text: "Keep going.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:03:00.000Z",
+    },
     role: "user",
-    text: "Keep going.",
-    createdAt: "2026-04-11T10:03:00.000Z",
+    desktop: {
+      lifecycleState: "visible",
+    },
   });
 
-  assert.deepEqual(snapshot.bubbleMessages, [
+  assert.deepEqual(snapshot.bubbleItems, [
     {
-      id: "msg-copy-1",
+      bubble: {
+        bubble_id: "bubble-copy-1",
+        task_id: "task-copy-1",
+        type: "status",
+        text: "Drafting update.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:02:00.000Z",
+      },
       role: "agent",
-      text: "Drafting update.",
-      createdAt: "2026-04-11T10:02:00.000Z",
+      desktop: {
+        lifecycleState: "visible",
+      },
     },
   ]);
 });
@@ -2027,10 +2119,11 @@ test("shell-ball coordinator snapshots carry shell-ball-local bubble messages",
     onPrimaryClick: () => {},
   });
 
-  assert.ok(Array.isArray(snapshot.bubbleMessages));
-  assert.ok(snapshot.bubbleMessages.length > 0);
-  assert.equal(snapshot.bubbleMessages.at(-1)?.freshnessHint, "fresh");
-  assert.equal(snapshot.bubbleMessages.at(-1)?.motionHint, "settle");
+  assert.ok(Array.isArray(snapshot.bubbleItems));
+  assert.ok(snapshot.bubbleItems.length > 0);
+  assert.equal(snapshot.bubbleItems.at(-1)?.bubble.created_at, "2026-04-11T10:05:00.000Z");
+  assert.equal(snapshot.bubbleItems.at(-1)?.desktop.freshnessHint, "fresh");
+  assert.equal(snapshot.bubbleItems.at(-1)?.desktop.motionHint, "settle");
 });
 
 test("shell-ball bubble zone keeps the latest message visible on feed updates", () => {
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index af413b6f8..c816091b0 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -1,5 +1,9 @@
-import { cloneShellBallBubbleMessages } from "./shellBall.bubble";
-import type { ShellBallBubbleMessage } from "./shellBall.bubble";
+import {
+  cloneShellBallBubbleItems,
+  createLegacyShellBallBubbleMessages,
+  createShellBallBubbleItemsFromLegacyMessages,
+} from "./shellBall.bubble";
+import type { ShellBallBubbleItem, ShellBallBubbleMessage } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import { getShellBallInputBarMode } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
@@ -28,7 +32,8 @@ export type ShellBallWindowSnapshot = {
   inputBarMode: ShellBallInputBarMode;
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
-  bubbleMessages: ShellBallBubbleMessage[];
+  bubbleItems: ShellBallBubbleItem[];
+  bubbleMessages?: ShellBallBubbleMessage[];
   visibility: ShellBallHelperWindowVisibility;
 };
 
@@ -82,16 +87,30 @@ export function createShellBallWindowSnapshot(input: {
   visualState: ShellBallVisualState;
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
+  bubbleItems?: ShellBallBubbleItem[];
   bubbleMessages?: ShellBallBubbleMessage[];
 }): ShellBallWindowSnapshot {
-  return {
+  const bubbleItems = cloneShellBallBubbleItems(
+    input.bubbleItems ?? createShellBallBubbleItemsFromLegacyMessages(input.bubbleMessages ?? []),
+  );
+  const snapshot: ShellBallWindowSnapshot = {
     visualState: input.visualState,
     inputBarMode: getShellBallInputBarMode(input.visualState),
     inputValue: input.inputValue,
     voicePreview: input.voicePreview,
-    bubbleMessages: cloneShellBallBubbleMessages(input.bubbleMessages ?? []),
+    bubbleItems,
     visibility: getShellBallHelperWindowVisibility(input.visualState),
   };
+
+  Object.defineProperty(snapshot, "bubbleMessages", {
+    enumerable: false,
+    configurable: true,
+    get() {
+      return createLegacyShellBallBubbleMessages(bubbleItems);
+    },
+  });
+
+  return snapshot;
 }
 
 export function createDefaultShellBallWindowSnapshot(): ShellBallWindowSnapshot {
@@ -99,6 +118,6 @@ export function createDefaultShellBallWindowSnapshot(): ShellBallWindowSnapshot
     visualState: "idle",
     inputValue: "",
     voicePreview: null,
-    bubbleMessages: [],
+    bubbleItems: [],
   });
 }
diff --git a/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts b/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts
new file mode 100644
index 000000000..6ea5e594d
--- /dev/null
+++ b/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts
@@ -0,0 +1,94 @@
+import type { BubbleMessage } from "@cialloclaw/protocol";
+
+export type ShellBallBubbleRole = "user" | "agent";
+
+export type ShellBallBubbleDesktopFreshnessHint = "fresh" | "stale";
+
+export type ShellBallBubbleDesktopMotionHint = "settle";
+
+export type ShellBallBubbleDesktopLifecycleState = "visible" | "fading" | "hidden";
+
+export type ShellBallBubbleDesktopState = {
+  detachedWindowId?: string;
+  lifecycleState: ShellBallBubbleDesktopLifecycleState;
+  freshnessHint?: ShellBallBubbleDesktopFreshnessHint;
+  motionHint?: ShellBallBubbleDesktopMotionHint;
+};
+
+export type ShellBallBubbleItem = {
+  bubble: BubbleMessage;
+  role: ShellBallBubbleRole;
+  desktop: ShellBallBubbleDesktopState;
+};
+
+export type ShellBallLegacyBubbleMessage = {
+  id: string;
+  role: ShellBallBubbleRole;
+  text: string;
+  createdAt: string;
+  freshnessHint?: ShellBallBubbleDesktopFreshnessHint;
+  motionHint?: ShellBallBubbleDesktopMotionHint;
+};
+
+export function cloneShellBallBubbleDesktopState(state: ShellBallBubbleDesktopState): ShellBallBubbleDesktopState {
+  return { ...state };
+}
+
+export function cloneShellBallBubbleItem(item: ShellBallBubbleItem): ShellBallBubbleItem {
+  return {
+    bubble: { ...item.bubble },
+    role: item.role,
+    desktop: cloneShellBallBubbleDesktopState(item.desktop),
+  };
+}
+
+export function cloneShellBallBubbleItems(items: ShellBallBubbleItem[]): ShellBallBubbleItem[] {
+  return items.map(cloneShellBallBubbleItem);
+}
+
+export function createShellBallBubbleItemFromLegacyMessage(
+  message: ShellBallLegacyBubbleMessage,
+): ShellBallBubbleItem {
+  return {
+    bubble: {
+      bubble_id: message.id,
+      task_id: "",
+      type: "status",
+      text: message.text,
+      pinned: false,
+      hidden: false,
+      created_at: message.createdAt,
+    },
+    role: message.role,
+    desktop: {
+      lifecycleState: "visible",
+      freshnessHint: message.freshnessHint,
+      motionHint: message.motionHint,
+    },
+  };
+}
+
+export function createLegacyShellBallBubbleMessage(item: ShellBallBubbleItem): ShellBallLegacyBubbleMessage {
+  return {
+    id: item.bubble.bubble_id,
+    role: item.role,
+    text: item.bubble.text,
+    createdAt: item.bubble.created_at,
+    freshnessHint: item.desktop.freshnessHint,
+    motionHint: item.desktop.motionHint,
+  };
+}
+
+export function cloneShellBallBubbleMessages(messages: ShellBallLegacyBubbleMessage[]): ShellBallLegacyBubbleMessage[] {
+  return messages.map((message) => ({ ...message }));
+}
+
+export function createShellBallBubbleItemsFromLegacyMessages(
+  messages: ShellBallLegacyBubbleMessage[],
+): ShellBallBubbleItem[] {
+  return messages.map(createShellBallBubbleItemFromLegacyMessage);
+}
+
+export function createLegacyShellBallBubbleMessages(items: ShellBallBubbleItem[]): ShellBallLegacyBubbleMessage[] {
+  return items.map(createLegacyShellBallBubbleMessage);
+}
diff --git a/apps/desktop/src/features/shell-ball/test-stubs/protocol.ts b/apps/desktop/src/features/shell-ball/test-stubs/protocol.ts
index 845d588f8..bb783f5b7 100644
--- a/apps/desktop/src/features/shell-ball/test-stubs/protocol.ts
+++ b/apps/desktop/src/features/shell-ball/test-stubs/protocol.ts
@@ -73,3 +73,15 @@ export type AgentSecurityRespondResult = {
 };
 
 export type Task = any;
+
+export type BubbleMessageType = "status" | "intent_confirm" | "result";
+
+export type BubbleMessage = {
+  bubble_id: string;
+  task_id: string;
+  type: BubbleMessageType;
+  text: string;
+  pinned: boolean;
+  hidden: boolean;
+  created_at: string;
+};

From a95ad448f769881724c10000147f27189f370341 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 19:24:45 +0800
Subject: [PATCH 12/19] fix(desktop-shell-ball): complete bubble item migration

---
 .../shell-ball/ShellBallBubbleWindow.tsx      |   2 +-
 .../components/ShellBallBubbleMessage.tsx     |  14 +--
 .../components/ShellBallBubbleZone.tsx        |  18 +--
 .../features/shell-ball/shellBall.bubble.ts   |   8 +-
 .../shell-ball/shellBall.contract.test.ts     | 117 +++++++++++++-----
 .../shell-ball/shellBall.windowSync.ts        |  27 +---
 .../shell-ball/shellBallBubbleDesktop.ts      |  57 ---------
 .../shell-ball/useShellBallCoordinator.ts     |  40 ++++--
 8 files changed, 137 insertions(+), 146 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
index 68626afdc..5b9ced072 100644
--- a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
+++ b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
@@ -17,7 +17,7 @@ export function ShellBallBubbleWindow({ visualState }: ShellBallBubbleWindowProp
 
   return (
     <div ref={rootRef} className="shell-ball-window shell-ball-window--bubble" aria-label="Shell-ball bubble window">
-      <ShellBallBubbleZone visualState={resolvedVisualState} bubbleMessages={snapshot.bubbleMessages} />
+      <ShellBallBubbleZone visualState={resolvedVisualState} bubbleItems={snapshot.bubbleItems} />
     </div>
   );
 }
diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
index 1f6bf81f2..1cead17c0 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
@@ -1,17 +1,17 @@
-import type { ShellBallBubbleMessage as ShellBallBubbleMessageModel } from "../shellBall.bubble";
+import type { ShellBallBubbleItem } from "../shellBall.bubble";
 
 type ShellBallBubbleMessageProps = {
-  message: ShellBallBubbleMessageModel;
+  item: ShellBallBubbleItem;
 };
 
-export function ShellBallBubbleMessage({ message }: ShellBallBubbleMessageProps) {
+export function ShellBallBubbleMessage({ item }: ShellBallBubbleMessageProps) {
   return (
     <div
-      className={`shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--${message.role}`}
-      data-role={message.role}
+      className={`shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--${item.role}`}
+      data-role={item.role}
     >
-      <div className={`shell-ball-bubble-message shell-ball-bubble-message--${message.role}`} data-message-id={message.id}>
-        <p className="shell-ball-bubble-message__text">{message.text}</p>
+      <div className={`shell-ball-bubble-message shell-ball-bubble-message--${item.role}`} data-message-id={item.bubble.bubble_id}>
+        <p className="shell-ball-bubble-message__text">{item.bubble.text}</p>
       </div>
     </div>
   );
diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
index afbd95db8..0bc9fb96b 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
@@ -1,14 +1,14 @@
 import { useEffect, useRef } from "react";
-import type { ShellBallBubbleMessage } from "../shellBall.bubble";
+import type { ShellBallBubbleItem } from "../shellBall.bubble";
 import type { ShellBallVisualState } from "../shellBall.types";
 import { ShellBallBubbleMessage as ShellBallBubbleMessageView } from "./ShellBallBubbleMessage";
 
 type ShellBallBubbleZoneProps = {
   visualState: ShellBallVisualState;
-  bubbleMessages?: ShellBallBubbleMessage[];
+  bubbleItems?: ShellBallBubbleItem[];
 };
 
-export function ShellBallBubbleZone({ visualState, bubbleMessages = [] }: ShellBallBubbleZoneProps) {
+export function ShellBallBubbleZone({ visualState, bubbleItems = [] }: ShellBallBubbleZoneProps) {
   const scrollRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -18,19 +18,19 @@ export function ShellBallBubbleZone({ visualState, bubbleMessages = [] }: ShellB
     }
 
     scrollElement.scrollTop = scrollElement.scrollHeight;
-  }, [bubbleMessages]);
+  }, [bubbleItems]);
 
   return (
     <section className="shell-ball-bubble-zone" data-state={visualState}>
       <div ref={scrollRef} className="shell-ball-bubble-zone__scroll">
-        {bubbleMessages.map((message) => (
+        {bubbleItems.map((item) => (
           <div
-            key={message.id}
+            key={item.bubble.bubble_id}
             className="shell-ball-bubble-zone__message-entry"
-            data-freshness={message.freshnessHint ?? "stale"}
-            data-motion={message.motionHint ?? "settle"}
+            data-freshness={item.desktop.freshnessHint ?? "stale"}
+            data-motion={item.desktop.motionHint ?? "settle"}
           >
-            <ShellBallBubbleMessageView message={message} />
+            <ShellBallBubbleMessageView item={item} />
           </div>
         ))}
         <div className="shell-ball-bubble-zone__bottom-anchor" aria-hidden="true" />
diff --git a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
index 62aee71b5..43f051a85 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.bubble.ts
@@ -1,20 +1,14 @@
 export type {
   ShellBallBubbleDesktopFreshnessHint,
-  ShellBallBubbleDesktopMotionHint,
   ShellBallBubbleDesktopLifecycleState,
+  ShellBallBubbleDesktopMotionHint,
   ShellBallBubbleDesktopState,
   ShellBallBubbleItem,
   ShellBallBubbleRole,
-  ShellBallLegacyBubbleMessage as ShellBallBubbleMessage,
 } from "./shellBallBubbleDesktop";
 
 export {
   cloneShellBallBubbleDesktopState,
   cloneShellBallBubbleItem,
   cloneShellBallBubbleItems,
-  cloneShellBallBubbleMessages,
-  createLegacyShellBallBubbleMessage,
-  createLegacyShellBallBubbleMessages,
-  createShellBallBubbleItemFromLegacyMessage,
-  createShellBallBubbleItemsFromLegacyMessages,
 } from "./shellBallBubbleDesktop";
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 9052f35a9..469d455d7 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -54,7 +54,7 @@ import {
   getShellBallHelperWindowVisibility,
   shellBallWindowSyncEvents,
 } from "./shellBall.windowSync";
-import type { ShellBallBubbleItem, ShellBallBubbleMessage } from "./shellBall.bubble";
+import type { ShellBallBubbleItem } from "./shellBall.bubble";
 import { cloneShellBallBubbleItems } from "./shellBall.bubble";
 import {
   SHELL_BALL_WINDOW_GAP_PX,
@@ -1178,6 +1178,7 @@ test("shell-ball bubble item contract wraps protocol payload and keeps desktop-o
   assert.equal("role" in bubbleItem.bubble, false);
   assert.equal("desktop" in bubbleItem.bubble, false);
   assert.doesNotMatch(bubbleContractSource, /"pulse"/);
+  assert.doesNotMatch(bubbleContractSource, /ShellBallBubbleMessage/);
 
   assert.deepEqual(createShellBallWindowSnapshot({
     visualState: "idle",
@@ -2155,12 +2156,21 @@ test("shell-ball bubble zone keeps the latest message visible on feed updates",
 
   RuntimeShellBallBubbleZone({
     visualState: "processing",
-    bubbleMessages: [
+    bubbleItems: [
       {
-        id: "msg-scroll-1",
+        bubble: {
+          bubble_id: "msg-scroll-1",
+          task_id: "task-scroll-1",
+          type: "status",
+          text: "Newest status.",
+          pinned: false,
+          hidden: false,
+          created_at: "2026-04-11T10:08:00.000Z",
+        },
         role: "agent",
-        text: "Newest status.",
-        createdAt: "2026-04-11T10:08:00.000Z",
+        desktop: {
+          lifecycleState: "visible",
+        },
       },
     ],
   });
@@ -2170,17 +2180,26 @@ test("shell-ball bubble zone keeps the latest message visible on feed updates",
   assert.equal(scrollElement.scrollTop, scrollElement.scrollHeight);
 });
 
-test("shell-ball bubble window resolves bubble messages from the helper-window snapshot", () => {
+test("shell-ball bubble window resolves bubble items from the helper-window snapshot", () => {
   const helperSnapshot = createShellBallWindowSnapshot({
     visualState: "processing",
     inputValue: "",
     voicePreview: null,
-    bubbleMessages: [
+    bubbleItems: [
       {
-        id: "msg-helper-1",
+        bubble: {
+          bubble_id: "msg-helper-1",
+          task_id: "task-helper-1",
+          type: "status",
+          text: "Drafting your update.",
+          pinned: false,
+          hidden: false,
+          created_at: "2026-04-11T10:04:00.000Z",
+        },
         role: "agent",
-        text: "Drafting your update.",
-        createdAt: "2026-04-11T10:04:00.000Z",
+        desktop: {
+          lifecycleState: "visible",
+        },
       },
     ],
   });
@@ -2210,7 +2229,7 @@ test("shell-ball bubble window resolves bubble messages from the helper-window s
 
   assert.deepEqual(capturedProps, {
     visualState: "processing",
-    bubbleMessages: helperSnapshot.bubbleMessages,
+    bubbleItems: helperSnapshot.bubbleItems,
   });
 });
 
@@ -2219,12 +2238,21 @@ test("shell-ball bubble window does not depend on only visualState to render its
     visualState: "idle",
     inputValue: "",
     voicePreview: null,
-    bubbleMessages: [
+    bubbleItems: [
       {
-        id: "msg-helper-2",
+        bubble: {
+          bubble_id: "msg-helper-2",
+          task_id: "task-helper-2",
+          type: "result",
+          text: "Open the dashboard.",
+          pinned: false,
+          hidden: false,
+          created_at: "2026-04-11T10:05:00.000Z",
+        },
         role: "user",
-        text: "Open the dashboard.",
-        createdAt: "2026-04-11T10:05:00.000Z",
+        desktop: {
+          lifecycleState: "visible",
+        },
       },
     ],
   });
@@ -2254,7 +2282,7 @@ test("shell-ball bubble window does not depend on only visualState to render its
 
   assert.deepEqual(capturedProps, {
     visualState: "voice_locked",
-    bubbleMessages: helperSnapshot.bubbleMessages,
+    bubbleItems: helperSnapshot.bubbleItems,
   });
 });
 
@@ -2262,20 +2290,38 @@ test("shell-ball bubble zone renders a real message list without placeholder chr
   const markup = renderToStaticMarkup(
     createElement(ShellBallBubbleZone, {
       visualState: "processing",
-      bubbleMessages: [
+      bubbleItems: [
         {
-          id: "msg-agent-1",
+          bubble: {
+            bubble_id: "msg-agent-1",
+            task_id: "task-agent-1",
+            type: "status",
+            text: "I found the latest dashboard status.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:06:00.000Z",
+          },
           role: "agent",
-          text: "I found the latest dashboard status.",
-          createdAt: "2026-04-11T10:06:00.000Z",
+          desktop: {
+            lifecycleState: "visible",
+          },
         },
         {
-          id: "msg-user-1",
+          bubble: {
+            bubble_id: "msg-user-1",
+            task_id: "task-user-1",
+            type: "result",
+            text: "Open it for me.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:06:05.000Z",
+          },
           role: "user",
-          text: "Open it for me.",
-          createdAt: "2026-04-11T10:06:05.000Z",
+          desktop: {
+            lifecycleState: "visible",
+          },
         },
-      ] satisfies ShellBallBubbleMessage[],
+      ] satisfies ShellBallBubbleItem[],
     }),
   );
 
@@ -2302,16 +2348,25 @@ test("shell-ball bubble window styles stay transparent, faded, and motion-ready"
   const markup = renderToStaticMarkup(
     createElement(ShellBallBubbleZone, {
       visualState: "processing",
-      bubbleMessages: [
+      bubbleItems: [
         {
-          id: "msg-style-1",
+          bubble: {
+            bubble_id: "msg-style-1",
+            task_id: "task-style-1",
+            type: "status",
+            text: "Draft ready.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:07:00.000Z",
+          },
           role: "agent",
-          text: "Draft ready.",
-          createdAt: "2026-04-11T10:07:00.000Z",
-          freshnessHint: "fresh",
-          motionHint: "settle",
+          desktop: {
+            lifecycleState: "visible",
+            freshnessHint: "fresh",
+            motionHint: "settle",
+          },
         },
-      ] satisfies ShellBallBubbleMessage[],
+      ] satisfies ShellBallBubbleItem[],
     }),
   );
 
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index c816091b0..2beaf42e8 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -1,9 +1,5 @@
-import {
-  cloneShellBallBubbleItems,
-  createLegacyShellBallBubbleMessages,
-  createShellBallBubbleItemsFromLegacyMessages,
-} from "./shellBall.bubble";
-import type { ShellBallBubbleItem, ShellBallBubbleMessage } from "./shellBall.bubble";
+import { cloneShellBallBubbleItems } from "./shellBall.bubble";
+import type { ShellBallBubbleItem } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import { getShellBallInputBarMode } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
@@ -33,7 +29,6 @@ export type ShellBallWindowSnapshot = {
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
   bubbleItems: ShellBallBubbleItem[];
-  bubbleMessages?: ShellBallBubbleMessage[];
   visibility: ShellBallHelperWindowVisibility;
 };
 
@@ -88,29 +83,15 @@ export function createShellBallWindowSnapshot(input: {
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
   bubbleItems?: ShellBallBubbleItem[];
-  bubbleMessages?: ShellBallBubbleMessage[];
 }): ShellBallWindowSnapshot {
-  const bubbleItems = cloneShellBallBubbleItems(
-    input.bubbleItems ?? createShellBallBubbleItemsFromLegacyMessages(input.bubbleMessages ?? []),
-  );
-  const snapshot: ShellBallWindowSnapshot = {
+  return {
     visualState: input.visualState,
     inputBarMode: getShellBallInputBarMode(input.visualState),
     inputValue: input.inputValue,
     voicePreview: input.voicePreview,
-    bubbleItems,
+    bubbleItems: cloneShellBallBubbleItems(input.bubbleItems ?? []),
     visibility: getShellBallHelperWindowVisibility(input.visualState),
   };
-
-  Object.defineProperty(snapshot, "bubbleMessages", {
-    enumerable: false,
-    configurable: true,
-    get() {
-      return createLegacyShellBallBubbleMessages(bubbleItems);
-    },
-  });
-
-  return snapshot;
 }
 
 export function createDefaultShellBallWindowSnapshot(): ShellBallWindowSnapshot {
diff --git a/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts b/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts
index 6ea5e594d..362817410 100644
--- a/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts
+++ b/apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts
@@ -9,7 +9,6 @@ export type ShellBallBubbleDesktopMotionHint = "settle";
 export type ShellBallBubbleDesktopLifecycleState = "visible" | "fading" | "hidden";
 
 export type ShellBallBubbleDesktopState = {
-  detachedWindowId?: string;
   lifecycleState: ShellBallBubbleDesktopLifecycleState;
   freshnessHint?: ShellBallBubbleDesktopFreshnessHint;
   motionHint?: ShellBallBubbleDesktopMotionHint;
@@ -21,15 +20,6 @@ export type ShellBallBubbleItem = {
   desktop: ShellBallBubbleDesktopState;
 };
 
-export type ShellBallLegacyBubbleMessage = {
-  id: string;
-  role: ShellBallBubbleRole;
-  text: string;
-  createdAt: string;
-  freshnessHint?: ShellBallBubbleDesktopFreshnessHint;
-  motionHint?: ShellBallBubbleDesktopMotionHint;
-};
-
 export function cloneShellBallBubbleDesktopState(state: ShellBallBubbleDesktopState): ShellBallBubbleDesktopState {
   return { ...state };
 }
@@ -45,50 +35,3 @@ export function cloneShellBallBubbleItem(item: ShellBallBubbleItem): ShellBallBu
 export function cloneShellBallBubbleItems(items: ShellBallBubbleItem[]): ShellBallBubbleItem[] {
   return items.map(cloneShellBallBubbleItem);
 }
-
-export function createShellBallBubbleItemFromLegacyMessage(
-  message: ShellBallLegacyBubbleMessage,
-): ShellBallBubbleItem {
-  return {
-    bubble: {
-      bubble_id: message.id,
-      task_id: "",
-      type: "status",
-      text: message.text,
-      pinned: false,
-      hidden: false,
-      created_at: message.createdAt,
-    },
-    role: message.role,
-    desktop: {
-      lifecycleState: "visible",
-      freshnessHint: message.freshnessHint,
-      motionHint: message.motionHint,
-    },
-  };
-}
-
-export function createLegacyShellBallBubbleMessage(item: ShellBallBubbleItem): ShellBallLegacyBubbleMessage {
-  return {
-    id: item.bubble.bubble_id,
-    role: item.role,
-    text: item.bubble.text,
-    createdAt: item.bubble.created_at,
-    freshnessHint: item.desktop.freshnessHint,
-    motionHint: item.desktop.motionHint,
-  };
-}
-
-export function cloneShellBallBubbleMessages(messages: ShellBallLegacyBubbleMessage[]): ShellBallLegacyBubbleMessage[] {
-  return messages.map((message) => ({ ...message }));
-}
-
-export function createShellBallBubbleItemsFromLegacyMessages(
-  messages: ShellBallLegacyBubbleMessage[],
-): ShellBallBubbleItem[] {
-  return messages.map(createShellBallBubbleItemFromLegacyMessage);
-}
-
-export function createLegacyShellBallBubbleMessages(items: ShellBallBubbleItem[]): ShellBallLegacyBubbleMessage[] {
-  return items.map(createLegacyShellBallBubbleMessage);
-}
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index 944bfcf47..b9158db3f 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { shellBallWindowLabels } from "../../platform/shellBallWindowController";
-import type { ShellBallBubbleMessage } from "./shellBall.bubble";
+import type { ShellBallBubbleItem } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
 import {
@@ -34,20 +34,38 @@ type ShellBallHelperSnapshotInput = {
   role: ShellBallHelperWindowRole;
 };
 
-const SHELL_BALL_LOCAL_BUBBLE_MESSAGES: ShellBallBubbleMessage[] = [
+const SHELL_BALL_LOCAL_BUBBLE_ITEMS: ShellBallBubbleItem[] = [
   {
-    id: "shell-ball-local-agent-1",
+    bubble: {
+      bubble_id: "shell-ball-local-agent-1",
+      task_id: "",
+      type: "status",
+      text: "Drafting your update.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:04:00.000Z",
+    },
     role: "agent",
-    text: "Drafting your update.",
-    createdAt: "2026-04-11T10:04:00.000Z",
+    desktop: {
+      lifecycleState: "visible",
+    },
   },
   {
-    id: "shell-ball-local-user-1",
+    bubble: {
+      bubble_id: "shell-ball-local-user-1",
+      task_id: "",
+      type: "result",
+      text: "Open the dashboard.",
+      pinned: false,
+      hidden: false,
+      created_at: "2026-04-11T10:05:00.000Z",
+    },
     role: "user",
-    text: "Open the dashboard.",
-    createdAt: "2026-04-11T10:05:00.000Z",
-    freshnessHint: "fresh",
-    motionHint: "settle",
+    desktop: {
+      lifecycleState: "visible",
+      freshnessHint: "fresh",
+      motionHint: "settle",
+    },
   },
 ];
 
@@ -58,7 +76,7 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
         visualState: input.visualState,
         inputValue: input.inputValue,
         voicePreview: input.voicePreview,
-        bubbleMessages: SHELL_BALL_LOCAL_BUBBLE_MESSAGES,
+        bubbleItems: SHELL_BALL_LOCAL_BUBBLE_ITEMS,
       }),
     [input.inputValue, input.visualState, input.voicePreview],
   );

From 6187a568f3223d34e2df269de31bd66a347096b0 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 19:35:13 +0800
Subject: [PATCH 13/19] feat(desktop-shell-ball): define bubble window
 existence strategy

---
 .../shell-ball/ShellBallBubbleWindow.tsx      |  7 +-
 .../shell-ball/shellBall.contract.test.ts     | 94 +++++++++++++++++--
 .../shell-ball/shellBall.windowSync.ts        | 28 +++++-
 .../shell-ball/useShellBallWindowMetrics.ts   |  7 +-
 4 files changed, 122 insertions(+), 14 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
index 5b9ced072..82c8908ff 100644
--- a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
+++ b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
@@ -1,4 +1,5 @@
 import type { ShellBallVisualState } from "./shellBall.types";
+import { getShellBallVisibleBubbleItems } from "./shellBall.windowSync";
 import { useShellBallHelperWindowSnapshot } from "./useShellBallCoordinator";
 import { useShellBallWindowMetrics } from "./useShellBallWindowMetrics";
 import { ShellBallBubbleZone } from "./components/ShellBallBubbleZone";
@@ -10,14 +11,16 @@ type ShellBallBubbleWindowProps = {
 export function ShellBallBubbleWindow({ visualState }: ShellBallBubbleWindowProps) {
   const snapshot = useShellBallHelperWindowSnapshot({ role: "bubble" });
   const resolvedVisualState = visualState ?? snapshot.visualState;
+  const visibleBubbleItems = getShellBallVisibleBubbleItems(snapshot.bubbleItems);
   const { rootRef } = useShellBallWindowMetrics({
     role: "bubble",
-    visible: snapshot.visibility.bubble,
+    visible: true,
+    clickThrough: snapshot.bubbleRegion.clickThrough,
   });
 
   return (
     <div ref={rootRef} className="shell-ball-window shell-ball-window--bubble" aria-label="Shell-ball bubble window">
-      <ShellBallBubbleZone visualState={resolvedVisualState} bubbleItems={snapshot.bubbleItems} />
+      <ShellBallBubbleZone visualState={resolvedVisualState} bubbleItems={visibleBubbleItems} />
     </div>
   );
 }
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 469d455d7..16bc165cd 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -50,8 +50,10 @@ import {
   resolveDashboardRoutePath,
 } from "../dashboard/shared/dashboardRouteTargets";
 import {
+  getShellBallBubbleRegionState,
   createShellBallWindowSnapshot,
   getShellBallHelperWindowVisibility,
+  getShellBallVisibleBubbleItems,
   shellBallWindowSyncEvents,
 } from "./shellBall.windowSync";
 import type { ShellBallBubbleItem } from "./shellBall.bubble";
@@ -776,7 +778,7 @@ test("shell-ball helper windows avoid auto-focus behavior", () => {
   assert.match(controllerSource, /setShellBallWindowFocusable\([^)]*focusable: boolean\)/);
   assert.match(controllerSource, /setShellBallWindowIgnoreCursorEvents\([^)]*ignore: boolean\)/);
   assert.match(metricsSource, /setShellBallWindowFocusable\(role, false\)/);
-  assert.match(metricsSource, /setShellBallWindowIgnoreCursorEvents\(role, true\)/);
+  assert.match(metricsSource, /setShellBallWindowIgnoreCursorEvents\(role, clickThrough\)/);
   assert.doesNotMatch(metricsSource, /setFocus\(\)/);
   assert.doesNotMatch(inputBarSource, /focus\(\{ preventScroll: true \}\)/);
   assert.doesNotMatch(planSource, /focusable: false/);
@@ -1072,7 +1074,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
   });
 
   assert.deepEqual(getShellBallHelperWindowVisibility("idle"), {
-    bubble: false,
+    bubble: true,
     input: false,
   });
 
@@ -1130,6 +1132,11 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
           },
         },
       ],
+      bubbleRegion: {
+        strategy: "persistent",
+        hasVisibleItems: true,
+        clickThrough: false,
+      },
       visibility: {
         bubble: true,
         input: true,
@@ -1138,6 +1145,68 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
   );
 });
 
+test("shell-ball bubble region existence strategy is explicit and item-driven", () => {
+  const bubbleItems: ShellBallBubbleItem[] = [
+    {
+      bubble: {
+        bubble_id: "bubble-visible",
+        task_id: "task-visible",
+        type: "status",
+        text: "Visible bubble",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:00:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "bubble-pinned",
+        task_id: "task-pinned",
+        type: "result",
+        text: "Pinned bubble",
+        pinned: true,
+        hidden: false,
+        created_at: "2026-04-11T10:01:00.000Z",
+      },
+      role: "user",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "bubble-hidden",
+        task_id: "task-hidden",
+        type: "status",
+        text: "Hidden bubble",
+        pinned: false,
+        hidden: true,
+        created_at: "2026-04-11T10:02:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "hidden",
+      },
+    },
+  ];
+
+  assert.deepEqual(getShellBallVisibleBubbleItems(bubbleItems).map((item) => item.bubble.bubble_id), ["bubble-visible"]);
+  assert.deepEqual(getShellBallBubbleRegionState(bubbleItems), {
+    strategy: "persistent",
+    hasVisibleItems: true,
+    clickThrough: false,
+  });
+  assert.deepEqual(getShellBallBubbleRegionState([]), {
+    strategy: "persistent",
+    hasVisibleItems: false,
+    clickThrough: true,
+  });
+});
+
 test("shell-ball bubble item contract wraps protocol payload and keeps desktop-only state local", () => {
   const bubbleContractSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.bubble.ts"), "utf8");
   const bubbleItem: ShellBallBubbleItem = {
@@ -2122,6 +2191,9 @@ test("shell-ball coordinator snapshots carry shell-ball-local bubble messages",
 
   assert.ok(Array.isArray(snapshot.bubbleItems));
   assert.ok(snapshot.bubbleItems.length > 0);
+  assert.equal(snapshot.bubbleRegion.strategy, "persistent");
+  assert.equal(snapshot.bubbleRegion.hasVisibleItems, true);
+  assert.equal(snapshot.bubbleRegion.clickThrough, false);
   assert.equal(snapshot.bubbleItems.at(-1)?.bubble.created_at, "2026-04-11T10:05:00.000Z");
   assert.equal(snapshot.bubbleItems.at(-1)?.desktop.freshnessHint, "fresh");
   assert.equal(snapshot.bubbleItems.at(-1)?.desktop.motionHint, "settle");
@@ -2203,6 +2275,7 @@ test("shell-ball bubble window resolves bubble items from the helper-window snap
       },
     ],
   });
+  helperSnapshot.bubbleRegion = getShellBallBubbleRegionState(helperSnapshot.bubbleItems);
   let capturedProps: Record<string, unknown> | null = null;
 
   const { ShellBallBubbleWindow: RuntimeShellBallBubbleWindow } = withShellBallModuleRuntime("ShellBallBubbleWindow.tsx", {
@@ -2219,7 +2292,7 @@ test("shell-ball bubble window resolves bubble items from the helper-window snap
     },
     "./components/ShellBallBubbleZone": {
       ShellBallBubbleZone(props: Record<string, unknown>) {
-        capturedProps = props;
+        capturedProps = { ...(capturedProps ?? {}), ...props };
         return createElement("section", { className: "shell-ball-bubble-zone-stub" });
       },
     },
@@ -2229,7 +2302,7 @@ test("shell-ball bubble window resolves bubble items from the helper-window snap
 
   assert.deepEqual(capturedProps, {
     visualState: "processing",
-    bubbleItems: helperSnapshot.bubbleItems,
+    bubbleItems: getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems),
   });
 });
 
@@ -2256,6 +2329,7 @@ test("shell-ball bubble window does not depend on only visualState to render its
       },
     ],
   });
+  helperSnapshot.bubbleRegion = getShellBallBubbleRegionState(helperSnapshot.bubbleItems);
   let capturedProps: Record<string, unknown> | null = null;
 
   const { ShellBallBubbleWindow: RuntimeShellBallBubbleWindow } = withShellBallModuleRuntime("ShellBallBubbleWindow.tsx", {
@@ -2266,13 +2340,14 @@ test("shell-ball bubble window does not depend on only visualState to render its
       },
     },
     "./useShellBallWindowMetrics": {
-      useShellBallWindowMetrics() {
+      useShellBallWindowMetrics(input: Record<string, unknown>) {
+        capturedProps = { ...(capturedProps ?? {}), metricsInput: input };
         return { rootRef: null };
       },
     },
     "./components/ShellBallBubbleZone": {
       ShellBallBubbleZone(props: Record<string, unknown>) {
-        capturedProps = props;
+        capturedProps = { ...(capturedProps ?? {}), ...props };
         return createElement("section", { className: "shell-ball-bubble-zone-stub" });
       },
     },
@@ -2282,7 +2357,12 @@ test("shell-ball bubble window does not depend on only visualState to render its
 
   assert.deepEqual(capturedProps, {
     visualState: "voice_locked",
-    bubbleItems: helperSnapshot.bubbleItems,
+    bubbleItems: getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems),
+    metricsInput: {
+      role: "bubble",
+      visible: true,
+      clickThrough: helperSnapshot.bubbleRegion.clickThrough,
+    },
   });
 });
 
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index 2beaf42e8..5a7868466 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -23,12 +23,19 @@ export type ShellBallHelperWindowVisibility = {
   input: boolean;
 };
 
+export type ShellBallBubbleRegionState = {
+  strategy: "persistent";
+  hasVisibleItems: boolean;
+  clickThrough: boolean;
+};
+
 export type ShellBallWindowSnapshot = {
   visualState: ShellBallVisualState;
   inputBarMode: ShellBallInputBarMode;
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
   bubbleItems: ShellBallBubbleItem[];
+  bubbleRegion: ShellBallBubbleRegionState;
   visibility: ShellBallHelperWindowVisibility;
 };
 
@@ -73,23 +80,40 @@ export function getShellBallHelperWindowVisibility(
   visualState: ShellBallVisualState,
 ): ShellBallHelperWindowVisibility {
   return {
-    bubble: visualState !== "idle",
+    bubble: true,
     input: getShellBallInputBarMode(visualState) !== "hidden",
   };
 }
 
+export function getShellBallVisibleBubbleItems(items: ShellBallBubbleItem[]): ShellBallBubbleItem[] {
+  return items.filter((item) => item.bubble.hidden === false && item.bubble.pinned === false);
+}
+
+export function getShellBallBubbleRegionState(items: ShellBallBubbleItem[]): ShellBallBubbleRegionState {
+  const visibleItems = getShellBallVisibleBubbleItems(items);
+
+  return {
+    strategy: "persistent",
+    hasVisibleItems: visibleItems.length > 0,
+    clickThrough: visibleItems.length === 0,
+  };
+}
+
 export function createShellBallWindowSnapshot(input: {
   visualState: ShellBallVisualState;
   inputValue: string;
   voicePreview: ShellBallVoicePreview;
   bubbleItems?: ShellBallBubbleItem[];
 }): ShellBallWindowSnapshot {
+  const bubbleItems = cloneShellBallBubbleItems(input.bubbleItems ?? []);
+
   return {
     visualState: input.visualState,
     inputBarMode: getShellBallInputBarMode(input.visualState),
     inputValue: input.inputValue,
     voicePreview: input.voicePreview,
-    bubbleItems: cloneShellBallBubbleItems(input.bubbleItems ?? []),
+    bubbleItems,
+    bubbleRegion: getShellBallBubbleRegionState(bubbleItems),
     visibility: getShellBallHelperWindowVisibility(input.visualState),
   };
 }
diff --git a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
index 9dcc665b6..90228e871 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
@@ -50,6 +50,7 @@ type ShellBallWindowBounds = {
 type UseShellBallWindowMetricsInput = {
   role: "ball" | ShellBallHelperWindowRole;
   visible?: boolean;
+  clickThrough?: boolean;
 };
 
 export function createShellBallWindowFrame(
@@ -132,7 +133,7 @@ function getShellBallBoundsFromMonitor(monitor: Monitor | null, geometry: ShellB
   };
 }
 
-export function useShellBallWindowMetrics({ role, visible = true }: UseShellBallWindowMetricsInput) {
+export function useShellBallWindowMetrics({ role, visible = true, clickThrough = false }: UseShellBallWindowMetricsInput) {
   const rootRef = useRef<HTMLDivElement>(null);
   const [windowFrame, setWindowFrame] = useState<ShellBallWindowSize | null>(null);
   const geometryRef = useRef<ShellBallWindowGeometry | null>(null);
@@ -262,7 +263,7 @@ export function useShellBallWindowMetrics({ role, visible = true }: UseShellBall
 
     if (role === "bubble") {
       void setShellBallWindowFocusable(role, false);
-      void setShellBallWindowIgnoreCursorEvents(role, true);
+      void setShellBallWindowIgnoreCursorEvents(role, clickThrough);
     }
 
     let cleanup: (() => void) | null = null;
@@ -325,7 +326,7 @@ export function useShellBallWindowMetrics({ role, visible = true }: UseShellBall
       disposed = true;
       cleanup?.();
     };
-  }, [role, visible, windowFrame]);
+  }, [clickThrough, role, visible, windowFrame]);
 
   useEffect(() => {
     if (role === "ball") {

From ccdb9263bd2adf0df535b434fd9959bab331aa18 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 19:42:14 +0800
Subject: [PATCH 14/19] feat(desktop-shell-ball): add bubble pin and delete
 controls

---
 .../shell-ball/ShellBallBubbleWindow.tsx      |  13 +-
 .../components/ShellBallBubbleMessage.tsx     |  32 +++-
 .../components/ShellBallBubbleZone.tsx        |  15 +-
 .../shell-ball/shellBall.contract.test.ts     | 154 ++++++++++++++++--
 .../src/features/shell-ball/shellBall.css     |  49 +++++-
 .../shell-ball/shellBall.windowSync.ts        |   9 +
 .../shell-ball/useShellBallCoordinator.ts     |  47 +++++-
 .../shell-ball/useShellBallWindowMetrics.ts   |  33 +++-
 8 files changed, 326 insertions(+), 26 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
index 82c8908ff..c13e33115 100644
--- a/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
+++ b/apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx
@@ -1,6 +1,6 @@
 import type { ShellBallVisualState } from "./shellBall.types";
 import { getShellBallVisibleBubbleItems } from "./shellBall.windowSync";
-import { useShellBallHelperWindowSnapshot } from "./useShellBallCoordinator";
+import { emitShellBallBubbleAction, useShellBallHelperWindowSnapshot } from "./useShellBallCoordinator";
 import { useShellBallWindowMetrics } from "./useShellBallWindowMetrics";
 import { ShellBallBubbleZone } from "./components/ShellBallBubbleZone";
 
@@ -20,7 +20,16 @@ export function ShellBallBubbleWindow({ visualState }: ShellBallBubbleWindowProp
 
   return (
     <div ref={rootRef} className="shell-ball-window shell-ball-window--bubble" aria-label="Shell-ball bubble window">
-      <ShellBallBubbleZone visualState={resolvedVisualState} bubbleItems={visibleBubbleItems} />
+      <ShellBallBubbleZone
+        visualState={resolvedVisualState}
+        bubbleItems={visibleBubbleItems}
+        onDeleteBubble={(bubbleId) => {
+          void emitShellBallBubbleAction("delete", bubbleId);
+        }}
+        onPinBubble={(bubbleId) => {
+          void emitShellBallBubbleAction("pin", bubbleId);
+        }}
+      />
     </div>
   );
 }
diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
index 1cead17c0..8e907804b 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx
@@ -2,15 +2,43 @@ import type { ShellBallBubbleItem } from "../shellBall.bubble";
 
 type ShellBallBubbleMessageProps = {
   item: ShellBallBubbleItem;
+  onDelete?: (bubbleId: string) => void;
+  onPin?: (bubbleId: string) => void;
 };
 
-export function ShellBallBubbleMessage({ item }: ShellBallBubbleMessageProps) {
+export function ShellBallBubbleMessage({ item, onDelete, onPin }: ShellBallBubbleMessageProps) {
+  const bubbleId = item.bubble.bubble_id;
+
   return (
     <div
       className={`shell-ball-bubble-zone__message-row shell-ball-bubble-zone__message-row--${item.role}`}
       data-role={item.role}
     >
-      <div className={`shell-ball-bubble-message shell-ball-bubble-message--${item.role}`} data-message-id={item.bubble.bubble_id}>
+      <div className={`shell-ball-bubble-message shell-ball-bubble-message--${item.role}`} data-message-id={bubbleId}>
+        <button
+          type="button"
+          className="shell-ball-bubble-message__control shell-ball-bubble-message__pin-control"
+          data-bubble-action="pin"
+          data-bubble-id={bubbleId}
+          aria-label="Pin bubble"
+          onClick={() => {
+            onPin?.(bubbleId);
+          }}
+        >
+          Pin
+        </button>
+        <button
+          type="button"
+          className="shell-ball-bubble-message__control shell-ball-bubble-message__delete-control"
+          data-bubble-action="delete"
+          data-bubble-id={bubbleId}
+          aria-label="Delete bubble"
+          onClick={() => {
+            onDelete?.(bubbleId);
+          }}
+        >
+          Delete
+        </button>
         <p className="shell-ball-bubble-message__text">{item.bubble.text}</p>
       </div>
     </div>
diff --git a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
index 0bc9fb96b..f533fe0d8 100644
--- a/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
+++ b/apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx
@@ -6,9 +6,16 @@ import { ShellBallBubbleMessage as ShellBallBubbleMessageView } from "./ShellBal
 type ShellBallBubbleZoneProps = {
   visualState: ShellBallVisualState;
   bubbleItems?: ShellBallBubbleItem[];
+  onDeleteBubble?: (bubbleId: string) => void;
+  onPinBubble?: (bubbleId: string) => void;
 };
 
-export function ShellBallBubbleZone({ visualState, bubbleItems = [] }: ShellBallBubbleZoneProps) {
+export function ShellBallBubbleZone({
+  visualState,
+  bubbleItems = [],
+  onDeleteBubble,
+  onPinBubble,
+}: ShellBallBubbleZoneProps) {
   const scrollRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -30,7 +37,11 @@ export function ShellBallBubbleZone({ visualState, bubbleItems = [] }: ShellBall
             data-freshness={item.desktop.freshnessHint ?? "stale"}
             data-motion={item.desktop.motionHint ?? "settle"}
           >
-            <ShellBallBubbleMessageView item={item} />
+            <ShellBallBubbleMessageView
+              item={item}
+              onDelete={onDeleteBubble}
+              onPin={onPinBubble}
+            />
           </div>
         ))}
         <div className="shell-ball-bubble-zone__bottom-anchor" aria-hidden="true" />
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 16bc165cd..e72d033b4 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -63,10 +63,12 @@ import {
   SHELL_BALL_WINDOW_SAFE_MARGIN_PX,
   clampShellBallFrameToBounds,
   createShellBallWindowFrame,
+  getShellBallHelperWindowInteractionMode,
   getShellBallBubbleAnchor,
   getShellBallInputAnchor,
   measureShellBallContentSize,
 } from "./useShellBallWindowMetrics";
+import { applyShellBallBubbleAction } from "./useShellBallCoordinator";
 import {
   getShellBallPostSubmitInputReset,
   getShellBallDashboardOpenGesturePolicy,
@@ -777,8 +779,9 @@ test("shell-ball helper windows avoid auto-focus behavior", () => {
   assert.doesNotMatch(tauriConfig, /"focusable": false/);
   assert.match(controllerSource, /setShellBallWindowFocusable\([^)]*focusable: boolean\)/);
   assert.match(controllerSource, /setShellBallWindowIgnoreCursorEvents\([^)]*ignore: boolean\)/);
-  assert.match(metricsSource, /setShellBallWindowFocusable\(role, false\)/);
-  assert.match(metricsSource, /setShellBallWindowIgnoreCursorEvents\(role, clickThrough\)/);
+  assert.match(metricsSource, /getShellBallHelperWindowInteractionMode/);
+  assert.match(metricsSource, /setShellBallWindowFocusable\(role, interactionMode\.focusable\)/);
+  assert.match(metricsSource, /setShellBallWindowIgnoreCursorEvents\(role, interactionMode\.ignoreCursorEvents\)/);
   assert.doesNotMatch(metricsSource, /setFocus\(\)/);
   assert.doesNotMatch(inputBarSource, /focus\(\{ preventScroll: true \}\)/);
   assert.doesNotMatch(planSource, /focusable: false/);
@@ -1071,6 +1074,7 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
     inputFocus: "desktop-shell-ball:input-focus",
     inputDraft: "desktop-shell-ball:input-draft",
     primaryAction: "desktop-shell-ball:primary-action",
+    bubbleAction: "desktop-shell-ball:bubble-action",
   });
 
   assert.deepEqual(getShellBallHelperWindowVisibility("idle"), {
@@ -2300,10 +2304,10 @@ test("shell-ball bubble window resolves bubble items from the helper-window snap
 
   renderToStaticMarkup(createElement(RuntimeShellBallBubbleWindow, null));
 
-  assert.deepEqual(capturedProps, {
-    visualState: "processing",
-    bubbleItems: getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems),
-  });
+  assert.deepEqual(capturedProps?.visualState, "processing");
+  assert.deepEqual(capturedProps?.bubbleItems, getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems));
+  assert.equal(typeof capturedProps?.onDeleteBubble, "function");
+  assert.equal(typeof capturedProps?.onPinBubble, "function");
 });
 
 test("shell-ball bubble window does not depend on only visualState to render its body", () => {
@@ -2355,15 +2359,15 @@ test("shell-ball bubble window does not depend on only visualState to render its
 
   renderToStaticMarkup(createElement(RuntimeShellBallBubbleWindow, { visualState: "voice_locked" }));
 
-  assert.deepEqual(capturedProps, {
-    visualState: "voice_locked",
-    bubbleItems: getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems),
-    metricsInput: {
-      role: "bubble",
-      visible: true,
-      clickThrough: helperSnapshot.bubbleRegion.clickThrough,
-    },
+  assert.deepEqual(capturedProps?.visualState, "voice_locked");
+  assert.deepEqual(capturedProps?.bubbleItems, getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems));
+  assert.deepEqual(capturedProps?.metricsInput, {
+    role: "bubble",
+    visible: true,
+    clickThrough: helperSnapshot.bubbleRegion.clickThrough,
   });
+  assert.equal(typeof capturedProps?.onDeleteBubble, "function");
+  assert.equal(typeof capturedProps?.onPinBubble, "function");
 });
 
 test("shell-ball bubble zone renders a real message list without placeholder chrome", () => {
@@ -2420,6 +2424,128 @@ test("shell-ball bubble zone renders a real message list without placeholder chr
   assert.doesNotMatch(markup, /toolbar/i);
 });
 
+test("shell-ball bubble zone renders per-bubble pin and delete controls", () => {
+  const markup = renderToStaticMarkup(
+    createElement(ShellBallBubbleZone, {
+      visualState: "processing",
+      bubbleItems: [
+        {
+          bubble: {
+            bubble_id: "msg-agent-pin-1",
+            task_id: "task-agent-pin-1",
+            type: "status",
+            text: "Keep this handy.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:09:00.000Z",
+          },
+          role: "agent",
+          desktop: {
+            lifecycleState: "visible",
+          },
+        },
+        {
+          bubble: {
+            bubble_id: "msg-user-pin-1",
+            task_id: "task-user-pin-1",
+            type: "result",
+            text: "Delete this after review.",
+            pinned: false,
+            hidden: false,
+            created_at: "2026-04-11T10:09:05.000Z",
+          },
+          role: "user",
+          desktop: {
+            lifecycleState: "visible",
+          },
+        },
+      ] satisfies ShellBallBubbleItem[],
+    }),
+  );
+
+  assert.match(markup, /shell-ball-bubble-message__pin-control/g);
+  assert.match(markup, /shell-ball-bubble-message__delete-control/g);
+  assert.equal(markup.match(/data-bubble-action="pin"/g)?.length, 2);
+  assert.equal(markup.match(/data-bubble-action="delete"/g)?.length, 2);
+});
+
+test("shell-ball coordinator bubble actions pin and delete local items", () => {
+  const sourceItems: ShellBallBubbleItem[] = [
+    {
+      bubble: {
+        bubble_id: "msg-action-1",
+        task_id: "task-action-1",
+        type: "status",
+        text: "Pin this.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:10:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "msg-action-2",
+        task_id: "task-action-2",
+        type: "result",
+        text: "Delete this.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:10:05.000Z",
+      },
+      role: "user",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+  ];
+
+  const pinnedItems = applyShellBallBubbleAction(sourceItems, {
+    action: "pin",
+    bubbleId: "msg-action-1",
+  });
+
+  assert.equal(pinnedItems[0]?.bubble.pinned, true);
+  assert.equal(pinnedItems[1]?.bubble.pinned, false);
+  assert.equal(sourceItems[0]?.bubble.pinned, false);
+
+  const remainingItems = applyShellBallBubbleAction(pinnedItems, {
+    action: "delete",
+    bubbleId: "msg-action-2",
+  });
+
+  assert.deepEqual(remainingItems.map((item) => item.bubble.bubble_id), ["msg-action-1"]);
+});
+
+test("shell-ball bubble interaction mode stays clickable while visible unpinned bubbles remain", () => {
+  assert.deepEqual(
+    getShellBallHelperWindowInteractionMode({
+      role: "bubble",
+      visible: true,
+      clickThrough: false,
+    }),
+    {
+      focusable: false,
+      ignoreCursorEvents: false,
+    },
+  );
+
+  assert.deepEqual(
+    getShellBallHelperWindowInteractionMode({
+      role: "bubble",
+      visible: true,
+      clickThrough: true,
+    }),
+    {
+      focusable: false,
+      ignoreCursorEvents: true,
+    },
+  );
+});
+
 test("shell-ball bubble window styles stay transparent, faded, and motion-ready", () => {
   const shellBallStyles = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.css"), "utf8");
   const mobileBubbleZoneBlock = shellBallStyles.match(
diff --git a/apps/desktop/src/features/shell-ball/shellBall.css b/apps/desktop/src/features/shell-ball/shellBall.css
index bc0eac5e2..7fb0e0256 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.css
+++ b/apps/desktop/src/features/shell-ball/shellBall.css
@@ -155,7 +155,8 @@
   border-radius: 1.15rem;
   box-shadow: 0 16px 28px -24px rgba(62, 56, 48, 0.34);
   max-width: min(18rem, calc(100% - 2rem));
-  padding: 0.65rem 0.85rem;
+  padding: 1.65rem 0.85rem 0.65rem;
+  position: relative;
 }
 
 .shell-ball-bubble-message--agent {
@@ -174,6 +175,52 @@
   word-break: break-word;
 }
 
+.shell-ball-bubble-message__control {
+  align-items: center;
+  appearance: none;
+  background: rgba(255, 255, 255, 0.72);
+  border: 1px solid rgba(132, 118, 99, 0.14);
+  border-radius: 999px;
+  color: var(--shell-ball-copy);
+  cursor: pointer;
+  display: inline-flex;
+  font-family: var(--font-mono);
+  font-size: 0.58rem;
+  inset-block-start: 0.45rem;
+  line-height: 1;
+  min-height: 1.25rem;
+  padding: 0.2rem 0.45rem;
+  position: absolute;
+  text-transform: uppercase;
+  transition:
+    background 160ms ease,
+    border-color 160ms ease,
+    color 160ms ease,
+    transform 160ms ease;
+}
+
+.shell-ball-bubble-message__control:hover {
+  background: rgba(255, 255, 255, 0.9);
+  border-color: rgba(106, 145, 200, 0.24);
+  color: var(--shell-ball-ink);
+  transform: translateY(-1px);
+}
+
+.shell-ball-bubble-message__control:focus-visible {
+  box-shadow:
+    0 0 0 2px rgba(255, 251, 244, 0.92),
+    0 0 0 4px rgba(106, 145, 200, 0.22);
+  outline: 0;
+}
+
+.shell-ball-bubble-message__pin-control {
+  inset-inline-start: 0.55rem;
+}
+
+.shell-ball-bubble-message__delete-control {
+  inset-inline-end: 0.55rem;
+}
+
 .shell-ball-bubble-zone[data-state="waiting_auth"] {
   --shell-ball-bubble-accent: rgba(193, 141, 70, 0.22);
 }
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index 5a7868466..873a9f768 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -12,12 +12,15 @@ export const shellBallWindowSyncEvents = Object.freeze({
   inputFocus: "desktop-shell-ball:input-focus",
   inputDraft: "desktop-shell-ball:input-draft",
   primaryAction: "desktop-shell-ball:primary-action",
+  bubbleAction: "desktop-shell-ball:bubble-action",
 });
 
 export type ShellBallHelperWindowRole = "bubble" | "input";
 
 export type ShellBallPrimaryAction = "attach_file" | "submit" | "primary_click";
 
+export type ShellBallBubbleAction = "pin" | "delete";
+
 export type ShellBallHelperWindowVisibility = {
   bubble: boolean;
   input: boolean;
@@ -76,6 +79,12 @@ export type ShellBallPrimaryActionPayload = {
   action: ShellBallPrimaryAction;
 };
 
+export type ShellBallBubbleActionPayload = {
+  source: "bubble";
+  action: ShellBallBubbleAction;
+  bubbleId: string;
+};
+
 export function getShellBallHelperWindowVisibility(
   visualState: ShellBallVisualState,
 ): ShellBallHelperWindowVisibility {
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index b9158db3f..15f943d0c 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -1,12 +1,14 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { getCurrentWindow } from "@tauri-apps/api/window";
 import { shellBallWindowLabels } from "../../platform/shellBallWindowController";
-import type { ShellBallBubbleItem } from "./shellBall.bubble";
+import { cloneShellBallBubbleItems, type ShellBallBubbleItem } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
 import {
   createDefaultShellBallWindowSnapshot,
   createShellBallWindowSnapshot,
+  type ShellBallBubbleAction,
+  type ShellBallBubbleActionPayload,
   shellBallWindowSyncEvents,
   type ShellBallHelperReadyPayload,
   type ShellBallHelperWindowRole,
@@ -69,16 +71,40 @@ const SHELL_BALL_LOCAL_BUBBLE_ITEMS: ShellBallBubbleItem[] = [
   },
 ];
 
+export function applyShellBallBubbleAction(
+  items: ShellBallBubbleItem[],
+  payload: Pick<ShellBallBubbleActionPayload, "action" | "bubbleId">,
+): ShellBallBubbleItem[] {
+  if (payload.action === "delete") {
+    return items.filter((item) => item.bubble.bubble_id !== payload.bubbleId);
+  }
+
+  return items.map((item) => {
+    if (item.bubble.bubble_id !== payload.bubbleId) {
+      return item;
+    }
+
+    return {
+      ...item,
+      bubble: {
+        ...item.bubble,
+        pinned: true,
+      },
+    };
+  });
+}
+
 export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
+  const [bubbleItems, setBubbleItems] = useState(() => cloneShellBallBubbleItems(SHELL_BALL_LOCAL_BUBBLE_ITEMS));
   const snapshot = useMemo(
     () =>
       createShellBallWindowSnapshot({
         visualState: input.visualState,
         inputValue: input.inputValue,
         voicePreview: input.voicePreview,
-        bubbleItems: SHELL_BALL_LOCAL_BUBBLE_ITEMS,
+        bubbleItems,
       }),
-    [input.inputValue, input.visualState, input.voicePreview],
+    [bubbleItems, input.inputValue, input.visualState, input.voicePreview],
   );
   const snapshotRef = useRef(snapshot);
   const handlersRef = useRef({
@@ -144,6 +170,10 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
       }
     }
 
+    function handleBubbleAction(payload: ShellBallBubbleActionPayload) {
+      setBubbleItems((currentItems) => applyShellBallBubbleAction(currentItems, payload));
+    }
+
     void Promise.all([
       currentWindow.listen<ShellBallHelperReadyPayload>(
         shellBallWindowSyncEvents.helperReady,
@@ -171,6 +201,9 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
           handlePrimaryAction(payload.action);
         },
       ),
+      currentWindow.listen<ShellBallBubbleActionPayload>(shellBallWindowSyncEvents.bubbleAction, ({ payload }) => {
+        handleBubbleAction(payload);
+      }),
     ]).then((unlisteners) => {
       if (disposed) {
         for (const unlisten of unlisteners) {
@@ -249,3 +282,11 @@ export async function emitShellBallPrimaryAction(action: ShellBallPrimaryAction,
     source,
   });
 }
+
+export async function emitShellBallBubbleAction(action: ShellBallBubbleAction, bubbleId: string) {
+  await getCurrentWindow().emitTo(shellBallWindowLabels.ball, shellBallWindowSyncEvents.bubbleAction, {
+    action,
+    bubbleId,
+    source: "bubble",
+  });
+}
diff --git a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
index 90228e871..ab60321ff 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
@@ -53,6 +53,11 @@ type UseShellBallWindowMetricsInput = {
   clickThrough?: boolean;
 };
 
+type ShellBallHelperWindowInteractionMode = {
+  focusable: boolean;
+  ignoreCursorEvents: boolean;
+};
+
 export function createShellBallWindowFrame(
   contentSize: ShellBallContentSize,
   safeMargin = SHELL_BALL_WINDOW_SAFE_MARGIN_PX,
@@ -112,6 +117,24 @@ export function clampShellBallFrameToBounds(
   };
 }
 
+export function getShellBallHelperWindowInteractionMode(input: {
+  role: ShellBallHelperWindowRole;
+  visible: boolean;
+  clickThrough: boolean;
+}): ShellBallHelperWindowInteractionMode {
+  if (input.role === "bubble") {
+    return {
+      focusable: false,
+      ignoreCursorEvents: input.clickThrough || input.visible === false,
+    };
+  }
+
+  return {
+    focusable: true,
+    ignoreCursorEvents: false,
+  };
+}
+
 function getShellBallBoundsFromMonitor(monitor: Monitor | null, geometry: ShellBallWindowGeometry | null): ShellBallWindowBounds {
   if (monitor === null) {
     return geometry?.bounds ?? {
@@ -262,8 +285,14 @@ export function useShellBallWindowMetrics({ role, visible = true, clickThrough =
     const helperFrame = windowFrame;
 
     if (role === "bubble") {
-      void setShellBallWindowFocusable(role, false);
-      void setShellBallWindowIgnoreCursorEvents(role, clickThrough);
+      const interactionMode = getShellBallHelperWindowInteractionMode({
+        role,
+        visible,
+        clickThrough,
+      });
+
+      void setShellBallWindowFocusable(role, interactionMode.focusable);
+      void setShellBallWindowIgnoreCursorEvents(role, interactionMode.ignoreCursorEvents);
     }
 
     let cleanup: (() => void) | null = null;

From 71ff46459a92bb819fb01666253118c52b55df1f Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 19:46:20 +0800
Subject: [PATCH 15/19] feat(desktop-shell-ball): define pinned bubble state
 ownership

---
 .../shell-ball/shellBall.contract.test.ts     | 30 +++++++++++++++++++
 .../shell-ball/shellBall.windowSync.ts        |  6 ++--
 .../shell-ball/useShellBallCoordinator.ts     | 10 +++++--
 3 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index e72d033b4..d911695c4 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -2518,6 +2518,36 @@ test("shell-ball coordinator bubble actions pin and delete local items", () => {
   });
 
   assert.deepEqual(remainingItems.map((item) => item.bubble.bubble_id), ["msg-action-1"]);
+
+  const unpinnedItems = applyShellBallBubbleAction(pinnedItems, {
+    action: "unpin",
+    bubbleId: "msg-action-1",
+  });
+
+  assert.equal(unpinnedItems[0]?.bubble.pinned, false);
+});
+
+test("shell-ball bubble actions stay coordinator-owned and detached-position free", () => {
+  const bubbleActionPayload = {
+    source: "pinned_window",
+    action: "unpin",
+    bubbleId: "msg-action-1",
+  } as const;
+  const coordinatorSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/useShellBallCoordinator.ts"), "utf8");
+  const syncSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.windowSync.ts"), "utf8");
+
+  assert.deepEqual(bubbleActionPayload, {
+    source: "pinned_window",
+    action: "unpin",
+    bubbleId: "msg-action-1",
+  });
+  assert.equal("x" in bubbleActionPayload, false);
+  assert.equal("y" in bubbleActionPayload, false);
+  assert.equal("position" in bubbleActionPayload, false);
+  assert.match(syncSource, /export type ShellBallBubbleAction = "pin" \| "unpin" \| "delete";/);
+  assert.match(syncSource, /export type ShellBallBubbleActionSource = "bubble" \| "pinned_window";/);
+  assert.match(coordinatorSource, /currentWindow\.listen<ShellBallBubbleActionPayload>\(shellBallWindowSyncEvents\.bubbleAction/);
+  assert.match(coordinatorSource, /setBubbleItems\(\(currentItems\) => applyShellBallBubbleAction\(currentItems, payload\)\)/);
 });
 
 test("shell-ball bubble interaction mode stays clickable while visible unpinned bubbles remain", () => {
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index 873a9f768..fc22f9702 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -19,7 +19,9 @@ export type ShellBallHelperWindowRole = "bubble" | "input";
 
 export type ShellBallPrimaryAction = "attach_file" | "submit" | "primary_click";
 
-export type ShellBallBubbleAction = "pin" | "delete";
+export type ShellBallBubbleAction = "pin" | "unpin" | "delete";
+
+export type ShellBallBubbleActionSource = "bubble" | "pinned_window";
 
 export type ShellBallHelperWindowVisibility = {
   bubble: boolean;
@@ -80,7 +82,7 @@ export type ShellBallPrimaryActionPayload = {
 };
 
 export type ShellBallBubbleActionPayload = {
-  source: "bubble";
+  source: ShellBallBubbleActionSource;
   action: ShellBallBubbleAction;
   bubbleId: string;
 };
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index 15f943d0c..f9d6f3a91 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -88,7 +88,7 @@ export function applyShellBallBubbleAction(
       ...item,
       bubble: {
         ...item.bubble,
-        pinned: true,
+        pinned: payload.action === "pin",
       },
     };
   });
@@ -283,10 +283,14 @@ export async function emitShellBallPrimaryAction(action: ShellBallPrimaryAction,
   });
 }
 
-export async function emitShellBallBubbleAction(action: ShellBallBubbleAction, bubbleId: string) {
+export async function emitShellBallBubbleAction(
+  action: ShellBallBubbleAction,
+  bubbleId: string,
+  source: ShellBallBubbleActionPayload["source"] = "bubble",
+) {
   await getCurrentWindow().emitTo(shellBallWindowLabels.ball, shellBallWindowSyncEvents.bubbleAction, {
     action,
     bubbleId,
-    source: "bubble",
+    source,
   });
 }

From ccbf69de67da3e133514c325e4fc192a5bbaae1c Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 20:00:53 +0800
Subject: [PATCH 16/19] feat(desktop-shell-ball): detach pinned bubbles into
 windows

---
 apps/desktop/shell-ball-bubble-pinned.html    |  12 ++
 .../src-tauri/capabilities/default.json       |   2 +-
 .../src-tauri/gen/schemas/capabilities.json   |   2 +-
 .../src/app/shell-ball-bubble-pinned/main.tsx |  19 ++
 .../ShellBallPinnedBubbleWindow.tsx           |  73 ++++++++
 .../shell-ball/shellBall.contract.test.ts     | 164 +++++++++++++++++-
 .../shell-ball/shellBall.windowSync.ts        |  15 +-
 .../shell-ball/useShellBallCoordinator.ts     | 133 +++++++++++++-
 .../shell-ball/useShellBallWindowMetrics.ts   |   6 +-
 .../src/platform/shellBallWindowController.ts | 112 +++++++++++-
 apps/desktop/vite.config.ts                   |   1 +
 11 files changed, 514 insertions(+), 25 deletions(-)
 create mode 100644 apps/desktop/shell-ball-bubble-pinned.html
 create mode 100644 apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx
 create mode 100644 apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx

diff --git a/apps/desktop/shell-ball-bubble-pinned.html b/apps/desktop/shell-ball-bubble-pinned.html
new file mode 100644
index 000000000..8891fbf1d
--- /dev/null
+++ b/apps/desktop/shell-ball-bubble-pinned.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>CialloClaw Shell Ball Bubble Pinned</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/app/shell-ball-bubble-pinned/main.tsx"></script>
+  </body>
+</html>
diff --git a/apps/desktop/src-tauri/capabilities/default.json b/apps/desktop/src-tauri/capabilities/default.json
index a41a00dbe..04c08d4b5 100644
--- a/apps/desktop/src-tauri/capabilities/default.json
+++ b/apps/desktop/src-tauri/capabilities/default.json
@@ -2,7 +2,7 @@
   "$schema": "../gen/schemas/desktop-schema.json",
   "identifier": "default",
   "description": "Default desktop app permissions plus shell-ball floating window controls.",
-  "windows": ["shell-ball", "shell-ball-bubble", "shell-ball-input", "dashboard", "control-panel"],
+  "windows": ["shell-ball", "shell-ball-bubble", "shell-ball-input", "shell-ball-bubble-pinned-*", "dashboard", "control-panel"],
   "permissions": [
     "core:default",
     "core:window:allow-create",
diff --git a/apps/desktop/src-tauri/gen/schemas/capabilities.json b/apps/desktop/src-tauri/gen/schemas/capabilities.json
index bf98e7ebb..e62e06134 100644
--- a/apps/desktop/src-tauri/gen/schemas/capabilities.json
+++ b/apps/desktop/src-tauri/gen/schemas/capabilities.json
@@ -1 +1 @@
-{"default":{"identifier":"default","description":"Default desktop app permissions plus shell-ball floating window controls.","local":true,"windows":["shell-ball","shell-ball-bubble","shell-ball-input","dashboard","control-panel"],"permissions":["core:default","core:window:allow-create","core:window:allow-show","core:window:allow-hide","core:window:allow-set-position","core:window:allow-set-size","core:window:allow-set-size-constraints","core:window:allow-set-focus","core:window:allow-set-focusable","core:window:allow-set-ignore-cursor-events","core:window:allow-set-always-on-top","core:window:allow-unminimize","core:window:allow-start-dragging"]}}
\ No newline at end of file
+{"default":{"identifier":"default","description":"Default desktop app permissions plus shell-ball floating window controls.","local":true,"windows":["shell-ball","shell-ball-bubble","shell-ball-input","shell-ball-bubble-pinned-*","dashboard","control-panel"],"permissions":["core:default","core:window:allow-create","core:window:allow-show","core:window:allow-hide","core:window:allow-set-position","core:window:allow-set-size","core:window:allow-set-size-constraints","core:window:allow-set-focus","core:window:allow-set-focusable","core:window:allow-set-ignore-cursor-events","core:window:allow-set-always-on-top","core:window:allow-unminimize","core:window:allow-start-dragging"]}}
diff --git a/apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx b/apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx
new file mode 100644
index 000000000..5570ba537
--- /dev/null
+++ b/apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx
@@ -0,0 +1,19 @@
+import ReactDOM from "react-dom/client";
+import { AppProviders } from "@/features/shared/AppProviders";
+import { ShellBallPinnedBubbleWindow } from "@/features/shell-ball/ShellBallPinnedBubbleWindow";
+import "@/features/shell-ball/shellBall.css";
+
+const rootElement = document.getElementById("root")!;
+
+document.documentElement.dataset.appWindow = "shell-ball-bubble-pinned";
+document.body.dataset.appWindow = "shell-ball-bubble-pinned";
+rootElement.dataset.appWindow = "shell-ball-bubble-pinned";
+document.documentElement.setAttribute("data-app-window", "shell-ball-bubble-pinned");
+document.body.setAttribute("data-app-window", "shell-ball-bubble-pinned");
+rootElement.setAttribute("data-app-window", "shell-ball-bubble-pinned");
+
+ReactDOM.createRoot(rootElement).render(
+  <AppProviders>
+    <ShellBallPinnedBubbleWindow />
+  </AppProviders>,
+);
diff --git a/apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx b/apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx
new file mode 100644
index 000000000..309d99c30
--- /dev/null
+++ b/apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx
@@ -0,0 +1,73 @@
+import { useMemo, useState } from "react";
+import {
+  getShellBallCurrentWindow,
+  getShellBallPinnedBubbleIdFromLabel,
+  startShellBallWindowDragging,
+} from "../../platform/shellBallWindowController";
+import { emitShellBallBubbleAction, emitShellBallPinnedWindowDetached, useShellBallHelperWindowSnapshot } from "./useShellBallCoordinator";
+
+export function ShellBallPinnedBubbleWindow() {
+  const windowLabel = getShellBallCurrentWindow().label;
+  const bubbleId = getShellBallPinnedBubbleIdFromLabel(windowLabel);
+  const snapshot = useShellBallHelperWindowSnapshot({ role: "pinned" });
+  const [followsShellBallGeometry, setFollowsShellBallGeometry] = useState(true);
+  const pinnedItem = useMemo(
+    () => snapshot.bubbleItems.find((item) => item.bubble.bubble_id === bubbleId && item.bubble.pinned),
+    [bubbleId, snapshot.bubbleItems],
+  );
+
+  if (bubbleId === null || pinnedItem === undefined) {
+    return <div className="shell-ball-window shell-ball-window--bubble" aria-label="Shell-ball pinned bubble window" />;
+  }
+
+  const pinnedBubbleId = bubbleId;
+
+  function handleDetachDrag() {
+    if (followsShellBallGeometry) {
+      setFollowsShellBallGeometry(false);
+      void emitShellBallPinnedWindowDetached(pinnedBubbleId);
+    }
+
+    void startShellBallWindowDragging();
+  }
+
+  return (
+    <div className="shell-ball-window shell-ball-window--bubble" aria-label="Shell-ball pinned bubble window">
+      <div className="shell-ball-bubble-message shell-ball-bubble-message--pinned" data-bubble-id={pinnedBubbleId}>
+        <button
+          type="button"
+          className="shell-ball-bubble-message__control shell-ball-bubble-message__pin-control"
+          data-bubble-action="unpin"
+          data-bubble-id={pinnedBubbleId}
+          aria-label="Unpin bubble"
+          onClick={() => {
+            void emitShellBallBubbleAction("unpin", pinnedBubbleId, "pinned_window");
+          }}
+        >
+          Unpin
+        </button>
+        <button
+          type="button"
+          className="shell-ball-bubble-message__control shell-ball-bubble-message__delete-control"
+          data-bubble-action="delete"
+          data-bubble-id={pinnedBubbleId}
+          aria-label="Delete bubble"
+          onClick={() => {
+            void emitShellBallBubbleAction("delete", pinnedBubbleId, "pinned_window");
+          }}
+        >
+          Delete
+        </button>
+        <button
+          type="button"
+          className="shell-ball-bubble-message__drag-handle"
+          aria-label="Drag pinned bubble"
+          onPointerDown={handleDetachDrag}
+        >
+          Drag
+        </button>
+        <p className="shell-ball-bubble-message__text">{pinnedItem.bubble.text}</p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index d911695c4..3d58975ee 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -662,6 +662,20 @@ test("shell-ball desktop host declares bubble and input helper windows", () => {
   assert.match(tauriConfig, /"url": "shell-ball-input\.html"/);
 });
 
+test("shell-ball desktop host declares detached pinned bubble windows", () => {
+  assert.equal(existsSync(resolve(desktopRoot, "shell-ball-bubble-pinned.html")), true);
+  assert.equal(existsSync(resolve(desktopRoot, "src/app/shell-ball-bubble-pinned/main.tsx")), true);
+
+  const pinnedHtml = readFileSync(resolve(desktopRoot, "shell-ball-bubble-pinned.html"), "utf8");
+  const pinnedEntry = readFileSync(resolve(desktopRoot, "src/app/shell-ball-bubble-pinned/main.tsx"), "utf8");
+  const viteConfig = readFileSync(resolve(desktopRoot, "vite.config.ts"), "utf8");
+
+  assert.match(pinnedHtml, /src="\/src\/app\/shell-ball-bubble-pinned\/main\.tsx"/);
+  assert.match(pinnedEntry, /ShellBallPinnedBubbleWindow/);
+  assert.match(pinnedEntry, /data-app-window/);
+  assert.match(viteConfig, /"shell-ball-bubble-pinned"/);
+});
+
 test("shell-ball desktop window controller and capabilities stay aligned", () => {
   assert.deepEqual(shellBallWindowLabels, {
     ball: "shell-ball",
@@ -687,6 +701,7 @@ test("shell-ball desktop window controller and capabilities stay aligned", () =>
     "shell-ball",
     "shell-ball-bubble",
     "shell-ball-input",
+    "shell-ball-bubble-pinned-*",
     "dashboard",
     "control-panel",
   ]);
@@ -711,6 +726,34 @@ test("shell-ball desktop window controller and capabilities stay aligned", () =>
   assert.equal(generatedCapabilitySchema.default.permissions.includes("core:window:allow-unminimize"), true);
 });
 
+test("shell-ball pinned window labels and capabilities stay deterministic", () => {
+  const controllerSource = readFileSync(
+    resolve(desktopRoot, "src/platform/shellBallWindowController.ts"),
+    "utf8",
+  );
+  const capabilityConfig = JSON.parse(
+    readFileSync(resolve(desktopRoot, "src-tauri/capabilities/default.json"), "utf8"),
+  ) as {
+    windows: string[];
+    permissions: string[];
+  };
+  const generatedCapabilitySchema = JSON.parse(
+    readFileSync(resolve(desktopRoot, "src-tauri/gen/schemas/capabilities.json"), "utf8"),
+  ) as {
+    default: {
+      windows: string[];
+      permissions: string[];
+    };
+  };
+
+  assert.match(controllerSource, /shellBallPinnedBubbleWindowLabelPrefix = "shell-ball-bubble-pinned-"/);
+  assert.match(controllerSource, /return `\$\{shellBallPinnedBubbleWindowLabelPrefix\}\$\{bubbleId\}`/);
+  assert.match(controllerSource, /shell-ball-bubble-pinned\.html/);
+  assert.equal(capabilityConfig.windows.includes("shell-ball-bubble-pinned-*"), true);
+  assert.deepEqual(generatedCapabilitySchema.default.windows, capabilityConfig.windows);
+  assert.equal(generatedCapabilitySchema.default.windows.includes("shell-ball-bubble-pinned-*"), true);
+});
+
 test("dashboard and control-panel stay hidden on cold launch until explicitly opened", () => {
   const tauriConfig = JSON.parse(
     readFileSync(resolve(desktopRoot, "src-tauri/tauri.conf.json"), "utf8"),
@@ -1070,6 +1113,8 @@ test("shell-ball helper window sync maps visual states into visibility and snaps
     snapshot: "desktop-shell-ball:snapshot",
     geometry: "desktop-shell-ball:geometry",
     helperReady: "desktop-shell-ball:helper-ready",
+    pinnedWindowReady: "desktop-shell-ball:pinned-window-ready",
+    pinnedWindowDetached: "desktop-shell-ball:pinned-window-detached",
     inputHover: "desktop-shell-ball:input-hover",
     inputFocus: "desktop-shell-ball:input-focus",
     inputDraft: "desktop-shell-ball:input-draft",
@@ -2304,10 +2349,13 @@ test("shell-ball bubble window resolves bubble items from the helper-window snap
 
   renderToStaticMarkup(createElement(RuntimeShellBallBubbleWindow, null));
 
-  assert.deepEqual(capturedProps?.visualState, "processing");
-  assert.deepEqual(capturedProps?.bubbleItems, getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems));
-  assert.equal(typeof capturedProps?.onDeleteBubble, "function");
-  assert.equal(typeof capturedProps?.onPinBubble, "function");
+  assert.notEqual(capturedProps, null);
+  const resolvedProps = capturedProps as unknown as Record<string, unknown>;
+
+  assert.deepEqual(resolvedProps.visualState, "processing");
+  assert.deepEqual(resolvedProps.bubbleItems, getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems));
+  assert.equal(typeof resolvedProps.onDeleteBubble, "function");
+  assert.equal(typeof resolvedProps.onPinBubble, "function");
 });
 
 test("shell-ball bubble window does not depend on only visualState to render its body", () => {
@@ -2359,15 +2407,18 @@ test("shell-ball bubble window does not depend on only visualState to render its
 
   renderToStaticMarkup(createElement(RuntimeShellBallBubbleWindow, { visualState: "voice_locked" }));
 
-  assert.deepEqual(capturedProps?.visualState, "voice_locked");
-  assert.deepEqual(capturedProps?.bubbleItems, getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems));
-  assert.deepEqual(capturedProps?.metricsInput, {
+  assert.notEqual(capturedProps, null);
+  const resolvedProps = capturedProps as unknown as Record<string, unknown>;
+
+  assert.deepEqual(resolvedProps.visualState, "voice_locked");
+  assert.deepEqual(resolvedProps.bubbleItems, getShellBallVisibleBubbleItems(helperSnapshot.bubbleItems));
+  assert.deepEqual(resolvedProps.metricsInput, {
     role: "bubble",
     visible: true,
     clickThrough: helperSnapshot.bubbleRegion.clickThrough,
   });
-  assert.equal(typeof capturedProps?.onDeleteBubble, "function");
-  assert.equal(typeof capturedProps?.onPinBubble, "function");
+  assert.equal(typeof resolvedProps.onDeleteBubble, "function");
+  assert.equal(typeof resolvedProps.onPinBubble, "function");
 });
 
 test("shell-ball bubble zone renders a real message list without placeholder chrome", () => {
@@ -2550,6 +2601,101 @@ test("shell-ball bubble actions stay coordinator-owned and detached-position fre
   assert.match(coordinatorSource, /setBubbleItems\(\(currentItems\) => applyShellBallBubbleAction\(currentItems, payload\)\)/);
 });
 
+test("shell-ball pinned bubble windows render one coordinator-owned pinned item and emit detached actions", () => {
+  const helperSnapshot = createShellBallWindowSnapshot({
+    visualState: "processing",
+    inputValue: "",
+    voicePreview: null,
+    bubbleItems: [
+      {
+        bubble: {
+          bubble_id: "msg-pinned-1",
+          task_id: "task-pinned-1",
+          type: "status",
+          text: "Keep this pinned.",
+          pinned: true,
+          hidden: false,
+          created_at: "2026-04-11T10:12:00.000Z",
+        },
+        role: "agent",
+        desktop: {
+          lifecycleState: "visible",
+        },
+      },
+      {
+        bubble: {
+          bubble_id: "msg-unpinned-1",
+          task_id: "task-unpinned-1",
+          type: "result",
+          text: "Leave this in the region.",
+          pinned: false,
+          hidden: false,
+          created_at: "2026-04-11T10:12:01.000Z",
+        },
+        role: "user",
+        desktop: {
+          lifecycleState: "visible",
+        },
+      },
+    ],
+  });
+  const actions: Array<{ action: string; bubbleId: string; source: string | undefined }> = [];
+
+  const { ShellBallPinnedBubbleWindow: RuntimeShellBallPinnedBubbleWindow } = withShellBallModuleRuntime(
+    "ShellBallPinnedBubbleWindow.tsx",
+    {
+      react: require("react"),
+      "./useShellBallCoordinator": {
+        useShellBallHelperWindowSnapshot() {
+          return helperSnapshot;
+        },
+        emitShellBallBubbleAction(action: string, bubbleId: string, source?: string) {
+          actions.push({ action, bubbleId, source });
+          return Promise.resolve();
+        },
+      },
+      "../../platform/shellBallWindowController": {
+        getShellBallPinnedBubbleIdFromLabel() {
+          return "msg-pinned-1";
+        },
+        getShellBallCurrentWindow() {
+          return { label: "shell-ball-bubble-pinned-msg-pinned-1" };
+        },
+        startShellBallWindowDragging() {
+          actions.push({ action: "drag", bubbleId: "msg-pinned-1", source: "window" });
+          return Promise.resolve();
+        },
+      },
+    },
+    (moduleExports) => moduleExports as {
+      ShellBallPinnedBubbleWindow: (props: Record<string, unknown>) => ReturnType<typeof createElement>;
+    },
+  );
+
+  const markup = renderToStaticMarkup(createElement(RuntimeShellBallPinnedBubbleWindow, null));
+
+  assert.match(markup, /Keep this pinned\./);
+  assert.doesNotMatch(markup, /Leave this in the region\./);
+  assert.match(markup, /Unpin/);
+  assert.match(markup, /Delete/);
+});
+
+test("shell-ball detached pinned window contract stays anchored before drag and detached after drag", () => {
+  const pinnedWindowSource = readFileSync(
+    resolve(desktopRoot, "src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx"),
+    "utf8",
+  );
+  const coordinatorSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/useShellBallCoordinator.ts"), "utf8");
+  const syncSource = readFileSync(resolve(desktopRoot, "src/features/shell-ball/shellBall.windowSync.ts"), "utf8");
+
+  assert.match(pinnedWindowSource, /startShellBallWindowDragging/);
+  assert.match(pinnedWindowSource, /setFollowsShellBallGeometry\(false\)/);
+  assert.match(syncSource, /pinnedWindowReady/);
+  assert.match(coordinatorSource, /openShellBallPinnedBubbleWindow/);
+  assert.match(coordinatorSource, /closeShellBallPinnedBubbleWindow/);
+  assert.match(coordinatorSource, /shellBallWindowSyncEvents\.pinnedWindowReady/);
+});
+
 test("shell-ball bubble interaction mode stays clickable while visible unpinned bubbles remain", () => {
   assert.deepEqual(
     getShellBallHelperWindowInteractionMode({
diff --git a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
index fc22f9702..e6c72c22f 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.windowSync.ts
@@ -8,6 +8,8 @@ export const shellBallWindowSyncEvents = Object.freeze({
   snapshot: "desktop-shell-ball:snapshot",
   geometry: "desktop-shell-ball:geometry",
   helperReady: "desktop-shell-ball:helper-ready",
+  pinnedWindowReady: "desktop-shell-ball:pinned-window-ready",
+  pinnedWindowDetached: "desktop-shell-ball:pinned-window-detached",
   inputHover: "desktop-shell-ball:input-hover",
   inputFocus: "desktop-shell-ball:input-focus",
   inputDraft: "desktop-shell-ball:input-draft",
@@ -15,7 +17,7 @@ export const shellBallWindowSyncEvents = Object.freeze({
   bubbleAction: "desktop-shell-ball:bubble-action",
 });
 
-export type ShellBallHelperWindowRole = "bubble" | "input";
+export type ShellBallHelperWindowRole = "bubble" | "input" | "pinned";
 
 export type ShellBallPrimaryAction = "attach_file" | "submit" | "primary_click";
 
@@ -61,7 +63,16 @@ export type ShellBallWindowGeometry = {
 };
 
 export type ShellBallHelperReadyPayload = {
-  role: ShellBallHelperWindowRole;
+  role: Exclude<ShellBallHelperWindowRole, "pinned">;
+};
+
+export type ShellBallPinnedWindowReadyPayload = {
+  windowLabel: string;
+  bubbleId: string;
+};
+
+export type ShellBallPinnedWindowDetachedPayload = {
+  bubbleId: string;
 };
 
 export type ShellBallInputHoverPayload = {
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index f9d6f3a91..4b799fcdc 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -1,6 +1,15 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { getCurrentWindow } from "@tauri-apps/api/window";
-import { shellBallWindowLabels } from "../../platform/shellBallWindowController";
+import {
+  SHELL_BALL_PINNED_BUBBLE_WINDOW_FRAME,
+  closeShellBallPinnedBubbleWindow,
+  emitToShellBallWindowLabel,
+  getShellBallPinnedBubbleIdFromLabel,
+  getShellBallPinnedBubbleWindowAnchor,
+  getShellBallPinnedBubbleWindowLabel,
+  openShellBallPinnedBubbleWindow,
+  shellBallWindowLabels,
+} from "../../platform/shellBallWindowController";
 import { cloneShellBallBubbleItems, type ShellBallBubbleItem } from "./shellBall.bubble";
 import type { ShellBallVoicePreview } from "./shellBall.interaction";
 import type { ShellBallInputBarMode, ShellBallVisualState } from "./shellBall.types";
@@ -15,9 +24,12 @@ import {
   type ShellBallInputDraftPayload,
   type ShellBallInputFocusPayload,
   type ShellBallInputHoverPayload,
+  type ShellBallPinnedWindowDetachedPayload,
+  type ShellBallPinnedWindowReadyPayload,
   type ShellBallPrimaryAction,
   type ShellBallPrimaryActionPayload,
 } from "./shellBall.windowSync";
+import { getShellBallBubbleAnchor } from "./useShellBallWindowMetrics";
 
 type ShellBallCoordinatorInput = {
   visualState: ShellBallVisualState;
@@ -34,6 +46,7 @@ type ShellBallCoordinatorInput = {
 
 type ShellBallHelperSnapshotInput = {
   role: ShellBallHelperWindowRole;
+  windowLabel?: string;
 };
 
 const SHELL_BALL_LOCAL_BUBBLE_ITEMS: ShellBallBubbleItem[] = [
@@ -107,6 +120,8 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
     [bubbleItems, input.inputValue, input.visualState, input.voicePreview],
   );
   const snapshotRef = useRef(snapshot);
+  const bubbleItemsRef = useRef(bubbleItems);
+  const detachedPinnedBubbleIdsRef = useRef(new Set<string>());
   const handlersRef = useRef({
     setInputValue: input.setInputValue,
     onRegionEnter: input.onRegionEnter,
@@ -118,6 +133,7 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
   });
 
   snapshotRef.current = snapshot;
+  bubbleItemsRef.current = bubbleItems;
   handlersRef.current = {
     setInputValue: input.setInputValue,
     onRegionEnter: input.onRegionEnter,
@@ -135,11 +151,19 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
       return;
     }
 
-    async function emitSnapshotTo(role: ShellBallHelperWindowRole) {
-      await currentWindow.emitTo(shellBallWindowLabels[role], shellBallWindowSyncEvents.snapshot, snapshotRef.current);
+    async function emitSnapshotToLabel(label: string) {
+      await emitToShellBallWindowLabel(label, shellBallWindowSyncEvents.snapshot, snapshotRef.current);
     }
 
-    void Promise.all([emitSnapshotTo("bubble"), emitSnapshotTo("input")]);
+    const pinnedBubbleLabels = snapshotRef.current.bubbleItems
+      .filter((item) => item.bubble.pinned)
+      .map((item) => getShellBallPinnedBubbleWindowLabel(item.bubble.bubble_id));
+
+    void Promise.all([
+      emitSnapshotToLabel(shellBallWindowLabels.bubble),
+      emitSnapshotToLabel(shellBallWindowLabels.input),
+      ...pinnedBubbleLabels.map((label) => emitSnapshotToLabel(label)),
+    ]);
   }, [snapshot]);
 
   useEffect(() => {
@@ -152,8 +176,49 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
     let disposed = false;
     let cleanupFns: Array<() => void> = [];
 
-    async function emitSnapshotTo(role: ShellBallHelperWindowRole) {
-      await currentWindow.emitTo(shellBallWindowLabels[role], shellBallWindowSyncEvents.snapshot, snapshotRef.current);
+    async function emitSnapshotTo(role: Exclude<ShellBallHelperWindowRole, "pinned">) {
+      await emitToShellBallWindowLabel(shellBallWindowLabels[role], shellBallWindowSyncEvents.snapshot, snapshotRef.current);
+    }
+
+    async function syncPinnedBubbleWindowAnchor(bubbleId: string) {
+      if (detachedPinnedBubbleIdsRef.current.has(bubbleId)) {
+        return;
+      }
+
+      const bubbleItem = bubbleItemsRef.current.find((item) => item.bubble.bubble_id === bubbleId && item.bubble.pinned);
+
+      if (bubbleItem === undefined) {
+        return;
+      }
+
+      const outerPosition = await currentWindow.outerPosition();
+      const outerSize = await currentWindow.outerSize();
+      const scaleFactor = await currentWindow.scaleFactor();
+      const logicalPosition = outerPosition.toLogical(scaleFactor);
+      const logicalSize = outerSize.toLogical(scaleFactor);
+      const bubbleAnchor = getShellBallBubbleAnchor({
+        ballFrame: {
+          x: logicalPosition.x,
+          y: logicalPosition.y,
+          width: logicalSize.width,
+          height: logicalSize.height,
+        },
+        helperFrame: SHELL_BALL_PINNED_BUBBLE_WINDOW_FRAME,
+      });
+
+      await openShellBallPinnedBubbleWindow({
+        bubbleId,
+        position: getShellBallPinnedBubbleWindowAnchor({ bubbleAnchor }),
+        size: SHELL_BALL_PINNED_BUBBLE_WINDOW_FRAME,
+      });
+    }
+
+    async function syncAnchoredPinnedBubbleWindows() {
+      await Promise.all(
+        bubbleItemsRef.current
+          .filter((item) => item.bubble.pinned)
+          .map((item) => syncPinnedBubbleWindowAnchor(item.bubble.bubble_id)),
+      );
     }
 
     function handlePrimaryAction(action: ShellBallPrimaryAction) {
@@ -172,6 +237,15 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
 
     function handleBubbleAction(payload: ShellBallBubbleActionPayload) {
       setBubbleItems((currentItems) => applyShellBallBubbleAction(currentItems, payload));
+
+      if (payload.action === "pin") {
+        detachedPinnedBubbleIdsRef.current.delete(payload.bubbleId);
+        void syncPinnedBubbleWindowAnchor(payload.bubbleId);
+        return;
+      }
+
+      detachedPinnedBubbleIdsRef.current.delete(payload.bubbleId);
+      void closeShellBallPinnedBubbleWindow(payload.bubbleId);
     }
 
     void Promise.all([
@@ -181,6 +255,19 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
           void emitSnapshotTo(payload.role);
         },
       ),
+      currentWindow.listen<ShellBallPinnedWindowReadyPayload>(
+        shellBallWindowSyncEvents.pinnedWindowReady,
+        ({ payload }) => {
+          void emitToShellBallWindowLabel(payload.windowLabel, shellBallWindowSyncEvents.snapshot, snapshotRef.current);
+          void syncPinnedBubbleWindowAnchor(payload.bubbleId);
+        },
+      ),
+      currentWindow.listen<ShellBallPinnedWindowDetachedPayload>(
+        shellBallWindowSyncEvents.pinnedWindowDetached,
+        ({ payload }) => {
+          detachedPinnedBubbleIdsRef.current.add(payload.bubbleId);
+        },
+      ),
       currentWindow.listen<ShellBallInputHoverPayload>(shellBallWindowSyncEvents.inputHover, ({ payload }) => {
         if (payload.active) {
           handlersRef.current.onRegionEnter();
@@ -204,6 +291,12 @@ export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
       currentWindow.listen<ShellBallBubbleActionPayload>(shellBallWindowSyncEvents.bubbleAction, ({ payload }) => {
         handleBubbleAction(payload);
       }),
+      currentWindow.onMoved(() => {
+        void syncAnchoredPinnedBubbleWindows();
+      }),
+      currentWindow.onResized(() => {
+        void syncAnchoredPinnedBubbleWindows();
+      }),
     ]).then((unlisteners) => {
       if (disposed) {
         for (const unlisten of unlisteners) {
@@ -232,7 +325,13 @@ export function useShellBallHelperWindowSnapshot({ role }: ShellBallHelperSnapsh
   useEffect(() => {
     const currentWindow = getCurrentWindow();
 
-    if (currentWindow.label !== shellBallWindowLabels[role]) {
+    const targetLabel = role === "pinned" ? currentWindow.label : shellBallWindowLabels[role];
+
+    if (role === "pinned" && getShellBallPinnedBubbleIdFromLabel(targetLabel) === null) {
+      return;
+    }
+
+    if (role !== "pinned" && currentWindow.label !== targetLabel) {
       return;
     }
 
@@ -250,6 +349,20 @@ export function useShellBallHelperWindowSnapshot({ role }: ShellBallHelperSnapsh
         }
 
         cleanup = unlisten;
+
+        if (role === "pinned") {
+          const bubbleId = getShellBallPinnedBubbleIdFromLabel(targetLabel);
+
+          if (bubbleId !== null) {
+            void currentWindow.emitTo(shellBallWindowLabels.ball, shellBallWindowSyncEvents.pinnedWindowReady, {
+              windowLabel: targetLabel,
+              bubbleId,
+            });
+          }
+
+          return;
+        }
+
         void currentWindow.emitTo(shellBallWindowLabels.ball, shellBallWindowSyncEvents.helperReady, { role });
       });
 
@@ -294,3 +407,9 @@ export async function emitShellBallBubbleAction(
     source,
   });
 }
+
+export async function emitShellBallPinnedWindowDetached(bubbleId: string) {
+  await getCurrentWindow().emitTo(shellBallWindowLabels.ball, shellBallWindowSyncEvents.pinnedWindowDetached, {
+    bubbleId,
+  });
+}
diff --git a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
index ab60321ff..5843c7b4e 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
@@ -13,6 +13,8 @@ import {
 } from "../../platform/shellBallWindowController";
 import { shellBallWindowSyncEvents, type ShellBallHelperWindowRole, type ShellBallWindowGeometry } from "./shellBall.windowSync";
 
+type AnchoredShellBallHelperWindowRole = Exclude<ShellBallHelperWindowRole, "pinned">;
+
 export const SHELL_BALL_WINDOW_SAFE_MARGIN_PX = 12;
 export const SHELL_BALL_WINDOW_GAP_PX = 12;
 
@@ -48,7 +50,7 @@ type ShellBallWindowBounds = {
 };
 
 type UseShellBallWindowMetricsInput = {
-  role: "ball" | ShellBallHelperWindowRole;
+  role: "ball" | AnchoredShellBallHelperWindowRole;
   visible?: boolean;
   clickThrough?: boolean;
 };
@@ -118,7 +120,7 @@ export function clampShellBallFrameToBounds(
 }
 
 export function getShellBallHelperWindowInteractionMode(input: {
-  role: ShellBallHelperWindowRole;
+  role: AnchoredShellBallHelperWindowRole;
   visible: boolean;
   clickThrough: boolean;
 }): ShellBallHelperWindowInteractionMode {
diff --git a/apps/desktop/src/platform/shellBallWindowController.ts b/apps/desktop/src/platform/shellBallWindowController.ts
index 961f011e2..0056a35cc 100644
--- a/apps/desktop/src/platform/shellBallWindowController.ts
+++ b/apps/desktop/src/platform/shellBallWindowController.ts
@@ -7,6 +7,15 @@ export const shellBallWindowLabels = Object.freeze({
   input: "shell-ball-input",
 });
 
+export const shellBallPinnedBubbleWindowLabelPrefix = "shell-ball-bubble-pinned-";
+
+export const SHELL_BALL_PINNED_BUBBLE_WINDOW_FRAME = Object.freeze({
+  width: 360,
+  height: 140,
+});
+
+export const SHELL_BALL_PINNED_BUBBLE_WINDOW_ANCHOR_OFFSET_PX = 24;
+
 export const shellBallWindowPermissions = Object.freeze([
   "core:window:allow-show",
   "core:window:allow-hide",
@@ -22,19 +31,52 @@ export const shellBallWindowPermissions = Object.freeze([
 
 export type ShellBallWindowRole = keyof typeof shellBallWindowLabels;
 
+export function getShellBallPinnedBubbleWindowLabel(bubbleId: string) {
+  return `${shellBallPinnedBubbleWindowLabelPrefix}${bubbleId}`;
+}
+
+export function isShellBallPinnedBubbleWindowLabel(label: string) {
+  return label.startsWith(shellBallPinnedBubbleWindowLabelPrefix);
+}
+
+export function getShellBallPinnedBubbleIdFromLabel(label: string) {
+  if (!isShellBallPinnedBubbleWindowLabel(label)) {
+    return null;
+  }
+
+  return label.slice(shellBallPinnedBubbleWindowLabelPrefix.length);
+}
+
+export function getShellBallPinnedBubbleWindowAnchor(input: {
+  bubbleAnchor: {
+    x: number;
+    y: number;
+  };
+}) {
+  return {
+    x: input.bubbleAnchor.x + SHELL_BALL_PINNED_BUBBLE_WINDOW_ANCHOR_OFFSET_PX,
+    y: input.bubbleAnchor.y + SHELL_BALL_PINNED_BUBBLE_WINDOW_ANCHOR_OFFSET_PX,
+  };
+}
+
 export function getShellBallCurrentWindow() {
   return getCurrentWindow();
 }
 
-export async function getShellBallWindow(role: ShellBallWindowRole) {
+async function getShellBallWindowByLabel(label: string) {
   const currentWindow = getCurrentWindow();
-  const label = shellBallWindowLabels[role];
 
   if (currentWindow.label === label) {
     return currentWindow;
   }
 
-  const windowHandle = await Window.getByLabel(label);
+  return Window.getByLabel(label);
+}
+
+export async function getShellBallWindow(role: ShellBallWindowRole) {
+  const label = shellBallWindowLabels[role];
+
+  const windowHandle = await getShellBallWindowByLabel(label);
 
   if (windowHandle === null) {
     throw new Error(`Shell-ball window not found: ${label}`);
@@ -77,6 +119,70 @@ export async function startShellBallWindowDragging() {
   await getCurrentWindow().startDragging();
 }
 
+export async function openShellBallPinnedBubbleWindow(input: {
+  bubbleId: string;
+  position: {
+    x: number;
+    y: number;
+  };
+  size?: {
+    width: number;
+    height: number;
+  };
+}) {
+  const label = getShellBallPinnedBubbleWindowLabel(input.bubbleId);
+  const size = input.size ?? SHELL_BALL_PINNED_BUBBLE_WINDOW_FRAME;
+  const existingWindow = await getShellBallWindowByLabel(label);
+
+  if (existingWindow !== null) {
+    await existingWindow.setPosition(createShellBallLogicalPosition(input.position.x, input.position.y));
+    await existingWindow.setSize(createShellBallLogicalSize(size.width, size.height));
+    await existingWindow.show();
+    return label;
+  }
+
+  const pinnedWindowOptions = {
+    title: "CialloClaw Shell Ball Bubble",
+    url: "shell-ball-bubble-pinned.html",
+    x: input.position.x,
+    y: input.position.y,
+    width: size.width,
+    height: size.height,
+    focus: false,
+    visible: true,
+    transparent: true,
+    decorations: false,
+    alwaysOnTop: true,
+    resizable: false,
+    skipTaskbar: true,
+    shadow: false,
+  };
+
+  new Window(label, pinnedWindowOptions);
+
+  return label;
+}
+
+export async function closeShellBallPinnedBubbleWindow(bubbleId: string) {
+  const windowHandle = await getShellBallWindowByLabel(getShellBallPinnedBubbleWindowLabel(bubbleId));
+
+  if (windowHandle === null) {
+    return;
+  }
+
+  await windowHandle.destroy();
+}
+
+export async function emitToShellBallWindowLabel<T>(label: string, event: string, payload?: T) {
+  const windowHandle = await getShellBallWindowByLabel(label);
+
+  if (windowHandle === null) {
+    return;
+  }
+
+  await getCurrentWindow().emitTo(label, event, payload);
+}
+
 export function createShellBallLogicalSize(width: number, height: number) {
   return new LogicalSize(width, height);
 }
diff --git a/apps/desktop/vite.config.ts b/apps/desktop/vite.config.ts
index e5b994097..e584ab31b 100644
--- a/apps/desktop/vite.config.ts
+++ b/apps/desktop/vite.config.ts
@@ -18,6 +18,7 @@ export default defineConfig({
       input: {
         "shell-ball": resolve(currentDirectory, "shell-ball.html"),
         "shell-ball-bubble": resolve(currentDirectory, "shell-ball-bubble.html"),
+        "shell-ball-bubble-pinned": resolve(currentDirectory, "shell-ball-bubble-pinned.html"),
         "shell-ball-input": resolve(currentDirectory, "shell-ball-input.html"),
         dashboard: resolve(currentDirectory, "dashboard.html"),
         "control-panel": resolve(currentDirectory, "control-panel.html"),

From ec626c9d7a581a244909413f2f5ff85462265bc5 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 20:35:46 +0800
Subject: [PATCH 17/19] feat(desktop-shell-ball): restore pinned bubbles to
 region order

---
 .../shell-ball/shellBall.contract.test.ts     | 261 ++++++++++++++++++
 .../shell-ball/useShellBallCoordinator.ts     |  44 ++-
 2 files changed, 291 insertions(+), 14 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 3d58975ee..319445a56 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -2578,6 +2578,267 @@ test("shell-ball coordinator bubble actions pin and delete local items", () => {
   assert.equal(unpinnedItems[0]?.bubble.pinned, false);
 });
 
+test("shell-ball coordinator bubble actions restore unpinned bubbles by timestamp then id", () => {
+  const sourceItems: ShellBallBubbleItem[] = [
+    {
+      bubble: {
+        bubble_id: "msg-order-2",
+        task_id: "task-order-2",
+        type: "status",
+        text: "Pinned later twin.",
+        pinned: true,
+        hidden: false,
+        created_at: "2026-04-11T10:10:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "msg-order-3",
+        task_id: "task-order-3",
+        type: "result",
+        text: "Newest visible bubble.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:11:00.000Z",
+      },
+      role: "user",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "msg-order-1",
+        task_id: "task-order-1",
+        type: "status",
+        text: "Oldest visible bubble.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:09:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "msg-order-0",
+        task_id: "task-order-0",
+        type: "status",
+        text: "Pinned earlier twin.",
+        pinned: true,
+        hidden: false,
+        created_at: "2026-04-11T10:10:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+  ];
+
+  const unpinnedItems = applyShellBallBubbleAction(sourceItems, {
+    action: "unpin",
+    bubbleId: "msg-order-2",
+  });
+
+  assert.deepEqual(
+    unpinnedItems.map((item) => ({
+      bubbleId: item.bubble.bubble_id,
+      pinned: item.bubble.pinned,
+      createdAt: item.bubble.created_at,
+    })),
+    [
+      {
+        bubbleId: "msg-order-1",
+        pinned: false,
+        createdAt: "2026-04-11T10:09:00.000Z",
+      },
+      {
+        bubbleId: "msg-order-0",
+        pinned: true,
+        createdAt: "2026-04-11T10:10:00.000Z",
+      },
+      {
+        bubbleId: "msg-order-2",
+        pinned: false,
+        createdAt: "2026-04-11T10:10:00.000Z",
+      },
+      {
+        bubbleId: "msg-order-3",
+        pinned: false,
+        createdAt: "2026-04-11T10:11:00.000Z",
+      },
+    ],
+  );
+});
+
+test("shell-ball detached bubble actions close pinned windows and delete detached bubbles entirely", () => {
+  const listeners = new Map<string, (event: { payload: unknown }) => void>();
+  const closeCalls: string[] = [];
+  let bubbleItemsState: ShellBallBubbleItem[] = [
+    {
+      bubble: {
+        bubble_id: "msg-detached-1",
+        task_id: "task-detached-1",
+        type: "status",
+        text: "Pinned bubble.",
+        pinned: true,
+        hidden: false,
+        created_at: "2026-04-11T10:10:00.000Z",
+      },
+      role: "agent",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+    {
+      bubble: {
+        bubble_id: "msg-detached-2",
+        task_id: "task-detached-2",
+        type: "result",
+        text: "Keep me visible.",
+        pinned: false,
+        hidden: false,
+        created_at: "2026-04-11T10:11:00.000Z",
+      },
+      role: "user",
+      desktop: {
+        lifecycleState: "visible",
+      },
+    },
+  ];
+
+  const { useShellBallCoordinator } = withShellBallModuleRuntime("useShellBallCoordinator.ts", {
+    react: {
+      ...require("react"),
+      useEffect(callback: () => void) {
+        callback();
+      },
+      useMemo<T>(factory: () => T) {
+        return factory();
+      },
+      useRef<T>(value: T) {
+        return { current: value };
+      },
+      useState<T>(value: T) {
+        const resolvedValue = typeof value === "function" ? (value as () => T)() : value;
+
+        if (
+          Array.isArray(resolvedValue) &&
+          resolvedValue.every((item) => item && typeof item === "object" && "bubble" in item) &&
+          bubbleItemsState.length === 0
+        ) {
+          bubbleItemsState = resolvedValue as ShellBallBubbleItem[];
+        }
+
+        return [bubbleItemsState as unknown as T || resolvedValue, (nextValue: T | ((currentValue: T) => T)) => {
+          bubbleItemsState = typeof nextValue === "function"
+            ? (nextValue as (currentValue: T) => T)(bubbleItemsState as unknown as T) as unknown as ShellBallBubbleItem[]
+            : nextValue as unknown as ShellBallBubbleItem[];
+        }] as const;
+      },
+    },
+    "@tauri-apps/api/window": {
+      getCurrentWindow() {
+        return {
+          label: shellBallWindowLabels.ball,
+          listen(eventName: string, callback: (event: { payload: unknown }) => void) {
+            listeners.set(eventName, callback);
+            return Promise.resolve(() => {});
+          },
+          onMoved() {
+            return Promise.resolve(() => {});
+          },
+          onResized() {
+            return Promise.resolve(() => {});
+          },
+          outerPosition() {
+            return Promise.resolve({ toLogical: () => ({ x: 0, y: 0 }) });
+          },
+          outerSize() {
+            return Promise.resolve({ toLogical: () => ({ width: 124, height: 104 }) });
+          },
+          scaleFactor() {
+            return Promise.resolve(1);
+          },
+        };
+      },
+    },
+    "../../platform/shellBallWindowController": {
+      SHELL_BALL_PINNED_BUBBLE_WINDOW_FRAME: { width: 240, height: 140 },
+      closeShellBallPinnedBubbleWindow(bubbleId: string) {
+        closeCalls.push(bubbleId);
+        return Promise.resolve();
+      },
+      emitToShellBallWindowLabel() {
+        return Promise.resolve();
+      },
+      getShellBallPinnedBubbleIdFromLabel() {
+        return null;
+      },
+      getShellBallPinnedBubbleWindowAnchor() {
+        return { x: 0, y: 0 };
+      },
+      getShellBallPinnedBubbleWindowLabel(bubbleId: string) {
+        return `shell-ball-bubble-pinned-${bubbleId}`;
+      },
+      openShellBallPinnedBubbleWindow() {
+        return Promise.resolve();
+      },
+      shellBallWindowLabels,
+    },
+    "./shellBall.bubble": require(resolve(desktopRoot, ".cache/shell-ball-tests/features/shell-ball/shellBall.bubble.js")),
+    "./shellBall.windowSync": require(resolve(desktopRoot, ".cache/shell-ball-tests/features/shell-ball/shellBall.windowSync.js")),
+    "./useShellBallWindowMetrics": {
+      getShellBallBubbleAnchor() {
+        return { x: 0, y: 0 };
+      },
+    },
+  }, (moduleExports) => moduleExports as { useShellBallCoordinator: typeof import("./useShellBallCoordinator").useShellBallCoordinator });
+
+  useShellBallCoordinator({
+    visualState: "hover_input",
+    inputValue: "",
+    voicePreview: null,
+    setInputValue: () => {},
+    onRegionEnter: () => {},
+    onRegionLeave: () => {},
+    onInputFocusChange: () => {},
+    onSubmitText: () => {},
+    onAttachFile: () => {},
+    onPrimaryClick: () => {},
+  });
+
+  listeners.get(shellBallWindowSyncEvents.pinnedWindowDetached)?.({
+    payload: { bubbleId: "msg-detached-1" },
+  });
+  listeners.get(shellBallWindowSyncEvents.bubbleAction)?.({
+    payload: { source: "pinned_window", action: "unpin", bubbleId: "msg-detached-1" },
+  });
+
+  assert.deepEqual(closeCalls, ["msg-detached-1"]);
+  assert.deepEqual(bubbleItemsState.map((item) => ({ bubbleId: item.bubble.bubble_id, pinned: item.bubble.pinned })), [
+    { bubbleId: "msg-detached-1", pinned: false },
+    { bubbleId: "msg-detached-2", pinned: false },
+  ]);
+
+  listeners.get(shellBallWindowSyncEvents.pinnedWindowDetached)?.({
+    payload: { bubbleId: "msg-detached-1" },
+  });
+  listeners.get(shellBallWindowSyncEvents.bubbleAction)?.({
+    payload: { source: "pinned_window", action: "delete", bubbleId: "msg-detached-1" },
+  });
+
+  assert.deepEqual(closeCalls, ["msg-detached-1", "msg-detached-1"]);
+  assert.deepEqual(bubbleItemsState.map((item) => item.bubble.bubble_id), ["msg-detached-2"]);
+});
+
 test("shell-ball bubble actions stay coordinator-owned and detached-position free", () => {
   const bubbleActionPayload = {
     source: "pinned_window",
diff --git a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
index 4b799fcdc..871bbc702 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts
@@ -84,31 +84,47 @@ const SHELL_BALL_LOCAL_BUBBLE_ITEMS: ShellBallBubbleItem[] = [
   },
 ];
 
+export function compareShellBallBubbleItemsByTimestamp(left: ShellBallBubbleItem, right: ShellBallBubbleItem) {
+  const createdAtOrder = left.bubble.created_at.localeCompare(right.bubble.created_at);
+
+  if (createdAtOrder !== 0) {
+    return createdAtOrder;
+  }
+
+  return left.bubble.bubble_id.localeCompare(right.bubble.bubble_id);
+}
+
+export function sortShellBallBubbleItemsByTimestamp(items: ShellBallBubbleItem[]) {
+  return [...items].sort(compareShellBallBubbleItemsByTimestamp);
+}
+
 export function applyShellBallBubbleAction(
   items: ShellBallBubbleItem[],
   payload: Pick<ShellBallBubbleActionPayload, "action" | "bubbleId">,
 ): ShellBallBubbleItem[] {
   if (payload.action === "delete") {
-    return items.filter((item) => item.bubble.bubble_id !== payload.bubbleId);
+    return sortShellBallBubbleItemsByTimestamp(items.filter((item) => item.bubble.bubble_id !== payload.bubbleId));
   }
 
-  return items.map((item) => {
-    if (item.bubble.bubble_id !== payload.bubbleId) {
-      return item;
-    }
+  return sortShellBallBubbleItemsByTimestamp(
+    items.map((item) => {
+      if (item.bubble.bubble_id !== payload.bubbleId) {
+        return item;
+      }
 
-    return {
-      ...item,
-      bubble: {
-        ...item.bubble,
-        pinned: payload.action === "pin",
-      },
-    };
-  });
+      return {
+        ...item,
+        bubble: {
+          ...item.bubble,
+          pinned: payload.action === "pin",
+        },
+      };
+    }),
+  );
 }
 
 export function useShellBallCoordinator(input: ShellBallCoordinatorInput) {
-  const [bubbleItems, setBubbleItems] = useState(() => cloneShellBallBubbleItems(SHELL_BALL_LOCAL_BUBBLE_ITEMS));
+  const [bubbleItems, setBubbleItems] = useState(() => sortShellBallBubbleItemsByTimestamp(cloneShellBallBubbleItems(SHELL_BALL_LOCAL_BUBBLE_ITEMS)));
   const snapshot = useMemo(
     () =>
       createShellBallWindowSnapshot({

From d7ce857dea1f184c1d6626e294d5eafa3bc844e0 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 20:38:18 +0800
Subject: [PATCH 18/19] feat(desktop-shell-ball): tune bubble region anchor

---
 .../src/features/shell-ball/shellBall.contract.test.ts | 10 +++++++---
 .../features/shell-ball/useShellBallWindowMetrics.ts   |  7 ++++---
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
index 319445a56..5bb776922 100644
--- a/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+++ b/apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
@@ -59,7 +59,8 @@ import {
 import type { ShellBallBubbleItem } from "./shellBall.bubble";
 import { cloneShellBallBubbleItems } from "./shellBall.bubble";
 import {
-  SHELL_BALL_WINDOW_GAP_PX,
+  SHELL_BALL_BUBBLE_GAP_PX,
+  SHELL_BALL_INPUT_GAP_PX,
   SHELL_BALL_WINDOW_SAFE_MARGIN_PX,
   clampShellBallFrameToBounds,
   createShellBallWindowFrame,
@@ -1429,7 +1430,8 @@ test("shell-ball window snapshot copies bubble item arrays defensively", () => {
 });
 
 test("shell-ball window metrics compute safe frames and helper anchors", () => {
-  assert.equal(SHELL_BALL_WINDOW_GAP_PX, 12);
+  assert.equal(SHELL_BALL_BUBBLE_GAP_PX, 6);
+  assert.equal(SHELL_BALL_INPUT_GAP_PX, 12);
   assert.equal(SHELL_BALL_WINDOW_SAFE_MARGIN_PX, 12);
 
   const ballFrame = createShellBallWindowFrame({ width: 100, height: 80 });
@@ -1453,10 +1455,12 @@ test("shell-ball window metrics compute safe frames and helper anchors", () => {
     }),
     {
       x: 172,
-      y: 198,
+      y: 204,
     },
   );
 
+  assert.equal(204 + 90 <= 300, true);
+
   assert.deepEqual(
     getShellBallInputAnchor({
       ballFrame: {
diff --git a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
index 5843c7b4e..56d4020cc 100644
--- a/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
+++ b/apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts
@@ -16,7 +16,8 @@ import { shellBallWindowSyncEvents, type ShellBallHelperWindowRole, type ShellBa
 type AnchoredShellBallHelperWindowRole = Exclude<ShellBallHelperWindowRole, "pinned">;
 
 export const SHELL_BALL_WINDOW_SAFE_MARGIN_PX = 12;
-export const SHELL_BALL_WINDOW_GAP_PX = 12;
+export const SHELL_BALL_BUBBLE_GAP_PX = 6;
+export const SHELL_BALL_INPUT_GAP_PX = 12;
 
 type ShellBallContentSize = {
   width: number;
@@ -84,7 +85,7 @@ export function getShellBallBubbleAnchor(input: {
   helperFrame: ShellBallWindowSize;
   gap?: number;
 }) {
-  const gap = input.gap ?? SHELL_BALL_WINDOW_GAP_PX;
+  const gap = input.gap ?? SHELL_BALL_BUBBLE_GAP_PX;
 
   return {
     x: Math.round(input.ballFrame.x + input.ballFrame.width / 2 - input.helperFrame.width / 2),
@@ -97,7 +98,7 @@ export function getShellBallInputAnchor(input: {
   helperFrame: ShellBallWindowSize;
   gap?: number;
 }) {
-  const gap = input.gap ?? SHELL_BALL_WINDOW_GAP_PX;
+  const gap = input.gap ?? SHELL_BALL_INPUT_GAP_PX;
 
   return {
     x: Math.round(input.ballFrame.x + input.ballFrame.width / 2 - input.helperFrame.width / 2),

From eb40cb653a8eaace28bc558cbcd4dcdc21ab84b8 Mon Sep 17 00:00:00 2001
From: gdemonc <1502689916@qq.com>
Date: Sat, 11 Apr 2026 20:41:38 +0800
Subject: [PATCH 19/19] feat(desktop-shell-ball): add pinned bubble plan

---
 ...ubble-pinned-window-implementation-plan.md | 439 ++++++++++++++++++
 1 file changed, 439 insertions(+)
 create mode 100644 apps/desktop/docs/2026-04-11-shell-ball-bubble-pinned-window-implementation-plan.md

diff --git a/apps/desktop/docs/2026-04-11-shell-ball-bubble-pinned-window-implementation-plan.md b/apps/desktop/docs/2026-04-11-shell-ball-bubble-pinned-window-implementation-plan.md
new file mode 100644
index 000000000..fe806239a
--- /dev/null
+++ b/apps/desktop/docs/2026-04-11-shell-ball-bubble-pinned-window-implementation-plan.md
@@ -0,0 +1,439 @@
+# Shell-Ball Bubble Pinned Window Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Upgrade the shell-ball bubble system so bubble items align to protocol semantics, support per-bubble pin/delete controls, detach pinned bubbles into standalone draggable windows, and return unpinned bubbles to their timestamp order in the transparent bubble region.
+
+**Architecture:** Keep `packages/protocol` as the semantic source of truth for the bubble payload core by wrapping protocol `BubbleMessage` objects in a shell-ball-local desktop state envelope instead of inventing a second independent message model. The always-present `shell-ball-bubble` window renders only unpinned items in the bubble region, while each pinned item gets its own runtime-created detached window that survives bubble-region lifecycle rules until unpinned or deleted.
+
+**Tech Stack:** Tauri 2 window API, React 18, TypeScript, existing shell-ball coordinator/window sync layer, shell-ball contract test suite.
+
+---
+
+## File Map
+
+- Create: `apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts`
+- Create: `apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx`
+- Create: `apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx`
+- Create: `apps/desktop/shell-ball-bubble-pinned.html`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.bubble.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.css`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts`
+- Modify: `apps/desktop/src/platform/shellBallWindowController.ts`
+- Modify: `apps/desktop/vite.config.ts`
+- Modify: `apps/desktop/src-tauri/capabilities/default.json`
+- Modify: `apps/desktop/src-tauri/gen/schemas/capabilities.json`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+## Target Model
+
+The follow-up implementation should replace the current ad hoc bubble item shape with a protocol-wrapped desktop bubble item:
+
+```ts
+type ShellBallBubbleRole = "user" | "agent"
+
+type ShellBallBubbleDesktopState = {
+  detachedWindowId?: string
+  lifecycleState: "visible" | "fading" | "hidden"
+  freshnessHint?: "fresh" | "stale"
+  motionHint?: "settle"
+}
+
+type ShellBallBubbleItem = {
+  bubble: BubbleMessage
+  role: ShellBallBubbleRole
+  desktop: ShellBallBubbleDesktopState
+}
+```
+
+Rules:
+
+- `bubble` carries the protocol-aligned payload core (`bubble_id`, `task_id`, `type`, `text`, `pinned`, `hidden`, `created_at`).
+- `role` remains a shell-ball UI concern until protocol adds role semantics.
+- `desktop` is shell-ball-local and must not be pushed into `packages/protocol`.
+- Bubble region renders items with `bubble.hidden === false && bubble.pinned === false`.
+- Pinned windows render items with `bubble.pinned === true`.
+
+## Window Interaction and Runtime Rules
+
+- `shell-ball-bubble` stays structurally present as the bubble-region window, but its interaction mode depends on content state:
+  - when there are no visible unpinned bubbles, it remains transparent and click-through
+  - when visible unpinned bubbles exist, it must disable click-through so pin/delete controls are usable
+- pinned windows use deterministic labels: `shell-ball-bubble-pinned-<bubble_id>`
+- pinned windows receive one `ShellBallBubbleItem` snapshot payload and return actions through shell-ball-local event names such as:
+  - `desktop-shell-ball:bubble-pin-toggle`
+  - `desktop-shell-ball:bubble-delete`
+- pinned windows spawn from a named pinned-window anchor near the bubble region before first drag
+- once the user drags a pinned window, it becomes free-positioned and no longer follows shell-ball or bubble-region geometry updates
+- only the main bubble region continues using the shared helper-window metrics/anchor flow
+- unpin ordering is stable by `bubble.created_at`, then `bubble.bubble_id`
+- bubble-region offset tuning must use named constants in the metrics layer and be verified against the ball frame so the region moves closer without overlapping the mascot window
+
+## Coordinator Ownership Contract
+
+- The coordinator is the single source of truth for bubble-item existence, ordering, `bubble.pinned`, and delete/unpin state transitions.
+- Pinned windows only render snapshot data from the coordinator; they do not own independent bubble-item state.
+- All `pin`, `unpin`, and `delete` actions round-trip through the coordinator before UI state changes are considered final.
+- Detached position may live in local desktop/window state after the first user drag, but bubble-item existence and region ordering remain coordinator-owned.
+
+## Behavioral Constraints
+
+- The bubble region window always exists, but its background remains fully transparent.
+- If there are no visible unpinned bubbles, the user sees nothing in the bubble region.
+- Every bubble item has two controls:
+  - top-left pin toggle
+  - top-right delete
+- Delete always destroys the bubble item immediately.
+- Pin removes the bubble item from the bubble region and creates a standalone detached pinned window.
+- Detached pinned windows:
+  - are draggable
+  - stay always-on-top
+  - do not participate in bubble fade/hide/disperse behavior
+- Unpin destroys the detached window and returns the bubble item to the bubble region sorted by `bubble.created_at`, then `bubble.bubble_id`.
+- Bubble region offset must be defined by named constants and verified against the ball frame so it moves closer without overlap.
+- Bubble region has no fixed item count limit; visibility is governed by space + scrolling only.
+
+### Task 1: Refactor Bubble Data to Protocol-Wrapped Items
+
+**Files:**
+- Create: `apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.bubble.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing contract test**
+
+Add tests asserting that shell-ball bubble data now wraps protocol `BubbleMessage` instead of exposing only front-end-local fields, while still preserving shell-ball-local `role` and desktop state.
+
+Cover:
+- `ShellBallBubbleItem.bubble` matches protocol field names
+- `role` stays outside protocol payload
+- `desktop` carries shell-ball-local lifecycle/window state
+- snapshot payload now uses `bubbleItems` instead of `bubbleMessages`
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because current bubble model still uses `bubbleMessages` and front-end-only fields.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts` for shell-ball-local desktop extensions and mapping helpers.
+
+Refactor `apps/desktop/src/features/shell-ball/shellBall.bubble.ts` so the exported type becomes protocol-wrapped `ShellBallBubbleItem`.
+
+Update `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts` to carry `bubbleItems` in the snapshot.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for the protocol-wrapped bubble item contract.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/shellBallBubbleDesktop.ts apps/desktop/src/features/shell-ball/shellBall.bubble.ts apps/desktop/src/features/shell-ball/shellBall.windowSync.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): align bubble items to protocol payloads"
+```
+
+### Task 2: Verify Bubble Region Window Existence Strategy First
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing contract test**
+
+Add tests asserting that:
+- the bubble helper window existence strategy is explicit and verified independently of rendering details
+- the bubble helper window is no longer gated purely by `visualState`
+- the snapshot/visibility contract distinguishes bubble-window existence from empty bubble-region content
+- it receives a flat `bubbleItems` list
+- the visible list excludes `bubble.pinned === true`
+- the empty region stays structurally present but visually transparent and click-through when there are no visible unpinned bubbles
+- non-empty bubble regions disable click-through so pin/delete controls are usable
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because current visibility/rendering still assumes the earlier message-only model and the existence strategy is not contract-defined.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Update the coordinator to produce the new `bubbleItems` snapshot.
+
+Update `shellBall.windowSync.ts` so bubble-region persistence is not driven only by `visualState`.
+
+Update `ShellBallBubbleWindow.tsx`, `ShellBallBubbleZone.tsx`, and `useShellBallWindowMetrics.ts` so the bubble region only renders unpinned items while the bubble window existence strategy is explicit and the interaction mode follows content state.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for the chosen existence strategy contract and unpinned-only rendering.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts apps/desktop/src/features/shell-ball/shellBall.windowSync.ts apps/desktop/src/features/shell-ball/ShellBallBubbleWindow.tsx apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): define bubble window existence strategy"
+```
+
+### Task 3: Add Per-Bubble Pin and Delete Controls
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing render/behavior test**
+
+Add tests asserting that each bubble renders:
+- a pin control at top-left
+- a delete control at top-right
+
+And that the coordinator exposes handlers that:
+- set `bubble.pinned = true` on pin
+- remove the bubble item on delete
+- switch the bubble window out of click-through mode when visible unpinned bubbles remain
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because bubble items do not yet have controls or state transitions.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Add pin/delete controls to `ShellBallBubbleMessage.tsx`.
+
+Thread handlers through `ShellBallBubbleZone.tsx`, implement the state transitions in the coordinator, and update the bubble window metrics path so the bubble window interaction mode follows visible content.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for pin/delete controls and local state transitions.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/components/ShellBallBubbleMessage.tsx apps/desktop/src/features/shell-ball/components/ShellBallBubbleZone.tsx apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): add bubble pin and delete controls"
+```
+
+### Task 4: Add Coordinator Ownership Contract for Pinned Bubble State
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing ownership contract test**
+
+Add tests asserting that:
+- pinned windows only render snapshot payloads from the coordinator
+- all `pin`, `unpin`, and `delete` actions round-trip through coordinator-owned events/state transitions
+- detached position may be local desktop state, but bubble-item existence/order is coordinator-owned
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because pinned-window ownership and action round-trip rules are not explicit yet.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Extend `shellBall.windowSync.ts` with the coordinator-owned pinned-window event contract.
+
+Update `useShellBallCoordinator.ts` to become the explicit source of truth for pin/unpin/delete state transitions before detached window implementation begins.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for pinned-window ownership/state contract.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/shellBall.windowSync.ts apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): define pinned bubble state ownership"
+```
+
+### Task 5: Create Detached Pinned Bubble Windows
+
+**Files:**
+- Create: `apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx`
+- Create: `apps/desktop/shell-ball-bubble-pinned.html`
+- Create: `apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx`
+- Modify: `apps/desktop/vite.config.ts`
+- Modify: `apps/desktop/src/platform/shellBallWindowController.ts`
+- Modify: `apps/desktop/src-tauri/capabilities/default.json`
+- Modify: `apps/desktop/src-tauri/gen/schemas/capabilities.json`
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.windowSync.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing window contract test**
+
+Add tests asserting that pinning a bubble:
+- assigns a deterministic pinned-window label using `bubble.bubble_id`
+- creates a detached window label for the bubble item
+- removes it from the bubble region view
+- renders the bubble item in a dedicated pinned-bubble window
+- keeps the pinned item outside normal bubble lifecycle rules
+- routes unpin/delete actions back through shell-ball-local pinned-window events
+- spawns the pinned window from a defined initial anchor near the bubble region
+- stops following shell-ball geometry after the user drags it
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because pinned windows do not exist yet.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Add the dedicated pinned bubble entrypoint and component.
+
+Extend `shellBallWindowController.ts` with runtime create/open/close helpers for pinned bubble windows.
+
+Extend `shellBall.windowSync.ts` with pinned-window event names and payloads.
+
+Update capabilities to allow the required create/show/hide/focus/drag behavior.
+
+Implement the pinned-window geometry contract explicitly:
+- initial spawn anchor comes from a named pinned-window anchor near the bubble region
+- free-dragged pinned windows stop following the shell-ball metrics flow after user drag
+- only the main bubble region remains on the shared helper-window metrics flow
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for detached pinned-window behavior.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/app/shell-ball-bubble-pinned/main.tsx apps/desktop/shell-ball-bubble-pinned.html apps/desktop/src/features/shell-ball/ShellBallPinnedBubbleWindow.tsx apps/desktop/vite.config.ts apps/desktop/src/platform/shellBallWindowController.ts apps/desktop/src-tauri/capabilities/default.json apps/desktop/src-tauri/gen/schemas/capabilities.json apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts apps/desktop/src/features/shell-ball/shellBall.windowSync.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): detach pinned bubbles into windows"
+```
+
+### Task 6: Support Unpin Return-by-Timestamp and Detached Delete Semantics
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing behavior/style test**
+
+Add tests asserting that:
+- unpinning destroys the detached window and restores the bubble item into bubble-region order by `bubble.created_at`, then `bubble.bubble_id`
+- deleting from a detached window destroys the bubble item entirely
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because unpin restore ordering and detached delete semantics are not implemented yet.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Implement unpin restore ordering in the coordinator using `bubble.created_at`, then `bubble.bubble_id`.
+
+Finish the detached delete path.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for unpin return and detached delete behavior.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/useShellBallCoordinator.ts apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): restore pinned bubbles to region order"
+```
+
+### Task 7: Tune Bubble-Region Offset Closer to the Shell-Ball
+
+**Files:**
+- Modify: `apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.css`
+- Modify: `apps/desktop/src/features/shell-ball/shellBall.contract.test.ts`
+
+- [ ] **Step 1: Write the failing offset contract test**
+
+Add tests asserting that:
+- bubble region anchor uses named constants
+- the region is closer to the shell-ball than the current baseline
+- the chosen offset still does not overlap the ball frame
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: FAIL because the old anchor gap constants still reflect the previous offset.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Tune the bubble-region anchor gap in `useShellBallWindowMetrics.ts` and any supporting CSS constants so the region sits lower and closer to the shell-ball using named constants and verified no-overlap behavior.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS for bubble-region offset tuning.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/desktop/src/features/shell-ball/useShellBallWindowMetrics.ts apps/desktop/src/features/shell-ball/shellBall.css apps/desktop/src/features/shell-ball/shellBall.contract.test.ts
+git commit -m "feat(desktop-shell-ball): tune bubble region anchor"
+```
+
+### Task 8: Verify Bubble Region and Detached Window Behavior End-to-End
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: Run shell-ball tests**
+
+Run: `pnpm --dir apps/desktop test:shell-ball`
+Expected: PASS.
+
+- [ ] **Step 2: Run typecheck**
+
+Run: `pnpm --dir apps/desktop typecheck`
+Expected: PASS.
+
+- [ ] **Step 3: Run build**
+
+Run: `pnpm --dir apps/desktop build`
+Expected: PASS.
+
+- [ ] **Step 4: Run the desktop app manually**
+
+Run: `pnpm --dir apps/desktop exec tauri dev`
+
+Expected:
+- bubble region stays visually transparent when empty
+- each new bubble appears in timestamp order within the bubble region
+- pin creates a detached window and removes the bubble from the bubble region
+- detached windows are draggable and stay alive regardless of bubble fade/disperse behavior
+- unpin returns the bubble to the region at its timestamp position
+- delete removes the bubble immediately from either location
+- bubble region sits closer to the shell-ball without overlapping it
+
+- [ ] **Step 5: Commit only if manual verification required a follow-up fix**
+
+Run: `git status --short`
+Expected: clean working tree; if not, commit with:
+
+```bash
+git add <fixed-files>
+git commit -m "feat(desktop-shell-ball): polish pinned bubble behavior"
+```