From 3f7f6c529bc73e119e7329a2cd084421bd7fe5f9 Mon Sep 17 00:00:00 2001
From: gene9831 <pacify.98@gmail.com>
Date: Thu, 3 Sep 2026 16:56:15 +0800
Subject: [PATCH 1/4] test(components): add contract coverage

---
 docs/src/components/container.md              |   4 +
 packages/components/src/container/index.ts    |  15 +-
 .../components/src/dropdown-menu/index.vue    |  82 ++++++++-
 .../src/history/components/MenuList.vue       |  54 +++++-
 .../history/composables/useRenameEditor.ts    |   4 +-
 packages/components/src/history/index.vue     |  59 ++++++-
 .../test/component/bubble/Bubble.fixture.vue  |  65 +++++++
 packages/test/component/bubble/Bubble.spec.ts |  58 +++++++
 .../component/bubble/BubbleList.fixture.vue   | 157 +++++++++++++++++
 .../test/component/bubble/BubbleList.spec.ts  |  92 ++++++++++
 .../bubble/BubbleProvider.fixture.vue         | 100 +++++++++++
 .../component/bubble/BubbleProvider.spec.ts   |  63 +++++++
 .../component/bubble/FallbackBoxRenderer.vue  |   9 +
 .../bubble/FallbackContentRenderer.vue        |   9 +
 .../bubble/SecondaryContentRenderer.vue       |   9 +
 .../test/component/bubble/TestBoxRenderer.vue |   9 +
 .../component/bubble/TestContentRenderer.vue  |  29 ++++
 .../dropdown-menu/DropdownMenu.fixture.vue    |  67 ++++++++
 .../dropdown-menu/DropdownMenu.spec.ts        | 123 ++++++++++++++
 .../ExtensionCard.fixture.vue                 |   3 +-
 .../ExtensionCardActionEvent.fixture.vue      |   3 +-
 .../component/history/History.fixture.vue     | 111 ++++++++++++
 .../test/component/history/History.spec.ts    | 160 ++++++++++++++++++
 .../theme-provider/ThemeConsumer.vue          |  27 +++
 .../theme-provider/ThemeProvider.fixture.vue  |  64 +++++++
 .../theme-provider/ThemeProvider.spec.ts      | 123 ++++++++++++++
 .../component/welcome/Welcome.fixture.vue     |  20 +++
 .../test/component/welcome/Welcome.spec.ts    |  27 +++
 packages/test/package.json                    |   1 +
 packages/test/tsconfig.ct.json                |   9 +
 30 files changed, 1536 insertions(+), 20 deletions(-)
 create mode 100644 packages/test/component/bubble/Bubble.fixture.vue
 create mode 100644 packages/test/component/bubble/Bubble.spec.ts
 create mode 100644 packages/test/component/bubble/BubbleList.fixture.vue
 create mode 100644 packages/test/component/bubble/BubbleList.spec.ts
 create mode 100644 packages/test/component/bubble/BubbleProvider.fixture.vue
 create mode 100644 packages/test/component/bubble/BubbleProvider.spec.ts
 create mode 100644 packages/test/component/bubble/FallbackBoxRenderer.vue
 create mode 100644 packages/test/component/bubble/FallbackContentRenderer.vue
 create mode 100644 packages/test/component/bubble/SecondaryContentRenderer.vue
 create mode 100644 packages/test/component/bubble/TestBoxRenderer.vue
 create mode 100644 packages/test/component/bubble/TestContentRenderer.vue
 create mode 100644 packages/test/component/dropdown-menu/DropdownMenu.fixture.vue
 create mode 100644 packages/test/component/dropdown-menu/DropdownMenu.spec.ts
 create mode 100644 packages/test/component/history/History.fixture.vue
 create mode 100644 packages/test/component/history/History.spec.ts
 create mode 100644 packages/test/component/theme-provider/ThemeConsumer.vue
 create mode 100644 packages/test/component/theme-provider/ThemeProvider.fixture.vue
 create mode 100644 packages/test/component/theme-provider/ThemeProvider.spec.ts
 create mode 100644 packages/test/component/welcome/Welcome.fixture.vue
 create mode 100644 packages/test/component/welcome/Welcome.spec.ts
 create mode 100644 packages/test/tsconfig.ct.json

diff --git a/docs/src/components/container.md b/docs/src/components/container.md
index d8eb8566c..6c8acf482 100644
--- a/docs/src/components/container.md
+++ b/docs/src/components/container.md
@@ -1,9 +1,13 @@
 ---
 outline: [1, 3]
+badge: deprecated
 ---
 
 # Container 容器
 
+> [!WARNING]
+> `Container` 已废弃，仅为兼容现有代码而保留。新布局请使用 [`Layout`](./layout.md)（`TrLayout`）。两者的 API 并非一一对应，迁移时请根据 Layout 的区域插槽、布局模式和浮层状态重新配置。
+
 ## 代码示例
 
 ### 基本示例
diff --git a/packages/components/src/container/index.ts b/packages/components/src/container/index.ts
index 58a652cae..76f84bfb3 100644
--- a/packages/components/src/container/index.ts
+++ b/packages/components/src/container/index.ts
@@ -1,12 +1,17 @@
 import { App } from 'vue'
-import Container from './index.vue'
+import ContainerComponent from './index.vue'
 
-Container.name = 'TrContainer'
+ContainerComponent.name = 'TrContainer'
 
 const install = function <T>(app: App<T>) {
-  app.component(Container.name!, Container)
+  app.component(ContainerComponent.name!, ContainerComponent)
 }
 
-Container.install = install
+ContainerComponent.install = install
 
-export default Container as typeof Container & { install: typeof install }
+/**
+ * @deprecated Container is kept for compatibility. Use `Layout` (`TrLayout`) for new layouts.
+ */
+const Container = ContainerComponent as typeof ContainerComponent & { install: typeof install }
+
+export default Container
diff --git a/packages/components/src/dropdown-menu/index.vue b/packages/components/src/dropdown-menu/index.vue
index d785e86f3..73fb6476f 100644
--- a/packages/components/src/dropdown-menu/index.vue
+++ b/packages/components/src/dropdown-menu/index.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { onClickOutside } from '@vueuse/core'
-import { computed, ref, watch } from 'vue'
+import { computed, nextTick, ref, watch, watchEffect } from 'vue'
 import TrBasePopper from '../base-popper'
 import { usePopperHover } from './composables/usePopperHover'
 import { DropdownMenuEmits, DropdownMenuItem, DropdownMenuProps } from './index.type'
@@ -33,6 +33,14 @@ const basePopperRef = ref<InstanceType<typeof TrBasePopper> | null>(null)
 const triggerRef = computed(() => basePopperRef.value?.triggerRef)
 const dropdownMenuRef = computed(() => basePopperRef.value?.popperRef)
 
+watchEffect(() => {
+  const trigger = triggerRef.value
+  if (!trigger) return
+
+  trigger.setAttribute('aria-haspopup', 'menu')
+  trigger.setAttribute('aria-expanded', String(Boolean(show.value)))
+})
+
 if (props.trigger === 'click' || props.trigger === 'manual') {
   onClickOutside(
     dropdownMenuRef,
@@ -56,9 +64,75 @@ const handleTriggerClick = () => {
   }
 }
 
+const focusTrigger = async () => {
+  await nextTick()
+  triggerRef.value?.focus()
+}
+
+const getMenuItems = () => {
+  return Array.from(dropdownMenuRef.value?.querySelectorAll<HTMLElement>('[role="menuitem"]') || [])
+}
+
+const focusMenuItem = async (position: 'first' | 'last') => {
+  await nextTick()
+  const items = getMenuItems()
+  items[position === 'first' ? 0 : items.length - 1]?.focus()
+}
+
+const handleTriggerKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    if (props.trigger === 'manual' && !show.value) return
+
+    event.preventDefault()
+    if (props.trigger !== 'manual') show.value = true
+    focusMenuItem(event.key === 'ArrowDown' ? 'first' : 'last')
+  } else if ((event.key === 'Enter' || event.key === ' ') && props.trigger !== 'manual') {
+    event.preventDefault()
+    show.value = true
+    focusMenuItem('first')
+  } else if (event.key === 'Escape' && show.value) {
+    event.preventDefault()
+    show.value = false
+  }
+}
+
+const handleMenuKeydown = (event: KeyboardEvent) => {
+  const items = getMenuItems()
+  const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+  if (event.key === 'Tab') {
+    if (props.trigger !== 'manual') show.value = false
+    return
+  }
+
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    show.value = false
+    focusTrigger()
+    return
+  }
+
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    items[currentIndex]?.click()
+    return
+  }
+
+  if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key) || items.length === 0) return
+
+  event.preventDefault()
+  let nextIndex = currentIndex
+  if (event.key === 'Home') nextIndex = 0
+  if (event.key === 'End') nextIndex = items.length - 1
+  if (event.key === 'ArrowDown') nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0
+  if (event.key === 'ArrowUp') nextIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1
+  items[nextIndex]?.focus()
+}
+
 const handleItemClick = (item: DropdownMenuItem) => {
   show.value = false
   emit('item-click', item)
+  focusTrigger()
 }
 
 defineExpose({
@@ -78,17 +152,19 @@ defineExpose({
     :offset="8"
     :transition-props="{ name: 'tr-dropdown-menu' }"
     :prevent-overflow="true"
-    :trigger-events="{ onClick: handleTriggerClick }"
+    :trigger-events="{ onClick: handleTriggerClick, onKeydown: handleTriggerKeydown }"
   >
     <template #trigger>
       <slot name="trigger" />
     </template>
     <template #content>
-      <ul class="tr-dropdown-menu__list">
+      <ul class="tr-dropdown-menu__list" role="menu" @keydown="handleMenuKeydown">
         <li
           class="tr-dropdown-menu__list-item"
           v-for="item in props.items"
           :key="item.id"
+          role="menuitem"
+          tabindex="-1"
           @click="handleItemClick(item)"
         >
           {{ item.text }}
diff --git a/packages/components/src/history/components/MenuList.vue b/packages/components/src/history/components/MenuList.vue
index 933f01617..f941a790a 100644
--- a/packages/components/src/history/components/MenuList.vue
+++ b/packages/components/src/history/components/MenuList.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts" generic="T">
 import { onClickOutside, useElementBounding, useElementSize, useWindowSize } from '@vueuse/core'
-import { computed, CSSProperties, ref } from 'vue'
+import { computed, CSSProperties, nextTick, ref } from 'vue'
 import { toCssUnit } from '../../shared/utils'
 import { HistoryMenuItem } from '../index.type'
 
@@ -60,11 +60,59 @@ const handleItemClick = (item: { id: string; text: string }) => {
   trigger.value = null
   data.value = null
 }
+
+const getMenuItems = () => Array.from(menuRef.value?.querySelectorAll<HTMLElement>('[role="menuitem"]') || [])
+
+const focusFirstItem = () => getMenuItems()[0]?.focus()
+const focusLastItem = () => getMenuItems().at(-1)?.focus()
+
+const closeAndFocusTrigger = () => {
+  const triggerElement = trigger.value
+  trigger.value = null
+  data.value = null
+  nextTick(() => triggerElement?.focus())
+}
+
+const handleKeydown = (event: KeyboardEvent) => {
+  const items = getMenuItems()
+  const currentIndex = items.indexOf(document.activeElement as HTMLElement)
+
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    closeAndFocusTrigger()
+    return
+  }
+
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    items[currentIndex]?.click()
+    return
+  }
+
+  if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key) || items.length === 0) return
+
+  event.preventDefault()
+  let nextIndex = currentIndex
+  if (event.key === 'Home') nextIndex = 0
+  if (event.key === 'End') nextIndex = items.length - 1
+  if (event.key === 'ArrowDown') nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0
+  if (event.key === 'ArrowUp') nextIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1
+  items[nextIndex]?.focus()
+}
+
+defineExpose({ focusFirstItem, focusLastItem })
 </script>
 
 <template>
-  <ul class="tr-history__menu-list" ref="menuRef" :style="styles">
-    <li class="tr-history__menu-list__item" v-for="item in props.items" :key="item.id" @click="handleItemClick(item)">
+  <ul class="tr-history__menu-list" ref="menuRef" :style="styles" role="menu" @keydown="handleKeydown">
+    <li
+      class="tr-history__menu-list__item"
+      v-for="item in props.items"
+      :key="item.id"
+      role="menuitem"
+      tabindex="-1"
+      @click="handleItemClick(item)"
+    >
       <component :is="item.icon" />
       <span>{{ item.text }}</span>
     </li>
