From 5d39a93bc33d77bcfa2958df515f7f2b352cecaa Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Sun, 29 Mar 2026 22:04:42 +0800
Subject: [PATCH 01/19] feat(stage-tamagotchi): add auto-hide controls island
 settings

Add configurable auto-hide feature for controls island:
- autoHideControlsIsland: toggle to enable/disable
- autoHideDelay: delay before hiding (0-60s, default 5s)
- autoShowDelay: delay before showing after mouse enters (0-5s, default 0)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../stage-islands/controls-island/index.vue   | 57 +++++++++++++++++--
 .../components/settings-general-fields.vue    | 48 +++++++++++++++-
 .../src/stores/settings/controls-island.ts    |  9 +++
 3 files changed, 106 insertions(+), 8 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index a99bf9f721..6786c03f32 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { defineInvoke } from '@moeru/eventa'
 import { useElectronEventaContext, useElectronEventaInvoke, useElectronMouseInElement } from '@proj-airi/electron-vueuse'
-import { useSettings, useSettingsAudioDevice } from '@proj-airi/stage-ui/stores/settings'
+import { useSettings, useSettingsAudioDevice, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
 import { useTheme } from '@proj-airi/ui'
 import { refDebounced, useIntervalFn } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
@@ -29,9 +29,11 @@ const { t } = useI18n()
 
 const settingsAudioDeviceStore = useSettingsAudioDevice()
 const settingsStore = useSettings()
+const settingsControlsIslandStore = useSettingsControlsIsland()
 const context = useElectronEventaContext()
 const { enabled } = storeToRefs(settingsAudioDeviceStore)
 const { alwaysOnTop, controlsIslandIconSize } = storeToRefs(settingsStore)
+const { autoHideControlsIsland, autoHideDelay, autoShowDelay } = storeToRefs(settingsControlsIslandStore)
 const openSettings = useElectronEventaInvoke(electronOpenSettings)
 const openChat = useElectronEventaInvoke(electronOpenChat)
 const isLinux = useElectronEventaInvoke(electron.app.isLinux)
@@ -46,7 +48,10 @@ const blockingOverlays = reactive(new Set<string>())
 const isBlocked = computed(() => blockingOverlays.size > 0)
 
 function setOverlay(key: string, active: boolean) {
-  active ? blockingOverlays.add(key) : blockingOverlays.delete(key)
+  if (active)
+    blockingOverlays.add(key)
+  else
+    blockingOverlays.delete(key)
 }
 
 // Expose for parent (e.g. to disable click-through when a dialog is open)
@@ -56,9 +61,42 @@ defineExpose({
 })
 
 const { isOutside } = useElectronMouseInElement(islandRef)
-const isOutsideAfter2seconds = refDebounced(isOutside, 1500)
 
-watch(isOutsideAfter2seconds, (outside) => {
+// Auto-hide logic with configurable delays
+const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
+const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
+
+// Debounced outside state for hide delay
+const isOutsideForHide = refDebounced(isOutside, () => autoHideDelayMs.value || 5000)
+
+// Debounced inside state for show delay
+const isInsideForShow = refDebounced(computed(() => !isOutside.value), () => autoShowDelayMs.value || 0)
+
+// Auto-hide: hide controls island when mouse leaves after delay
+// Auto-show: show controls island when mouse enters after delay
+const isHidden = computed(() => {
+  if (!autoHideControlsIsland.value)
+    return false
+
+  // Don't hide if there's a blocking overlay or expanded panel should stay
+  if (isBlocked.value || expanded.value)
+    return false
+
+  // When mouse is inside, always show immediately
+  if (!isOutside.value)
+    return false
+
+  // When autoShowDelay > 0, wait for mouse to be inside for the configured delay before showing
+  if (autoShowDelay.value > 0) {
+    // Hide if not yet inside for show delay
+    return !isInsideForShow.value
+  }
+
+  // Default: hide when mouse has been outside for the configured delay
+  return isOutsideForHide.value
+})
+
+watch(isOutsideForHide, (outside) => {
   if (outside && expanded.value && !isBlocked.value) {
     expanded.value = false
   }
@@ -74,7 +112,7 @@ useIntervalFn(() => {
   if (expanded.value && isOutside.value && !isBlocked.value) {
     expanded.value = false
   }
-}, 1500)
+}, () => autoHideDelayMs.value || 5000)
 
 // Apply alwaysOnTop on mount and when it changes
 watch(alwaysOnTop, (val) => {
@@ -125,7 +163,14 @@ function refreshWindow() {
 </script>
 
 <template>
-  <div ref="islandRef" fixed bottom-2 right-2>
+  <div
+    ref="islandRef"
+    fixed bottom-2 right-2
+    :class="[
+      autoHideControlsIsland ? 'transition-opacity duration-300' : '',
+      isHidden ? 'opacity-0' : 'opacity-100',
+    ]"
+  >
     <div flex flex-col items-end gap-1>
       <!-- iOS Style Drawer Panel -->
       <Transition
diff --git a/packages/stage-pages/src/components/settings-general-fields.vue b/packages/stage-pages/src/components/settings-general-fields.vue
index e36c79c39a..668029d704 100644
--- a/packages/stage-pages/src/components/settings-general-fields.vue
+++ b/packages/stage-pages/src/components/settings-general-fields.vue
@@ -2,20 +2,24 @@
 import { all } from '@proj-airi/i18n'
 import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { isPosthogAvailableInBuild } from '@proj-airi/stage-ui/stores/analytics'
-import { useSettings } from '@proj-airi/stage-ui/stores/settings'
-import { FieldCheckbox, FieldCombobox, useTheme } from '@proj-airi/ui'
+import { useSettings, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
+import { FieldCheckbox, FieldCombobox, FieldInput, useTheme } from '@proj-airi/ui'
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 const props = withDefaults(defineProps<{
   needsControlsIslandIconSizeSetting?: boolean
+  needsAutoHideControlsIslandSetting?: boolean
 }>(), {
   needsControlsIslandIconSizeSetting: import.meta.env.RUNTIME_ENVIRONMENT === 'electron',
+  needsAutoHideControlsIslandSetting: import.meta.env.RUNTIME_ENVIRONMENT === 'electron',
 })
 
 const settings = useSettings()
+const settingsControlsIsland = useSettingsControlsIsland()
 
 const showControlsIsland = computed(() => props.needsControlsIslandIconSizeSetting)
+const showAutoHideControlsIsland = computed(() => props.needsAutoHideControlsIslandSetting)
 const showAnalyticsSettings = computed(() => isPosthogAvailableInBuild())
 const analyticsToggleValue = computed({
   get: () => showAnalyticsSettings.value ? settings.analyticsEnabled : false,
@@ -77,6 +81,46 @@ const languages = computed(() => {
       ]"
     />
 
+    <FieldCheckbox
+      v-if="showAutoHideControlsIsland"
+      v-model="settingsControlsIsland.autoHideControlsIsland"
+      v-motion
+      :initial="{ opacity: 0, y: 10 }"
+      :enter="{ opacity: 1, y: 0 }"
+      :duration="250 + (5 * 10)"
+      :delay="5 * 50"
+      label="Auto-hide controls island"
+      description="Hide controls island after mouse leaves, show after mouse enters"
+    />
+
+    <template v-if="showAutoHideControlsIsland && settingsControlsIsland.autoHideControlsIsland">
+      <FieldInput
+        v-model.number="settingsControlsIsland.autoHideDelay"
+        v-motion
+        :initial="{ opacity: 0, y: 10 }"
+        :enter="{ opacity: 1, y: 0 }"
+        :duration="250 + (6 * 10)"
+        :delay="6 * 50"
+        type="number"
+        :min="0"
+        :max="60"
+        label="Hide delay (seconds)"
+      />
+
+      <FieldInput
+        v-model.number="settingsControlsIsland.autoShowDelay"
+        v-motion
+        :initial="{ opacity: 0, y: 10 }"
+        :enter="{ opacity: 1, y: 0 }"
+        :duration="250 + (7 * 10)"
+        :delay="7 * 50"
+        type="number"
+        :min="0"
+        :max="5"
+        label="Show delay (seconds)"
+      />
+    </template>
+
     <FieldCheckbox
       v-model="analyticsToggleValue"
       v-motion
diff --git a/packages/stage-ui/src/stores/settings/controls-island.ts b/packages/stage-ui/src/stores/settings/controls-island.ts
index 67ae1d47cc..f9104b3e72 100644
--- a/packages/stage-ui/src/stores/settings/controls-island.ts
+++ b/packages/stage-ui/src/stores/settings/controls-island.ts
@@ -5,17 +5,26 @@ export const useSettingsControlsIsland = defineStore('settings-controls-island',
   const allowVisibleOnAllWorkspaces = useLocalStorageManualReset<boolean>('settings/allow-visible-on-all-workspaces', true)
   const alwaysOnTop = useLocalStorageManualReset<boolean>('settings/always-on-top', true)
   const controlsIslandIconSize = useLocalStorageManualReset<'auto' | 'large' | 'small'>('settings/controls-island/icon-size', 'auto')
+  const autoHideControlsIsland = useLocalStorageManualReset<boolean>('settings/controls-island/auto-hide', false)
+  const autoHideDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-hide-delay', 5)
+  const autoShowDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-show-delay', 0)
 
   function resetState() {
     allowVisibleOnAllWorkspaces.reset()
     alwaysOnTop.reset()
     controlsIslandIconSize.reset()
+    autoHideControlsIsland.reset()
+    autoHideDelay.reset()
+    autoShowDelay.reset()
   }
 
   return {
     allowVisibleOnAllWorkspaces,
     alwaysOnTop,
     controlsIslandIconSize,
+    autoHideControlsIsland,
+    autoHideDelay,
+    autoShowDelay,
     resetState,
   }
 })

From bcdbad72af6fdd24256abbbae740856c9c31ec3f Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Sun, 29 Mar 2026 22:35:19 +0800
Subject: [PATCH 02/19] feat(stage-tamagotchi): watch show delay and hide delay

---
 .../stage-islands/controls-island/index.vue   | 49 +++++++++++++------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 6786c03f32..3ad23fc940 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -3,7 +3,7 @@ import { defineInvoke } from '@moeru/eventa'
 import { useElectronEventaContext, useElectronEventaInvoke, useElectronMouseInElement } from '@proj-airi/electron-vueuse'
 import { useSettings, useSettingsAudioDevice, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
 import { useTheme } from '@proj-airi/ui'
-import { refDebounced, useIntervalFn } from '@vueuse/core'
+import { useIntervalFn } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
 import { computed, reactive, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
@@ -66,11 +66,27 @@ const { isOutside } = useElectronMouseInElement(islandRef)
 const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
 const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
 
-// Debounced outside state for hide delay
-const isOutsideForHide = refDebounced(isOutside, () => autoHideDelayMs.value || 5000)
+// Track time since mouse left/entered
+const timeSinceOutside = ref(0)
+const timeSinceInside = ref(0)
 
-// Debounced inside state for show delay
-const isInsideForShow = refDebounced(computed(() => !isOutside.value), () => autoShowDelayMs.value || 0)
+let lastUpdateTime = Date.now()
+
+// Update time tracking
+useIntervalFn(() => {
+  const now = Date.now()
+  const delta = now - lastUpdateTime
+  lastUpdateTime = now
+
+  if (isOutside.value) {
+    timeSinceOutside.value += delta
+    timeSinceInside.value = 0
+  }
+  else {
+    timeSinceInside.value += delta
+    timeSinceOutside.value = 0
+  }
+}, 100)
 
 // Auto-hide: hide controls island when mouse leaves after delay
 // Auto-show: show controls island when mouse enters after delay
@@ -82,21 +98,24 @@ const isHidden = computed(() => {
   if (isBlocked.value || expanded.value)
     return false
 
-  // When mouse is inside, always show immediately
-  if (!isOutside.value)
+  // When mouse is inside, always show immediately (unless show delay is set)
+  if (!isOutside.value) {
+    if (autoShowDelay.value > 0) {
+      // Wait for mouse to be inside for the configured delay before showing
+      return timeSinceInside.value < autoShowDelayMs.value
+    }
     return false
-
-  // When autoShowDelay > 0, wait for mouse to be inside for the configured delay before showing
-  if (autoShowDelay.value > 0) {
-    // Hide if not yet inside for show delay
-    return !isInsideForShow.value
   }
 
-  // Default: hide when mouse has been outside for the configured delay
-  return isOutsideForHide.value
+  // When mouse is outside, hide after delay
+  return timeSinceOutside.value >= autoHideDelayMs.value
 })
 
-watch(isOutsideForHide, (outside) => {
+watch(isOutside, (outside) => {
+  lastUpdateTime = Date.now()
+  timeSinceOutside.value = 0
+  timeSinceInside.value = 0
+
   if (outside && expanded.value && !isBlocked.value) {
     expanded.value = false
   }

From 2f5562ba7576814c152744bc358118f6c046328a Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Tue, 31 Mar 2026 23:57:20 +0800
Subject: [PATCH 03/19] feat(settings): add auto-hide opacity setting for
 controls island

---
 .../stage-islands/controls-island/index.vue   |  7 ++--
 .../components/settings-general-fields.vue    | 32 ++++++++++++++-----
 .../src/stores/settings/controls-island.ts    |  7 ++--
 3 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 3ad23fc940..e0ff60a242 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -33,7 +33,7 @@ const settingsControlsIslandStore = useSettingsControlsIsland()
 const context = useElectronEventaContext()
 const { enabled } = storeToRefs(settingsAudioDeviceStore)
 const { alwaysOnTop, controlsIslandIconSize } = storeToRefs(settingsStore)
-const { autoHideControlsIsland, autoHideDelay, autoShowDelay } = storeToRefs(settingsControlsIslandStore)
+const { autoHideControlsIsland, autoHideDelay, autoShowDelay, autoHideOpacity } = storeToRefs(settingsControlsIslandStore)
 const openSettings = useElectronEventaInvoke(electronOpenSettings)
 const openChat = useElectronEventaInvoke(electronOpenChat)
 const isLinux = useElectronEventaInvoke(electron.app.isLinux)
@@ -88,6 +88,9 @@ useIntervalFn(() => {
   }
 }, 100)
 
+// Calculate opacity when hidden (0-100 range converted to 0-1)
+const hiddenOpacity = computed(() => autoHideOpacity.value / 100)
+
 // Auto-hide: hide controls island when mouse leaves after delay
 // Auto-show: show controls island when mouse enters after delay
 const isHidden = computed(() => {
@@ -185,9 +188,9 @@ function refreshWindow() {
   <div
     ref="islandRef"
     fixed bottom-2 right-2
+    :style="autoHideControlsIsland ? { opacity: isHidden ? hiddenOpacity : 1 } : {}"
     :class="[
       autoHideControlsIsland ? 'transition-opacity duration-300' : '',
-      isHidden ? 'opacity-0' : 'opacity-100',
     ]"
   >
     <div flex flex-col items-end gap-1>
diff --git a/packages/stage-pages/src/components/settings-general-fields.vue b/packages/stage-pages/src/components/settings-general-fields.vue
index 668029d704..443810d55c 100644
--- a/packages/stage-pages/src/components/settings-general-fields.vue
+++ b/packages/stage-pages/src/components/settings-general-fields.vue
@@ -3,7 +3,7 @@ import { all } from '@proj-airi/i18n'
 import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { isPosthogAvailableInBuild } from '@proj-airi/stage-ui/stores/analytics'
 import { useSettings, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
-import { FieldCheckbox, FieldCombobox, FieldInput, useTheme } from '@proj-airi/ui'
+import { FieldCheckbox, FieldCombobox, FieldRange, useTheme } from '@proj-airi/ui'
 import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 
@@ -94,30 +94,46 @@ const languages = computed(() => {
     />
 
     <template v-if="showAutoHideControlsIsland && settingsControlsIsland.autoHideControlsIsland">
-      <FieldInput
+      <FieldRange
         v-model.number="settingsControlsIsland.autoHideDelay"
         v-motion
         :initial="{ opacity: 0, y: 10 }"
         :enter="{ opacity: 1, y: 0 }"
         :duration="250 + (6 * 10)"
         :delay="6 * 50"
-        type="number"
         :min="0"
-        :max="60"
-        label="Hide delay (seconds)"
+        :max="5"
+        :step="0.1"
+        :format-value="v => `${v}s`"
+        label="Hide delay"
       />
 
-      <FieldInput
+      <FieldRange
         v-model.number="settingsControlsIsland.autoShowDelay"
         v-motion
         :initial="{ opacity: 0, y: 10 }"
         :enter="{ opacity: 1, y: 0 }"
         :duration="250 + (7 * 10)"
         :delay="7 * 50"
-        type="number"
         :min="0"
         :max="5"
-        label="Show delay (seconds)"
+        :step="0.1"
+        :format-value="v => `${v}s`"
+        label="Show delay"
+      />
+
+      <FieldRange
+        v-model.number="settingsControlsIsland.autoHideOpacity"
+        v-motion
+        :initial="{ opacity: 0, y: 10 }"
+        :enter="{ opacity: 1, y: 0 }"
+        :duration="250 + (8 * 10)"
+        :delay="8 * 50"
+        :min="0"
+        :max="100"
+        :step="1"
+        :format-value="v => `${v}%`"
+        label="Hidden opacity"
       />
     </template>
 
diff --git a/packages/stage-ui/src/stores/settings/controls-island.ts b/packages/stage-ui/src/stores/settings/controls-island.ts
index f9104b3e72..6af3ed3d4a 100644
--- a/packages/stage-ui/src/stores/settings/controls-island.ts
+++ b/packages/stage-ui/src/stores/settings/controls-island.ts
@@ -6,8 +6,9 @@ export const useSettingsControlsIsland = defineStore('settings-controls-island',
   const alwaysOnTop = useLocalStorageManualReset<boolean>('settings/always-on-top', true)
   const controlsIslandIconSize = useLocalStorageManualReset<'auto' | 'large' | 'small'>('settings/controls-island/icon-size', 'auto')
   const autoHideControlsIsland = useLocalStorageManualReset<boolean>('settings/controls-island/auto-hide', false)
-  const autoHideDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-hide-delay', 5)
-  const autoShowDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-show-delay', 0)
+  const autoHideDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-hide-delay', 0.5)
+  const autoShowDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-show-delay', 0.5)
+  const autoHideOpacity = useLocalStorageManualReset<number>('settings/controls-island/auto-hide-opacity', 30)
 
   function resetState() {
     allowVisibleOnAllWorkspaces.reset()
@@ -16,6 +17,7 @@ export const useSettingsControlsIsland = defineStore('settings-controls-island',
     autoHideControlsIsland.reset()
     autoHideDelay.reset()
     autoShowDelay.reset()
+    autoHideOpacity.reset()
   }
 
   return {
@@ -25,6 +27,7 @@ export const useSettingsControlsIsland = defineStore('settings-controls-island',
     autoHideControlsIsland,
     autoHideDelay,
     autoShowDelay,
+    autoHideOpacity,
     resetState,
   }
 })

From 98981fd20de013f857a63888aa681a02cc931f06 Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 00:15:49 +0800
Subject: [PATCH 04/19] feat(settings): remove controls island icon size
 setting and simplify styles

---
 .../stage-islands/controls-island/index.vue   | 34 +++++--------------
 .../components/settings-general-fields.vue    | 21 ------------
 .../src/stores/settings/controls-island.ts    |  3 --
 .../stage-ui/src/stores/settings/index.ts     |  1 -
 4 files changed, 8 insertions(+), 51 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index e0ff60a242..5853b2bc4b 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -32,7 +32,7 @@ const settingsStore = useSettings()
 const settingsControlsIslandStore = useSettingsControlsIsland()
 const context = useElectronEventaContext()
 const { enabled } = storeToRefs(settingsAudioDeviceStore)
-const { alwaysOnTop, controlsIslandIconSize } = storeToRefs(settingsStore)
+const { alwaysOnTop } = storeToRefs(settingsStore)
 const { autoHideControlsIsland, autoHideDelay, autoShowDelay, autoHideOpacity } = storeToRefs(settingsControlsIslandStore)
 const openSettings = useElectronEventaInvoke(electronOpenSettings)
 const openChat = useElectronEventaInvoke(electronOpenChat)
@@ -145,31 +145,13 @@ function toggleAlwaysOnTop() {
   alwaysOnTop.value = !alwaysOnTop.value
 }
 
-// Grouped classes for icon / border / padding and combined style class
-const adjustStyleClasses = computed(() => {
-  let isLarge: boolean
-
-  // Determine size based on setting
-  switch (controlsIslandIconSize.value) {
-    case 'large':
-      isLarge = true
-      break
-    case 'small':
-      isLarge = false
-      break
-    case 'auto':
-    default:
-      // Fixed to large for better visibility in the new layout,
-      // can be changed to windowHeight based check if absolutely needed.
-      isLarge = true
-      break
-  }
-
-  const icon = isLarge ? 'size-5' : 'size-3'
-  const border = isLarge ? 'border-2' : 'border-0'
-  const padding = isLarge ? 'p-2' : 'p-0.5'
-  return { icon, border, padding, button: `${border} ${padding}` }
-})
+// Static style classes for icon / border / padding
+const adjustStyleClasses = {
+  icon: 'size-5',
+  border: 'border-2',
+  padding: 'p-2',
+  button: 'border-2 p-2',
+}
 
 /**
  * This is a know issue (or expected behavior maybe) to Electron.
diff --git a/packages/stage-pages/src/components/settings-general-fields.vue b/packages/stage-pages/src/components/settings-general-fields.vue
index 443810d55c..f07d44eba0 100644
--- a/packages/stage-pages/src/components/settings-general-fields.vue
+++ b/packages/stage-pages/src/components/settings-general-fields.vue
@@ -8,17 +8,14 @@ import { computed } from 'vue'
 import { useI18n } from 'vue-i18n'
 
 const props = withDefaults(defineProps<{
-  needsControlsIslandIconSizeSetting?: boolean
   needsAutoHideControlsIslandSetting?: boolean
 }>(), {
-  needsControlsIslandIconSizeSetting: import.meta.env.RUNTIME_ENVIRONMENT === 'electron',
   needsAutoHideControlsIslandSetting: import.meta.env.RUNTIME_ENVIRONMENT === 'electron',
 })
 
 const settings = useSettings()
 const settingsControlsIsland = useSettingsControlsIsland()
 
-const showControlsIsland = computed(() => props.needsControlsIslandIconSizeSetting)
 const showAutoHideControlsIsland = computed(() => props.needsAutoHideControlsIslandSetting)
 const showAnalyticsSettings = computed(() => isPosthogAvailableInBuild())
 const analyticsToggleValue = computed({
@@ -63,24 +60,6 @@ const languages = computed(() => {
       :options="languages"
     />
 
-    <FieldCombobox
-      v-if="showControlsIsland"
-      v-model="settings.controlsIslandIconSize"
-      v-motion
-      :initial="{ opacity: 0, y: 10 }"
-      :enter="{ opacity: 1, y: 0 }"
-      :duration="250 + (4 * 10)"
-      :delay="4 * 50"
-      :class="['transition-all', 'ease-in-out', 'duration-250']"
-      :label="t('settings.controls-island.icon-size.title')"
-      :description="t('settings.controls-island.icon-size.description')"
-      :options="[
-        { value: 'auto', label: t('settings.controls-island.icon-size.auto') },
-        { value: 'large', label: t('settings.controls-island.icon-size.large') },
-        { value: 'small', label: t('settings.controls-island.icon-size.small') },
-      ]"
-    />
-
     <FieldCheckbox
       v-if="showAutoHideControlsIsland"
       v-model="settingsControlsIsland.autoHideControlsIsland"
diff --git a/packages/stage-ui/src/stores/settings/controls-island.ts b/packages/stage-ui/src/stores/settings/controls-island.ts
index 6af3ed3d4a..0c2149cc4d 100644
--- a/packages/stage-ui/src/stores/settings/controls-island.ts
+++ b/packages/stage-ui/src/stores/settings/controls-island.ts
@@ -4,7 +4,6 @@ import { defineStore } from 'pinia'
 export const useSettingsControlsIsland = defineStore('settings-controls-island', () => {
   const allowVisibleOnAllWorkspaces = useLocalStorageManualReset<boolean>('settings/allow-visible-on-all-workspaces', true)
   const alwaysOnTop = useLocalStorageManualReset<boolean>('settings/always-on-top', true)
-  const controlsIslandIconSize = useLocalStorageManualReset<'auto' | 'large' | 'small'>('settings/controls-island/icon-size', 'auto')
   const autoHideControlsIsland = useLocalStorageManualReset<boolean>('settings/controls-island/auto-hide', false)
   const autoHideDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-hide-delay', 0.5)
   const autoShowDelay = useLocalStorageManualReset<number>('settings/controls-island/auto-show-delay', 0.5)
@@ -13,7 +12,6 @@ export const useSettingsControlsIsland = defineStore('settings-controls-island',
   function resetState() {
     allowVisibleOnAllWorkspaces.reset()
     alwaysOnTop.reset()
-    controlsIslandIconSize.reset()
     autoHideControlsIsland.reset()
     autoHideDelay.reset()
     autoShowDelay.reset()
@@ -23,7 +21,6 @@ export const useSettingsControlsIsland = defineStore('settings-controls-island',
   return {
     allowVisibleOnAllWorkspaces,
     alwaysOnTop,
-    controlsIslandIconSize,
     autoHideControlsIsland,
     autoHideDelay,
     autoShowDelay,
diff --git a/packages/stage-ui/src/stores/settings/index.ts b/packages/stage-ui/src/stores/settings/index.ts
index c74bc7b629..9c501c1389 100644
--- a/packages/stage-ui/src/stores/settings/index.ts
+++ b/packages/stage-ui/src/stores/settings/index.ts
@@ -82,7 +82,6 @@ export const useSettings = defineStore('settings', () => {
     // UI settings
     allowVisibleOnAllWorkspaces: controlsIslandRefs.allowVisibleOnAllWorkspaces,
     alwaysOnTop: controlsIslandRefs.alwaysOnTop,
-    controlsIslandIconSize: controlsIslandRefs.controlsIslandIconSize,
 
     // Methods
     setThemeColorsHue: theme.setThemeColorsHue,

From 91c6ad26b49636ec6e0a8bf1e8b362c20d500f02 Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 00:25:08 +0800
Subject: [PATCH 05/19] feat(settings): update auto-hide controls island
 setting to use isStageTamagotchi

---
 .../stage-pages/src/components/settings-general-fields.vue     | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/stage-pages/src/components/settings-general-fields.vue b/packages/stage-pages/src/components/settings-general-fields.vue
index f07d44eba0..2920dafa43 100644
--- a/packages/stage-pages/src/components/settings-general-fields.vue
+++ b/packages/stage-pages/src/components/settings-general-fields.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { all } from '@proj-airi/i18n'
+import { isStageTamagotchi } from '@proj-airi/stage-shared'
 import { useAnalytics } from '@proj-airi/stage-ui/composables/use-analytics'
 import { isPosthogAvailableInBuild } from '@proj-airi/stage-ui/stores/analytics'
 import { useSettings, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
@@ -10,7 +11,7 @@ import { useI18n } from 'vue-i18n'
 const props = withDefaults(defineProps<{
   needsAutoHideControlsIslandSetting?: boolean
 }>(), {
-  needsAutoHideControlsIslandSetting: import.meta.env.RUNTIME_ENVIRONMENT === 'electron',
+  needsAutoHideControlsIslandSetting: isStageTamagotchi(),
 })
 
 const settings = useSettings()

From a2b65bcc46d08b0444c5caba8bfbf419cdb706a8 Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 00:56:27 +0800
Subject: [PATCH 06/19] feat(tests): add unit tests for
 settings-controls-island store

---
 .../stores/settings/controls-island.test.ts   | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 packages/stage-ui/src/stores/settings/controls-island.test.ts

diff --git a/packages/stage-ui/src/stores/settings/controls-island.test.ts b/packages/stage-ui/src/stores/settings/controls-island.test.ts
new file mode 100644
index 0000000000..7ba5f3c068
--- /dev/null
+++ b/packages/stage-ui/src/stores/settings/controls-island.test.ts
@@ -0,0 +1,67 @@
+import { createTestingPinia } from '@pinia/testing'
+import { setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { useSettingsControlsIsland } from './controls-island'
+
+describe('store settings-controls-island', () => {
+  beforeEach(() => {
+    const pinia = createTestingPinia({ createSpy: vi.fn, stubActions: false })
+    setActivePinia(pinia)
+  })
+
+  it('should have correct default values', () => {
+    const store = useSettingsControlsIsland()
+
+    expect(store.allowVisibleOnAllWorkspaces).toBe(true)
+    expect(store.alwaysOnTop).toBe(true)
+    expect(store.autoHideControlsIsland).toBe(false)
+    expect(store.autoHideDelay).toBe(0.5)
+    expect(store.autoShowDelay).toBe(0.5)
+    expect(store.autoHideOpacity).toBe(30)
+  })
+
+  it('should allow updating values', () => {
+    const store = useSettingsControlsIsland()
+
+    store.allowVisibleOnAllWorkspaces = false
+    store.alwaysOnTop = false
+    store.autoHideControlsIsland = true
+    store.autoHideDelay = 2
+    store.autoShowDelay = 1.5
+    store.autoHideOpacity = 50
+
+    expect(store.allowVisibleOnAllWorkspaces).toBe(false)
+    expect(store.alwaysOnTop).toBe(false)
+    expect(store.autoHideControlsIsland).toBe(true)
+    expect(store.autoHideDelay).toBe(2)
+    expect(store.autoShowDelay).toBe(1.5)
+    expect(store.autoHideOpacity).toBe(50)
+  })
+
+  it('should reset to default values via resetState action', () => {
+    const store = useSettingsControlsIsland()
+
+    // Modify values
+    store.allowVisibleOnAllWorkspaces = false
+    store.alwaysOnTop = false
+    store.autoHideControlsIsland = true
+    store.autoHideDelay = 3
+    store.autoShowDelay = 2
+    store.autoHideOpacity = 80
+
+    // Verify values were modified
+    expect(store.allowVisibleOnAllWorkspaces).toBe(false)
+
+    // Reset via action
+    store.resetState()
+
+    // Check defaults are restored
+    expect(store.allowVisibleOnAllWorkspaces).toBe(true)
+    expect(store.alwaysOnTop).toBe(true)
+    expect(store.autoHideControlsIsland).toBe(false)
+    expect(store.autoHideDelay).toBe(0.5)
+    expect(store.autoShowDelay).toBe(0.5)
+    expect(store.autoHideOpacity).toBe(30)
+  })
+})

From a41440a8313b62d739b07cc180b5a78ab0a90084 Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 01:41:46 +0800
Subject: [PATCH 07/19] feat(settings): refactor auto-hide logic using
 refDebounced for improved delay handling

---
 .../stage-islands/controls-island/index.vue   | 50 +++++--------------
 1 file changed, 13 insertions(+), 37 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 5853b2bc4b..0aae4d7851 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -3,7 +3,7 @@ import { defineInvoke } from '@moeru/eventa'
 import { useElectronEventaContext, useElectronEventaInvoke, useElectronMouseInElement } from '@proj-airi/electron-vueuse'
 import { useSettings, useSettingsAudioDevice, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
 import { useTheme } from '@proj-airi/ui'
-import { useIntervalFn } from '@vueuse/core'
+import { refDebounced } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
 import { computed, reactive, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
@@ -66,27 +66,11 @@ const { isOutside } = useElectronMouseInElement(islandRef)
 const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
 const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
 
-// Track time since mouse left/entered
-const timeSinceOutside = ref(0)
-const timeSinceInside = ref(0)
+// Use refDebounced for auto-hide: isOutside becomes true after autoHideDelay
+const isOutsideDelayed = refDebounced(isOutside, autoHideControlsIsland.value ? autoHideDelayMs.value : 1500)
 
-let lastUpdateTime = Date.now()
-
-// Update time tracking
-useIntervalFn(() => {
-  const now = Date.now()
-  const delta = now - lastUpdateTime
-  lastUpdateTime = now
-
-  if (isOutside.value) {
-    timeSinceOutside.value += delta
-    timeSinceInside.value = 0
-  }
-  else {
-    timeSinceInside.value += delta
-    timeSinceOutside.value = 0
-  }
-}, 100)
+// Use refDebounced for auto-show: isOutside becomes false after autoShowDelay
+const isInsideDelayed = refDebounced(computed(() => !isOutside.value), autoShowDelayMs)
 
 // Calculate opacity when hidden (0-100 range converted to 0-1)
 const hiddenOpacity = computed(() => autoHideOpacity.value / 100)
@@ -101,27 +85,17 @@ const isHidden = computed(() => {
   if (isBlocked.value || expanded.value)
     return false
 
-  // When mouse is inside, always show immediately (unless show delay is set)
+  // When mouse is inside, wait for show delay before fully showing
   if (!isOutside.value) {
     if (autoShowDelay.value > 0) {
       // Wait for mouse to be inside for the configured delay before showing
-      return timeSinceInside.value < autoShowDelayMs.value
+      return !isInsideDelayed.value
     }
     return false
   }
 
   // When mouse is outside, hide after delay
-  return timeSinceOutside.value >= autoHideDelayMs.value
-})
-
-watch(isOutside, (outside) => {
-  lastUpdateTime = Date.now()
-  timeSinceOutside.value = 0
-  timeSinceInside.value = 0
-
-  if (outside && expanded.value && !isBlocked.value) {
-    expanded.value = false
-  }
+  return isOutsideDelayed.value
 })
 
 watch(expanded, (isExpanded) => {
@@ -130,11 +104,13 @@ watch(expanded, (isExpanded) => {
   }
 })
 
-useIntervalFn(() => {
-  if (expanded.value && isOutside.value && !isBlocked.value) {
+// Auto-collapse expanded panel when mouse leaves for configured delay
+// Using refDebounced for consistent delay behavior
+watch(isOutsideDelayed, (isDelayedOutside) => {
+  if (isDelayedOutside && expanded.value && !isBlocked.value) {
     expanded.value = false
   }
-}, () => autoHideDelayMs.value || 5000)
+})
 
 // Apply alwaysOnTop on mount and when it changes
 watch(alwaysOnTop, (val) => {

From b944bd81e7987090a1c2b4a2e1068be356df5aa9 Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 02:53:13 +0800
Subject: [PATCH 08/19] feat(settings): update auto-hide logic to use computed
 for dynamic delay handling

---
 .../renderer/components/stage-islands/controls-island/index.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 0aae4d7851..438e8efa39 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -67,7 +67,7 @@ const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
 const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
 
 // Use refDebounced for auto-hide: isOutside becomes true after autoHideDelay
-const isOutsideDelayed = refDebounced(isOutside, autoHideControlsIsland.value ? autoHideDelayMs.value : 1500)
+const isOutsideDelayed = refDebounced(isOutside, computed(() => autoHideControlsIsland.value ? autoHideDelayMs.value : 1500))
 
 // Use refDebounced for auto-show: isOutside becomes false after autoShowDelay
 const isInsideDelayed = refDebounced(computed(() => !isOutside.value), autoShowDelayMs)

From 0597d3f3e32b073806ae9abcdda990fc0448d1c2 Mon Sep 17 00:00:00 2001
From: leafyy <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 03:35:00 +0800
Subject: [PATCH 09/19] feat(settings): update auto-hide delay logic to use
 configurable settings

---
 .../components/stage-islands/controls-island/index.vue     | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 438e8efa39..9e8ec1372a 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -63,11 +63,10 @@ defineExpose({
 const { isOutside } = useElectronMouseInElement(islandRef)
 
 // Auto-hide logic with configurable delays
-const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
+const autoHideDelayMs = computed(() => autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500)
 const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
-
 // Use refDebounced for auto-hide: isOutside becomes true after autoHideDelay
-const isOutsideDelayed = refDebounced(isOutside, computed(() => autoHideControlsIsland.value ? autoHideDelayMs.value : 1500))
+const isOutsideDelayed = refDebounced(isOutside, autoHideDelayMs)
 
 // Use refDebounced for auto-show: isOutside becomes false after autoShowDelay
 const isInsideDelayed = refDebounced(computed(() => !isOutside.value), autoShowDelayMs)
@@ -145,7 +144,7 @@ function refreshWindow() {
 <template>
   <div
     ref="islandRef"
-    fixed bottom-2 right-2
+    fixed bottom-2 right-2 bg-red
     :style="autoHideControlsIsland ? { opacity: isHidden ? hiddenOpacity : 1 } : {}"
     :class="[
       autoHideControlsIsland ? 'transition-opacity duration-300' : '',

From c29304cc28bdada87d0787c76cadf6ee77a772b3 Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 10:36:42 +0800
Subject: [PATCH 10/19] feat(stage-ui): remove redundant background color class
 from island div

---
 .../renderer/components/stage-islands/controls-island/index.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 9e8ec1372a..2844d17c9b 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -144,7 +144,7 @@ function refreshWindow() {
 <template>
   <div
     ref="islandRef"
-    fixed bottom-2 right-2 bg-red
+    fixed bottom-2 right-2
     :style="autoHideControlsIsland ? { opacity: isHidden ? hiddenOpacity : 1 } : {}"
     :class="[
       autoHideControlsIsland ? 'transition-opacity duration-300' : '',

From 577b94594c4e53bacce0c0800a275177b4e50f19 Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 17:32:52 +0800
Subject: [PATCH 11/19] feat(controls-island): refactor auto-hide logic to use
 useTimeoutFn for improved delay handling

---
 .../stage-islands/controls-island/index.vue   |  75 ++-
 .../settings/controls-island-autohide.test.ts | 444 ++++++++++++++++++
 2 files changed, 503 insertions(+), 16 deletions(-)
 create mode 100644 packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 2844d17c9b..e691c012b6 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -3,7 +3,7 @@ import { defineInvoke } from '@moeru/eventa'
 import { useElectronEventaContext, useElectronEventaInvoke, useElectronMouseInElement } from '@proj-airi/electron-vueuse'
 import { useSettings, useSettingsAudioDevice, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
 import { useTheme } from '@proj-airi/ui'
-import { refDebounced } from '@vueuse/core'
+import { useTimeoutFn } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
 import { computed, reactive, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
@@ -62,14 +62,65 @@ defineExpose({
 
 const { isOutside } = useElectronMouseInElement(islandRef)
 
-// Auto-hide logic with configurable delays
-const autoHideDelayMs = computed(() => autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500)
-const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
-// Use refDebounced for auto-hide: isOutside becomes true after autoHideDelay
-const isOutsideDelayed = refDebounced(isOutside, autoHideDelayMs)
+// Custom debounced refs that respond to both value AND delay configuration changes
+// Using manual setTimeout with watch to properly support reactive delay changes
+const isOutsideDelayed = ref(isOutside.value)
+const isInsideDelayed = ref(!isOutside.value)
 
-// Use refDebounced for auto-show: isOutside becomes false after autoShowDelay
-const isInsideDelayed = refDebounced(computed(() => !isOutside.value), autoShowDelayMs)
+// --- Collapse expanded panel ---
+const collapseDelayMs = computed(() =>
+  autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
+)
+
+const { start: startCollapse, stop: stopCollapse } = useTimeoutFn(() => {
+  if (expanded.value && !isBlocked.value)
+    expanded.value = false
+}, () => collapseDelayMs.value, { immediate: false })
+
+watch(isOutside, (val) => {
+  stopCollapse()
+  if (val)
+    startCollapse()
+})
+
+// --- Auto-hide island（仅 autoHideControlsIsland = true 时生效）---
+const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+  isOutsideDelayed.value = true
+}, () => autoHideDelay.value * 1000, { immediate: false })
+
+const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+  isInsideDelayed.value = true
+}, () => autoShowDelay.value * 1000, { immediate: false })
+
+watch(isOutside, (val) => {
+  if (!autoHideControlsIsland.value) {
+    // 非自动隐藏模式，重置状态
+    stopOutside()
+    stopInside()
+    isOutsideDelayed.value = val
+    isInsideDelayed.value = !val
+    return
+  }
+  stopOutside()
+  stopInside()
+  if (val) {
+    isInsideDelayed.value = false
+    startOutside()
+  }
+  else {
+    isOutsideDelayed.value = false
+    startInside()
+  }
+})
+
+// 当 autoHideControlsIsland 切换时重置所有状态
+watch(autoHideControlsIsland, () => {
+  stopOutside()
+  stopInside()
+  stopCollapse()
+  isOutsideDelayed.value = isOutside.value
+  isInsideDelayed.value = !isOutside.value
+})
 
 // Calculate opacity when hidden (0-100 range converted to 0-1)
 const hiddenOpacity = computed(() => autoHideOpacity.value / 100)
@@ -103,14 +154,6 @@ watch(expanded, (isExpanded) => {
   }
 })
 
-// Auto-collapse expanded panel when mouse leaves for configured delay
-// Using refDebounced for consistent delay behavior
-watch(isOutsideDelayed, (isDelayedOutside) => {
-  if (isDelayedOutside && expanded.value && !isBlocked.value) {
-    expanded.value = false
-  }
-})
-
 // Apply alwaysOnTop on mount and when it changes
 watch(alwaysOnTop, (val) => {
   setAlwaysOnTop(val)
diff --git a/packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts b/packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts
new file mode 100644
index 0000000000..aa9c0cfad9
--- /dev/null
+++ b/packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts
@@ -0,0 +1,444 @@
+import { useTimeoutFn } from '@vueuse/core'
+import { createPinia, setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { computed, ref, watch } from 'vue'
+
+import { useSettingsControlsIsland } from './controls-island'
+
+// Helper to wait for a duration
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+describe('controls-island auto-hide logic with useTimeoutFn', () => {
+  beforeEach(() => {
+    vi.useRealTimers()
+    const pinia = createPinia()
+    setActivePinia(pinia)
+  })
+
+  // =============================================================================
+  // Pinia Store Tests
+  // =============================================================================
+
+  describe('pinia store: useSettingsControlsIsland', () => {
+    it('should have correct default values', () => {
+      const store = useSettingsControlsIsland()
+
+      expect(store.autoHideControlsIsland).toBe(false)
+      expect(store.autoHideDelay).toBe(0.5)
+      expect(store.autoShowDelay).toBe(0.5)
+      expect(store.autoHideOpacity).toBe(30)
+    })
+
+    it('should update store values', () => {
+      const store = useSettingsControlsIsland()
+
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 2
+      store.autoShowDelay = 1.5
+      store.autoHideOpacity = 50
+
+      expect(store.autoHideControlsIsland).toBe(true)
+      expect(store.autoHideDelay).toBe(2)
+      expect(store.autoShowDelay).toBe(1.5)
+      expect(store.autoHideOpacity).toBe(50)
+    })
+
+    it('should calculate delay based on autoHideControlsIsland flag', () => {
+      const store = useSettingsControlsIsland()
+
+      // Default: autoHideControlsIsland = false, so delay = 1500ms
+      const delayWhenDisabled = computed(() =>
+        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
+      )
+      expect(delayWhenDisabled.value).toBe(1500)
+
+      // Enable auto-hide
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 2
+      const delayWhenEnabled = computed(() =>
+        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
+      )
+      expect(delayWhenEnabled.value).toBe(2000)
+    })
+
+    it('should update delay values reactively', () => {
+      const store = useSettingsControlsIsland()
+
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+      expect(autoHideDelayMs.value).toBe(500)
+
+      store.autoHideDelay = 1
+      expect(autoHideDelayMs.value).toBe(1000)
+
+      store.autoHideDelay = 0.2
+      expect(autoHideDelayMs.value).toBe(200)
+    })
+  })
+
+  // =============================================================================
+  // useTimeoutFn behavior tests with store
+  // =============================================================================
+
+  describe('useTimeoutFn responds to delay from store', () => {
+    it('should use new delay when store delay changes', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideDelay = 0.2 // 200ms
+
+      const isOutsideDelayed = ref(false)
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+
+      const { start, stop } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      // Start timer
+      start()
+
+      // Before timer fires, change delay
+      await wait(100)
+      store.autoHideDelay = 0.5 // Change to 500ms
+      stop()
+      start() // Restart with new delay
+
+      // At 400ms (old delay 200ms) - should still be false
+      await wait(300) // 400ms total
+      expect(isOutsideDelayed.value).toBe(false)
+
+      // At 600ms total (new delay 500ms from change) - should be true
+      await wait(300) // 700ms total
+      expect(isOutsideDelayed.value).toBe(true)
+    })
+
+    it('should stop and restart correctly when isOutside changes', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideDelay = 0.2
+      store.autoShowDelay = 0.2
+
+      const isOutside = ref(false)
+      const isOutsideDelayed = ref(false)
+      const isInsideDelayed = ref(true)
+
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+      const autoShowDelayMs = computed(() => store.autoShowDelay * 1000)
+
+      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+        isInsideDelayed.value = true
+      }, () => autoShowDelayMs.value, { immediate: false })
+
+      // Mouse leaves - start outside timer
+      isOutside.value = true
+      isInsideDelayed.value = false
+      stopOutside()
+      stopInside()
+      startOutside()
+
+      // Before timer fires, mouse enters - switch timers
+      await wait(100)
+      isOutside.value = false
+      isOutsideDelayed.value = false
+      stopOutside()
+      stopInside()
+      startInside()
+
+      // At 200ms - outside timer should not have fired (was stopped)
+      await wait(200)
+      expect(isOutsideDelayed.value).toBe(false)
+
+      // At 300ms - inside timer should have fired
+      await wait(100)
+      expect(isInsideDelayed.value).toBe(true)
+    })
+  })
+
+  // =============================================================================
+  // Integration tests with real store and useTimeoutFn
+  // =============================================================================
+
+  describe('integration: auto-hide island with store', () => {
+    it('should hide after configured delay when mouse leaves', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 0.3 // 300ms
+      store.autoShowDelay = 0.3
+
+      const isOutside = ref(false) // Mouse inside
+      const isOutsideDelayed = ref(false)
+      const isInsideDelayed = ref(true)
+
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+      const autoShowDelayMs = computed(() => store.autoShowDelay * 1000)
+
+      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+        isInsideDelayed.value = true
+      }, () => autoShowDelayMs.value, { immediate: false })
+
+      // Simulate component watch behavior
+      watch(isOutside, (val) => {
+        if (!store.autoHideControlsIsland) {
+          stopOutside()
+          stopInside()
+          isOutsideDelayed.value = val
+          isInsideDelayed.value = !val
+          return
+        }
+        stopOutside()
+        stopInside()
+        if (val) {
+          isInsideDelayed.value = false
+          startOutside()
+        }
+        else {
+          isOutsideDelayed.value = false
+          startInside()
+        }
+      })
+
+      // Initial: mouse inside
+      expect(isOutsideDelayed.value).toBe(false)
+      expect(isInsideDelayed.value).toBe(true)
+
+      // Mouse leaves
+      isOutside.value = true
+
+      // Before delay - should still be visible
+      await wait(250)
+      expect(isOutsideDelayed.value).toBe(false)
+
+      // After delay (300ms) - should be hidden
+      await wait(100)
+      expect(isOutsideDelayed.value).toBe(true)
+    })
+
+    it('should show after configured delay when mouse enters', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 0.3
+      store.autoShowDelay = 0.3
+
+      const isOutside = ref(true) // Mouse outside
+      const isOutsideDelayed = ref(true)
+      const isInsideDelayed = ref(false)
+
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+      const autoShowDelayMs = computed(() => store.autoShowDelay * 1000)
+
+      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+        isInsideDelayed.value = true
+      }, () => autoShowDelayMs.value, { immediate: false })
+
+      // Simulate component watch behavior
+      watch(isOutside, (val) => {
+        if (!store.autoHideControlsIsland) {
+          stopOutside()
+          stopInside()
+          isOutsideDelayed.value = val
+          isInsideDelayed.value = !val
+          return
+        }
+        stopOutside()
+        stopInside()
+        if (val) {
+          isInsideDelayed.value = false
+          startOutside()
+        }
+        else {
+          isOutsideDelayed.value = false
+          startInside()
+        }
+      })
+
+      // Initial: mouse outside
+      expect(isOutsideDelayed.value).toBe(true)
+      expect(isInsideDelayed.value).toBe(false)
+
+      // Mouse enters
+      isOutside.value = false
+
+      // Before delay - should still be hidden
+      await wait(250)
+      expect(isInsideDelayed.value).toBe(false)
+
+      // After delay (300ms) - should be shown
+      await wait(100)
+      expect(isInsideDelayed.value).toBe(true)
+    })
+
+    it('should use 1500ms fallback when autoHideControlsIsland is false', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = false
+      store.autoHideDelay = 0.5
+
+      const _isOutside = ref(true) // Mouse outside
+      const isOutsideDelayed = ref(true)
+
+      const autoHideDelayMs = computed(() =>
+        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
+      )
+
+      expect(autoHideDelayMs.value).toBe(1500)
+
+      const { start } = useTimeoutFn(() => {
+        isOutsideDelayed.value = false
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      start()
+
+      await wait(1400)
+      expect(isOutsideDelayed.value).toBe(true)
+
+      await wait(200)
+      expect(isOutsideDelayed.value).toBe(false)
+    })
+
+    it('should reset state when autoHideControlsIsland changes', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 0.5
+
+      const isOutside = ref(true) // Mouse outside
+      const isOutsideDelayed = ref(true)
+      const isInsideDelayed = ref(false)
+
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+
+      const { stop: stopOutside } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      // Simulate watch for autoHideControlsIsland
+      watch(() => store.autoHideControlsIsland, () => {
+        stopOutside()
+        isOutsideDelayed.value = isOutside.value
+        isInsideDelayed.value = !isOutside.value
+      })
+
+      // Disable auto-hide
+      store.autoHideControlsIsland = false
+
+      expect(isOutsideDelayed.value).toBe(true)
+      expect(isInsideDelayed.value).toBe(false)
+    })
+
+    it('should handle delay update from store correctly', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 0.2
+
+      const isOutside = ref(false)
+      const isOutsideDelayed = ref(false)
+
+      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
+
+      const { start, stop } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      // Mouse leaves
+      isOutside.value = true
+      start()
+
+      // Change delay before timer fires
+      await wait(100)
+      store.autoHideDelay = 1 // 1000ms
+      stop()
+      start() // Restart with new delay
+
+      // At 200ms - original timer would have fired with old delay
+      await wait(150) // 250ms total
+      expect(isOutsideDelayed.value).toBe(false)
+
+      // At 1200ms total (200ms + 1000ms new delay) - should now fire
+      await wait(1000) // 1250ms total
+      expect(isOutsideDelayed.value).toBe(true)
+    })
+  })
+
+  // =============================================================================
+  // Collapse behavior tests
+  // =============================================================================
+
+  describe('collapse behavior with store', () => {
+    it('should collapse after delay when mouse leaves', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 0.3
+
+      const isOutside = ref(false) // Mouse inside
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const collapseDelayMs = computed(() =>
+        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
+      )
+
+      const { start, stop } = useTimeoutFn(() => {
+        if (expanded.value && !isBlocked.value)
+          expanded.value = false
+      }, () => collapseDelayMs.value, { immediate: false })
+
+      // Simulate watch for isOutside
+      watch(isOutside, (val) => {
+        if (val) {
+          stop()
+          start()
+        }
+      })
+
+      // Mouse leaves
+      isOutside.value = true
+
+      // Before delay - should still be expanded
+      await wait(250)
+      expect(expanded.value).toBe(true)
+
+      // After delay - should be collapsed
+      await wait(100)
+      expect(expanded.value).toBe(false)
+    })
+
+    it('should not collapse when blocked', async () => {
+      const store = useSettingsControlsIsland()
+      store.autoHideControlsIsland = true
+      store.autoHideDelay = 0.3
+
+      const isOutside = ref(true)
+      const expanded = ref(true)
+      const isBlocked = ref(true) // Blocked
+
+      const collapseDelayMs = computed(() =>
+        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
+      )
+
+      const { start, stop } = useTimeoutFn(() => {
+        if (expanded.value && !isBlocked.value)
+          expanded.value = false
+      }, () => collapseDelayMs.value, { immediate: false })
+
+      watch(isOutside, (val) => {
+        if (val) {
+          stop()
+          start()
+        }
+      })
+
+      isOutside.value = true
+
+      await wait(400)
+
+      // Should still be expanded because blocked
+      expect(expanded.value).toBe(true)
+    })
+  })
+})

From a0e185ecabf27720d6576932c236c25c578704e3 Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 17:55:37 +0800
Subject: [PATCH 12/19] feat(controls-island): implement auto-hide and
 auto-collapse composables for improved UI behavior

---
 .../stage-islands/controls-island/index.vue   |  98 ++--------
 packages/stage-ui/src/composables/index.ts    |   1 +
 .../use-controls-island-autohide.ts           | 167 ++++++++++++++++++
 3 files changed, 187 insertions(+), 79 deletions(-)
 create mode 100644 packages/stage-ui/src/composables/use-controls-island-autohide.ts

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index e691c012b6..96f3efd533 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { defineInvoke } from '@moeru/eventa'
 import { useElectronEventaContext, useElectronEventaInvoke, useElectronMouseInElement } from '@proj-airi/electron-vueuse'
+import { useControlsIslandAutohide, useControlsIslandCollapse } from '@proj-airi/stage-ui/composables'
 import { useSettings, useSettingsAudioDevice, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
 import { useTheme } from '@proj-airi/ui'
-import { useTimeoutFn } from '@vueuse/core'
 import { storeToRefs } from 'pinia'
 import { computed, reactive, ref, watch } from 'vue'
 import { useI18n } from 'vue-i18n'
@@ -62,92 +62,32 @@ defineExpose({
 
 const { isOutside } = useElectronMouseInElement(islandRef)
 
-// Custom debounced refs that respond to both value AND delay configuration changes
-// Using manual setTimeout with watch to properly support reactive delay changes
-const isOutsideDelayed = ref(isOutside.value)
-const isInsideDelayed = ref(!isOutside.value)
-
-// --- Collapse expanded panel ---
-const collapseDelayMs = computed(() =>
-  autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
-)
+// Auto-hide / Auto-show behavior
+const { isHidden, hiddenOpacity } = useControlsIslandAutohide({
+  autoHideControlsIsland,
+  autoHideDelay,
+  autoShowDelay,
+  autoHideOpacity,
+  isOutside,
+  isBlocked,
+  expanded,
+})
 
-const { start: startCollapse, stop: stopCollapse } = useTimeoutFn(() => {
-  if (expanded.value && !isBlocked.value)
-    expanded.value = false
-}, () => collapseDelayMs.value, { immediate: false })
+// Auto-collapse behavior
+const { startCollapse, stopCollapse } = useControlsIslandCollapse({
+  autoHideDelay,
+  autoHideControlsIsland,
+  expanded,
+  isBlocked,
+})
 
+// Watch mouse position to trigger collapse
 watch(isOutside, (val) => {
   stopCollapse()
   if (val)
     startCollapse()
 })
 
-// --- Auto-hide island（仅 autoHideControlsIsland = true 时生效）---
-const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
-  isOutsideDelayed.value = true
-}, () => autoHideDelay.value * 1000, { immediate: false })
-
-const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
-  isInsideDelayed.value = true
-}, () => autoShowDelay.value * 1000, { immediate: false })
-
-watch(isOutside, (val) => {
-  if (!autoHideControlsIsland.value) {
-    // 非自动隐藏模式，重置状态
-    stopOutside()
-    stopInside()
-    isOutsideDelayed.value = val
-    isInsideDelayed.value = !val
-    return
-  }
-  stopOutside()
-  stopInside()
-  if (val) {
-    isInsideDelayed.value = false
-    startOutside()
-  }
-  else {
-    isOutsideDelayed.value = false
-    startInside()
-  }
-})
-
-// 当 autoHideControlsIsland 切换时重置所有状态
-watch(autoHideControlsIsland, () => {
-  stopOutside()
-  stopInside()
-  stopCollapse()
-  isOutsideDelayed.value = isOutside.value
-  isInsideDelayed.value = !isOutside.value
-})
-
-// Calculate opacity when hidden (0-100 range converted to 0-1)
-const hiddenOpacity = computed(() => autoHideOpacity.value / 100)
-
-// Auto-hide: hide controls island when mouse leaves after delay
-// Auto-show: show controls island when mouse enters after delay
-const isHidden = computed(() => {
-  if (!autoHideControlsIsland.value)
-    return false
-
-  // Don't hide if there's a blocking overlay or expanded panel should stay
-  if (isBlocked.value || expanded.value)
-    return false
-
-  // When mouse is inside, wait for show delay before fully showing
-  if (!isOutside.value) {
-    if (autoShowDelay.value > 0) {
-      // Wait for mouse to be inside for the configured delay before showing
-      return !isInsideDelayed.value
-    }
-    return false
-  }
-
-  // When mouse is outside, hide after delay
-  return isOutsideDelayed.value
-})
-
 watch(expanded, (isExpanded) => {
   if (!isExpanded) {
     blockingOverlays.clear()
diff --git a/packages/stage-ui/src/composables/index.ts b/packages/stage-ui/src/composables/index.ts
index 35f7753028..d1ffedbb86 100644
--- a/packages/stage-ui/src/composables/index.ts
+++ b/packages/stage-ui/src/composables/index.ts
@@ -8,6 +8,7 @@ export * from './use-async-state'
 export * from './use-breakpoints'
 export * from './use-build-info'
 export * from './use-chat-session/summary'
+export * from './use-controls-island-autohide'
 export * from './use-optimistic'
 export * from './use-scroll-to-hash'
 export * from './vision'
diff --git a/packages/stage-ui/src/composables/use-controls-island-autohide.ts b/packages/stage-ui/src/composables/use-controls-island-autohide.ts
new file mode 100644
index 0000000000..4284e956de
--- /dev/null
+++ b/packages/stage-ui/src/composables/use-controls-island-autohide.ts
@@ -0,0 +1,167 @@
+import type { Ref } from 'vue'
+
+import { useTimeoutFn } from '@vueuse/core'
+import { computed, ref, watch } from 'vue'
+
+export interface UseControlsIslandAutohideOptions {
+  /** Whether auto-hide is enabled */
+  autoHideControlsIsland: Ref<boolean>
+  /** Delay in seconds before hiding when mouse leaves */
+  autoHideDelay: Ref<number>
+  /** Delay in seconds before showing when mouse enters */
+  autoShowDelay: Ref<number>
+  /** Opacity value (0-100) when hidden */
+  autoHideOpacity: Ref<number>
+  /** Whether mouse is outside the element */
+  isOutside: Ref<boolean>
+  /** Whether there's a blocking overlay */
+  isBlocked: Ref<boolean>
+  /** Whether the panel is expanded */
+  expanded: Ref<boolean>
+}
+
+export interface UseControlsIslandAutohideReturn {
+  /** Delayed state: true after mouse has been outside for configured delay */
+  isOutsideDelayed: Ref<boolean>
+  /** Delayed state: true after mouse has been inside for configured delay */
+  isInsideDelayed: Ref<boolean>
+  /** Whether the island is currently hidden */
+  isHidden: Ref<boolean>
+  /** Opacity value (0-1) when hidden */
+  hiddenOpacity: Ref<number>
+  /** Stop all timers (useful when component unmounts) */
+  stopAll: () => void
+}
+
+/**
+ * Composable for controls island auto-hide/show behavior.
+ * Handles delayed hide/show based on mouse position and configurable delays.
+ */
+export function useControlsIslandAutohide(options: UseControlsIslandAutohideOptions): UseControlsIslandAutohideReturn {
+  const { autoHideControlsIsland, autoHideDelay, autoShowDelay, autoHideOpacity, isOutside, isBlocked, expanded } = options
+
+  // Delayed states that respond to both value AND delay configuration changes
+  const isOutsideDelayed = ref(isOutside.value)
+  const isInsideDelayed = ref(!isOutside.value)
+
+  // --- Auto-hide island (only works when autoHideControlsIsland = true) ---
+  const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+    isOutsideDelayed.value = true
+  }, () => autoHideDelay.value * 1000, { immediate: false })
+
+  const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+    isInsideDelayed.value = true
+  }, () => autoShowDelay.value * 1000, { immediate: false })
+
+  // Watch mouse position changes
+  watch(isOutside, (val) => {
+    if (!autoHideControlsIsland.value) {
+      // Not in auto-hide mode, reset states
+      stopOutside()
+      stopInside()
+      isOutsideDelayed.value = val
+      isInsideDelayed.value = !val
+      return
+    }
+    stopOutside()
+    stopInside()
+    if (val) {
+      // Mouse left - start hide delay timer
+      isInsideDelayed.value = false
+      startOutside()
+    }
+    else {
+      // Mouse entered - start show delay timer
+      isOutsideDelayed.value = false
+      startInside()
+    }
+  })
+
+  // Reset all states when autoHideControlsIsland toggles
+  watch(autoHideControlsIsland, () => {
+    stopOutside()
+    stopInside()
+    isOutsideDelayed.value = isOutside.value
+    isInsideDelayed.value = !isOutside.value
+  })
+
+  // Calculate opacity when hidden (0-100 range converted to 0-1)
+  const hiddenOpacity = computed(() => autoHideOpacity.value / 100)
+
+  // Determine if island should be hidden
+  const isHidden = computed(() => {
+    if (!autoHideControlsIsland.value)
+      return false
+
+    // Don't hide if there's a blocking overlay or expanded panel should stay
+    if (isBlocked.value || expanded.value)
+      return false
+
+    // When mouse is inside, wait for show delay before fully showing
+    if (!isOutside.value) {
+      if (autoShowDelay.value > 0) {
+        // Wait for mouse to be inside for the configured delay before showing
+        return !isInsideDelayed.value
+      }
+      return false
+    }
+
+    // When mouse is outside, hide after delay
+    return isOutsideDelayed.value
+  })
+
+  const stopAll = () => {
+    stopOutside()
+    stopInside()
+  }
+
+  return {
+    isOutsideDelayed,
+    isInsideDelayed,
+    isHidden,
+    hiddenOpacity,
+    stopAll,
+  }
+}
+
+export interface UseControlsIslandCollapseOptions {
+  /** Delay in seconds before collapsing */
+  autoHideDelay: Ref<number>
+  /** Whether auto-hide is enabled */
+  autoHideControlsIsland: Ref<boolean>
+  /** Whether the panel is expanded */
+  expanded: Ref<boolean>
+  /** Whether there's a blocking overlay */
+  isBlocked: Ref<boolean>
+}
+
+export interface UseControlsIslandCollapseReturn {
+  /** Start the collapse timer */
+  startCollapse: () => void
+  /** Stop the collapse timer */
+  stopCollapse: () => void
+  collapseDelayMs: Ref<number>
+}
+
+/**
+ * Composable for controls island auto-collapse behavior.
+ * Collapses the expanded panel after a delay when mouse leaves.
+ */
+export function useControlsIslandCollapse(options: UseControlsIslandCollapseOptions): UseControlsIslandCollapseReturn {
+  const { autoHideDelay, autoHideControlsIsland, expanded, isBlocked } = options
+
+  const collapseDelayMs = computed(() =>
+    autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
+  )
+
+  const { start: startCollapse, stop: stopCollapse } = useTimeoutFn(() => {
+    if (expanded.value && !isBlocked.value)
+      expanded.value = false
+  }, () => collapseDelayMs.value, { immediate: false })
+
+  return {
+    startCollapse,
+    stopCollapse,
+    collapseDelayMs,
+  }
+}

From 72492c1e8bdf50d2053d2f4c4fe849f1c1991eef Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 19:12:32 +0800
Subject: [PATCH 13/19] fix(controls-island): correct import name for auto-hide
 composable

---
 .../components/stage-islands/controls-island/index.vue      | 4 ++--
 packages/stage-ui/src/composables/index.ts                  | 2 +-
 ...-island-autohide.ts => use-controls-island-auto-hide.ts} | 6 +++---
 3 files changed, 6 insertions(+), 6 deletions(-)
 rename packages/stage-ui/src/composables/{use-controls-island-autohide.ts => use-controls-island-auto-hide.ts} (95%)

diff --git a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
index 96f3efd533..e113996bd1 100644
--- a/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
+++ b/apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { defineInvoke } from '@moeru/eventa'
 import { useElectronEventaContext, useElectronEventaInvoke, useElectronMouseInElement } from '@proj-airi/electron-vueuse'
-import { useControlsIslandAutohide, useControlsIslandCollapse } from '@proj-airi/stage-ui/composables'
+import { useControlsIslandAutoHide, useControlsIslandCollapse } from '@proj-airi/stage-ui/composables'
 import { useSettings, useSettingsAudioDevice, useSettingsControlsIsland } from '@proj-airi/stage-ui/stores/settings'
 import { useTheme } from '@proj-airi/ui'
 import { storeToRefs } from 'pinia'
@@ -63,7 +63,7 @@ defineExpose({
 const { isOutside } = useElectronMouseInElement(islandRef)
 
 // Auto-hide / Auto-show behavior
-const { isHidden, hiddenOpacity } = useControlsIslandAutohide({
+const { isHidden, hiddenOpacity } = useControlsIslandAutoHide({
   autoHideControlsIsland,
   autoHideDelay,
   autoShowDelay,
diff --git a/packages/stage-ui/src/composables/index.ts b/packages/stage-ui/src/composables/index.ts
index d1ffedbb86..15c0bc3bbb 100644
--- a/packages/stage-ui/src/composables/index.ts
+++ b/packages/stage-ui/src/composables/index.ts
@@ -8,7 +8,7 @@ export * from './use-async-state'
 export * from './use-breakpoints'
 export * from './use-build-info'
 export * from './use-chat-session/summary'
-export * from './use-controls-island-autohide'
+export * from './use-controls-island-auto-hide'
 export * from './use-optimistic'
 export * from './use-scroll-to-hash'
 export * from './vision'
diff --git a/packages/stage-ui/src/composables/use-controls-island-autohide.ts b/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
similarity index 95%
rename from packages/stage-ui/src/composables/use-controls-island-autohide.ts
rename to packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
index 4284e956de..1196377bef 100644
--- a/packages/stage-ui/src/composables/use-controls-island-autohide.ts
+++ b/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
@@ -3,7 +3,7 @@ import type { Ref } from 'vue'
 import { useTimeoutFn } from '@vueuse/core'
 import { computed, ref, watch } from 'vue'
 
-export interface UseControlsIslandAutohideOptions {
+export interface UseControlsIslandAutoHideOptions {
   /** Whether auto-hide is enabled */
   autoHideControlsIsland: Ref<boolean>
   /** Delay in seconds before hiding when mouse leaves */
@@ -20,7 +20,7 @@ export interface UseControlsIslandAutohideOptions {
   expanded: Ref<boolean>
 }
 
-export interface UseControlsIslandAutohideReturn {
+export interface UseControlsIslandAutoHideReturn {
   /** Delayed state: true after mouse has been outside for configured delay */
   isOutsideDelayed: Ref<boolean>
   /** Delayed state: true after mouse has been inside for configured delay */
@@ -37,7 +37,7 @@ export interface UseControlsIslandAutohideReturn {
  * Composable for controls island auto-hide/show behavior.
  * Handles delayed hide/show based on mouse position and configurable delays.
  */
-export function useControlsIslandAutohide(options: UseControlsIslandAutohideOptions): UseControlsIslandAutohideReturn {
+export function useControlsIslandAutoHide(options: UseControlsIslandAutoHideOptions): UseControlsIslandAutoHideReturn {
   const { autoHideControlsIsland, autoHideDelay, autoShowDelay, autoHideOpacity, isOutside, isBlocked, expanded } = options
 
   // Delayed states that respond to both value AND delay configuration changes

From 4c4ea5c081a77d5c8a0167ded623b4211e462103 Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 19:28:33 +0800
Subject: [PATCH 14/19] feat(tests): add unit tests for
 useControlsIslandAutoHide and useControlsIslandCollapse composables

---
 .../use-controls-island-auto-hide.test.ts     | 583 ++++++++++++++++++
 .../settings/controls-island-autohide.test.ts | 444 -------------
 2 files changed, 583 insertions(+), 444 deletions(-)
 create mode 100644 packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
 delete mode 100644 packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts

diff --git a/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts b/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
new file mode 100644
index 0000000000..0ff92279cb
--- /dev/null
+++ b/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
@@ -0,0 +1,583 @@
+import { useTimeoutFn } from '@vueuse/core'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { computed, ref, watch } from 'vue'
+
+import { useControlsIslandAutoHide, useControlsIslandCollapse } from './use-controls-island-auto-hide'
+
+// Helper to wait for a duration
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+describe('useControlsIslandAutoHide', () => {
+  beforeEach(() => {
+    vi.useRealTimers()
+  })
+
+  // =============================================================================
+  // Basic Functionality Tests
+  // =============================================================================
+
+  describe('hiddenOpacity calculation', () => {
+    it('should convert 0-100 to 0-1', () => {
+      const autoHideOpacity = ref(30)
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { hiddenOpacity } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0.5),
+        autoHideOpacity,
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      expect(hiddenOpacity.value).toBe(0.3)
+
+      autoHideOpacity.value = 100
+      expect(hiddenOpacity.value).toBe(1)
+
+      autoHideOpacity.value = 0
+      expect(hiddenOpacity.value).toBe(0)
+    })
+  })
+
+  describe('initial state', () => {
+    it('should initialize delayed states based on isOutside', () => {
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { isOutsideDelayed, isInsideDelayed } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      expect(isOutsideDelayed.value).toBe(true)
+      expect(isInsideDelayed.value).toBe(false)
+
+      // Test with isOutside = false
+      const isOutside2 = ref(false)
+      const { isOutsideDelayed: d2, isInsideDelayed: i2 } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside: isOutside2,
+        isBlocked: ref(false),
+        expanded: ref(false),
+      })
+
+      expect(d2.value).toBe(false)
+      expect(i2.value).toBe(true)
+    })
+  })
+
+  // =============================================================================
+  // isHidden Computation Tests
+  // =============================================================================
+
+  describe('isHidden computation', () => {
+    it('should return false when autoHideControlsIsland is false', () => {
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { isHidden } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(false),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      expect(isHidden.value).toBe(false)
+    })
+
+    it('should return false when isBlocked is true', () => {
+      const isOutside = ref(true)
+      const isBlocked = ref(true) // Blocked
+      const expanded = ref(false)
+
+      const { isHidden } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      expect(isHidden.value).toBe(false)
+    })
+
+    it('should return false when expanded is true', () => {
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(true) // Expanded
+
+      const { isHidden } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      expect(isHidden.value).toBe(false)
+    })
+
+    it('should return false immediately when mouse is inside and autoShowDelay is 0', () => {
+      const isOutside = ref(false) // Mouse inside
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { isHidden } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay: ref(0.5),
+        autoShowDelay: ref(0), // No delay
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      expect(isHidden.value).toBe(false)
+    })
+
+    it('should return true when mouse is outside and delay reached', () => {
+      const isOutside = ref(true) // Mouse outside
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      // Create composable and manually control delayed state
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.5)
+      const autoShowDelay = ref(0.5)
+      const autoHideOpacity = ref(30)
+
+      const { isHidden, isOutsideDelayed: delayedRef } = useControlsIslandAutoHide({
+        autoHideControlsIsland,
+        autoHideDelay,
+        autoShowDelay,
+        autoHideOpacity,
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      // Simulate delay reached
+      delayedRef.value = true
+
+      expect(isHidden.value).toBe(true)
+    })
+  })
+
+  // =============================================================================
+  // useTimeoutFn Integration Tests
+  // =============================================================================
+
+  describe('useTimeoutFn responds to delay changes', () => {
+    it('should use new delay when delay changes', async () => {
+      const autoHideDelay = ref(0.2) // 200ms
+
+      // Test the timeout mechanism separately
+      const timeoutFlag = ref(false)
+      const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
+
+      const { start, stop } = useTimeoutFn(() => {
+        timeoutFlag.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      start()
+
+      // Before timer fires, change delay
+      await wait(100)
+      autoHideDelay.value = 0.5 // Change to 500ms
+      stop()
+      start()
+
+      // At 400ms (old delay 200ms) - should still be false
+      await wait(300)
+      expect(timeoutFlag.value).toBe(false)
+
+      // At 600ms total (new delay 500ms from change) - should be true
+      await wait(300)
+      expect(timeoutFlag.value).toBe(true)
+    })
+
+    it('should stop and restart correctly when isOutside changes', async () => {
+      const autoHideDelay = ref(0.2)
+      const autoShowDelay = ref(0.2)
+      const isOutside = ref(false)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      // Create composable instance (not using its values, just for setup)
+      useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay,
+        autoShowDelay,
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      // Test timer switching separately
+      const isOutsideDel = ref(false)
+      const isInsideDel = ref(true)
+
+      const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
+      const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
+
+      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+        isOutsideDel.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+        isInsideDel.value = true
+      }, () => autoShowDelayMs.value, { immediate: false })
+
+      // Mouse leaves - start outside timer
+      isOutside.value = true
+      isInsideDel.value = false
+      stopOutside()
+      stopInside()
+      startOutside()
+
+      // Before timer fires, mouse enters - switch timers
+      await wait(100)
+      isOutside.value = false
+      isOutsideDel.value = false
+      stopOutside()
+      stopInside()
+      startInside()
+
+      // At 200ms - outside timer should not have fired
+      await wait(200)
+      expect(isOutsideDel.value).toBe(false)
+
+      // At 300ms - inside timer should have fired
+      await wait(100)
+      expect(isInsideDel.value).toBe(true)
+    })
+  })
+
+  // =============================================================================
+  // Integration: Full Auto-Hide/Show Flow
+  // =============================================================================
+
+  describe('integration: auto-hide island behavior', () => {
+    it('should hide after configured delay when mouse leaves', async () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.3) // 300ms
+      const autoShowDelay = ref(0.3)
+      const isOutside = ref(false) // Mouse inside
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { isOutsideDelayed, isHidden } = useControlsIslandAutoHide({
+        autoHideControlsIsland,
+        autoHideDelay,
+        autoShowDelay,
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      // Simulate watch for isOutside
+      const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
+      const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
+
+      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
+        isOutsideDelayed.value = true
+      }, () => autoHideDelayMs.value, { immediate: false })
+
+      const { stop: stopInside } = useTimeoutFn(() => {}, () => autoShowDelayMs.value, { immediate: false })
+
+      watch(isOutside, (val) => {
+        if (!autoHideControlsIsland.value) {
+          stopOutside()
+          stopInside()
+          return
+        }
+        stopOutside()
+        stopInside()
+        if (val) {
+          startOutside()
+        }
+      })
+
+      // Mouse leaves
+      isOutside.value = true
+      startOutside()
+
+      // Before delay - should still be visible
+      await wait(250)
+      expect(isOutsideDelayed.value).toBe(false)
+      expect(isHidden.value).toBe(false)
+
+      // After delay (300ms) - should be hidden
+      await wait(100)
+      expect(isOutsideDelayed.value).toBe(true)
+      expect(isHidden.value).toBe(true)
+    })
+
+    it('should show after configured delay when mouse enters', async () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.3)
+      const autoShowDelay = ref(0.3)
+      const isOutside = ref(true) // Mouse initially outside
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { isInsideDelayed, isHidden } = useControlsIslandAutoHide({
+        autoHideControlsIsland,
+        autoHideDelay,
+        autoShowDelay,
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
+      const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
+
+      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {}, () => autoHideDelayMs.value, { immediate: false })
+
+      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
+        isInsideDelayed.value = true
+      }, () => autoShowDelayMs.value, { immediate: false })
+
+      watch(isOutside, (val) => {
+        if (!autoHideControlsIsland.value) {
+          stopOutside()
+          stopInside()
+          return
+        }
+        stopOutside()
+        stopInside()
+        if (!val) {
+          startInside()
+        }
+      })
+
+      // Initial: mouse outside, isHidden should be true (delay already passed)
+      // Simulate that delay has passed for being outside
+      const isOutsideDelayed = ref(true)
+      expect(isHidden.value).toBe(true)
+
+      // Mouse enters (isOutside = false)
+      isOutside.value = false
+
+      // Before delay - should still be hidden (waiting for show delay)
+      await wait(250)
+      expect(isInsideDelayed.value).toBe(false)
+      expect(isHidden.value).toBe(true)
+
+      // Start the timer
+      startInside()
+
+      // After delay (300ms) - should be shown
+      await wait(100)
+      expect(isInsideDelayed.value).toBe(true)
+      expect(isHidden.value).toBe(false)
+    })
+
+    it('should use 1500ms fallback when autoHideControlsIsland is false', () => {
+      const autoHideControlsIsland = ref(false)
+      const autoHideDelay = ref(0.5)
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const collapseDelayMs = computed(() =>
+        autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
+      )
+
+      expect(collapseDelayMs.value).toBe(1500)
+    })
+
+    it('should reset state when autoHideControlsIsland changes', () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.5)
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { isOutsideDelayed, isInsideDelayed } = useControlsIslandAutoHide({
+        autoHideControlsIsland,
+        autoHideDelay,
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      // Initial state when isOutside = true
+      expect(isOutsideDelayed.value).toBe(true)
+      expect(isInsideDelayed.value).toBe(false)
+
+      // Change autoHideControlsIsland to false
+      autoHideControlsIsland.value = false
+
+      // Should reset to immediate sync (not delayed)
+      expect(isOutsideDelayed.value).toBe(isOutside.value)
+      expect(isInsideDelayed.value).toBe(!isOutside.value)
+    })
+  })
+
+  // =============================================================================
+  // stopAll Function
+  // =============================================================================
+
+  describe('stopAll function', () => {
+    it('should stop all timers', () => {
+      const autoHideDelay = ref(0.5)
+      const isOutside = ref(true)
+      const isBlocked = ref(false)
+      const expanded = ref(false)
+
+      const { stopAll, isOutsideDelayed, isInsideDelayed } = useControlsIslandAutoHide({
+        autoHideControlsIsland: ref(true),
+        autoHideDelay,
+        autoShowDelay: ref(0.5),
+        autoHideOpacity: ref(30),
+        isOutside,
+        isBlocked,
+        expanded,
+      })
+
+      // Start timers by triggering isOutside change
+      isOutside.value = false
+      isOutside.value = true
+
+      // stopAll should not throw
+      expect(() => stopAll()).not.toThrow()
+    })
+  })
+})
+
+// =============================================================================
+// useControlsIslandCollapse Tests
+// =============================================================================
+
+describe('useControlsIslandCollapse', () => {
+  beforeEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('collapseDelayMs calculation', () => {
+    it('should use autoHideDelay * 1000 when enabled', () => {
+      const autoHideDelay = ref(0.5)
+      const autoHideControlsIsland = ref(true)
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const { collapseDelayMs } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      expect(collapseDelayMs.value).toBe(500)
+    })
+
+    it('should use 1500ms fallback when disabled', () => {
+      const autoHideDelay = ref(0.5)
+      const autoHideControlsIsland = ref(false)
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const { collapseDelayMs } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      expect(collapseDelayMs.value).toBe(1500)
+    })
+  })
+
+  describe('collapse behavior', () => {
+    it('should collapse after delay when mouse leaves', async () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.3)
+      const isOutside = ref(false) // Mouse inside
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const { startCollapse, stopCollapse } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      // Simulate watch for isOutside
+      watch(isOutside, (val) => {
+        if (val) {
+          stopCollapse()
+          startCollapse()
+        }
+      })
+
+      // Mouse leaves
+      isOutside.value = true
+
+      // Before delay - should still be expanded
+      await wait(250)
+      expect(expanded.value).toBe(true)
+
+      // After delay - should be collapsed
+      await wait(100)
+      expect(expanded.value).toBe(false)
+    })
+
+    it('should not collapse when blocked', async () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.3)
+      const isOutside = ref(true)
+      const expanded = ref(true)
+      const isBlocked = ref(true) // Blocked
+
+      const { startCollapse, stopCollapse } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      watch(isOutside, (val) => {
+        if (val) {
+          stopCollapse()
+          startCollapse()
+        }
+      })
+
+      isOutside.value = true
+
+      await wait(400)
+
+      // Should still be expanded because blocked
+      expect(expanded.value).toBe(true)
+    })
+  })
+})
diff --git a/packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts b/packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts
deleted file mode 100644
index aa9c0cfad9..0000000000
--- a/packages/stage-ui/src/stores/settings/controls-island-autohide.test.ts
+++ /dev/null
@@ -1,444 +0,0 @@
-import { useTimeoutFn } from '@vueuse/core'
-import { createPinia, setActivePinia } from 'pinia'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { computed, ref, watch } from 'vue'
-
-import { useSettingsControlsIsland } from './controls-island'
-
-// Helper to wait for a duration
-const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
-
-describe('controls-island auto-hide logic with useTimeoutFn', () => {
-  beforeEach(() => {
-    vi.useRealTimers()
-    const pinia = createPinia()
-    setActivePinia(pinia)
-  })
-
-  // =============================================================================
-  // Pinia Store Tests
-  // =============================================================================
-
-  describe('pinia store: useSettingsControlsIsland', () => {
-    it('should have correct default values', () => {
-      const store = useSettingsControlsIsland()
-
-      expect(store.autoHideControlsIsland).toBe(false)
-      expect(store.autoHideDelay).toBe(0.5)
-      expect(store.autoShowDelay).toBe(0.5)
-      expect(store.autoHideOpacity).toBe(30)
-    })
-
-    it('should update store values', () => {
-      const store = useSettingsControlsIsland()
-
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 2
-      store.autoShowDelay = 1.5
-      store.autoHideOpacity = 50
-
-      expect(store.autoHideControlsIsland).toBe(true)
-      expect(store.autoHideDelay).toBe(2)
-      expect(store.autoShowDelay).toBe(1.5)
-      expect(store.autoHideOpacity).toBe(50)
-    })
-
-    it('should calculate delay based on autoHideControlsIsland flag', () => {
-      const store = useSettingsControlsIsland()
-
-      // Default: autoHideControlsIsland = false, so delay = 1500ms
-      const delayWhenDisabled = computed(() =>
-        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
-      )
-      expect(delayWhenDisabled.value).toBe(1500)
-
-      // Enable auto-hide
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 2
-      const delayWhenEnabled = computed(() =>
-        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
-      )
-      expect(delayWhenEnabled.value).toBe(2000)
-    })
-
-    it('should update delay values reactively', () => {
-      const store = useSettingsControlsIsland()
-
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-      expect(autoHideDelayMs.value).toBe(500)
-
-      store.autoHideDelay = 1
-      expect(autoHideDelayMs.value).toBe(1000)
-
-      store.autoHideDelay = 0.2
-      expect(autoHideDelayMs.value).toBe(200)
-    })
-  })
-
-  // =============================================================================
-  // useTimeoutFn behavior tests with store
-  // =============================================================================
-
-  describe('useTimeoutFn responds to delay from store', () => {
-    it('should use new delay when store delay changes', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideDelay = 0.2 // 200ms
-
-      const isOutsideDelayed = ref(false)
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-
-      const { start, stop } = useTimeoutFn(() => {
-        isOutsideDelayed.value = true
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      // Start timer
-      start()
-
-      // Before timer fires, change delay
-      await wait(100)
-      store.autoHideDelay = 0.5 // Change to 500ms
-      stop()
-      start() // Restart with new delay
-
-      // At 400ms (old delay 200ms) - should still be false
-      await wait(300) // 400ms total
-      expect(isOutsideDelayed.value).toBe(false)
-
-      // At 600ms total (new delay 500ms from change) - should be true
-      await wait(300) // 700ms total
-      expect(isOutsideDelayed.value).toBe(true)
-    })
-
-    it('should stop and restart correctly when isOutside changes', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideDelay = 0.2
-      store.autoShowDelay = 0.2
-
-      const isOutside = ref(false)
-      const isOutsideDelayed = ref(false)
-      const isInsideDelayed = ref(true)
-
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-      const autoShowDelayMs = computed(() => store.autoShowDelay * 1000)
-
-      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
-        isOutsideDelayed.value = true
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
-        isInsideDelayed.value = true
-      }, () => autoShowDelayMs.value, { immediate: false })
-
-      // Mouse leaves - start outside timer
-      isOutside.value = true
-      isInsideDelayed.value = false
-      stopOutside()
-      stopInside()
-      startOutside()
-
-      // Before timer fires, mouse enters - switch timers
-      await wait(100)
-      isOutside.value = false
-      isOutsideDelayed.value = false
-      stopOutside()
-      stopInside()
-      startInside()
-
-      // At 200ms - outside timer should not have fired (was stopped)
-      await wait(200)
-      expect(isOutsideDelayed.value).toBe(false)
-
-      // At 300ms - inside timer should have fired
-      await wait(100)
-      expect(isInsideDelayed.value).toBe(true)
-    })
-  })
-
-  // =============================================================================
-  // Integration tests with real store and useTimeoutFn
-  // =============================================================================
-
-  describe('integration: auto-hide island with store', () => {
-    it('should hide after configured delay when mouse leaves', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 0.3 // 300ms
-      store.autoShowDelay = 0.3
-
-      const isOutside = ref(false) // Mouse inside
-      const isOutsideDelayed = ref(false)
-      const isInsideDelayed = ref(true)
-
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-      const autoShowDelayMs = computed(() => store.autoShowDelay * 1000)
-
-      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
-        isOutsideDelayed.value = true
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
-        isInsideDelayed.value = true
-      }, () => autoShowDelayMs.value, { immediate: false })
-
-      // Simulate component watch behavior
-      watch(isOutside, (val) => {
-        if (!store.autoHideControlsIsland) {
-          stopOutside()
-          stopInside()
-          isOutsideDelayed.value = val
-          isInsideDelayed.value = !val
-          return
-        }
-        stopOutside()
-        stopInside()
-        if (val) {
-          isInsideDelayed.value = false
-          startOutside()
-        }
-        else {
-          isOutsideDelayed.value = false
-          startInside()
-        }
-      })
-
-      // Initial: mouse inside
-      expect(isOutsideDelayed.value).toBe(false)
-      expect(isInsideDelayed.value).toBe(true)
-
-      // Mouse leaves
-      isOutside.value = true
-
-      // Before delay - should still be visible
-      await wait(250)
-      expect(isOutsideDelayed.value).toBe(false)
-
-      // After delay (300ms) - should be hidden
-      await wait(100)
-      expect(isOutsideDelayed.value).toBe(true)
-    })
-
-    it('should show after configured delay when mouse enters', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 0.3
-      store.autoShowDelay = 0.3
-
-      const isOutside = ref(true) // Mouse outside
-      const isOutsideDelayed = ref(true)
-      const isInsideDelayed = ref(false)
-
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-      const autoShowDelayMs = computed(() => store.autoShowDelay * 1000)
-
-      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {
-        isOutsideDelayed.value = true
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
-        isInsideDelayed.value = true
-      }, () => autoShowDelayMs.value, { immediate: false })
-
-      // Simulate component watch behavior
-      watch(isOutside, (val) => {
-        if (!store.autoHideControlsIsland) {
-          stopOutside()
-          stopInside()
-          isOutsideDelayed.value = val
-          isInsideDelayed.value = !val
-          return
-        }
-        stopOutside()
-        stopInside()
-        if (val) {
-          isInsideDelayed.value = false
-          startOutside()
-        }
-        else {
-          isOutsideDelayed.value = false
-          startInside()
-        }
-      })
-
-      // Initial: mouse outside
-      expect(isOutsideDelayed.value).toBe(true)
-      expect(isInsideDelayed.value).toBe(false)
-
-      // Mouse enters
-      isOutside.value = false
-
-      // Before delay - should still be hidden
-      await wait(250)
-      expect(isInsideDelayed.value).toBe(false)
-
-      // After delay (300ms) - should be shown
-      await wait(100)
-      expect(isInsideDelayed.value).toBe(true)
-    })
-
-    it('should use 1500ms fallback when autoHideControlsIsland is false', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = false
-      store.autoHideDelay = 0.5
-
-      const _isOutside = ref(true) // Mouse outside
-      const isOutsideDelayed = ref(true)
-
-      const autoHideDelayMs = computed(() =>
-        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
-      )
-
-      expect(autoHideDelayMs.value).toBe(1500)
-
-      const { start } = useTimeoutFn(() => {
-        isOutsideDelayed.value = false
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      start()
-
-      await wait(1400)
-      expect(isOutsideDelayed.value).toBe(true)
-
-      await wait(200)
-      expect(isOutsideDelayed.value).toBe(false)
-    })
-
-    it('should reset state when autoHideControlsIsland changes', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 0.5
-
-      const isOutside = ref(true) // Mouse outside
-      const isOutsideDelayed = ref(true)
-      const isInsideDelayed = ref(false)
-
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-
-      const { stop: stopOutside } = useTimeoutFn(() => {
-        isOutsideDelayed.value = true
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      // Simulate watch for autoHideControlsIsland
-      watch(() => store.autoHideControlsIsland, () => {
-        stopOutside()
-        isOutsideDelayed.value = isOutside.value
-        isInsideDelayed.value = !isOutside.value
-      })
-
-      // Disable auto-hide
-      store.autoHideControlsIsland = false
-
-      expect(isOutsideDelayed.value).toBe(true)
-      expect(isInsideDelayed.value).toBe(false)
-    })
-
-    it('should handle delay update from store correctly', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 0.2
-
-      const isOutside = ref(false)
-      const isOutsideDelayed = ref(false)
-
-      const autoHideDelayMs = computed(() => store.autoHideDelay * 1000)
-
-      const { start, stop } = useTimeoutFn(() => {
-        isOutsideDelayed.value = true
-      }, () => autoHideDelayMs.value, { immediate: false })
-
-      // Mouse leaves
-      isOutside.value = true
-      start()
-
-      // Change delay before timer fires
-      await wait(100)
-      store.autoHideDelay = 1 // 1000ms
-      stop()
-      start() // Restart with new delay
-
-      // At 200ms - original timer would have fired with old delay
-      await wait(150) // 250ms total
-      expect(isOutsideDelayed.value).toBe(false)
-
-      // At 1200ms total (200ms + 1000ms new delay) - should now fire
-      await wait(1000) // 1250ms total
-      expect(isOutsideDelayed.value).toBe(true)
-    })
-  })
-
-  // =============================================================================
-  // Collapse behavior tests
-  // =============================================================================
-
-  describe('collapse behavior with store', () => {
-    it('should collapse after delay when mouse leaves', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 0.3
-
-      const isOutside = ref(false) // Mouse inside
-      const expanded = ref(true)
-      const isBlocked = ref(false)
-
-      const collapseDelayMs = computed(() =>
-        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
-      )
-
-      const { start, stop } = useTimeoutFn(() => {
-        if (expanded.value && !isBlocked.value)
-          expanded.value = false
-      }, () => collapseDelayMs.value, { immediate: false })
-
-      // Simulate watch for isOutside
-      watch(isOutside, (val) => {
-        if (val) {
-          stop()
-          start()
-        }
-      })
-
-      // Mouse leaves
-      isOutside.value = true
-
-      // Before delay - should still be expanded
-      await wait(250)
-      expect(expanded.value).toBe(true)
-
-      // After delay - should be collapsed
-      await wait(100)
-      expect(expanded.value).toBe(false)
-    })
-
-    it('should not collapse when blocked', async () => {
-      const store = useSettingsControlsIsland()
-      store.autoHideControlsIsland = true
-      store.autoHideDelay = 0.3
-
-      const isOutside = ref(true)
-      const expanded = ref(true)
-      const isBlocked = ref(true) // Blocked
-
-      const collapseDelayMs = computed(() =>
-        store.autoHideControlsIsland ? store.autoHideDelay * 1000 : 1500,
-      )
-
-      const { start, stop } = useTimeoutFn(() => {
-        if (expanded.value && !isBlocked.value)
-          expanded.value = false
-      }, () => collapseDelayMs.value, { immediate: false })
-
-      watch(isOutside, (val) => {
-        if (val) {
-          stop()
-          start()
-        }
-      })
-
-      isOutside.value = true
-
-      await wait(400)
-
-      // Should still be expanded because blocked
-      expect(expanded.value).toBe(true)
-    })
-  })
-})

From 33ea17ad65fb7e6ac64ad8e56917bd47557f606e Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 19:31:04 +0800
Subject: [PATCH 15/19] refactor(useControlsIslandAutoHide): remove unused
 variables and streamline timeout function

---
 .../src/composables/use-controls-island-auto-hide.test.ts | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts b/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
index 0ff92279cb..8e175cfe1c 100644
--- a/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
+++ b/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
@@ -357,7 +357,7 @@ describe('useControlsIslandAutoHide', () => {
       const autoHideDelayMs = computed(() => autoHideDelay.value * 1000)
       const autoShowDelayMs = computed(() => autoShowDelay.value * 1000)
 
-      const { start: startOutside, stop: stopOutside } = useTimeoutFn(() => {}, () => autoHideDelayMs.value, { immediate: false })
+      const { stop: stopOutside } = useTimeoutFn(() => {}, () => autoHideDelayMs.value, { immediate: false })
 
       const { start: startInside, stop: stopInside } = useTimeoutFn(() => {
         isInsideDelayed.value = true
@@ -378,7 +378,6 @@ describe('useControlsIslandAutoHide', () => {
 
       // Initial: mouse outside, isHidden should be true (delay already passed)
       // Simulate that delay has passed for being outside
-      const isOutsideDelayed = ref(true)
       expect(isHidden.value).toBe(true)
 
       // Mouse enters (isOutside = false)
@@ -401,9 +400,6 @@ describe('useControlsIslandAutoHide', () => {
     it('should use 1500ms fallback when autoHideControlsIsland is false', () => {
       const autoHideControlsIsland = ref(false)
       const autoHideDelay = ref(0.5)
-      const isOutside = ref(true)
-      const isBlocked = ref(false)
-      const expanded = ref(false)
 
       const collapseDelayMs = computed(() =>
         autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
@@ -453,7 +449,7 @@ describe('useControlsIslandAutoHide', () => {
       const isBlocked = ref(false)
       const expanded = ref(false)
 
-      const { stopAll, isOutsideDelayed, isInsideDelayed } = useControlsIslandAutoHide({
+      const { stopAll } = useControlsIslandAutoHide({
         autoHideControlsIsland: ref(true),
         autoHideDelay,
         autoShowDelay: ref(0.5),

From 6018619d3cdf054afa938a35d66edd0b29c35aa7 Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Wed, 1 Apr 2026 19:42:06 +0800
Subject: [PATCH 16/19] feat(controls-island): add useControlsIslandCollapse
 composable and related tests

---
 packages/stage-ui/src/composables/index.ts    |   1 +
 .../use-controls-island-auto-hide.test.ts     | 111 +----------------
 .../use-controls-island-auto-hide.ts          |  42 -------
 .../use-controls-island-collapse.test.ts      | 115 ++++++++++++++++++
 .../use-controls-island-collapse.ts           |  46 +++++++
 5 files changed, 163 insertions(+), 152 deletions(-)
 create mode 100644 packages/stage-ui/src/composables/use-controls-island-collapse.test.ts
 create mode 100644 packages/stage-ui/src/composables/use-controls-island-collapse.ts

diff --git a/packages/stage-ui/src/composables/index.ts b/packages/stage-ui/src/composables/index.ts
index 15c0bc3bbb..894248516a 100644
--- a/packages/stage-ui/src/composables/index.ts
+++ b/packages/stage-ui/src/composables/index.ts
@@ -9,6 +9,7 @@ export * from './use-breakpoints'
 export * from './use-build-info'
 export * from './use-chat-session/summary'
 export * from './use-controls-island-auto-hide'
+export * from './use-controls-island-collapse'
 export * from './use-optimistic'
 export * from './use-scroll-to-hash'
 export * from './vision'
diff --git a/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts b/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
index 8e175cfe1c..0f76cbd6fb 100644
--- a/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
+++ b/packages/stage-ui/src/composables/use-controls-island-auto-hide.test.ts
@@ -2,7 +2,7 @@ import { useTimeoutFn } from '@vueuse/core'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { computed, ref, watch } from 'vue'
 
-import { useControlsIslandAutoHide, useControlsIslandCollapse } from './use-controls-island-auto-hide'
+import { useControlsIslandAutoHide } from './use-controls-island-auto-hide'
 
 // Helper to wait for a duration
 const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
@@ -468,112 +468,3 @@ describe('useControlsIslandAutoHide', () => {
     })
   })
 })
-
-// =============================================================================
-// useControlsIslandCollapse Tests
-// =============================================================================
-
-describe('useControlsIslandCollapse', () => {
-  beforeEach(() => {
-    vi.useRealTimers()
-  })
-
-  describe('collapseDelayMs calculation', () => {
-    it('should use autoHideDelay * 1000 when enabled', () => {
-      const autoHideDelay = ref(0.5)
-      const autoHideControlsIsland = ref(true)
-      const expanded = ref(true)
-      const isBlocked = ref(false)
-
-      const { collapseDelayMs } = useControlsIslandCollapse({
-        autoHideDelay,
-        autoHideControlsIsland,
-        expanded,
-        isBlocked,
-      })
-
-      expect(collapseDelayMs.value).toBe(500)
-    })
-
-    it('should use 1500ms fallback when disabled', () => {
-      const autoHideDelay = ref(0.5)
-      const autoHideControlsIsland = ref(false)
-      const expanded = ref(true)
-      const isBlocked = ref(false)
-
-      const { collapseDelayMs } = useControlsIslandCollapse({
-        autoHideDelay,
-        autoHideControlsIsland,
-        expanded,
-        isBlocked,
-      })
-
-      expect(collapseDelayMs.value).toBe(1500)
-    })
-  })
-
-  describe('collapse behavior', () => {
-    it('should collapse after delay when mouse leaves', async () => {
-      const autoHideControlsIsland = ref(true)
-      const autoHideDelay = ref(0.3)
-      const isOutside = ref(false) // Mouse inside
-      const expanded = ref(true)
-      const isBlocked = ref(false)
-
-      const { startCollapse, stopCollapse } = useControlsIslandCollapse({
-        autoHideDelay,
-        autoHideControlsIsland,
-        expanded,
-        isBlocked,
-      })
-
-      // Simulate watch for isOutside
-      watch(isOutside, (val) => {
-        if (val) {
-          stopCollapse()
-          startCollapse()
-        }
-      })
-
-      // Mouse leaves
-      isOutside.value = true
-
-      // Before delay - should still be expanded
-      await wait(250)
-      expect(expanded.value).toBe(true)
-
-      // After delay - should be collapsed
-      await wait(100)
-      expect(expanded.value).toBe(false)
-    })
-
-    it('should not collapse when blocked', async () => {
-      const autoHideControlsIsland = ref(true)
-      const autoHideDelay = ref(0.3)
-      const isOutside = ref(true)
-      const expanded = ref(true)
-      const isBlocked = ref(true) // Blocked
-
-      const { startCollapse, stopCollapse } = useControlsIslandCollapse({
-        autoHideDelay,
-        autoHideControlsIsland,
-        expanded,
-        isBlocked,
-      })
-
-      watch(isOutside, (val) => {
-        if (val) {
-          stopCollapse()
-          startCollapse()
-        }
-      })
-
-      isOutside.value = true
-
-      await wait(400)
-
-      // Should still be expanded because blocked
-      expect(expanded.value).toBe(true)
-    })
-  })
-})
diff --git a/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts b/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
index 1196377bef..816654bd89 100644
--- a/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
+++ b/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
@@ -123,45 +123,3 @@ export function useControlsIslandAutoHide(options: UseControlsIslandAutoHideOpti
     stopAll,
   }
 }
-
-export interface UseControlsIslandCollapseOptions {
-  /** Delay in seconds before collapsing */
-  autoHideDelay: Ref<number>
-  /** Whether auto-hide is enabled */
-  autoHideControlsIsland: Ref<boolean>
-  /** Whether the panel is expanded */
-  expanded: Ref<boolean>
-  /** Whether there's a blocking overlay */
-  isBlocked: Ref<boolean>
-}
-
-export interface UseControlsIslandCollapseReturn {
-  /** Start the collapse timer */
-  startCollapse: () => void
-  /** Stop the collapse timer */
-  stopCollapse: () => void
-  collapseDelayMs: Ref<number>
-}
-
-/**
- * Composable for controls island auto-collapse behavior.
- * Collapses the expanded panel after a delay when mouse leaves.
- */
-export function useControlsIslandCollapse(options: UseControlsIslandCollapseOptions): UseControlsIslandCollapseReturn {
-  const { autoHideDelay, autoHideControlsIsland, expanded, isBlocked } = options
-
-  const collapseDelayMs = computed(() =>
-    autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
-  )
-
-  const { start: startCollapse, stop: stopCollapse } = useTimeoutFn(() => {
-    if (expanded.value && !isBlocked.value)
-      expanded.value = false
-  }, () => collapseDelayMs.value, { immediate: false })
-
-  return {
-    startCollapse,
-    stopCollapse,
-    collapseDelayMs,
-  }
-}
diff --git a/packages/stage-ui/src/composables/use-controls-island-collapse.test.ts b/packages/stage-ui/src/composables/use-controls-island-collapse.test.ts
new file mode 100644
index 0000000000..b7e907b924
--- /dev/null
+++ b/packages/stage-ui/src/composables/use-controls-island-collapse.test.ts
@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ref, watch } from 'vue'
+
+import { useControlsIslandCollapse } from './use-controls-island-collapse'
+
+// Helper to wait for a duration
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+// =============================================================================
+// useControlsIslandCollapse Tests
+// =============================================================================
+
+describe('useControlsIslandCollapse', () => {
+  beforeEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('collapseDelayMs calculation', () => {
+    it('should use autoHideDelay * 1000 when enabled', () => {
+      const autoHideDelay = ref(0.5)
+      const autoHideControlsIsland = ref(true)
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const { collapseDelayMs } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      expect(collapseDelayMs.value).toBe(500)
+    })
+
+    it('should use 1500ms fallback when disabled', () => {
+      const autoHideDelay = ref(0.5)
+      const autoHideControlsIsland = ref(false)
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const { collapseDelayMs } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      expect(collapseDelayMs.value).toBe(1500)
+    })
+  })
+
+  describe('collapse behavior', () => {
+    it('should collapse after delay when mouse leaves', async () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.3)
+      const isOutside = ref(false) // Mouse inside
+      const expanded = ref(true)
+      const isBlocked = ref(false)
+
+      const { startCollapse, stopCollapse } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      // Simulate watch for isOutside
+      watch(isOutside, (val) => {
+        if (val) {
+          stopCollapse()
+          startCollapse()
+        }
+      })
+
+      // Mouse leaves
+      isOutside.value = true
+
+      // Before delay - should still be expanded
+      await wait(250)
+      expect(expanded.value).toBe(true)
+
+      // After delay - should be collapsed
+      await wait(100)
+      expect(expanded.value).toBe(false)
+    })
+
+    it('should not collapse when blocked', async () => {
+      const autoHideControlsIsland = ref(true)
+      const autoHideDelay = ref(0.3)
+      const isOutside = ref(true)
+      const expanded = ref(true)
+      const isBlocked = ref(true) // Blocked
+
+      const { startCollapse, stopCollapse } = useControlsIslandCollapse({
+        autoHideDelay,
+        autoHideControlsIsland,
+        expanded,
+        isBlocked,
+      })
+
+      watch(isOutside, (val) => {
+        if (val) {
+          stopCollapse()
+          startCollapse()
+        }
+      })
+
+      isOutside.value = true
+
+      await wait(400)
+
+      // Should still be expanded because blocked
+      expect(expanded.value).toBe(true)
+    })
+  })
+})
diff --git a/packages/stage-ui/src/composables/use-controls-island-collapse.ts b/packages/stage-ui/src/composables/use-controls-island-collapse.ts
new file mode 100644
index 0000000000..9ebbb56c16
--- /dev/null
+++ b/packages/stage-ui/src/composables/use-controls-island-collapse.ts
@@ -0,0 +1,46 @@
+import type { Ref } from 'vue'
+
+import { useTimeoutFn } from '@vueuse/core'
+import { computed } from 'vue'
+
+export interface UseControlsIslandCollapseOptions {
+  /** Delay in seconds before collapsing */
+  autoHideDelay: Ref<number>
+  /** Whether auto-hide is enabled */
+  autoHideControlsIsland: Ref<boolean>
+  /** Whether the panel is expanded */
+  expanded: Ref<boolean>
+  /** Whether there's a blocking overlay */
+  isBlocked: Ref<boolean>
+}
+
+export interface UseControlsIslandCollapseReturn {
+  /** Start the collapse timer */
+  startCollapse: () => void
+  /** Stop the collapse timer */
+  stopCollapse: () => void
+  collapseDelayMs: Ref<number>
+}
+
+/**
+ * Composable for controls island auto-collapse behavior.
+ * Collapses the expanded panel after a delay when mouse leaves.
+ */
+export function useControlsIslandCollapse(options: UseControlsIslandCollapseOptions): UseControlsIslandCollapseReturn {
+  const { autoHideDelay, autoHideControlsIsland, expanded, isBlocked } = options
+
+  const collapseDelayMs = computed(() =>
+    autoHideControlsIsland.value ? autoHideDelay.value * 1000 : 1500,
+  )
+
+  const { start: startCollapse, stop: stopCollapse } = useTimeoutFn(() => {
+    if (expanded.value && !isBlocked.value)
+      expanded.value = false
+  }, () => collapseDelayMs.value, { immediate: false })
+
+  return {
+    startCollapse,
+    stopCollapse,
+    collapseDelayMs,
+  }
+}

From a76fb38046c7a98140dd362c12aab9576011518e Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Thu, 2 Apr 2026 15:47:57 +0800
Subject: [PATCH 17/19] [claudesquad] update from 'beautify-feat' on 02 Apr 26
 15:47 CST (paused)

---
 packages/i18n/src/locales/en/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/es/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/fr/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/ja/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/ko/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/ru/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/vi/settings.yaml             |  9 +++++++++
 packages/i18n/src/locales/zh-Hans/settings.yaml        |  9 +++++++++
 packages/i18n/src/locales/zh-Hant/settings.yaml        |  9 +++++++++
 .../src/components/settings-general-fields.vue         | 10 +++++-----
 10 files changed, 86 insertions(+), 5 deletions(-)

diff --git a/packages/i18n/src/locales/en/settings.yaml b/packages/i18n/src/locales/en/settings.yaml
index e1e7612f46..e706e3a423 100644
--- a/packages/i18n/src/locales/en/settings.yaml
+++ b/packages/i18n/src/locales/en/settings.yaml
@@ -79,6 +79,15 @@ controls-island:
     auto: Auto (responsive)
     large: Large (default)
     small: Small
+  auto-hide:
+    title: Auto-hide controls island
+    description: Hide controls island after mouse leaves, show after mouse enters
+  hide-delay:
+    title: Hide delay
+  show-delay:
+    title: Show delay
+  hidden-opacity:
+    title: Hidden opacity
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/i18n/src/locales/es/settings.yaml b/packages/i18n/src/locales/es/settings.yaml
index d0785a986c..9eaaae2b20 100644
--- a/packages/i18n/src/locales/es/settings.yaml
+++ b/packages/i18n/src/locales/es/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: Automático (adaptativo)
     large: Grande (predeterminado)
     small: Pequeño
+  auto-hide:
+    title: Ocultar automáticamente la isla de controles
+    description: Ocultar la isla de controles cuando el ratón sale, mostrar cuando entra
+  hide-delay:
+    title: Retraso al ocultar
+  show-delay:
+    title: Retraso al mostrar
+  hidden-opacity:
+    title: Opacidad al ocultar
 analytics:
   notice:
     title: Análisis de uso
diff --git a/packages/i18n/src/locales/fr/settings.yaml b/packages/i18n/src/locales/fr/settings.yaml
index dce37099be..4ac228a636 100644
--- a/packages/i18n/src/locales/fr/settings.yaml
+++ b/packages/i18n/src/locales/fr/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: Auto (réactif)
     large: Grande (défaut)
     small: Petite
+  auto-hide:
+    title: Masquer automatiquement l'îlot de contrôle
+    description: Masquer l'îlot de contrôle lorsque la souris sort, afficher cuando la souris entre
+  hide-delay:
+    title: Délai de masquage
+  show-delay:
+    title: Délai d'affichage
+  hidden-opacity:
+    title: Opacité lors du masquage
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/i18n/src/locales/ja/settings.yaml b/packages/i18n/src/locales/ja/settings.yaml
index 5768163330..3b33ac7bbb 100644
--- a/packages/i18n/src/locales/ja/settings.yaml
+++ b/packages/i18n/src/locales/ja/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: 自動 (レスポンシブ)
     large: 大 (デフォルト)
     small: 小
+  auto-hide:
+    title: コントロールアイランドを自動非表示
+    description: マウ스가離れたときにコントロールアイランドを非表示にし、 入ると表示します
+  hide-delay:
+    title: 非表示までの遅延
+  show-delay:
+    title: 表示までの遅延
+  hidden-opacity:
+    title: 非表示時の透明度
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/i18n/src/locales/ko/settings.yaml b/packages/i18n/src/locales/ko/settings.yaml
index 01d7a51f8b..ea55ae991e 100644
--- a/packages/i18n/src/locales/ko/settings.yaml
+++ b/packages/i18n/src/locales/ko/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: 자동 (능동적)
     large: 크게 (기본값)
     small: 작게
+  auto-hide:
+    title: 컨트롤 아일랜드 자동 숨기기
+    description: 마우스가 떠날 때 컨트롤 아일랜드를 숨기고, 들어오면 표시합니다
+  hide-delay:
+    title: 숨기기 지연
+  show-delay:
+    title: 표시 지연
+  hidden-opacity:
+    title: 숨기기 시 투명도
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/i18n/src/locales/ru/settings.yaml b/packages/i18n/src/locales/ru/settings.yaml
index 41ce6416e6..8b2793b1fb 100644
--- a/packages/i18n/src/locales/ru/settings.yaml
+++ b/packages/i18n/src/locales/ru/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: Автоматически (отвечает)
     large: Большой (по умолчанию)
     small: Маленький
+  auto-hide:
+    title: Автоматически скрывать остров управления
+    description: Скрывать остров управления, когда мышь уходит, показывать, когда наводится
+  hide-delay:
+    title: Задержка скрытия
+  show-delay:
+    title: Задержка показа
+  hidden-opacity:
+    title: Прозрачность при скрытии
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/i18n/src/locales/vi/settings.yaml b/packages/i18n/src/locales/vi/settings.yaml
index 17732f4102..b040217f80 100644
--- a/packages/i18n/src/locales/vi/settings.yaml
+++ b/packages/i18n/src/locales/vi/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: Tự động (thích ứng)
     large: Lớn (mặc định)
     small: Nhỏ
+  auto-hide:
+    title: Tự động ẩn đảo điều khiển
+    description: Ẩn đảo điều khiển khi chuột rời đi, hiển thị khi chuột di vào
+  hide-delay:
+    title: Độ trễ ẩn
+  show-delay:
+    title: Độ trễ hiển thị
+  hidden-opacity:
+    title: Độ mờ khi ẩn
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/i18n/src/locales/zh-Hans/settings.yaml b/packages/i18n/src/locales/zh-Hans/settings.yaml
index 512d2efd06..94d11aa971 100644
--- a/packages/i18n/src/locales/zh-Hans/settings.yaml
+++ b/packages/i18n/src/locales/zh-Hans/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: 自动（响应式）
     large: 大（默认）
     small: 小
+  auto-hide:
+    title: 自动隐藏控制岛
+    description: 鼠标离开后隐藏控制岛，鼠标进入后显示
+  hide-delay:
+    title: 隐藏延迟
+  show-delay:
+    title: 显示延迟
+  hidden-opacity:
+    title: 隐藏时透明度
 analytics:
   notice:
     title: 使用数据及崩溃分析
diff --git a/packages/i18n/src/locales/zh-Hant/settings.yaml b/packages/i18n/src/locales/zh-Hant/settings.yaml
index 2abe183671..166a4518b2 100644
--- a/packages/i18n/src/locales/zh-Hant/settings.yaml
+++ b/packages/i18n/src/locales/zh-Hant/settings.yaml
@@ -72,6 +72,15 @@ controls-island:
     auto: 自動（回應式）
     large: 大(默認)
     small: 小
+  auto-hide:
+    title: 自動隱藏控制島
+    description: 滑鼠離開後隱藏控制島，滑鼠進入後顯示
+  hide-delay:
+    title: 隱藏延遲
+  show-delay:
+    title: 顯示延遲
+  hidden-opacity:
+    title: 隱藏時透明度
 analytics:
   notice:
     title: Usage analytics
diff --git a/packages/stage-pages/src/components/settings-general-fields.vue b/packages/stage-pages/src/components/settings-general-fields.vue
index 2920dafa43..32b0320ed4 100644
--- a/packages/stage-pages/src/components/settings-general-fields.vue
+++ b/packages/stage-pages/src/components/settings-general-fields.vue
@@ -69,8 +69,8 @@ const languages = computed(() => {
       :enter="{ opacity: 1, y: 0 }"
       :duration="250 + (5 * 10)"
       :delay="5 * 50"
-      label="Auto-hide controls island"
-      description="Hide controls island after mouse leaves, show after mouse enters"
+      :label="t('settings.controls-island.auto-hide.title')"
+      :description="t('settings.controls-island.auto-hide.description')"
     />
 
     <template v-if="showAutoHideControlsIsland && settingsControlsIsland.autoHideControlsIsland">
@@ -85,7 +85,7 @@ const languages = computed(() => {
         :max="5"
         :step="0.1"
         :format-value="v => `${v}s`"
-        label="Hide delay"
+        :label="t('settings.controls-island.hide-delay.title')"
       />
 
       <FieldRange
@@ -99,7 +99,7 @@ const languages = computed(() => {
         :max="5"
         :step="0.1"
         :format-value="v => `${v}s`"
-        label="Show delay"
+        :label="t('settings.controls-island.show-delay.title')"
       />
 
       <FieldRange
@@ -113,7 +113,7 @@ const languages = computed(() => {
         :max="100"
         :step="1"
         :format-value="v => `${v}%`"
-        label="Hidden opacity"
+        :label="t('settings.controls-island.hidden-opacity.title')"
       />
     </template>
 

From 9d35be2c89d1ac2dca894687c9d7ba3ee00fdb4a Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Thu, 2 Apr 2026 16:17:33 +0800
Subject: [PATCH 18/19] feat(settings): expose auto-hide controls island
 settings in deprecated useSettings

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/stage-ui/src/stores/settings/index.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/stage-ui/src/stores/settings/index.ts b/packages/stage-ui/src/stores/settings/index.ts
index 9c501c1389..11cfa0caf3 100644
--- a/packages/stage-ui/src/stores/settings/index.ts
+++ b/packages/stage-ui/src/stores/settings/index.ts
@@ -82,6 +82,10 @@ export const useSettings = defineStore('settings', () => {
     // UI settings
     allowVisibleOnAllWorkspaces: controlsIslandRefs.allowVisibleOnAllWorkspaces,
     alwaysOnTop: controlsIslandRefs.alwaysOnTop,
+    autoHideControlsIsland: controlsIslandRefs.autoHideControlsIsland,
+    autoHideDelay: controlsIslandRefs.autoHideDelay,
+    autoShowDelay: controlsIslandRefs.autoShowDelay,
+    autoHideOpacity: controlsIslandRefs.autoHideOpacity,
 
     // Methods
     setThemeColorsHue: theme.setThemeColorsHue,

From 7773b30ee5409da507d0556ffa70c9fcadd323c4 Mon Sep 17 00:00:00 2001
From: leaft <wuqizq@outlook.com>
Date: Thu, 2 Apr 2026 17:27:19 +0800
Subject: [PATCH 19/19] fix(controls-island): prevent flicker during quick
 mouse movements

Only update delayed states when the respective delays are met (or when
delay is 0), avoiding unnecessary state transitions during rapid mouse
movements in/out of the island area.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../use-controls-island-auto-hide.ts          | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts b/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
index 816654bd89..181f1ca7dc 100644
--- a/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
+++ b/packages/stage-ui/src/composables/use-controls-island-auto-hide.ts
@@ -63,17 +63,28 @@ export function useControlsIslandAutoHide(options: UseControlsIslandAutoHideOpti
       isInsideDelayed.value = !val
       return
     }
+    // Stop any pending timers
     stopOutside()
     stopInside()
     if (val) {
       // Mouse left - start hide delay timer
-      isInsideDelayed.value = false
-      startOutside()
+      // Only update state when delay is met (or delay is 0)
+      if (autoHideDelay.value <= 0) {
+        isOutsideDelayed.value = true
+      }
+      else {
+        startOutside()
+      }
     }
     else {
       // Mouse entered - start show delay timer
-      isOutsideDelayed.value = false
-      startInside()
+      // Only update state when delay is met (or delay is 0)
+      if (autoShowDelay.value <= 0) {
+        isInsideDelayed.value = true
+      }
+      else {
+        startInside()
+      }
     }
   })