docs(web): align whale animation and modal cache descriptions

packages/client/shortcuts/src/client/dom.ts

@@ -21,12 +21,12 @@ export function detectEnvironment(document: Document, navigator: Navigator): {
 }
 
 /**
- * Install document composition tracking and application dispatch after local handlers.
+ * Install document composition tracking, modal-cache invalidation, and dispatch after local handlers.
  * @param window - input window owned by the client plugin.
  * @param shortcuts - command registry for this window.
  * @param fixed - optional fixed-sequence consumer after local controls.
  * @param native - native input owns configurable bindings; DOM delivery only feeds fixed actions.
- * @returns disposer releasing every listener.
+ * @returns disposer releasing every listener, the modal observer, and cached nodes.
  */
 export function installKeyboard(window: Window, shortcuts: Pick<ShortcutRegistry, 'dispatch' | 'runtime' | 'platform'>,
   fixed?: (input: ShortcutFixedInput) => void, native = false): () => void {
@@ -69,6 +69,7 @@ export function installKeyboard(window: Window, shortcuts: Pick<ShortcutRegistry
     const element = target instanceof Element ? target : document.activeElement
     const region = element?.closest('.xterm') ? 'terminal'
       : element?.closest('input, textarea, select, [contenteditable="true"], [contenteditable=""]') ? 'editable' : 'page'
+    // Local handlers can change modals before MutationObserver delivers its records.
     changedModals(observer.takeRecords())
     dialogs ??= document.querySelectorAll<HTMLElement>(modalSelector)
     const top = dialogs[dialogs.length - 1]

packages/client/ui-chat/README.i18n.yaml

@@ -33,8 +33,8 @@
   en: 0ca3e8c4eab1ca78
   zh: 1a1c71bab151eb7d
 /deepseek-ai-dsh-client-ui-chat/grouped-rendering:
-  en: 1ccc8de0d1ca0481
-  zh: 156cdfb5b6ba6490
+  en: 1dc0ab19a6469e37
+  zh: 75c788f1b7b214e5
 /deepseek-ai-dsh-client-ui-chat/scroll-ownership:
   en: 69b021c5a5d8b5a7
   zh: 091ae7986c7a8a20
@@ -45,8 +45,8 @@
   en: 15a7151ff9268f15
   zh: 6eae68c718be579b
 /deepseek-ai-dsh-client-ui-chat/known-limitations-and-deferred-work:
-  en: 1e7e55adf5c87246
-  zh: dd5befdf58ea084f
+  en: 811787a5d2feaa90
+  zh: 3f1697bbc1fc7691
 /deepseek-ai-dsh-client-ui-chat/known-limitations-and-deferred-work/dev-note:
   en: b8b7eeb4ae675d2a
   zh: fbe7022074ba81b9

packages/client/ui-chat/README.md

@@ -97,6 +97,8 @@ The process group uses a stable `div` layout box, a scroll body, and an uncapped
 
 Running group titles, reasoning previews, tool and command rows, the active retry line, and the bottom running status use the shared [TextShimmer](../ui-primitives/README.md#component-catalog). Each row’s text shares one left-to-right highlight, including collapsed group titles; icons and hover chevrons retain their base appearance. Tool and process rows sit 6px apart. An expanded group title has 8px before its content, Assistant responses have 12px from adjacent process rows, and completed-Turn duration/status controls have 16px around them. Hidden and empty rows, including retained empty slot anchors, add no gap. The running “Deep diving” text retains its blue base while its theme-specific highlight sweeps across it.
 
+The running status shows a whale whose APNG mask inherits the text color. CSS selects the static SVG when reduced motion or forced colors are active, or alpha masks are unsupported. The build embeds the image in the plugin stylesheet; React does not pass image data through DOM styles.
+
 Scroll-edge fades initialize when `ResizeObserver` reports the open group's layout; opening the group performs no immediate scroll-dimension read in a layout effect.
 
 Each group owns local `useDisclosure` state that survives mode changes while its component stays mounted.
@@ -159,6 +161,7 @@ None; Chat presentation does not assemble or mutate provider requests.
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- **Running-icon resolution** — the animated whale uses a 28×28 image at a default 14×14 CSS size. Larger content fonts or device pixel ratios above 2 can soften the raster stroke; the static fallback remains vector-based. Browser image caching owns the animation clock, so remounting does not guarantee playback restarts at the first frame.
 
 - **Tool-change presentation** — The `developer-message` Definition shares context presentation with `input-message`. Tool-only developer messages name a single added or removed tool inline without expansion. Multiple changes show added/removed counts and expand to comma-separated tool lists, one line per change kind. Mixed content uses the generic context presentation.
 

packages/client/ui-chat/README.zh.md

@@ -97,6 +97,8 @@ Chat 通过 `uiConversation.groups` 注册过程 Group Definition。React 通过
 
 运行中的分组标题、思考预览、工具与命令行、当前重试行以及底部运行状态使用共享的 [TextShimmer](../ui-primitives/README.zh.md#component-catalog)。每行的文字共用一道从左到右的高光，包括折叠的分组标题；图标和悬停箭头保留底色。工具和过程行之间相隔 6px；展开的分组标题与内容之间相隔 8px；Assistant 回复与相邻过程行之间相隔 12px；每轮完成／耗时控件周围保留 16px。隐藏行与空行（包括保留的空 slot 锚点）不产生间距。“深度求索”运行文字保留蓝色底色，并使用主题专用高光扫过文字。
 
+运行状态显示一只鲸鱼，其 APNG 遮罩继承文字颜色。启用减少动态效果或强制颜色模式、或浏览器不支持 alpha 遮罩时，CSS 选择静态 SVG。构建将图片嵌入插件样式表；React 不通过 DOM 样式传递图片数据。
+
 滚动边缘渐隐在 `ResizeObserver` 报告已展开组的布局后初始化；展开组时不会在 layout effect 中立即读取滚动尺寸。
 
 每个组拥有本地 `useDisclosure` 状态，组件保持挂载时，模式切换保留该状态。
@@ -159,6 +161,7 @@ Chat 会在历史前插与 renderer 重新挂载时恢复语义锚点，并且
 
 <a id="known-limitations-and-deferred-work"></a>
 
+- **运行图标分辨率**——动态鲸鱼使用 28×28 图片，默认 CSS 尺寸为 14×14。较大的正文字号或大于 2 的设备像素比可能使位图描边变模糊；静态回退图标仍为矢量图。浏览器图片缓存管理动画时钟，因此重新挂载不保证从第一帧重新播放。
 
 - **工具变更展示** — `developer-message` Definition 与 `input-message` 共用上下文展示。仅包含工具变更的 developer 消息在单个工具新增或移除时直接显示工具名，不提供展开操作。多个变更显示新增、移除数量，展开后按变更类型分别以逗号分隔显示一行工具列表。混合内容使用通用上下文展示。
 

packages/client/ui-chat/src/client/chat/RunningWhaleTail.tsx

@@ -1,12 +1,11 @@
-/** Native SVG contour animation for the whale Chat shows while the Session runs. */
+/** Animated whale mask and static SVG fallback for the running Chat status. */
 import css from './ChatView.module.css'
 
-/** Same cubic segments in every pose keep both tail-base endpoints stationary. */
 const REST_PATH = 'M8.844 13.742C8.967 12.328 8.45 10.4 8.45 9.65C8.45 8.94 8.88 8.43 9.6 8.43C11.285 8.43 12.106 8.281 12.685 8.104C13.71 7.791 14.585 6.768 15.055 5.945C15.137 5.803 14.99 5.641 14.829 5.671C13.829 5.86 12.828 5.376 11.827 4.978C10.659 4.514 9.491 4.707 8.935 4.876C8.805 4.915 8.658 4.819 8.636 4.686C8.468 3.643 7.405 2.615 5.498 2.238C4.54 2.048 3.748 1.574 3.347 1.202C3.252 1.113 3.088 1.125 3.03 1.242C2.628 2.059 2.168 3.82 5.248 6.115C5.82 6.494 6.31 6.785 6.574 7.637C6.72 8.104 6.157 9.168 6.061 9.368C5.157 11.27 5.089 12.19 4.926 13.742'
 
 /**
- * Loop the tail every three seconds after a 0.3s delay.
- * @returns animated and resting contours switched by the reduced-motion stylesheet.
+ * Render the decorative running icon; the APNG asset owns its animation timing.
+ * @returns mask and static SVG selected by browser capabilities and accessibility preferences.
  */
 export function RunningWhaleTail() {
   return (