diff --git a/packages/components/src/history/composables/useRenameEditor.ts b/packages/components/src/history/composables/useRenameEditor.ts
index 62c7b213c..d9e6a542c 100644
--- a/packages/components/src/history/composables/useRenameEditor.ts
+++ b/packages/components/src/history/composables/useRenameEditor.ts
@@ -1,5 +1,5 @@
 import { onClickOutside } from '@vueuse/core'
-import { computed, nextTick, ref, type Ref } from 'vue'
+import { computed, nextTick, ref, shallowRef, type Ref } from 'vue'
 
 export interface UseRenameEditorProps<T extends { title: string }> {
   renameControlOnClickOutside?: 'confirm' | 'cancel' | 'none'
@@ -21,7 +21,7 @@ export const useRenameEditor = <T extends { title: string }>({
   renameControlOnClickOutside,
   onItemTitleChange,
 }: UseRenameEditorProps<T>): UseRenameEditorReturn<T> => {
-  const editingItem = ref<T | undefined>(undefined) as Ref<T | undefined>
+  const editingItem = shallowRef<T | undefined>(undefined) as Ref<T | undefined>
   const editorRefList = ref<HTMLInputElement[] | null>(null)
   const editorRef = computed(() => editorRefList.value?.at(0))
   const editorConfirmRefList = ref<HTMLButtonElement[] | null>(null)
diff --git a/packages/components/src/history/index.vue b/packages/components/src/history/index.vue
index 255c76541..676205450 100644
--- a/packages/components/src/history/index.vue
+++ b/packages/components/src/history/index.vue
@@ -1,6 +1,6 @@
 <script lang="ts" setup generic="T extends HistoryItem">
 import { IconCheck, IconClose, IconDelete, IconEditPen, IconMore } from '@opentiny/tiny-robot-svgs'
-import { computed, ref, type Ref } from 'vue'
+import { computed, nextTick, ref, shallowRef } from 'vue'
 import { useTouchDevice } from '../shared/composables'
 import Empty from './components/Empty.vue'
 import MenuList from './components/MenuList.vue'
@@ -62,7 +62,18 @@ const {
 const { isTouchDevice } = useTouchDevice()
 
 const menuTriggerEl = ref<HTMLButtonElement | null>(null)
-const menuTriggerItem = ref<T | null>(null) as Ref<T | null>
+const menuTriggerItem = shallowRef<T | null>(null)
+const menuListRef = ref<{ focusFirstItem: () => void; focusLastItem: () => void } | null>(null)
+
+const focusMenuItem = (position: 'first' | 'last') => {
+  nextTick(() => {
+    if (position === 'first') {
+      menuListRef.value?.focusFirstItem()
+    } else {
+      menuListRef.value?.focusLastItem()
+    }
+  })
+}
 
 const toggleMenu = (ev: MouseEvent, item: T) => {
   if (ev.currentTarget instanceof HTMLButtonElement) {
@@ -74,14 +85,27 @@ const toggleMenu = (ev: MouseEvent, item: T) => {
 
     menuTriggerEl.value = ev.currentTarget
     menuTriggerItem.value = item
+    if (ev.detail === 0) focusMenuItem('first')
   } else {
     menuTriggerEl.value = null
     menuTriggerItem.value = null
   }
 }
 
+const handleMenuTriggerKeydown = (event: KeyboardEvent, item: T, position: 'first' | 'last') => {
+  event.preventDefault()
+  event.stopPropagation()
+
+  if (event.currentTarget instanceof HTMLButtonElement) {
+    menuTriggerEl.value = event.currentTarget
+    menuTriggerItem.value = item
+    focusMenuItem(position)
+  }
+}
+
 const handleClickMenuItem = (action: HistoryMenuItem) => {
   const item = menuTriggerItem.value
+  const trigger = menuTriggerEl.value
 
   if (!item) {
     return
@@ -89,6 +113,8 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
 
   if (action.id === 'rename') {
     handleEdit(item)
+  } else {
+    nextTick(() => trigger?.focus())
   }
   emit('item-action', action, item)
 }
@@ -131,6 +157,8 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
                 class="editor-confirm"
                 v-if="props.showRenameControls && editingItem === item"
                 ref="editorConfirmRefList"
+                type="button"
+                aria-label="确认重命名"
                 @click="handleEditConfirm"
               >
                 <IconCheck></IconCheck>
@@ -139,11 +167,23 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
                 class="editor-cancel"
                 v-if="props.showRenameControls && editingItem === item"
                 ref="editorCancelRefList"
+                type="button"
+                aria-label="取消重命名"
                 @click="handleEditCancel"
               >
                 <IconClose></IconClose>
               </button>
-              <button class="menu" :class="{ hidden: editingItem === item }" @click="(ev) => toggleMenu(ev, item)">
+              <button
+                class="menu"
+                :class="{ hidden: editingItem === item }"
+                type="button"
+                :aria-label="`${item.title} 更多操作`"
+                aria-haspopup="menu"
+                :aria-expanded="menuTriggerItem === item"
+                @click="(ev) => toggleMenu(ev, item)"
+                @keydown.down="(ev) => handleMenuTriggerKeydown(ev, item, 'first')"
+                @keydown.up="(ev) => handleMenuTriggerKeydown(ev, item, 'last')"
+              >
                 <IconMore></IconMore>
               </button>
             </span>
@@ -151,6 +191,7 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
         </div>
       </div>
       <MenuList
+        ref="menuListRef"
         v-show="menuTriggerEl"
         v-model:trigger="menuTriggerEl"
         v-model:data="menuTriggerItem"
@@ -169,7 +210,14 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
     & > .tr-history__item-actions {
       & > .menu {
         position: absolute;
-        visibility: hidden;
+        opacity: 0;
+        pointer-events: none;
+
+        &:focus-visible {
+          position: static;
+          opacity: 1;
+          pointer-events: auto;
+        }
       }
     }
   }
@@ -178,7 +226,8 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
     & > .tr-history__item-actions {
       & > .menu {
         position: static;
-        visibility: visible;
+        opacity: 1;
+        pointer-events: auto;
       }
     }
   }
diff --git a/packages/test/component/bubble/Bubble.fixture.vue b/packages/test/component/bubble/Bubble.fixture.vue
new file mode 100644
index 000000000..8fbe063bd
--- /dev/null
+++ b/packages/test/component/bubble/Bubble.fixture.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { h } from 'vue'
+import Bubble from '../../../components/src/bubble/Bubble.vue'
+import BubbleProvider from '../../../components/src/bubble/BubbleProvider.vue'
+import type { BubbleMessage } from '../../../components/src/bubble/index.type'
+import FallbackContentRenderer from './FallbackContentRenderer.vue'
+
+const avatar = h('span', { 'data-testid': 'bubble-avatar', 'aria-hidden': 'true' }, 'U')
+const splitContent: BubbleMessage['content'] = [
+  { type: 'text', text: 'First segment' },
+  { type: 'text', text: 'Second segment' },
+]
+const unresolvedContent: BubbleMessage['content'] = [{ type: 'unknown', label: 'Unknown segment' }]
+</script>
+
+<template>
+  <main>
+    <Bubble
+      data-testid="presentation-bubble"
+      role="user"
+      content="Hello bubble"
+      placement="end"
+      shape="rounded"
+      :avatar="avatar"
+    >
+      <template #prefix="{ role, messages }">
+        <span data-testid="bubble-prefix">{{ role }}:{{ messages.length }}</span>
+      </template>
+      <template #suffix="{ role, messages }">
+        <span data-testid="bubble-suffix">{{ role }}:{{ messages.length }}</span>
+      </template>
+      <template #after="{ role, messages }">
+        <span data-testid="bubble-after">{{ role }}:{{ messages.length }}</span>
+      </template>
+      <template #content-footer="{ role, messages, contentIndex }">
+        <span data-testid="bubble-footer">{{ role }}:{{ messages.length }}:{{ String(contentIndex) }}</span>
+      </template>
+    </Bubble>
+
+    <Bubble data-testid="empty-bubble" role="assistant" />
+    <Bubble data-testid="hidden-bubble" role="assistant" content="Hidden text" hidden />
+
+    <Bubble data-testid="split-bubble" role="assistant" :content="splitContent" content-render-mode="split">
+      <template #content-footer="{ contentIndex }">
+        <span data-testid="split-footer">footer-{{ contentIndex }}</span>
+      </template>
+    </Bubble>
+
+    <Bubble
+      data-testid="resolved-bubble"
+      role="assistant"
+      content="Original content"
+      :content-resolver="() => 'Resolved content'"
+    />
+
+    <BubbleProvider>
+      <Bubble
+        data-testid="fallback-bubble"
+        role="assistant"
+        :content="unresolvedContent"
+        :fallback-content-renderer="FallbackContentRenderer"
+      />
+    </BubbleProvider>
+  </main>
+</template>
diff --git a/packages/test/component/bubble/Bubble.spec.ts b/packages/test/component/bubble/Bubble.spec.ts
new file mode 100644
index 000000000..697505450
--- /dev/null
+++ b/packages/test/component/bubble/Bubble.spec.ts
@@ -0,0 +1,58 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import BubbleFixture from './Bubble.fixture.vue'
+
+test.describe('Bubble', () => {
+  test('renders presentation props and default text content', async ({ mount }) => {
+    const component = await mount(BubbleFixture)
+    const bubble = component.getByTestId('presentation-bubble')
+    const box = bubble.locator('[data-box-type="box"]')
+
+    await expect(bubble).toContainText('Hello bubble')
+    await expect(bubble).toHaveAttribute('data-role', 'user')
+    await expect(bubble).toHaveAttribute('data-placement', 'end')
+    await expect(box).toHaveAttribute('data-placement', 'end')
+    await expect(box).toHaveAttribute('data-shape', 'rounded')
+    await expect(bubble.getByTestId('bubble-avatar')).toHaveText('U')
+  })
+
+  test('forwards messages and role to every named slot', async ({ mount }) => {
+    const component = await mount(BubbleFixture)
+    const bubble = component.getByTestId('presentation-bubble')
+
+    await expect(bubble.getByTestId('bubble-prefix')).toHaveText('user:1')
+    await expect(bubble.getByTestId('bubble-suffix')).toHaveText('user:1')
+    await expect(bubble.getByTestId('bubble-after')).toHaveText('user:1')
+    await expect(bubble.getByTestId('bubble-footer')).toHaveText('user:1:undefined')
+  })
+
+  test('renders an empty message without text and hides hidden messages', async ({ mount }) => {
+    const component = await mount(BubbleFixture)
+
+    await expect(component.getByTestId('empty-bubble').locator('[data-type="text"]')).toHaveCount(0)
+    await expect(component.getByTestId('hidden-bubble')).toBeHidden()
+  })
+
+  test('splits array content into boxes and exposes each footer index', async ({ mount }) => {
+    const component = await mount(BubbleFixture)
+    const bubble = component.getByTestId('split-bubble')
+
+    await expect(bubble.locator('[data-box-type="box"]')).toHaveCount(2)
+    await expect(bubble.locator('[data-type="text"]')).toHaveText(['First segment', 'Second segment'])
+    await expect(bubble.getByTestId('split-footer')).toHaveText(['footer-0', 'footer-1'])
+  })
+
+  test('renders content returned by contentResolver', async ({ mount }) => {
+    const component = await mount(BubbleFixture)
+
+    await expect(component.getByTestId('resolved-bubble')).toContainText('Resolved content')
+    await expect(component.getByTestId('resolved-bubble')).not.toContainText('Original content')
+  })
+
+  test('prefers a Bubble-level fallback content renderer', async ({ mount }) => {
+    const component = await mount(BubbleFixture)
+
+    await expect(component.getByTestId('fallback-bubble').getByTestId('fallback-content-renderer')).toHaveText(
+      'Fallback content 0',
+    )
+  })
+})
diff --git a/packages/test/component/bubble/BubbleList.fixture.vue b/packages/test/component/bubble/BubbleList.fixture.vue
new file mode 100644
index 000000000..97ca33684
--- /dev/null
+++ b/packages/test/component/bubble/BubbleList.fixture.vue
@@ -0,0 +1,157 @@
+<script setup lang="ts">
+import { markRaw, ref } from 'vue'
+import BubbleList from '../../../components/src/bubble/BubbleList.vue'
+import BubbleProvider from '../../../components/src/bubble/BubbleProvider.vue'
+import type {
+  BubbleContentRendererMatch,
+  BubbleEvent,
+  BubbleMessage,
+  BubbleMessageGroup,
+} from '../../../components/src/bubble/index.type'
+import TestContentRenderer from './TestContentRenderer.vue'
+
+const dividerMessages: BubbleMessage[] = [
+  { id: 'u1', role: 'user', content: 'Question one' },
+  { id: 'a1', role: 'assistant', content: 'Answer one' },
+  { id: 'a2', role: 'assistant', content: 'Answer continued' },
+  { id: 'u2', role: 'user', content: 'Question two' },
+  { id: 'a3', role: 'assistant', content: 'Answer two' },
+]
+
+const consecutiveMessages: BubbleMessage[] = [
+  { id: 'a1', role: 'assistant', content: 'Assistant one' },
+  { id: 'a2', role: 'assistant', content: 'Assistant two' },
+  { id: 's1', role: 'secret', content: 'Hidden one' },
+  { id: 'h1', role: 'hidden-tool', content: 'Hidden two' },
+  { id: 'u1', role: 'user', content: 'User one' },
+]
+
+const fallbackMessages: BubbleMessage[] = [{ id: 'fallback', content: 'Ignored fallback content' }]
+
+const eventMessages: BubbleMessage[] = [
+  { id: 'm0', role: 'assistant', content: [{ type: 'custom', text: 'Message zero' }] },
+  { id: 'm1', role: 'assistant', content: [{ type: 'custom', text: 'Message one' }] },
+  { id: 'm2', role: 'assistant', content: [{ type: 'custom', text: 'Message two' }] },
+]
+
+const customGroup = (messages: BubbleMessage[]): BubbleMessageGroup[] => [
+  {
+    role: 'assistant',
+    messages: [messages[2], messages[0]],
+    messageIndexes: [2, 0],
+  },
+]
+
+const contentMatches: BubbleContentRendererMatch[] = [
+  {
+    find: (_message, content) => content.type === 'custom',
+    renderer: markRaw(TestContentRenderer),
+    priority: -10,
+  },
+]
+
+const lastStateChange = ref('')
+const lastBubbleEvent = ref('')
+
+const recordState = (payload: unknown) => {
+  lastStateChange.value = JSON.stringify(payload)
+}
+
+const recordBubbleEvent = (payload: BubbleEvent & { messageIndex: number; contentIndex: number }) => {
+  lastBubbleEvent.value = JSON.stringify(payload)
+}
+
+const scrollMessages = ref<BubbleMessage[]>(
+  Array.from({ length: 12 }, (_, index) => ({
+    id: `scroll-${index}`,
+    role: 'assistant',
+    content: `Scrollable message ${index}`,
+  })),
+)
+const scrollList = ref<{ scrollToBottom: (behavior?: ScrollBehavior) => Promise<void> } | null>(null)
+
+const appendUserMessage = () => {
+  scrollMessages.value.push({ id: 'latest-user', role: 'user', content: 'Latest user message' })
+}
+</script>
+
+<template>
+  <main>
+    <section data-testid="divider-list">
+      <BubbleList :messages="dividerMessages">
+        <template #prefix="{ role, messages, messageIndexes }">
+          <span data-testid="list-prefix">{{ role }}:{{ messageIndexes.join(',') }}:{{ messages.length }}</span>
+        </template>
+        <template #suffix="{ role, messageIndexes }">
+          <span data-testid="list-suffix">{{ role }}:{{ messageIndexes.join(',') }}</span>
+        </template>
+        <template #after="{ role, messageIndexes }">
+          <span data-testid="list-after">{{ role }}:{{ messageIndexes.join(',') }}</span>
+        </template>
+        <template #content-footer="{ role, messageIndexes, contentIndex }">
+          <span data-testid="list-footer"> {{ role }}:{{ messageIndexes.join(',') }}:{{ String(contentIndex) }} </span>
+        </template>
+      </BubbleList>
+    </section>
+
+    <section data-testid="consecutive-list">
+      <BubbleList
+        :messages="consecutiveMessages"
+        group-strategy="consecutive"
+        :role-configs="{ secret: { hidden: true }, 'hidden-tool': { hidden: true } }"
+      >
+        <template #prefix="{ role, messageIndexes }">
+          <span data-testid="consecutive-group">{{ role }}:{{ messageIndexes.join(',') }}</span>
+        </template>
+      </BubbleList>
+    </section>
+
+    <section data-testid="fallback-list">
+      <BubbleList
+        :messages="fallbackMessages"
+        fallback-role="assistant"
+        :role-configs="{ assistant: { placement: 'end', shape: 'rounded' } }"
+        :content-resolver="(message) => `Resolved ${message.id}`"
+      />
+    </section>
+
+    <section data-testid="custom-list">
+      <BubbleProvider :content-renderer-matches="contentMatches">
+        <BubbleList
+          :messages="eventMessages"
+          :group-strategy="customGroup"
+          @state-change="recordState"
+          @bubble-event="recordBubbleEvent"
+        >
+          <template #prefix="{ messageIndexes }">
+            <span data-testid="custom-indexes">{{ messageIndexes.join(',') }}</span>
+          </template>
+        </BubbleList>
+      </BubbleProvider>
+      <output data-testid="list-state-output">{{ lastStateChange }}</output>
+      <output data-testid="list-event-output">{{ lastBubbleEvent }}</output>
+    </section>
+
+    <section data-testid="scroll-section">
+      <button type="button" @click="scrollList?.scrollToBottom('auto')">Scroll to bottom</button>
+      <button type="button" @click="appendUserMessage">Append user message</button>
+      <BubbleList
+        ref="scrollList"
+        data-testid="scroll-list"
+        class="scroll-list"
+        :messages="scrollMessages"
+        :auto-scroll="true"
+      />
+    </section>
+  </main>
+</template>
+
+<style scoped>
+.scroll-list {
+  height: 100px;
+}
+
+.scroll-list :deep([data-type='text']) {
+  min-height: 24px;
+}
+</style>
diff --git a/packages/test/component/bubble/BubbleList.spec.ts b/packages/test/component/bubble/BubbleList.spec.ts
new file mode 100644
index 000000000..f9353a1d7
--- /dev/null
+++ b/packages/test/component/bubble/BubbleList.spec.ts
@@ -0,0 +1,92 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import BubbleListFixture from './BubbleList.fixture.vue'
+
+test.describe('BubbleList', () => {
+  test('groups messages by the default divider strategy', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const list = component.getByTestId('divider-list')
+
+    await expect(list.getByTestId('list-prefix')).toHaveText([
+      'user:0:1',
+      'assistant:1,2:2',
+      'user:3:1',
+      'assistant:4:1',
+    ])
+    await expect(list.locator('.tr-bubble')).toHaveCount(4)
+  })
+
+  test('forwards every named slot with original message indexes', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const list = component.getByTestId('divider-list')
+
+    await expect(list.getByTestId('list-suffix')).toHaveText(['user:0', 'assistant:1,2', 'user:3', 'assistant:4'])
+    await expect(list.getByTestId('list-after')).toHaveCount(4)
+    await expect(list.getByTestId('list-footer')).toHaveText([
+      'user:0:undefined',
+      'assistant:1,2:undefined',
+      'user:3:undefined',
+      'assistant:4:undefined',
+    ])
+  })
+
+  test('groups consecutive roles while isolating adjacent hidden roles', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const list = component.getByTestId('consecutive-list')
+
+    await expect(list.getByTestId('consecutive-group')).toHaveText(['assistant:0,1', 'secret:2,3', 'user:4'])
+    await expect(list.locator('.tr-bubble')).toHaveCount(3)
+    await expect(list.locator('.tr-bubble').nth(1)).toBeHidden()
+  })
+
+  test('uses fallbackRole configuration and the list contentResolver', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const bubble = component.getByTestId('fallback-list').locator('.tr-bubble')
+
+    await expect(bubble).toHaveAttribute('data-placement', 'end')
+    await expect(bubble.locator('[data-box-type="box"]')).toHaveAttribute('data-shape', 'rounded')
+    await expect(bubble).toContainText('Resolved fallback')
+  })
+
+  test('preserves non-contiguous custom indexes and maps state events globally', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const list = component.getByTestId('custom-list')
+
+    await expect(list.getByTestId('custom-indexes')).toHaveText('2,0')
+    await expect(list.getByTestId('test-content-renderer')).toHaveCount(2)
+
+    await list.getByRole('button', { name: 'Update bubble state' }).first().click()
+    await expect(list.getByTestId('list-state-output')).toHaveText(
+      JSON.stringify({ key: 'expanded', value: true, contentIndex: 0, messageIndex: 2 }),
+    )
+  })
+
+  test('maps custom bubble events back to the original message index', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const list = component.getByTestId('custom-list')
+
+    await list.getByRole('button', { name: 'Retry bubble' }).nth(1).click()
+    await expect(list.getByTestId('list-event-output')).toHaveText(
+      JSON.stringify({ name: 'retry', payload: { source: 'renderer' }, contentIndex: 0, messageIndex: 0 }),
+    )
+  })
+
+  test('exposes scrollToBottom and auto-scrolls a newly appended user message', async ({ mount }) => {
+    const component = await mount(BubbleListFixture)
+    const section = component.getByTestId('scroll-section')
+    const list = section.getByTestId('scroll-list')
+
+    await list.evaluate((element) => {
+      element.scrollTop = 0
+    })
+    await section.getByRole('button', { name: 'Scroll to bottom' }).click()
+    await expect
+      .poll(() => list.evaluate((element) => element.scrollHeight - element.scrollTop - element.clientHeight))
+      .toBeLessThanOrEqual(1)
+
+    await section.getByRole('button', { name: 'Append user message' }).click()
+    await expect(list).toContainText('Latest user message')
+    await expect
+      .poll(() => list.evaluate((element) => element.scrollHeight - element.scrollTop - element.clientHeight))
+      .toBeLessThanOrEqual(1)
+  })
+})
diff --git a/packages/test/component/bubble/BubbleProvider.fixture.vue b/packages/test/component/bubble/BubbleProvider.fixture.vue
new file mode 100644
index 000000000..dd5aaf0c3
--- /dev/null
+++ b/packages/test/component/bubble/BubbleProvider.fixture.vue
@@ -0,0 +1,100 @@
+<script setup lang="ts">
+import { markRaw, ref } from 'vue'
+import Bubble from '../../../components/src/bubble/Bubble.vue'
+import BubbleProvider from '../../../components/src/bubble/BubbleProvider.vue'
+import type {
+  BubbleBoxRendererMatch,
+  BubbleContentRendererMatch,
+  BubbleEvent,
+  BubbleMessage,
+} from '../../../components/src/bubble/index.type'
+import FallbackBoxRenderer from './FallbackBoxRenderer.vue'
+import FallbackContentRenderer from './FallbackContentRenderer.vue'
+import SecondaryContentRenderer from './SecondaryContentRenderer.vue'
+import TestBoxRenderer from './TestBoxRenderer.vue'
+import TestContentRenderer from './TestContentRenderer.vue'
+
+const customContent: BubbleMessage['content'] = [{ type: 'custom', text: 'Provider content' }]
+const unknownContent: BubbleMessage['content'] = [{ type: 'unknown', label: 'Unknown content' }]
+
+const contentMatches: BubbleContentRendererMatch[] = [
+  {
+    find: (_message, content) => content.type === 'custom',
+    renderer: markRaw(SecondaryContentRenderer),
+    priority: 20,
+  },
+  {
+    find: (_message, content) => content.type === 'custom',
+    renderer: markRaw(TestContentRenderer),
+    priority: -10,
+    attributes: { 'data-match-attribute': 'content-priority' },
+  },
+]
+
+const boxMatches: BubbleBoxRendererMatch[] = [
+  {
+    find: (_messages, content) => content?.type === 'custom',
+    renderer: markRaw(TestBoxRenderer),
+    priority: -10,
+    attributes: { 'data-match-attribute': 'box-priority' },
+  },
+]
+
+const lastStateChange = ref('')
+const lastBubbleEvent = ref('')
+
+const recordState = (payload: unknown) => {
+  lastStateChange.value = JSON.stringify(payload)
+}
+
+const recordBubbleEvent = (payload: BubbleEvent & { messageIndex: number; contentIndex: number }) => {
+  lastBubbleEvent.value = JSON.stringify(payload)
+}
+</script>
+
+<template>
+  <main>
+    <section data-testid="matched-provider">
+      <BubbleProvider
+        :box-renderer-matches="boxMatches"
+        :content-renderer-matches="contentMatches"
+        :box-attributes="(_messages, _content, index) => ({ 'data-provider-box-index': String(index) })"
+        :content-attributes="(_message, _content, index) => ({ 'data-provider-content-index': String(index) })"
+        :store="{ label: 'provider-store' }"
+      >
+        <Bubble
+          role="assistant"
+          :content="customContent"
+          content-render-mode="split"
+          @state-change="recordState"
+          @bubble-event="recordBubbleEvent"
+        />
+      </BubbleProvider>
+      <output data-testid="state-output">{{ lastStateChange }}</output>
+      <output data-testid="event-output">{{ lastBubbleEvent }}</output>
+    </section>
+
+    <section data-testid="provider-fallbacks">
+      <BubbleProvider
+        :fallback-box-renderer="FallbackBoxRenderer"
+        :fallback-content-renderer="SecondaryContentRenderer"
+      >
+        <Bubble role="assistant" :content="unknownContent" />
+        <Bubble
+          data-testid="prop-fallback-bubble"
+          role="assistant"
+          :content="unknownContent"
+          :fallback-content-renderer="FallbackContentRenderer"
+        />
+      </BubbleProvider>
+    </section>
+
+    <section data-testid="nested-provider">
+      <BubbleProvider :content-renderer-matches="contentMatches" :store="{ label: 'outer-store' }">
+        <BubbleProvider :content-renderer-matches="contentMatches" :store="{ label: 'inner-store' }">
+          <Bubble role="assistant" :content="customContent" />
+        </BubbleProvider>
+      </BubbleProvider>
+    </section>
+  </main>
+</template>
diff --git a/packages/test/component/bubble/BubbleProvider.spec.ts b/packages/test/component/bubble/BubbleProvider.spec.ts
new file mode 100644
index 000000000..761c6e703
--- /dev/null
+++ b/packages/test/component/bubble/BubbleProvider.spec.ts
@@ -0,0 +1,63 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import BubbleProviderFixture from './BubbleProvider.fixture.vue'
+
+test.describe('BubbleProvider', () => {
+  test('uses the lowest-priority matching content and box renderers', async ({ mount }) => {
+    const component = await mount(BubbleProviderFixture)
+    const provider = component.getByTestId('matched-provider')
+
+    await expect(provider.getByTestId('test-content-renderer')).toContainText('Provider content')
+    await expect(provider.getByTestId('secondary-content-renderer')).toHaveCount(0)
+    await expect(provider.getByTestId('test-box-renderer')).toBeVisible()
+  })
+
+  test('merges provider and match attributes onto renderer roots', async ({ mount }) => {
+    const component = await mount(BubbleProviderFixture)
+    const provider = component.getByTestId('matched-provider')
+
+    await expect(provider.getByTestId('test-box-renderer')).toHaveAttribute('data-provider-box-index', '0')
+    await expect(provider.getByTestId('test-box-renderer')).toHaveAttribute('data-match-attribute', 'box-priority')
+    await expect(provider.getByTestId('test-content-renderer')).toHaveAttribute('data-provider-content-index', '0')
+    await expect(provider.getByTestId('test-content-renderer')).toHaveAttribute(
+      'data-match-attribute',
+      'content-priority',
+    )
+  })
+
+  test('provides store data and preserves the outer store across nested providers', async ({ mount }) => {
+    const component = await mount(BubbleProviderFixture)
+
+    await expect(component.getByTestId('matched-provider').getByTestId('test-content-renderer')).toHaveAttribute(
+      'data-store-label',
+      'provider-store',
+    )
+    await expect(component.getByTestId('nested-provider').getByTestId('test-content-renderer')).toHaveAttribute(
+      'data-store-label',
+      'outer-store',
+    )
+  })
+
+  test('uses provider fallbacks while preserving Bubble-level fallback precedence', async ({ mount }) => {
+    const component = await mount(BubbleProviderFixture)
+    const provider = component.getByTestId('provider-fallbacks')
+
+    await expect(provider.getByTestId('fallback-box-renderer')).toHaveCount(2)
+    await expect(provider.getByTestId('secondary-content-renderer')).toHaveCount(1)
+    await expect(provider.getByTestId('prop-fallback-bubble').getByTestId('fallback-content-renderer')).toBeVisible()
+  })
+
+  test('maps renderer state and custom events to Bubble payload indexes', async ({ mount }) => {
+    const component = await mount(BubbleProviderFixture)
+    const provider = component.getByTestId('matched-provider')
+
+    await provider.getByRole('button', { name: 'Update bubble state' }).click()
+    await expect(provider.getByTestId('state-output')).toHaveText(
+      JSON.stringify({ key: 'expanded', value: true, contentIndex: 0, messageIndex: 0 }),
+    )
+
+    await provider.getByRole('button', { name: 'Retry bubble' }).click()
+    await expect(provider.getByTestId('event-output')).toHaveText(
+      JSON.stringify({ name: 'retry', payload: { source: 'renderer' }, contentIndex: 0, messageIndex: 0 }),
+    )
+  })
+})
diff --git a/packages/test/component/bubble/FallbackBoxRenderer.vue b/packages/test/component/bubble/FallbackBoxRenderer.vue
new file mode 100644
index 000000000..6390fa9e4
--- /dev/null
+++ b/packages/test/component/bubble/FallbackBoxRenderer.vue
@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import type { BubbleBoxRendererProps } from '../../../components/src/bubble/index.type'
+
+defineProps<BubbleBoxRendererProps>()
+</script>
+
+<template>
+  <aside data-testid="fallback-box-renderer"><slot /></aside>
+</template>
diff --git a/packages/test/component/bubble/FallbackContentRenderer.vue b/packages/test/component/bubble/FallbackContentRenderer.vue
new file mode 100644
index 000000000..f8e470a4b
--- /dev/null
+++ b/packages/test/component/bubble/FallbackContentRenderer.vue
@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import type { BubbleContentRendererProps } from '../../../components/src/bubble/index.type'
+
+const props = defineProps<BubbleContentRendererProps>()
+</script>
+
+<template>
+  <div data-testid="fallback-content-renderer">Fallback content {{ props.contentIndex }}</div>
+</template>
diff --git a/packages/test/component/bubble/SecondaryContentRenderer.vue b/packages/test/component/bubble/SecondaryContentRenderer.vue
new file mode 100644
index 000000000..922cb9c26
--- /dev/null
+++ b/packages/test/component/bubble/SecondaryContentRenderer.vue
@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import type { BubbleContentRendererProps } from '../../../components/src/bubble/index.type'
+
+defineProps<BubbleContentRendererProps>()
+</script>
+
+<template>
+  <div data-testid="secondary-content-renderer">Secondary renderer</div>
+</template>
diff --git a/packages/test/component/bubble/TestBoxRenderer.vue b/packages/test/component/bubble/TestBoxRenderer.vue
new file mode 100644
index 000000000..b51e73ff3
--- /dev/null
+++ b/packages/test/component/bubble/TestBoxRenderer.vue
@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import type { BubbleBoxRendererProps } from '../../../components/src/bubble/index.type'
+
+defineProps<BubbleBoxRendererProps>()
+</script>
+
+<template>
+  <section data-testid="test-box-renderer"><slot /></section>
+</template>
diff --git a/packages/test/component/bubble/TestContentRenderer.vue b/packages/test/component/bubble/TestContentRenderer.vue
new file mode 100644
index 000000000..7c699a754
--- /dev/null
+++ b/packages/test/component/bubble/TestContentRenderer.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useBubbleEventFn, useBubbleStateChangeFn, useBubbleStore } from '../../../components/src/bubble/composables'
+import type { BubbleContentRendererProps, ChatMessageContentItem } from '../../../components/src/bubble/index.type'
+
+const props = defineProps<BubbleContentRendererProps>()
+const emitBubbleEvent = useBubbleEventFn()
+const emitStateChange = useBubbleStateChangeFn()
+const store = useBubbleStore<{ label?: string }>()
+
+const content = computed(() => {
+  if (!Array.isArray(props.message.content)) return undefined
+  return props.message.content[props.contentIndex] as ChatMessageContentItem | undefined
+})
+</script>
+
+<template>
+  <article
+    data-testid="test-content-renderer"
+    :data-content-index="props.contentIndex"
+    :data-store-label="store.label || ''"
+  >
+    <span>{{ content?.text || content?.label || 'custom content' }}</span>
+    <button type="button" @click="emitStateChange('expanded', true)">Update bubble state</button>
+    <button type="button" @click="emitBubbleEvent({ name: 'retry', payload: { source: 'renderer' } })">
+      Retry bubble
+    </button>
+  </article>
+</template>
diff --git a/packages/test/component/dropdown-menu/DropdownMenu.fixture.vue b/packages/test/component/dropdown-menu/DropdownMenu.fixture.vue
new file mode 100644
index 000000000..e6d3bf20f
--- /dev/null
+++ b/packages/test/component/dropdown-menu/DropdownMenu.fixture.vue
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import DropdownMenu from '../../../components/src/dropdown-menu/index.vue'
+import type { DropdownMenuItem } from '../../../components/src/dropdown-menu/index.type'
+
+const items: DropdownMenuItem[] = [
+  { id: 'reasoning', text: 'Reasoning model' },
+  { id: 'fast', text: 'Fast model' },
+]
+
+const clickShow = ref(false)
+const manualShow = ref(false)
+const selectedItem = ref('')
+const outsideEvent = ref('')
+
+const recordItem = (item: DropdownMenuItem) => {
+  selectedItem.value = JSON.stringify(item)
+}
+
+const recordOutside = (event: MouseEvent) => {
+  outsideEvent.value = event.type
+}
+</script>
+
+<template>
+  <main>
+    <section data-testid="click-menu">
+      <DropdownMenu v-model:show="clickShow" :items="items" @item-click="recordItem" @click-outside="recordOutside">
+        <template #trigger>
+          <button type="button">Choose model</button>
+        </template>
+      </DropdownMenu>
+      <output data-testid="click-show">{{ clickShow }}</output>
+      <output data-testid="selected-item">{{ selectedItem }}</output>
+      <output data-testid="outside-event">{{ outsideEvent }}</output>
+    </section>
+
+    <section data-testid="manual-menu">
+      <button type="button" @click="manualShow = !manualShow">Toggle manual menu</button>
+      <DropdownMenu :show="manualShow" trigger="manual" :items="items">
+        <template #trigger>
+          <button type="button">Manual trigger</button>
+        </template>
+      </DropdownMenu>
+      <output data-testid="manual-show">{{ manualShow }}</output>
+    </section>
+
+    <section data-testid="hover-menu">
+      <DropdownMenu trigger="hover" :items="items">
+        <template #trigger>
+          <button type="button">Hover trigger</button>
+        </template>
+      </DropdownMenu>
+    </section>
+
+    <div id="dropdown-append-target" data-testid="append-target"></div>
+    <section data-testid="appended-menu">
+      <DropdownMenu :items="items" append-to="#dropdown-append-target">
+        <template #trigger>
+          <button type="button">Appended trigger</button>
+        </template>
+      </DropdownMenu>
+    </section>
+
+    <button type="button">Outside control</button>
+  </main>
+</template>
diff --git a/packages/test/component/dropdown-menu/DropdownMenu.spec.ts b/packages/test/component/dropdown-menu/DropdownMenu.spec.ts
new file mode 100644
index 000000000..caae20190
--- /dev/null
+++ b/packages/test/component/dropdown-menu/DropdownMenu.spec.ts
@@ -0,0 +1,123 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import DropdownMenuFixture from './DropdownMenu.fixture.vue'
+
+test.describe('DropdownMenu', () => {
+  test('renders the trigger slot and toggles click-controlled visibility', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('click-menu')
+    const trigger = section.getByRole('button', { name: 'Choose model' })
+
+    await expect(trigger).toHaveAttribute('aria-haspopup', 'menu')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await trigger.click()
+    await expect(section.getByTestId('click-show')).toHaveText('true')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+    await expect(page.getByRole('menu')).toBeVisible()
+
+    await trigger.click()
+    await expect(section.getByTestId('click-show')).toHaveText('false')
+  })
+
+  test('emits the selected item and closes the click menu', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('click-menu')
+
+    await section.getByRole('button', { name: 'Choose model' }).click()
+    await page.getByRole('menuitem', { name: 'Fast model' }).click()
+    await expect(section.getByTestId('selected-item')).toHaveText(JSON.stringify({ id: 'fast', text: 'Fast model' }))
+    await expect(section.getByTestId('click-show')).toHaveText('false')
+  })
+
+  test('emits click-outside and closes the click menu', async ({ mount }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('click-menu')
+
+    await section.getByRole('button', { name: 'Choose model' }).click()
+    await component.getByRole('button', { name: 'Outside control' }).click()
+    await expect(section.getByTestId('outside-event')).toHaveText('click')
+    await expect(section.getByTestId('click-show')).toHaveText('false')
+  })
+
+  test('keeps manual visibility controlled by the parent', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('manual-menu')
+
+    await section.getByRole('button', { name: 'Toggle manual menu' }).click()
+    await expect(section.getByTestId('manual-show')).toHaveText('true')
+    await expect(page.getByRole('menu').filter({ hasText: 'Reasoning model' })).toBeVisible()
+
+    await section.getByRole('button', { name: 'Manual trigger' }).click()
+    await expect(section.getByTestId('manual-show')).toHaveText('true')
+
+    await page.getByRole('menuitem', { name: 'Reasoning model' }).click()
+    await expect(section.getByTestId('manual-show')).toHaveText('true')
+  })
+
+  test('opens and closes after the hover delays', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const trigger = component.getByRole('button', { name: 'Hover trigger' })
+
+    await trigger.hover()
+    await expect(page.getByRole('menu').filter({ hasText: 'Fast model' })).toBeVisible()
+
+    await component.getByRole('button', { name: 'Outside control' }).hover()
+    await expect(page.getByRole('menu').filter({ hasText: 'Fast model' })).toBeHidden()
+  })
+
+  test('teleports the menu to appendTo', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+
+    await component.getByRole('button', { name: 'Appended trigger' }).click()
+    await expect(page.getByTestId('append-target').getByRole('menu')).toBeVisible()
+  })
+
+  test('moves focus into click menus opened with Enter or Space and dismisses them on Tab', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('click-menu')
+    const trigger = section.getByRole('button', { name: 'Choose model' })
+
+    await trigger.focus()
+    await trigger.press('Enter')
+    await expect(page.getByRole('menuitem', { name: 'Reasoning model' })).toBeFocused()
+
+    await page.getByRole('menuitem', { name: 'Reasoning model' }).press('Tab')
+    await expect(page.getByRole('menu')).toBeHidden()
+
+    await trigger.focus()
+    await trigger.press('Space')
+    await expect(page.getByRole('menuitem', { name: 'Reasoning model' })).toBeFocused()
+  })
+
+  test('supports keyboard navigation, selection, Escape, and focus restoration', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('click-menu')
+    const trigger = section.getByRole('button', { name: 'Choose model' })
+
+    await trigger.focus()
+    await trigger.press('ArrowDown')
+    await expect(page.getByRole('menuitem', { name: 'Reasoning model' })).toBeFocused()
+    await page.getByRole('menuitem', { name: 'Reasoning model' }).press('ArrowDown')
+    await expect(page.getByRole('menuitem', { name: 'Fast model' })).toBeFocused()
+    await page.getByRole('menuitem', { name: 'Fast model' }).press('Enter')
+    await expect(section.getByTestId('selected-item')).toContainText('"id":"fast"')
+    await expect(trigger).toBeFocused()
+
+    await trigger.press('Enter')
+    await expect(page.getByRole('menu')).toBeVisible()
+    await page.getByRole('menuitem', { name: 'Reasoning model' }).press('Escape')
+    await expect(page.getByRole('menu')).toBeHidden()
+    await expect(trigger).toBeFocused()
+  })
+
+  test('moves focus into an externally opened manual menu with ArrowDown', async ({ mount, page }) => {
+    const component = await mount(DropdownMenuFixture)
+    const section = component.getByTestId('manual-menu')
+    const trigger = section.getByRole('button', { name: 'Manual trigger' })
+
+    await section.getByRole('button', { name: 'Toggle manual menu' }).click()
+    await trigger.focus()
+    await trigger.press('ArrowDown')
+
+    await expect(page.getByRole('menuitem', { name: 'Reasoning model' })).toBeFocused()
+  })
+})
diff --git a/packages/test/component/extension-manager/ExtensionCard.fixture.vue b/packages/test/component/extension-manager/ExtensionCard.fixture.vue
index d4d90d2d0..9e48d10a2 100644
--- a/packages/test/component/extension-manager/ExtensionCard.fixture.vue
+++ b/packages/test/component/extension-manager/ExtensionCard.fixture.vue
@@ -39,10 +39,11 @@ const handleAction = (event: ExtensionCardActionEvent) => {
   lastEvent.value = event
 
   if (event.type !== 'switch' || typeof event.checked !== 'boolean') return
+  const checked = event.checked
 
   overflowActions.value = overflowActions.value.map((action) =>
     action.id === event.id && action.type === 'switch'
-      ? { ...action, checked: event.checked, label: getOverflowSwitchLabel(event.checked) }
+      ? { ...action, checked, label: getOverflowSwitchLabel(checked) }
       : action,
   )
 }
diff --git a/packages/test/component/extension-manager/ExtensionCardActionEvent.fixture.vue b/packages/test/component/extension-manager/ExtensionCardActionEvent.fixture.vue
index 25a392b11..a5ec3ff1d 100644
--- a/packages/test/component/extension-manager/ExtensionCardActionEvent.fixture.vue
+++ b/packages/test/component/extension-manager/ExtensionCardActionEvent.fixture.vue
@@ -24,9 +24,10 @@ const eventPayload = computed(() => JSON.stringify(lastEvent.value?.payload ?? n
 const handleAction = (event: ExtensionCardActionEvent) => {
   lastEvent.value = event
   if (event.type !== 'switch' || typeof event.checked !== 'boolean' || !commitSwitchChanges.value) return
+  const checked = event.checked
 
   actions.value = actions.value.map((action) =>
-    action.id === event.id && action.type === 'switch' ? { ...action, checked: event.checked } : action,
+    action.id === event.id && action.type === 'switch' ? { ...action, checked } : action,
   )
 }
 </script>
diff --git a/packages/test/component/history/History.fixture.vue b/packages/test/component/history/History.fixture.vue
new file mode 100644
index 000000000..62df19dc1
--- /dev/null
+++ b/packages/test/component/history/History.fixture.vue
@@ -0,0 +1,111 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import History from '../../../components/src/history/index.vue'
+import type { HistoryItem, HistoryMenuItem } from '../../../components/src/history/index.type'
+
+type FixtureItem = HistoryItem & { kind: string }
+
+const flatItems: FixtureItem[] = [
+  { id: 'chat-1', title: 'First chat', kind: 'work' },
+  { id: 'chat-2', title: 'Second chat', kind: 'personal' },
+]
+
+const groupedItems = [
+  { group: 'Today', items: [{ id: 'today-1', title: 'Today chat', kind: 'work' }] },
+  { group: 'Earlier', items: [{ id: 'old-1', title: 'Older chat', kind: 'personal' }] },
+]
+
+const menuItems: HistoryMenuItem[] = [
+  { id: 'rename', text: '重命名' },
+  { id: 'archive', text: '归档' },
+]
+
+const lastItemClick = ref('')
+const lastItemAction = ref('')
+const lastActionIdentity = ref('')
+const confirmedRename = ref('')
+const confirmedRenameIdentity = ref('')
+const cancelledRename = ref('')
+const untouchedRename = ref('')
+
+const recordClick = (item: FixtureItem) => {
+  lastItemClick.value = JSON.stringify(item)
+}
+
+const recordAction = (action: HistoryMenuItem, item: FixtureItem) => {
+  lastItemAction.value = JSON.stringify({ action, item })
+  lastActionIdentity.value = item === flatItems.find((candidate) => candidate.id === item.id) ? 'same' : 'different'
+}
+
+const serializeRename = (newTitle: string, item: FixtureItem) => JSON.stringify({ newTitle, item })
+
+const recordConfirmedRename = (newTitle: string, item: FixtureItem) => {
+  confirmedRename.value = serializeRename(newTitle, item)
+  confirmedRenameIdentity.value =
+    item === flatItems.find((candidate) => candidate.id === item.id) ? 'same' : 'different'
+}
+
+const recordCancelledRename = (newTitle: string, item: FixtureItem) => {
+  cancelledRename.value = serializeRename(newTitle, item)
+}
+
+const recordUntouchedRename = (newTitle: string, item: FixtureItem) => {
+  untouchedRename.value = serializeRename(newTitle, item)
+}
+</script>
+
+<template>
+  <main>
+    <section data-testid="flat-history">
+      <History
+        :data="flatItems"
+        selected="chat-2"
+        :menu-items="menuItems"
+        @item-click="recordClick"
+        @item-action="recordAction"
+      >
+        <template #item-prefix="{ item }">
+          <span :data-testid="`prefix-${item.id}`">{{ item.kind }}</span>
+        </template>
+        <template #item-title="{ item }">
+          <strong :data-testid="`title-${item.id}`">{{ item.title }} custom</strong>
+        </template>
+      </History>
+      <output data-testid="item-click-output">{{ lastItemClick }}</output>
+      <output data-testid="item-action-output">{{ lastItemAction }}</output>
+      <output data-testid="item-action-identity">{{ lastActionIdentity }}</output>
+    </section>
+
+    <section data-testid="grouped-history">
+      <History :data="groupedItems" />
+    </section>
+
+    <section data-testid="empty-history">
+      <History :data="[]" />
+    </section>
+
+    <button data-testid="outside-confirm" type="button">Outside confirm</button>
+    <section data-testid="confirm-history">
+      <History
+        :data="flatItems"
+        :show-rename-controls="true"
+        rename-control-on-click-outside="confirm"
+        @item-title-change="recordConfirmedRename"
+      />
+      <output data-testid="confirm-output">{{ confirmedRename }}</output>
+      <output data-testid="confirm-identity">{{ confirmedRenameIdentity }}</output>
+    </section>
+
+    <button data-testid="outside-cancel" type="button">Outside cancel</button>
+    <section data-testid="cancel-history">
+      <History :data="flatItems" rename-control-on-click-outside="cancel" @item-title-change="recordCancelledRename" />
+      <output data-testid="cancel-output">{{ cancelledRename }}</output>
+    </section>
+
+    <button data-testid="outside-none" type="button">Outside none</button>
+    <section data-testid="none-history">
+      <History :data="flatItems" rename-control-on-click-outside="none" @item-title-change="recordUntouchedRename" />
+      <output data-testid="none-output">{{ untouchedRename }}</output>
+    </section>
+  </main>
+</template>
diff --git a/packages/test/component/history/History.spec.ts b/packages/test/component/history/History.spec.ts
new file mode 100644
index 000000000..a2ce16d12
--- /dev/null
+++ b/packages/test/component/history/History.spec.ts
@@ -0,0 +1,160 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import type { Locator } from '@playwright/test'
+import HistoryFixture from './History.fixture.vue'
+
+const openRenameEditor = async (history: Locator, title: string) => {
+  const trigger = history.getByRole('button', { name: `${title} 更多操作` })
+  await trigger.focus()
+  await trigger.press('ArrowDown')
+  await history.getByRole('menuitem', { name: '重命名' }).click()
+  return history.getByRole('textbox')
+}
+
+test.describe('History', () => {
+  test('renders empty, flat, and grouped data with selection', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const flat = component.getByTestId('flat-history')
+    const grouped = component.getByTestId('grouped-history')
+
+    await expect(component.getByTestId('empty-history')).toContainText('暂无内容')
+    await expect(flat.locator('.tr-history__item')).toHaveCount(2)
+    await expect(flat.locator('.tr-history__item.selected')).toContainText('Second chat')
+    await expect(grouped.locator('.tr-history__group-title')).toHaveText(['Today', 'Earlier'])
+    await expect(grouped.locator('.tr-history__item')).toHaveCount(2)
+  })
+
+  test('passes the complete item to prefix and title slots', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+
+    await expect(component.getByTestId('prefix-chat-1')).toHaveText('work')
+    await expect(component.getByTestId('title-chat-1')).toHaveText('First chat custom')
+    await expect(component.getByTestId('prefix-chat-2')).toHaveText('personal')
+  })
+
+  test('emits the clicked item and custom menu action', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const flat = component.getByTestId('flat-history')
+
+    await flat.getByTestId('title-chat-1').click()
+    await expect(flat.getByTestId('item-click-output')).toHaveText(
+      JSON.stringify({ id: 'chat-1', title: 'First chat', kind: 'work' }),
+    )
+
+    const secondMenuTrigger = flat.getByRole('button', { name: 'Second chat 更多操作' })
+    await secondMenuTrigger.focus()
+    await secondMenuTrigger.press('ArrowDown')
+    await flat.getByRole('menuitem', { name: '归档' }).click()
+    await expect(flat.getByTestId('item-action-output')).toHaveText(
+      JSON.stringify({
+        action: { id: 'archive', text: '归档' },
+        item: { id: 'chat-2', title: 'Second chat', kind: 'personal' },
+      }),
+    )
+    await expect(flat.getByTestId('item-action-identity')).toHaveText('same')
+  })
+
+  test('focuses and selects the title when rename starts, then confirms with Enter', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('confirm-history')
+    const editor = await openRenameEditor(history, 'First chat')
+
+    await expect(editor).toBeFocused()
+    await expect(editor).toHaveJSProperty('selectionStart', 0)
+    await expect(editor).toHaveJSProperty('selectionEnd', 'First chat'.length)
+
+    await editor.fill('Renamed chat')
+    await editor.press('Enter')
+    await expect(history.getByTestId('confirm-output')).toHaveText(
+      JSON.stringify({
+        newTitle: 'Renamed chat',
+        item: { id: 'chat-1', title: 'First chat', kind: 'work' },
+      }),
+    )
+    await expect(history.getByTestId('confirm-identity')).toHaveText('same')
+    await expect(editor).toHaveCount(0)
+  })
+
+  test('opens and operates the action menu from the keyboard', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('flat-history')
+    const trigger = history.getByRole('button', { name: 'First chat 更多操作' })
+
+    await trigger.focus()
+    await trigger.press('ArrowDown')
+    await expect(history.getByRole('menuitem', { name: '重命名' })).toBeFocused()
+    await history.getByRole('menuitem', { name: '重命名' }).press('ArrowDown')
+    await expect(history.getByRole('menuitem', { name: '归档' })).toBeFocused()
+    await history.getByRole('menuitem', { name: '归档' }).press('Enter')
+
+    await expect(history.getByTestId('item-action-output')).toContainText('archive')
+    await expect(trigger).toBeFocused()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+
+    await trigger.press('ArrowDown')
+    await history.getByRole('menuitem', { name: '重命名' }).press('Escape')
+    await expect(trigger).toBeFocused()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  test('cancels rename with Escape without emitting a title change', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('cancel-history')
+    const editor = await openRenameEditor(history, 'First chat')
+
+    await editor.fill('Discarded title')
+    await editor.press('Escape')
+    await expect(editor).toHaveCount(0)
+    await expect(history.getByTestId('cancel-output')).toBeEmpty()
+  })
+
+  test('supports explicit rename confirmation and cancellation controls', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('confirm-history')
+    let editor = await openRenameEditor(history, 'Second chat')
+
+    await editor.fill('Confirmed by button')
+    await history.getByRole('button', { name: '确认重命名' }).click()
+    await expect(history.getByTestId('confirm-output')).toContainText('Confirmed by button')
+
+    editor = await openRenameEditor(history, 'Second chat')
+    await editor.fill('Cancelled by button')
+    await history.getByRole('button', { name: '取消重命名' }).click()
+    await expect(editor).toHaveCount(0)
+    await expect(history.getByTestId('confirm-output')).not.toContainText('Cancelled by button')
+  })
+
+  test('confirms rename when clicking outside the editor', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const confirmHistory = component.getByTestId('confirm-history')
+    const confirmEditor = await openRenameEditor(confirmHistory, 'First chat')
+
+    await confirmEditor.fill('Confirmed outside')
+    await component.getByTestId('outside-confirm').click()
+    await expect(confirmHistory.getByTestId('confirm-output')).toContainText('Confirmed outside')
+  })
+
+  test('cancels rename when configured to cancel on outside clicks', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+
+    const cancelHistory = component.getByTestId('cancel-history')
+    const cancelEditor = await openRenameEditor(cancelHistory, 'First chat')
+
+    await cancelEditor.fill('Cancelled outside')
+    await component.getByTestId('outside-cancel').click()
+    await expect(cancelEditor).toHaveCount(0)
+    await expect(cancelHistory.getByTestId('cancel-output')).toBeEmpty()
+  })
+
+  test('leaves rename open when outside clicks are disabled', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+
+    const noneHistory = component.getByTestId('none-history')
+    const noneEditor = await openRenameEditor(noneHistory, 'First chat')
+
+    await expect(noneEditor).toBeVisible()
+    await noneEditor.fill('Still editing')
+    await component.getByTestId('outside-none').click()
+    await expect(noneEditor).toHaveValue('Still editing')
+    await expect(noneHistory.getByTestId('none-output')).toBeEmpty()
+  })
+})
diff --git a/packages/test/component/theme-provider/ThemeConsumer.vue b/packages/test/component/theme-provider/ThemeConsumer.vue
new file mode 100644
index 000000000..39cf53c89
--- /dev/null
+++ b/packages/test/component/theme-provider/ThemeConsumer.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useTheme } from '../../../components/src/theme-provider/useTheme'
+
+defineProps<{ prefix: string }>()
+
+const { theme, colorMode, resolvedColorMode, systemColorMode, setTheme, setColorMode, toggleColorMode } = useTheme()
+const lastResult = ref('')
+
+const run = (operation: () => boolean) => {
+  lastResult.value = String(operation())
+}
+</script>
+
+<template>
+  <div :data-testid="`${prefix}-consumer`">
+    <button type="button" @click="run(() => setTheme('forest'))">Set forest theme</button>
+    <button type="button" @click="run(() => setColorMode('auto'))">Set auto mode</button>
+    <button type="button" @click="run(() => setColorMode('dark'))">Set dark mode</button>
+    <button type="button" @click="run(toggleColorMode)">Toggle color mode</button>
+    <output :data-testid="`${prefix}-theme`">{{ theme }}</output>
+    <output :data-testid="`${prefix}-color-mode`">{{ colorMode }}</output>
+    <output :data-testid="`${prefix}-resolved-mode`">{{ resolvedColorMode }}</output>
+    <output :data-testid="`${prefix}-system-mode`">{{ systemColorMode }}</output>
+    <output :data-testid="`${prefix}-result`">{{ lastResult }}</output>
+  </div>
+</template>
diff --git a/packages/test/component/theme-provider/ThemeProvider.fixture.vue b/packages/test/component/theme-provider/ThemeProvider.fixture.vue
new file mode 100644
index 000000000..1dde5ad86
--- /dev/null
+++ b/packages/test/component/theme-provider/ThemeProvider.fixture.vue
@@ -0,0 +1,64 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import ThemeProvider from '../../../components/src/theme-provider/index.vue'
+import type { ThemeStorage } from '../../../components/src/theme-provider/index.type'
+import ThemeConsumer from './ThemeConsumer.vue'
+
+const theme = ref('ocean')
+const colorMode = ref<'light' | 'dark' | 'auto'>('auto')
+
+const storedValue = ref(JSON.stringify({ theme: 'stored-theme', colorMode: 'dark', retained: 'yes' }))
+const storage: ThemeStorage = {
+  getItem: (key) => (key === 'custom-theme-key' ? storedValue.value : null),
+  setItem: (key, value) => {
+    if (key === 'custom-theme-key') storedValue.value = value
+  },
+}
+
+const malformedValue = ref('{not-json')
+const malformedStorage: ThemeStorage = {
+  getItem: () => malformedValue.value,
+  setItem: (_key, value) => {
+    malformedValue.value = value
+  },
+}
+</script>
+
+<template>
+  <main>
+    <ThemeProvider theme="default-theme" color-mode="light">
+      <span data-testid="default-slot">Default provider slot</span>
+    </ThemeProvider>
+
+    <div id="controlled-theme-target" data-testid="controlled-target"></div>
+    <ThemeProvider v-model:theme="theme" v-model:color-mode="colorMode" target-element="#controlled-theme-target">
+      <ThemeConsumer prefix="controlled" />
+    </ThemeProvider>
+    <output data-testid="controlled-theme-model">{{ theme }}</output>
+    <output data-testid="controlled-mode-model">{{ colorMode }}</output>
+
+    <div id="stored-theme-target" data-testid="stored-target"></div>
+    <ThemeProvider
+      theme="fallback-theme"
+      color-mode="light"
+      target-element="#stored-theme-target"
+      :storage="storage"
+      storage-key="custom-theme-key"
+    >
+      <ThemeConsumer prefix="stored" />
+    </ThemeProvider>
+    <output data-testid="stored-value">{{ storedValue }}</output>
+
+    <div id="malformed-theme-target" data-testid="malformed-target"></div>
+    <ThemeProvider
+      theme="safe-theme"
+      color-mode="light"
+      target-element="#malformed-theme-target"
+      :storage="malformedStorage"
+    >
+      <span data-testid="malformed-slot">Malformed storage provider</span>
+    </ThemeProvider>
+
+    <ThemeConsumer prefix="outside" />
+  </main>
+</template>
diff --git a/packages/test/component/theme-provider/ThemeProvider.spec.ts b/packages/test/component/theme-provider/ThemeProvider.spec.ts
new file mode 100644
index 000000000..a27d2ba54
--- /dev/null
+++ b/packages/test/component/theme-provider/ThemeProvider.spec.ts
@@ -0,0 +1,123 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import type { Page } from '@playwright/test'
+import ThemeProviderFixture from './ThemeProvider.fixture.vue'
+
+const installMatchMedia = async (page: Page, initialDark = false) => {
+  await page.evaluate((dark) => {
+    let matches = dark
+    const listeners = new Set<(event: MediaQueryListEvent) => void>()
+    const mediaQuery = {
+      media: '(prefers-color-scheme: dark)',
+      onchange: null,
+      get matches() {
+        return matches
+      },
+      addEventListener: (_type: string, listener: (event: MediaQueryListEvent) => void) => listeners.add(listener),
+      removeEventListener: (_type: string, listener: (event: MediaQueryListEvent) => void) =>
+        listeners.delete(listener),
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => true,
+    }
+
+    Object.defineProperty(window, 'matchMedia', {
+      configurable: true,
+      value: () => mediaQuery,
+    })
+
+    ;(window as typeof window & { setSystemDark: (value: boolean) => void }).setSystemDark = (value) => {
+      matches = value
+      const event = { matches: value, media: mediaQuery.media } as MediaQueryListEvent
+      listeners.forEach((listener) => listener(event))
+    }
+  }, initialDark)
+}
+
+test.beforeEach(async ({ page }) => {
+  await installMatchMedia(page)
+})
+
+test.describe('ThemeProvider and useTheme', () => {
+  test('renders its slot and applies explicit theme data to the default html target', async ({ mount, page }) => {
+    const component = await mount(ThemeProviderFixture)
+
+    await expect(component.getByTestId('default-slot')).toHaveText('Default provider slot')
+    await expect(page.locator('html')).toHaveAttribute('data-tr-theme', 'default-theme')
+    await expect(page.locator('html')).toHaveAttribute('data-tr-color-mode', 'light')
+  })
+
+  test('applies controlled theme models to a custom target element', async ({ mount }) => {
+    const component = await mount(ThemeProviderFixture)
+    const target = component.getByTestId('controlled-target')
+
+    await expect(target).toHaveAttribute('data-tr-theme', 'ocean')
+    await expect(target).toHaveAttribute('data-tr-color-mode', 'light')
+    await expect(component.getByTestId('controlled-theme-model')).toHaveText('ocean')
+    await expect(component.getByTestId('controlled-mode-model')).toHaveText('auto')
+  })
+
+  test('updates theme and color-mode models through useTheme', async ({ mount }) => {
+    const component = await mount(ThemeProviderFixture)
+    const consumer = component.getByTestId('controlled-consumer')
+    const target = component.getByTestId('controlled-target')
+
+    await consumer.getByRole('button', { name: 'Set forest theme' }).click()
+    await expect(component.getByTestId('controlled-theme-model')).toHaveText('forest')
+    await expect(target).toHaveAttribute('data-tr-theme', 'forest')
+    await expect(consumer.getByTestId('controlled-result')).toHaveText('true')
+
+    await consumer.getByRole('button', { name: 'Set dark mode' }).click()
+    await expect(component.getByTestId('controlled-mode-model')).toHaveText('dark')
+    await expect(target).toHaveAttribute('data-tr-color-mode', 'dark')
+
+    await consumer.getByRole('button', { name: 'Toggle color mode' }).click()
+    await expect(component.getByTestId('controlled-mode-model')).toHaveText('light')
+    await expect(consumer.getByTestId('controlled-resolved-mode')).toHaveText('light')
+  })
+
+  test('resolves auto mode from matchMedia and reacts to system changes', async ({ mount, page }) => {
+    const component = await mount(ThemeProviderFixture)
+    const target = component.getByTestId('controlled-target')
+
+    await expect(target).toHaveAttribute('data-tr-color-mode', 'light')
+    await page.evaluate(() => {
+      ;(window as typeof window & { setSystemDark: (value: boolean) => void }).setSystemDark(true)
+    })
+    await expect(target).toHaveAttribute('data-tr-color-mode', 'dark')
+    await expect(component.getByTestId('controlled-system-mode')).toHaveText('dark')
+  })
+
+  test('restores and merges persisted theme data using the configured key', async ({ mount }) => {
+    const component = await mount(ThemeProviderFixture)
+    const target = component.getByTestId('stored-target')
+    const consumer = component.getByTestId('stored-consumer')
+
+    await expect(target).toHaveAttribute('data-tr-theme', 'stored-theme')
+    await expect(target).toHaveAttribute('data-tr-color-mode', 'dark')
+    await consumer.getByRole('button', { name: 'Set forest theme' }).click()
+    await expect(component.getByTestId('stored-value')).toHaveText(
+      JSON.stringify({ theme: 'forest', colorMode: 'dark', retained: 'yes' }),
+    )
+  })
+
+  test('falls back to explicit props when stored JSON is malformed', async ({ mount }) => {
+    const component = await mount(ThemeProviderFixture)
+    const target = component.getByTestId('malformed-target')
+
+    await expect(component.getByTestId('malformed-slot')).toBeVisible()
+    await expect(target).toHaveAttribute('data-tr-theme', 'safe-theme')
+    await expect(target).toHaveAttribute('data-tr-color-mode', 'light')
+  })
+
+  test('returns false when useTheme setters run outside a provider', async ({ mount }) => {
+    const component = await mount(ThemeProviderFixture)
+    const outside = component.getByTestId('outside-consumer')
+
+    await outside.getByRole('button', { name: 'Set forest theme' }).click()
+    await expect(outside.getByTestId('outside-result')).toHaveText('false')
+    await outside.getByRole('button', { name: 'Set dark mode' }).click()
+    await expect(outside.getByTestId('outside-result')).toHaveText('false')
+    await outside.getByRole('button', { name: 'Toggle color mode' }).click()
+    await expect(outside.getByTestId('outside-result')).toHaveText('false')
+  })
+})
diff --git a/packages/test/component/welcome/Welcome.fixture.vue b/packages/test/component/welcome/Welcome.fixture.vue
new file mode 100644
index 000000000..ad1c5eb3f
--- /dev/null
+++ b/packages/test/component/welcome/Welcome.fixture.vue
@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { h } from 'vue'
+import Welcome from '../../../components/src/welcome/index.vue'
+
+const icon = h('span', { 'data-testid': 'welcome-icon', 'aria-hidden': 'true' }, 'AI')
+</script>
+
+<template>
+  <div>
+    <Welcome data-testid="default-welcome" title="Start here" description="Ask anything" />
+
+    <Welcome data-testid="aligned-welcome" title="Aligned" description="Right aligned" align="right" />
+
+    <Welcome data-testid="slotted-welcome" title="With icon" description="Choose a prompt" :icon="icon">
+      <template #footer>
+        <button type="button">Try prompt</button>
+      </template>
+    </Welcome>
+  </div>
+</template>
diff --git a/packages/test/component/welcome/Welcome.spec.ts b/packages/test/component/welcome/Welcome.spec.ts
new file mode 100644
index 000000000..e417064bd
--- /dev/null
+++ b/packages/test/component/welcome/Welcome.spec.ts
@@ -0,0 +1,27 @@
+import { expect, test } from '@playwright/experimental-ct-vue'
+import WelcomeFixture from './Welcome.fixture.vue'
+
+test.describe('Welcome', () => {
+  test('renders required copy with the default centered alignment', async ({ mount }) => {
+    const component = await mount(WelcomeFixture)
+    const welcome = component.getByTestId('default-welcome')
+
+    await expect(welcome.getByRole('heading', { name: 'Start here' })).toBeVisible()
+    await expect(welcome).toContainText('Ask anything')
+    await expect(welcome).toHaveCSS('text-align', 'center')
+  })
+
+  test('applies a custom alignment', async ({ mount }) => {
+    const component = await mount(WelcomeFixture)
+
+    await expect(component.getByTestId('aligned-welcome')).toHaveCSS('text-align', 'right')
+  })
+
+  test('renders the optional icon and footer slot', async ({ mount }) => {
+    const component = await mount(WelcomeFixture)
+    const welcome = component.getByTestId('slotted-welcome')
+
+    await expect(welcome.getByTestId('welcome-icon')).toHaveText('AI')
+    await expect(welcome.getByRole('button', { name: 'Try prompt' })).toBeVisible()
+  })
+})
diff --git a/packages/test/package.json b/packages/test/package.json
index cc80b4487..f899b6789 100644
--- a/packages/test/package.json
+++ b/packages/test/package.json
@@ -10,6 +10,7 @@
     "test": "pnpm run test:e2e && pnpm run test:ct",
     "test:e2e": "playwright test",
     "test:ct": "playwright test -c playwright-ct.config.ts",
+    "type-check:ct": "vue-tsc --noEmit -p tsconfig.ct.json",
     "test:ui": "playwright test --ui",
     "test:codegen": "playwright codegen localhost:3333",
     "test:headed": "playwright test --headed",
diff --git a/packages/test/tsconfig.ct.json b/packages/test/tsconfig.ct.json
new file mode 100644
index 000000000..169e4bae5
--- /dev/null
+++ b/packages/test/tsconfig.ct.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../components/tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "allowSyntheticDefaultImports": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["component/**/*.ts", "component/**/*.vue", "../components/src/vite-env.d.ts"]
+}

From 28cd1a5f22a73d5f0687f096680068f02bd0c6d3 Mon Sep 17 00:00:00 2001
From: gene9831 <pacify.98@gmail.com>
Date: Thu, 3 Sep 2026 18:45:57 +0800
Subject: [PATCH 2/4] docs: refine deprecation and history demos

---
 docs/.vitepress/plugins/badge/constants.ts |  2 +-
 docs/.vitepress/theme/style.css            | 15 +++++++++------
 docs/.vitepress/themeConfig.ts             |  2 +-
 docs/demos/history/basic.vue               |  4 +++-
 docs/demos/history/custom-menu.vue         |  6 +++++-
 docs/demos/history/icon.vue                |  2 +-
 docs/demos/history/slot-item-prefix.vue    |  2 +-
 docs/demos/history/slot-item-title.vue     |  2 +-
 8 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/docs/.vitepress/plugins/badge/constants.ts b/docs/.vitepress/plugins/badge/constants.ts
index d13196347..656dfbbd5 100644
--- a/docs/.vitepress/plugins/badge/constants.ts
+++ b/docs/.vitepress/plugins/badge/constants.ts
@@ -17,7 +17,7 @@ export type BadgeValue = BadgeType | string
  */
 export const BADGE_TEXT_MAP: Record<BadgeType, string> = {
   new: '新增',
-  deprecated: '已废弃',
+  deprecated: '弃用',
   beta: 'Beta',
   alpha: 'Alpha',
 }
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index 14e85c8e3..d2da971df 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -328,9 +328,13 @@ div:has(h1[id='bubble-气泡组件']) {
 }
 
 .version-badge--deprecated {
-  background-color: #fef0f0;
-  color: #f56c6c;
-  border: 1px solid #fde2e2;
+  padding: 1px 6px;
+  background-color: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-3);
+  border: 0;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 400;
 }
 
 .version-badge--beta {
@@ -353,9 +357,8 @@ div:has(h1[id='bubble-气泡组件']) {
 }
 
 .dark .version-badge--deprecated {
-  background-color: rgba(245, 108, 108, 0.15);
-  color: #f89898;
-  border-color: rgba(245, 108, 108, 0.25);
+  background-color: rgba(255, 255, 255, 0.08);
+  color: var(--vp-c-text-2);
 }
 
 .dark .version-badge--beta {
diff --git a/docs/.vitepress/themeConfig.ts b/docs/.vitepress/themeConfig.ts
index a5f10ae3a..b3c8c3335 100644
--- a/docs/.vitepress/themeConfig.ts
+++ b/docs/.vitepress/themeConfig.ts
@@ -14,7 +14,6 @@ const sharedSidebarItems = [
     text: '组件',
     base: '/components/',
     items: [
-      { text: 'Container 容器', link: 'container' },
       { text: 'Layout 布局', link: 'layout' },
       { text: 'Bubble 气泡', link: 'bubble' },
       { text: 'Sender 消息输入框', link: 'sender' },
@@ -30,6 +29,7 @@ const sharedSidebarItems = [
       { text: 'Attachments 附件卡片', link: 'attachments' },
       { text: 'McpServerPicker 插件选择器', link: 'mcp-server-picker' },
       { text: 'Theme 主题', link: 'theme' },
+      { text: 'Container 容器', link: 'container' },
     ],
   },
   {
diff --git a/docs/demos/history/basic.vue b/docs/demos/history/basic.vue
index 3cc2c32ff..6c46adca5 100644
--- a/docs/demos/history/basic.vue
+++ b/docs/demos/history/basic.vue
@@ -3,7 +3,7 @@
     :data="data"
     :selected="selected"
     :show-rename-controls="isTouchDevice"
-    rename-control-on-click-outside="cancel"
+    :rename-control-on-click-outside="isTouchDevice ? 'cancel' : 'confirm'"
     @item-click="(item) => (selected = item.id)"
     @item-title-change="(newTitle, item) => (item.title = newTitle)"
     @item-action="(item) => console.log(item)"
@@ -13,6 +13,8 @@
   <tr-history
     :data="groups"
     :selected="selected2"
+    :show-rename-controls="isTouchDevice"
+    :rename-control-on-click-outside="isTouchDevice ? 'cancel' : 'confirm'"
     @item-click="(item) => (selected2 = item.id)"
     @item-title-change="(newTitle, item) => (item.title = newTitle)"
     @item-action="(item) => console.log(item)"
diff --git a/docs/demos/history/custom-menu.vue b/docs/demos/history/custom-menu.vue
index 4de436c69..41ba5fbb7 100644
--- a/docs/demos/history/custom-menu.vue
+++ b/docs/demos/history/custom-menu.vue
@@ -3,6 +3,8 @@
     :data="data"
     :selected="selected"
     :menu-items="menuItems"
+    :show-rename-controls="isTouchDevice"
+    :rename-control-on-click-outside="isTouchDevice ? 'cancel' : 'confirm'"
     @item-click="(item) => (selected = item.id)"
     @item-title-change="(newTitle, item) => (item.title = newTitle)"
     @item-action="(action, item) => handleAction(action, item)"
@@ -10,10 +12,12 @@
 </template>
 
 <script setup lang="ts">
-import { TrHistory } from '@opentiny/tiny-robot'
+import { TrHistory, useTouchDevice } from '@opentiny/tiny-robot'
 import { IconEditPen, IconDelete, IconCopy } from '@opentiny/tiny-robot-svgs'
 import { reactive, ref } from 'vue'
 
+const { isTouchDevice } = useTouchDevice()
+
 const data = reactive([
   { title: '如何训练一只聪明的小狗', id: '1' },
   { title: 'How to make a perfect soufflé', id: '2' },
diff --git a/docs/demos/history/icon.vue b/docs/demos/history/icon.vue
index 45e29c222..7e0854484 100644
--- a/docs/demos/history/icon.vue
+++ b/docs/demos/history/icon.vue
@@ -3,7 +3,7 @@
     :data="data"
     :selected="selected"
     :show-rename-controls="isTouchDevice"
-    rename-control-on-click-outside="cancel"
+    :rename-control-on-click-outside="isTouchDevice ? 'cancel' : 'confirm'"
     @item-click="(item) => (selected = item.id)"
     @item-title-change="(newTitle, item) => (item.title = newTitle)"
     @item-action="(item) => console.log(item)"
diff --git a/docs/demos/history/slot-item-prefix.vue b/docs/demos/history/slot-item-prefix.vue
index c76e63d57..72aeda365 100644
--- a/docs/demos/history/slot-item-prefix.vue
+++ b/docs/demos/history/slot-item-prefix.vue
@@ -8,7 +8,7 @@
     :data="data"
     :selected="selected"
     :show-rename-controls="isTouchDevice"
-    rename-control-on-click-outside="cancel"
+    :rename-control-on-click-outside="isTouchDevice ? 'cancel' : 'confirm'"
     @item-click="(item) => (selected = item.id)"
     @item-title-change="(newTitle, item) => (item.title = newTitle)"
     @item-action="(item) => console.log(item)"
diff --git a/docs/demos/history/slot-item-title.vue b/docs/demos/history/slot-item-title.vue
index c6f26df40..4946246a4 100644
--- a/docs/demos/history/slot-item-title.vue
+++ b/docs/demos/history/slot-item-title.vue
@@ -3,7 +3,7 @@
     :data="data"
     :selected="selected"
     :show-rename-controls="isTouchDevice"
-    rename-control-on-click-outside="cancel"
+    :rename-control-on-click-outside="isTouchDevice ? 'cancel' : 'confirm'"
     @item-click="(item) => (selected = item.id)"
     @item-title-change="(newTitle, item) => (item.title = newTitle)"
     @item-action="(item) => console.log(item)"

From deb967f15b0b9d1524b3735706687a542f4fb773 Mon Sep 17 00:00:00 2001
From: gene9831 <pacify.98@gmail.com>
Date: Thu, 3 Sep 2026 19:12:17 +0800
Subject: [PATCH 3/4] fix(components): address component test review feedback

---
 packages/components/src/dropdown-menu/index.vue |  2 +-
 .../component/bubble/BubbleProvider.fixture.vue | 11 +++++++++++
 .../component/bubble/BubbleProvider.spec.ts     |  8 ++++++++
 .../component/bubble/TestContentRenderer.vue    | 16 ++++++++--------
 .../dropdown-menu/DropdownMenu.spec.ts          | 17 +++++++++++++++++
 5 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/packages/components/src/dropdown-menu/index.vue b/packages/components/src/dropdown-menu/index.vue
index 73fb6476f..cf5c67a31 100644
--- a/packages/components/src/dropdown-menu/index.vue
+++ b/packages/components/src/dropdown-menu/index.vue
@@ -66,7 +66,7 @@ const handleTriggerClick = () => {
 
 const focusTrigger = async () => {
   await nextTick()
-  triggerRef.value?.focus()
+  if (!show.value) triggerRef.value?.focus()
 }
 
 const getMenuItems = () => {
diff --git a/packages/test/component/bubble/BubbleProvider.fixture.vue b/packages/test/component/bubble/BubbleProvider.fixture.vue
index dd5aaf0c3..cb9da0176 100644
--- a/packages/test/component/bubble/BubbleProvider.fixture.vue
+++ b/packages/test/component/bubble/BubbleProvider.fixture.vue
@@ -16,6 +16,7 @@ import TestContentRenderer from './TestContentRenderer.vue'
 
 const customContent: BubbleMessage['content'] = [{ type: 'custom', text: 'Provider content' }]
 const unknownContent: BubbleMessage['content'] = [{ type: 'unknown', label: 'Unknown content' }]
+const sourceContent: BubbleMessage['content'] = [{ type: 'source', text: 'Source content' }]
 
 const contentMatches: BubbleContentRendererMatch[] = [
   {
@@ -96,5 +97,15 @@ const recordBubbleEvent = (payload: BubbleEvent & { messageIndex: number; conten
         </BubbleProvider>
       </BubbleProvider>
     </section>
+
+    <section data-testid="resolved-provider">
+      <BubbleProvider :content-renderer-matches="contentMatches">
+        <Bubble
+          role="assistant"
+          :content="sourceContent"
+          :content-resolver="() => [{ type: 'custom', text: 'Resolved provider content' }]"
+        />
+      </BubbleProvider>
+    </section>
   </main>
 </template>
diff --git a/packages/test/component/bubble/BubbleProvider.spec.ts b/packages/test/component/bubble/BubbleProvider.spec.ts
index 761c6e703..6635a5ece 100644
--- a/packages/test/component/bubble/BubbleProvider.spec.ts
+++ b/packages/test/component/bubble/BubbleProvider.spec.ts
@@ -46,6 +46,14 @@ test.describe('BubbleProvider', () => {
     await expect(provider.getByTestId('prop-fallback-bubble').getByTestId('fallback-content-renderer')).toBeVisible()
   })
 
+  test('renders contentResolver output in custom content renderers', async ({ mount }) => {
+    const component = await mount(BubbleProviderFixture)
+
+    await expect(component.getByTestId('resolved-provider').getByTestId('test-content-renderer')).toContainText(
+      'Resolved provider content',
+    )
+  })
+
   test('maps renderer state and custom events to Bubble payload indexes', async ({ mount }) => {
     const component = await mount(BubbleProviderFixture)
     const provider = component.getByTestId('matched-provider')
diff --git a/packages/test/component/bubble/TestContentRenderer.vue b/packages/test/component/bubble/TestContentRenderer.vue
index 7c699a754..d85ed2802 100644
--- a/packages/test/component/bubble/TestContentRenderer.vue
+++ b/packages/test/component/bubble/TestContentRenderer.vue
@@ -1,17 +1,17 @@
 <script setup lang="ts">
-import { computed } from 'vue'
-import { useBubbleEventFn, useBubbleStateChangeFn, useBubbleStore } from '../../../components/src/bubble/composables'
-import type { BubbleContentRendererProps, ChatMessageContentItem } from '../../../components/src/bubble/index.type'
+import {
+  useBubbleEventFn,
+  useBubbleStateChangeFn,
+  useBubbleStore,
+  useMessageContent,
+} from '../../../components/src/bubble/composables'
+import type { BubbleContentRendererProps } from '../../../components/src/bubble/index.type'
 
 const props = defineProps<BubbleContentRendererProps>()
 const emitBubbleEvent = useBubbleEventFn()
 const emitStateChange = useBubbleStateChangeFn()
 const store = useBubbleStore<{ label?: string }>()
-
-const content = computed(() => {
-  if (!Array.isArray(props.message.content)) return undefined
-  return props.message.content[props.contentIndex] as ChatMessageContentItem | undefined
-})
+const { content } = useMessageContent(props)
 </script>
 
 <template>
diff --git a/packages/test/component/dropdown-menu/DropdownMenu.spec.ts b/packages/test/component/dropdown-menu/DropdownMenu.spec.ts
index caae20190..76dd54f15 100644
--- a/packages/test/component/dropdown-menu/DropdownMenu.spec.ts
+++ b/packages/test/component/dropdown-menu/DropdownMenu.spec.ts
@@ -120,4 +120,21 @@ test.describe('DropdownMenu', () => {
 
     await expect(page.getByRole('menuitem', { name: 'Reasoning model' })).toBeFocused()
   })
+
+  for (const key of ['Escape', 'Enter']) {
+    test(`keeps focus in a manual menu that remains open after ${key}`, async ({ mount, page }) => {
+      const component = await mount(DropdownMenuFixture)
+      const section = component.getByTestId('manual-menu')
+      const trigger = section.getByRole('button', { name: 'Manual trigger' })
+      const item = page.getByRole('menuitem', { name: 'Reasoning model' })
+
+      await section.getByRole('button', { name: 'Toggle manual menu' }).click()
+      await trigger.focus()
+      await trigger.press('ArrowDown')
+      await item.press(key)
+
+      await expect(page.getByRole('menu').filter({ hasText: 'Reasoning model' })).toBeVisible()
+      await expect(item).toBeFocused()
+    })
+  }
 })

From ceec2fdcdebee39f3b4b0d54169b6b07b4c94be2 Mon Sep 17 00:00:00 2001
From: gene9831 <pacify.98@gmail.com>
Date: Wed, 9 Sep 2026 14:51:40 +0800
Subject: [PATCH 4/4] fix(history): close action menu on tab and escape

---
 .../src/history/components/MenuList.vue       |  6 +++
 packages/components/src/history/index.vue     | 15 ++++++
 .../test/component/history/History.spec.ts    | 51 +++++++++++++++++++
 3 files changed, 72 insertions(+)

diff --git a/packages/components/src/history/components/MenuList.vue b/packages/components/src/history/components/MenuList.vue
index f941a790a..c9f63c099 100644
--- a/packages/components/src/history/components/MenuList.vue
+++ b/packages/components/src/history/components/MenuList.vue
@@ -74,6 +74,12 @@ const closeAndFocusTrigger = () => {
 }
 
 const handleKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'Tab') {
+    trigger.value = null
+    data.value = null
+    return
+  }
+
   const items = getMenuItems()
   const currentIndex = items.indexOf(document.activeElement as HTMLElement)
 
diff --git a/packages/components/src/history/index.vue b/packages/components/src/history/index.vue
index 676205450..2d39e7e97 100644
--- a/packages/components/src/history/index.vue
+++ b/packages/components/src/history/index.vue
@@ -103,6 +103,19 @@ const handleMenuTriggerKeydown = (event: KeyboardEvent, item: T, position: 'firs
   }
 }
 
+const closeMenu = () => {
+  menuTriggerEl.value = null
+  menuTriggerItem.value = null
+}
+
+const handleMenuTriggerEscape = (event: KeyboardEvent) => {
+  if (!menuTriggerEl.value) return
+
+  event.preventDefault()
+  event.stopPropagation()
+  closeMenu()
+}
+
 const handleClickMenuItem = (action: HistoryMenuItem) => {
   const item = menuTriggerItem.value
   const trigger = menuTriggerEl.value
@@ -183,6 +196,8 @@ const handleClickMenuItem = (action: HistoryMenuItem) => {
                 @click="(ev) => toggleMenu(ev, item)"
                 @keydown.down="(ev) => handleMenuTriggerKeydown(ev, item, 'first')"
                 @keydown.up="(ev) => handleMenuTriggerKeydown(ev, item, 'last')"
+                @keydown.escape="handleMenuTriggerEscape"
+                @keydown.tab="closeMenu"
               >
                 <IconMore></IconMore>
               </button>
diff --git a/packages/test/component/history/History.spec.ts b/packages/test/component/history/History.spec.ts
index a2ce16d12..8f78825e9 100644
--- a/packages/test/component/history/History.spec.ts
+++ b/packages/test/component/history/History.spec.ts
@@ -96,6 +96,57 @@ test.describe('History', () => {
     await expect(trigger).toHaveAttribute('aria-expanded', 'false')
   })
 
+  test('closes the action menu when Tab moves focus away', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('flat-history')
+    const trigger = history.getByRole('button', { name: 'First chat 更多操作' })
+    const menu = history.getByRole('menu')
+
+    await trigger.focus()
+    await trigger.press('ArrowDown')
+    await expect(history.getByRole('menuitem', { name: '重命名' })).toBeFocused()
+
+    await history.getByRole('menuitem', { name: '重命名' }).press('Tab')
+
+    await expect(menu).toBeHidden()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  test('closes a mouse-opened action menu with Escape from the trigger', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('flat-history')
+    const trigger = history.getByRole('button', { name: 'First chat 更多操作' })
+    const menu = history.getByRole('menu')
+
+    await history.locator('.tr-history__item').first().hover()
+    await trigger.click()
+    await expect(menu).toBeVisible()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+
+    await trigger.press('Escape')
+
+    await expect(menu).toBeHidden()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+  })
+
+  test('closes a mouse-opened action menu when Tab leaves the trigger', async ({ mount }) => {
+    const component = await mount(HistoryFixture)
+    const history = component.getByTestId('flat-history')
+    const trigger = history.getByRole('button', { name: 'First chat 更多操作' })
+    const nextTrigger = history.getByRole('button', { name: 'Second chat 更多操作' })
+    const menu = history.getByRole('menu')
+
+    await history.locator('.tr-history__item').first().hover()
+    await trigger.click()
+    await expect(menu).toBeVisible()
+
+    await trigger.press('Tab')
+
+    await expect(menu).toBeHidden()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+    await expect(nextTrigger).toBeFocused()
+  })
+
   test('cancels rename with Escape without emitting a title change', async ({ mount }) => {
     const component = await mount(HistoryFixture)
     const history = component.getByTestId('cancel-history')