@lrplrplrp/dsh-live2d 0.1.2 → 0.1.4

package/lib/client.js

@@ -1,3 +1,6 @@
+// ⚠️ 本文件由 scripts/build-client.mjs 从 lib/src/ 源码拼接生成，请勿直接编辑。
+//    修改请改 lib/src/*.js 或 lib/shared/states.js，然后运行 `npm run build`。
+//    `npm run check` 会校验本产物与源码是否一致。
 // dsh-live2d — Client (browser) side.
 //
 // DSH 插件：在 Web GUI 中渲染 Live2D 看板娘模型。
@@ -11,7 +14,7 @@
 //
 // 移除了原项目的：对话框、小飞机游戏、关闭/关于/GitHub 按钮。
 
-window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
+window.__ModuleLoader__.load({ id: '@lrplrplrp/dsh-live2d', factory: (require) => {
   var module = { exports: {} }
   var exports = module.exports
 
@@ -19,41 +22,59 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
   const { useState, useEffect, useRef, useCallback } = React
   const h = React.createElement
 
+  // >>> shared/states.js (generated — do not edit here) >>>
+  // 由 scripts/build-client.mjs 从 lib/shared/states.js 内联生成，请勿直接修改此处。
+  // dsh-live2d — 共享的状态常量（host 与 client 的单一来源）。
+  //
+  // host 端（lib/index.js）直接 `import { DSHState }`；
+  // client 端（lib/client.js）由 scripts/build-client.mjs 在构建时内联本文件内容
+  // （浏览器侧无法 import 本地文件，client.js 必须保持单文件投放）。
+  //
+  // 本文件不得依赖 node 或浏览器任何专有 API，保持“纯数据 + 纯函数”以便两端复用。
+
+  const DSHState = Object.freeze({
+    IDLE: 'IDLE',
+    THINKING: 'THINKING',
+    WORKING: 'WORKING',
+    SPEAKING: 'SPEAKING', // 开始输出对话内容
+    SUCCESS: 'SUCCESS',
+    ERROR: 'ERROR',
+  })
+  // <<< shared/states.js <<<
   // ══════════════════════════════════════════════════════════════════════
   //  常量 & 配置
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：常量、默认模型列表、localStorage 配置读写与内存缓存（+ 构建时内联的共享 DSHState））
 
   const STORAGE_KEY = 'dsh-live2d.v1'
   const POSITION_KEY = 'dsh-live2d.position'
   const ACTIVE_MODEL_KEY = 'dsh-live2d.activeModel'
 
+  // 容器默认屏幕位置（无本地存档时使用），对应 position:fixed 的 left/top
+  const DEFAULT_POSITION = { x: 1240, y: 330 }
+
   // 本地文件路由前缀（由 host 端 index.js 注册）
   const LIB_BASE = '/plugins/dsh-live2d/lib/'
   const ASSETS_BASE = '/plugins/dsh-live2d/assets/'
 
-  // 配置 / 上传接口（与 host 端 index.js 中的 CONFIG_ENDPOINT 对应）
-  const CONFIG_ENDPOINT = '/plugins/dsh-live2d/config'
-
-  // 需要按顺序加载的本地库文件
-  const LIB_SCRIPTS = [
-    'pixi.min.js',
-    'live2d.min.js',
-    'live2dcubismcore.min.js',
-    'index.min.js',
+  // 需要按【依赖顺序】加载的本地库文件，分组表示加载阶段：
+  //   - 第一段 pixi 必须先行执行完成；
+  //   - 第二段的 live2d / core / display 可并行，但都要在 pixi 之后（display 在
+  //     加载期就访问 PIXI，若与 pixi 并行下载可能因 pixi 体积大而晚到，导致报错）。
+  const LIB_PHASES = [
+    ['pixi.min.js'],
+    ['live2d.min.js', 'live2dcubismcore.min.js', 'index.min.js'],
   ]
 
-  const DSHState = {
-    IDLE: 'IDLE',
-    THINKING: 'THINKING',
-    WORKING: 'WORKING',
-    SPEAKING: 'SPEAKING',
-    SUCCESS: 'SUCCESS',
-    ERROR: 'ERROR',
-  }
+  // DSHState 由 lib/shared/states.js 内联提供（host 与 client 的单一来源），
+  // 见 scripts/build-client.mjs —— 此处不再重复定义。
 
-  const ANIMATION_STATES =['IDLE', 'THINKING', 'THINK_END', 'WORKING', 'SPEAKING', 'SUCCESS', 'ERROR']
+  // 客户端动画状态：除 host 广播的 DSHState 外，额外含 WELCOME（欢迎）与
+  // THINK_END（思考结束过渡态，由客户端在 THINKING → 非 THINKING 时触发一次）。
+  const ANIMATION_STATES = ['WELCOME', 'IDLE', 'THINKING', 'THINK_END', 'WORKING', 'SPEAKING', 'SUCCESS', 'ERROR']
 
   const ANIMATION_STATE_LABELS = {
+    WELCOME: '欢迎',
     IDLE: '空闲',
     THINKING: '开始思考',
     THINK_END: '思考结束',
@@ -69,19 +90,22 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       url: ASSETS_BASE + 'deepseek_l2d/deepseek.model3.json',
       canvasWidth: 300,
       canvasHeight: 400,
-      config: { x: -50, y: 100, scaleX: 2, scaleY: 2 },
+      config: { x: 0, y: 0, scaleX: 1.5, scaleY: 1.5 },
       animations: {
+        WELCOME: { motion: { group: 'Idle', index: 0 }, loop: false },
         IDLE: { motion: { group: 'Idle', index: 0 }, loop: false },
-        THINKING: { motion: { group: 'Anima', index: 2 }, loop: false },
+        THINKING: { motion: { group: 'Anima', index: 2 }, loop: true },
         THINK_END: { motion: { group: 'Anima', index: 1 }, loop: false },
-        WORKING: { motion: { group: 'Anima', index: 0 }, loop: false },
-        SPEAKING: { motion: { group: 'Anima', index: 0 }, loop: false },
+        WORKING: { expression: 'puzzled' },
+        SPEAKING: { motion: { group: 'Anima', index: 0 }, loop: true },
         SUCCESS: { expression: 'happy' },
         ERROR: { expression: 'unhappy' },
       },
     }],
     // 眼睛是否跟随鼠标（全局开关）
     eyeFollow: true,
+    // 点击命中区域开关（全局开关，默认开启）
+    hitArea: true,
   }
 
   // ══════════════════════════════════════════════════════════════════════
@@ -95,7 +119,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     var models = cfg.models
     if (!Array.isArray(models)) models = []
     models = models.map(function(m) {
-      if (!m || typeof m !== 'object') return { name: '', url: '', groups: [], groupCounts: {}, groupMotions: {}, expressions: [], animations: {} }
+      if (!m || typeof m !== 'object') return { name: '', url: '', groups: [], groupCounts: {}, groupMotions: {}, expressions: [], animations: {}, timeMappings: [] }
       return {
         name: m.name || '',
         url: m.url || '',
@@ -107,27 +131,54 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         groupMotions: m.groupMotions && typeof m.groupMotions === 'object' ? m.groupMotions : {},
         expressions: Array.isArray(m.expressions) ? m.expressions : [],
         animations: m.animations && typeof m.animations === 'object' ? m.animations : {},
+        // 时间映射：[{ start: 'HH:MM', end: 'HH:MM', animation: {...} }]
+        timeMappings: Array.isArray(m.timeMappings) ? m.timeMappings : [],
       }
     })
-    return Object.assign({}, cfg, { models: models, eyeFollow: cfg.eyeFollow === false ? false : true })
+    return Object.assign({}, cfg, { models: models, eyeFollow: cfg.eyeFollow === false ? false : true, hitArea: cfg.hitArea === false ? false : true })
   }
 
+  // 配置在内存中缓存一份：缩放 / 拖动画布这类高频操作需要在内存里连续累加，
+  // 不能每次都从 localStorage 重新解析（否则上一次的防抖写入还没落盘，会读到旧值）。
+  // 读取一律走缓存，写入由 saveConfig 防抖落盘，保证内存与持久化一致。
+  let _configCache = null
+
   function getConfig() {
+    if (_configCache) return _configCache
     try {
       const raw = window.localStorage.getItem(STORAGE_KEY)
-      if (!raw) return normalizeConfig(JSON.parse(JSON.stringify(DEFAULT_MODEL_LIST)))
-      const stored = JSON.parse(raw)
-      return normalizeConfig(stored)
+      _configCache = raw
+        ? normalizeConfig(JSON.parse(raw))
+        : normalizeConfig(JSON.parse(JSON.stringify(DEFAULT_MODEL_LIST)))
     } catch {
-      return normalizeConfig(JSON.parse(JSON.stringify(DEFAULT_MODEL_LIST)))
+      _configCache = normalizeConfig(JSON.parse(JSON.stringify(DEFAULT_MODEL_LIST)))
     }
+    return _configCache
   }
 
+  let _saveTimer = null
   function saveConfig(cfg) {
+    // 始终以传入对象（或当前缓存）作为权威状态，确保与内存一致
+    if (cfg) _configCache = cfg
+    if (_saveTimer) clearTimeout(_saveTimer)
+    _saveTimer = setTimeout(function() {
+      _saveTimer = null
+      try {
+        if (_configCache) window.localStorage.setItem(STORAGE_KEY, JSON.stringify(_configCache))
+      } catch {}
+    }, 150)
+  }
+
+  // 立即落盘：在页面卸载/隐藏前把待写的配置同步刷入 localStorage，
+  // 避免 debounce 窗口内（150ms）用户关闭页面导致最后一次修改丢失。
+  function flushConfig() {
+    if (_saveTimer) { clearTimeout(_saveTimer); _saveTimer = null }
     try {
-      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(cfg))
+      if (_configCache) window.localStorage.setItem(STORAGE_KEY, JSON.stringify(_configCache))
     } catch {}
   }
+  window.addEventListener('pagehide', flushConfig)
+  window.addEventListener('beforeunload', flushConfig)
 
   function getPosition() {
     try {
@@ -166,46 +217,208 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
   // ══════════════════════════════════════════════════════════════════════
   //  本地库加载器（通过 host 端 webserver 路由）
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：本地 Live2D 库脚本加载 + 浏览器自动播放策略的音频解锁）
 
   let libsLoaded = false
+  // 加载进行中的 Promise：并发调用（apply 预加载 + 组件 init）共享同一次加载。
+  // 不能靠「DOM 里是否已有该 script 标签」判断是否加载完成 —— 标签刚 append 时
+  // 脚本尚未下载/执行，此时 resolve 会让调用方误以为库已就绪（曾导致
+  // 「PIXI not found」以及 index.min.js 在 PIXI 之前执行而报错）。
+  let libsLoadingPromise = null
 
-  function loadScript(url) {
-    return new Promise((resolve, reject) => {
-      if (document.querySelector('script[src="' + url + '"]')) {
-        resolve()
+  /**
+   * 加载本地库脚本。
+   *
+   * 关键点：这些脚本互相之间有「执行顺序」依赖（index.min.js 在加载期就要用 PIXI），
+   * 但没有「下载」依赖。同一阶段内显式 async=false 让浏览器并行下载、按插入顺序执行；
+   * 阶段之间串行等待（见 LIB_PHASES），确保 pixi 先执行完成。
+   *
+   * 已由本模块插入过（data-dsh-live2d-lib）的 script 直接复用其加载结果；
+   * 不用选择器判断「存在即完成」。
+   */
+  const SCRIPT_MARK = 'data-dsh-live2d-lib'
+  function loadOneScript(url) {
+    return new Promise(function(resolve, reject) {
+      const done = function() { resolve() }
+      // 复用本模块此前插入的标签（可能仍在加载中）：按当前 readyState 决定等待还是立即返回
+      const existing = document.querySelector('script[' + SCRIPT_MARK + '][src="' + url + '"]')
+      if (existing) {
+        if (existing.readyState === 'loaded' || existing.readyState === 'complete') { done(); return }
+        existing.addEventListener('load', done, { once: true })
+        existing.addEventListener('error', function() { reject(new Error('Failed to load ' + url)) }, { once: true })
         return
       }
       const script = document.createElement('script')
+      script.setAttribute(SCRIPT_MARK, '')
       script.src = url
-      script.onload = resolve
+      script.onload = done
       script.onerror = function() { reject(new Error('Failed to load ' + url)) }
+      // 关键：动态插入的 <script> 默认是 async（谁先下载完谁先执行），必须显式
+      // async=false 才会「按插入顺序执行」。否则同段的 live2d/core/display 之间
+      // 顺序不可控（历史上就是这里让 index.min.js 抢在 PIXI 之前执行而报错）。
+      script.async = false
       document.head.appendChild(script)
     })
   }
 
-  async function ensureLibsLoaded() {
-    if (libsLoaded) return true
+  function loadScripts(urls) {
+    return Promise.all(urls.map(loadOneScript))
+  }
+
+  /**
+   * 按依赖顺序加载库（LIB_PHASES 见 10-config.js）：
+   *   pixi.min.js 先单独加载并【执行完成】，其余脚本再并行加载。
+   * 为什么不能一次性全部并行插入：动态插入的 <script> 虽然理论上按插入顺序执行，
+   * 但实际取决于下载完成的先后（pixi 体积最大、往往最后到），index.min.js 会在
+   * 加载期就访问 PIXI 而报 "Cannot read properties of undefined"。
+   */
+  async function loadLibsInOrder() {
+    for (const phase of LIB_PHASES) {
+      await loadScripts(phase.map(function(name) { return LIB_BASE + name }))
+    }
+  }
+
+  function ensureLibsLoaded() {
+    if (libsLoaded) return Promise.resolve(true)
+    if (libsLoadingPromise) {
+      return libsLoadingPromise
+    }
+    libsLoadingPromise = loadLibsInOrder()
+      .then(function() {
+        libsLoaded = true
+        // 库就绪后立刻预热模型文件（含体积最大的贴图），与后续的引擎初始化重叠，
+        // 让 Live2DModel.from 直接从缓存取，缩短首开等待（刷新时本就有缓存，故无感）。
+        preloadModelAssets()
+        return true
+      })
+      .catch(function(err) {
+        console.warn('[dsh-live2d] Failed to load Live2D libraries from local server:', err)
+        // 允许后续重试
+        libsLoadingPromise = null
+        return false
+      })
+    return libsLoadingPromise
+  }
+
+  /** 复位加载状态，让下一次 ensureLibsLoaded 重新尝试（用于库加载异常后的自愈）。 */
+  function resetLibsLoaded() {
+    libsLoaded = false
+    libsLoadingPromise = null
+  }
+
+  // 预热当前模型的 model3.json 及其引用的贴图/动作文件。
+  // 仅用 <link rel=preload> / fetch 拉取进缓存，不解析，失败也不影响正常加载路径。
+  let _assetsPreloaded = false
+  function preloadModelAssets() {
+    if (_assetsPreloaded) return
+    _assetsPreloaded = true
+    let entry = null
     try {
-      for (const name of LIB_SCRIPTS) {
-        await loadScript(LIB_BASE + name)
-      }
-      libsLoaded = true
-      return true
-    } catch (err) {
-      console.warn('[dsh-live2d] Failed to load Live2D libraries from local server:', err)
-      return false
+      const cfg = getConfig()
+      const idx = getActiveModelIndex(cfg.models)
+      entry = cfg.models[idx]
+    } catch (e) { return }
+    const url = entry && entry.url
+    if (!url) return
+
+    // 先取 model3.json，再按 FileReferences 预热贴图与动作（仅贴图通常占大头）
+    fetch(url, { cache: 'force-cache' })
+      .then(function(r) { return r.ok ? r.json() : null })
+      .then(function(model3) {
+        if (!model3 || !model3.FileReferences) return
+        const fr = model3.FileReferences
+        const base = url.slice(0, url.lastIndexOf('/') + 1)
+        const targets = []
+        // 贴图（体积最大，优先）
+        if (Array.isArray(fr.Textures)) {
+          for (const t of fr.Textures) if (typeof t === 'string') targets.push(base + t)
+        }
+        // 动作/表情/物理等 JSON（体积小但数量多，一并预热）
+        const motions = fr.Motions || {}
+        for (const g of Object.keys(motions)) {
+          const list = Array.isArray(motions[g]) ? motions[g] : []
+          for (const mo of list) {
+            const f = typeof mo === 'string' ? mo : (mo && (mo.File || mo.file))
+            if (typeof f === 'string') targets.push(base + f)
+          }
+        }
+        for (const e of (fr.Expressions || [])) {
+          const f = typeof e === 'string' ? e : (e && (e.File || e.file))
+          if (typeof f === 'string') targets.push(base + f)
+        }
+        for (const key of ['Physics', 'Pose', 'DisplayInfo']) {
+          if (typeof fr[key] === 'string') targets.push(base + fr[key])
+        }
+        for (const t of targets) {
+          try { fetch(t, { cache: 'force-cache' }).catch(function() {}) } catch (e) {}
+        }
+      })
+      .catch(function() {})
+  }
+
+  // 浏览器自动播放策略允许在用户手势（点击/按键/触摸）中播放音频。
+  // Live2D 显示库用裸 HTMLAudioElement.play() 播放动作附带的语音，欢迎动画
+  // 在页面加载后立即自动触发（早于任何用户交互），其 play() 会被浏览器拦截
+  // —— 动作照常播放，但声音被静默丢弃。其余状态均在用户已交互后才触发，故
+  // 能正常出声。这里在首次用户手势中用一段 1 采样静音 wav 解锁音频，确保
+  // 浏览器自动播放策略：页面加载后、任意用户手势前，直接 audio.play() 会被静默拦截。
+  // 因此“加载期即触发”的自动动画（欢迎、时间映射）会只剩动作、没有声音。处理策略：
+  // 在音频未解锁前，这类自动动画【整体推迟播放】，不真正播放；待首次用户手势
+  // （pointerdown/keydown/touchstart）解锁音频后，再补播（动作+语音一同出现）。
+  // 注意：不依赖“播放静音 WAV 是否 resolve”来预判能否自动播放——部分浏览器即便
+  // 实际会拦截语音，也会让静音 WAV 的 play() resolve，导致误判已解锁而仍被静音。
+  // 故只以真实用户手势作为解锁信号（与首版欢迎修复一致）。推迟是“动作+语音”一起的，
+  // 不做逐动作语音探测（cubism2/3/4 的语音字段命名不一致，探测不可靠）。
+  let _audioUnlocked = false
+  let _engineInstance = null
+  // "HH:MM" → 分钟数 的解析缓存（值域有限，避免 ticker 每轮重复正则）
+  const _timeParseCache = new Map()
+  // 待解锁后补播的自动动画目标：'welcome' | 'timemapping' | null
+  // （仅记录“最近一个”即可；欢迎优先于时间映射）
+  let _deferredAuto = null
+  function unlockAudioOnce() {
+    if (_audioUnlocked) return
+    _audioUnlocked = true
+    // 解锁后立刻补播加载期被推迟的自动动画（动作+语音一起出）
+    const target = _deferredAuto
+    _deferredAuto = null
+    // 加载期因音频未解锁而被推迟的时间映射（IDLE 分支记录的），解锁后补播
+    const pendingTimeMapping = _engineInstance && _engineInstance._timeMappingDeferred
+    if ((target || pendingTimeMapping) && _engineInstance) {
+      try {
+        if (target === 'welcome') {
+          // 欢迎优先：补播欢迎，并明确丢弃被推迟的时间映射，避免紧接着又被时间映射
+          // 抢走画面（欢迎播放期间由 _firstOpenSuppressing/_welcomePending 继续抑制）。
+          _engineInstance._timeMappingDeferred = false
+          _engineInstance.playWelcomeFirstOpen()
+        } else if (target === 'timemapping' || pendingTimeMapping) {
+          _engineInstance.checkTimeMappings()
+        }
+      } catch (e) {}
     }
   }
+  function installAudioUnlock() {
+    const handler = () => {
+      unlockAudioOnce()
+      document.removeEventListener('pointerdown', handler, true)
+      document.removeEventListener('keydown', handler, true)
+      document.removeEventListener('touchstart', handler, true)
+    }
+    document.addEventListener('pointerdown', handler, true)
+    document.addEventListener('keydown', handler, true)
+    document.addEventListener('touchstart', handler, true)
+  }
 
   // ══════════════════════════════════════════════════════════════════════
   //  CSS 注入
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：看板娘容器/画布/控制浮层的样式注入）
 
   const LIVE2D_CSS = [
     '#dsh-live2d-container {',
     '  position: fixed;',
-    '  top: 24px;',
-    '  left: 24px;',
+    '  top: 330px;',
+    '  left: 1240px;',
     '  bottom: auto;',
     '  z-index: 9999;',
     // 容器本身不拦截指针事件，画布区域点击完全穿透到页面，不影响输入；
@@ -225,9 +438,14 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     '}',
     '#dsh-live2d-container canvas {',
     '  display: block;',
-    // 模型本体的 HitAreas 为空（deepseek.model3.json: "HitAreas": []），
-    // canvas 不需要接收指针事件；交给容器统一处理，拖动才能从画布上起手。
+    // 画布始终不拦截指针：鼠标滚轮/点击全部原生穿透给页面下层。
+    // hit area 的命中检测在 document 捕获阶段完成（client.js 的
+    // _setupCanvasInteraction），命中时触发 Tap 动画但不会消费事件。
     '  pointer-events: none;',
+    // 模型未就绪前画布透明；就绪后由引擎 _fadeInCanvas 淡入显示
+    // （CSS transition 使用先快后慢的贝塞尔曲线）
+    '  opacity: 0;',
+    '  transition: opacity 0.8s cubic-bezier(0.05, 0.9, 0.15, 1);',
     '}',
     '#dsh-live2d-container .dsh-live2d-label {',
     '  position: absolute;',
@@ -247,6 +465,8 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     // 控制浮层：固定定位，位置由 JS 动态计算——理想位置是画布右下角，
     // 但会被夹在视口内（画布拖出屏幕时，图标停在离画布右下角最近的屏幕边缘）。
     // 浮层本身不拦截指针（pointer-events:none），只有里面的图标可点。
+    // 默认隐藏，仅当鼠标位于 Live2D 画布上方时才显示（由 JS 命中检测切换 .show，
+    // 因为容器/canvas 为 pointer-events:none，CSS :hover 无法触发，且不能改动穿透逻辑）。
     '#dsh-live2d-controls {',
     '  position: fixed;',
     '  z-index: 10000;',
@@ -254,6 +474,17 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     '  align-items: center;',
     '  gap: 8px;',
     '  pointer-events: none;',
+    '  opacity: 0;',
+    '  transition: opacity 0.2s;',
+    '}',
+    // 鼠标位于画布上方时显示控制浮层
+    '#dsh-live2d-controls.show {',
+    '  opacity: 1;',
+    '}',
+    // 未显示时彻底禁用图标交互，避免透明状态下仍能误触
+    '#dsh-live2d-controls:not(.show) .dsh-live2d-resize,',
+    '#dsh-live2d-controls:not(.show) .dsh-live2d-drag {',
+    '  pointer-events: none;',
     '}',
     // 画布大小拖拽手柄：常驻右下角浮层，与移动图标并排
     '#dsh-live2d-controls .dsh-live2d-resize {',
@@ -302,6 +533,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
   // ══════════════════════════════════════════════════════════════════════
   //  Live2D 引擎
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：Live2DEngine：渲染、状态动画、时间映射、点击命中、画布缩放）
 
   class Live2DEngine {
     constructor() {
@@ -316,24 +548,57 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       // 眼睛跟随鼠标：全局开关 + 归一化鼠标坐标（-1~1 范围，0.5 为屏幕中心）
       this.eyeFollow = true
       this.pointer = { x: 0.5, y: 0.5 }
+      // 点击命中区域（hit area）全局开关
+      this.hitArea = true
       // 循环播放状态：{ group, index } 或 null；motionFinish 时若仍为该状态则重启
       this._loopState = null
       this._loopCooldown = 0
+      // 时间映射状态：当前 DSH 状态名 + 当前命中的时间映射下标 + 检查帧计数
+      this.currentStateName = 'IDLE'
+      this._activeTimeMapping = -1
+      this._timeCheckFrame = 0
+      // 首开页面：欢迎状态是否正在等待确认（host 返回 welcome 标记）。
+      // 为 true 时，加载期不抢触发时间映射，优先把决定权交给欢迎状态。
+      this._welcomePending = false
+      // 本次首开会话是否仍处于“仅播欢迎、抑制时间映射”状态（首次打开页面为 true，
+      // 欢迎标记写入 sessionStorage 后变为 false）。刷新页面会重置 JS 上下文且
+      // sessionStorage 已有 welcomed 标记，故刷新后不影响时间映射照常播放。
+      this._firstOpenSuppressing = false
+      // 首开页面欢迎状态是否已被优先播放（避免与加载期命中的时间映射抢触发）
+      this._welcomePlayed = false
+      // 时间映射因音频未解锁而推迟播放的标记：解锁后由 checkTimeMappings 补播（带语音）
+      this._timeMappingDeferred = false
     }
 
     async     init(containerEl) {
       this.container = containerEl
 
-      // 从全局配置读取眼睛跟随开关初始值
+      // 首开页面：立即进入“欢迎优先待确认”期，挂起时间映射的自动触发，
+      // 直到欢迎标记查询完成（或欢迎播放结束）。这样即便 ticker 在异步查询
+      // 窗口内轮询到命中时间段，也不会抢在欢迎之前播放时间映射。
+      this._welcomePending = true
+
+      // 从全局配置读取眼睛跟随/点击命中区域开关初始值
       try { this.eyeFollow = getConfig().eyeFollow !== false } catch {}
       if (this.eyeFollow === undefined) this.eyeFollow = true
+      try { this.hitArea = getConfig().hitArea !== false } catch {}
+      if (this.hitArea === undefined) this.hitArea = true
 
       const ok = await ensureLibsLoaded()
       if (!ok) return false
 
+      // 安装一次性音频解锁：在首个用户手势中解锁浏览器自动播放策略，
+      // 使欢迎动画（页面加载即自动触发，早于任何交互）所附声音也能播放。
+      installAudioUnlock()
+      // 记录引擎实例，供模块级音频解锁回调在解锁后回放排队的带语音动作
+      _engineInstance = this
+
       const PIXI = window.PIXI
       if (!PIXI) {
-        console.error('[dsh-live2d] PIXI not found after loading scripts')
+        // 库报「已加载」但 PIXI 仍未就绪：通常是脚本执行顺序被破坏（如动态插入的
+        // script 以 async 方式乱序执行）。清掉加载缓存并允许下次重试，避免永久空白。
+        console.error('[dsh-live2d] PIXI not found after loading scripts; will retry on next init')
+        resetLibsLoaded()
         return false
       }
 
@@ -356,6 +621,10 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       this.canvas.style.height = canvasHeight + 'px'
       containerEl.appendChild(this.canvas)
 
+      // 点击交互：画布保持 pointer-events:none，鼠标事件（含滚轮）原生穿透给页面；
+      // hit area 的命中检测在 document 捕获阶段完成（见 _setupCanvasInteraction）。
+      this._setupCanvasInteraction()
+
       // 创建 PIXI 应用
       this.app = new PIXI.Application({
         width: appWidth,
@@ -388,6 +657,11 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         } else {
           try { this.model.focus(0, 0) } catch {}
         }
+        // 时间映射：每 120 帧（约 2 秒）检查一次时间条件，命中/离开时间段时切换动画。
+        // 首开欢迎期由 _welcomePending/_firstOpenSuppressing 在 checkTimeMappings 内部守卫，
+        // 这里照常调度即可，不会抢触发。
+        this._timeCheckFrame = (this._timeCheckFrame || 0) + 1
+        if (this._timeCheckFrame % 120 === 0) this.checkTimeMappings()
         // 循环播放：loop 状态激活且当前没有 motion 在播时，重启当前动作（带冷却避免抖动）
         if (this._loopState && this._loopState.index !== null) {
           if (this._loopCooldown > 0) {
@@ -434,12 +708,14 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
 
         // 解析模型路径（此时已经是完整的本地 URL）
         const modelUrl = this.resolveUrl(modelEntry.url, textureId)
-        console.log('[dsh-live2d] Loading model from:', modelUrl)
 
         // 加载新模型
         this.model = await live2d.Live2DModel.from(modelUrl)
         this.app.stage.addChild(this.model)
         this.model.buttonMode = false
+        // 点击 hit area 由本插件在 canvas 上统一处理，禁用模型自带的
+        // autoInteract(pointertap) 以避免重复触发/冲突
+        try { this.model.autoInteract = false } catch {}
 
         // 自动调整大小和位置
         this.autoSetTransform(modelEntry)
@@ -447,10 +723,13 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         // 绑定点击区域
         this.drawHitArea()
 
-        // 模型切换后清除循环状态，避免对不存在的 group/动作重启
+        // 模型切换后清除循环/时间映射状态，避免对不存在的 group/动作重启
         this._loopState = null
+        this._activeTimeMapping = -1
+        this.currentStateName = 'IDLE'
 
-        console.log('[dsh-live2d] Model ' + modelId + '-' + textureId + ' loaded')
+        // 模型就绪：淡入显示画布（从透明渐显，贝塞尔先快后慢）
+        this._fadeInCanvas()
       } catch (err) {
         console.error('[dsh-live2d] Failed to load model:', err)
       }
@@ -490,12 +769,67 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       if (!this.model) return
       try {
         const model = this.model
-        if (Object.keys(model.internalModel.hitAreas).length > 0) {
-          model.on('hit', (hitarea) => {
-            this.triggerMotion('Tap' + hitarea)
-          })
+        // 记录模型是否定义了可点击的 hit area。canvas 始终保持
+        // pointer-events:none（不拦截任何鼠标事件），hit area 的命中检测
+        // 放在 document 捕获阶段完成，见 handleCanvasClick。
+        this._hasHitAreas = Object.keys(model.internalModel.hitAreas).length > 0
+      } catch {}
+    }
+
+    // 模型就绪后淡入画布：从透明（opacity:0）渐显到不透明，使用 CSS transition
+    // 的贝塞尔曲线（先快后慢）。double requestAnimationFrame 确保先绘制出
+    // 透明帧、再开始过渡，避免浏览器跳过淡入直接显示。
+    _fadeInCanvas() {
+      if (!this.canvas) return
+      const canvas = this.canvas
+      canvas.style.opacity = '0'
+      requestAnimationFrame(function() {
+        requestAnimationFrame(function() {
+          try { canvas.style.opacity = '1' } catch {}
+        })
+      })
+    }
+
+    // 画布保持 pointer-events:none，鼠标滚轮/点击都会原生穿透给页面下层；
+    // 这里在 document 捕获阶段"旁听"点击：命中 hit area 时触发 Tap 动画，
+    // 但不消费事件（不 preventDefault/stopPropagation），页面仍能收到点击。
+    _setupCanvasInteraction() {
+      if (this._onCanvasClick) return
+      this._onCanvasClick = (e) => this.handleCanvasClick(e)
+      document.addEventListener('click', this._onCanvasClick, true)
+    }
+
+    handleCanvasClick(e) {
+      if (!this.model || !this.canvas) return
+      // 通用设置中关闭点击命中区域后，不再做 hit area 检测（点击仍原生穿透）
+      if (!this.hitArea) return
+      // 点击的是控制浮层图标（拖拽/画布大小手柄）时不触发 Tap
+      try {
+        if (e.target && e.target.closest && e.target.closest('#dsh-live2d-controls')) return
+      } catch {}
+      // 点击不在画布矩形内则忽略（点击画布外的页面元素不受影响）
+      const rect = this.canvas.getBoundingClientRect()
+      const x = e.clientX
+      const y = e.clientY
+      if (x < rect.left || x > rect.right || y < rect.top || y > rect.bottom) return
+      let hits = []
+      try {
+        if (this.model.hitTest && this._hasHitAreas) {
+          // model.hitTest 接收 PIXI 全局坐标：以 canvas 左上角为原点，单位是
+          // 画布实际像素（CSS 像素 × devicePixelRatio）。因此要把视口坐标先减去
+          // canvas 边界偏移，再乘上 renderer.width/rect.width 换算系数，否则
+          // 高分屏/缩放画布或模型后，命中区域不会跟随模型的视觉位置。
+          const ratioX = this.app && rect.width > 0 ? this.app.renderer.width / rect.width : 1
+          const ratioY = this.app && rect.height > 0 ? this.app.renderer.height / rect.height : 1
+          const gx = (x - rect.left) * ratioX
+          const gy = (y - rect.top) * ratioY
+          hits = this.model.hitTest(gx, gy) || []
         }
       } catch {}
+      // 命中 hit area 则触发 Tap 动画；点击本身仍然原生穿透给页面下层
+      for (const area of hits) {
+        this.triggerMotion('Tap' + area)
+      }
     }
 
     // ── 动画控制 ──────────────────────────────────────────────────────
@@ -503,35 +837,250 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     async playAnimation(stateName) {
       if (!this.model) return
 
+      // 记录当前 DSH 状态（时间映射仅在空闲状态生效）
+      this.currentStateName = stateName
+
       const modelList = getConfig()
       const modelEntry = modelList.models[this.currentModelIndex]
       if (!modelEntry || !modelEntry.animations) return
 
+      // 空闲状态：时间映射优先——当前时间命中某时间段时，播放该时间段的动画
+      if (stateName === 'IDLE') {
+        // 首开会话“仅播欢迎”：完全不触发时间映射
+        if (this._firstOpenSuppressing) { return }
+        // 首开页面欢迎待确认期：暂不抢触发时间映射，等欢迎状态决定
+        if (this._welcomePending) { return }
+        const mappings = this.getTimeMappings()
+        const idx = this.findActiveTimeMapping(mappings)
+        if (idx >= 0) {
+          // 音频未解锁（页面加载期、早于任意用户手势）：时间映射语音会被自动播放策略
+          // 静音，故整体推迟，先不播；记录命中下标，待首次手势解锁后由 checkTimeMappings 补播
+          // （动作+语音一同出声）。已解锁则直接播，并记录命中下标。
+          if (!_audioUnlocked) {
+            this._activeTimeMapping = idx
+            this._timeMappingDeferred = true
+            return
+          }
+          const played = await this._applyAnimConfig(mappings[idx].animation, 'timemapping')
+          if (played) this._activeTimeMapping = idx
+          return
+        }
+        this._activeTimeMapping = -1
+      } else {
+        // 非空闲状态：清除时间映射（DSH 状态动画优先）
+        this._activeTimeMapping = -1
+      }
+
       const anim = modelEntry.animations[stateName]
-      if (!anim) return
+      await this._applyAnimConfig(anim, stateName)
+    }
 
-      // 切换状态：先清除旧的循环状态（避免重启已停止的动作），再据本状态是否循环设定
-      this._loopState = null
+    // 播放“自动动画”动作（欢迎 / 时间映射）。这类动画在页面加载期即触发，
+    // 早于任意用户手势；音频尚未解锁时直接播放会被自动播放策略静音，故推迟到
+    // 首次用户手势解锁后再播，确保动作与语音一同出现。已解锁则直接播。
+    // 来自用户主动交互的状态（点击/状态切换）不在其列，它们本就发生在手势之后。
+    async playAutoMotion(group, index, reason) {
+      if (!this.model) return false
+      if (_audioUnlocked) {
+        // 已解锁：直接播
+        await this.triggerMotion(group, index, reason)
+        return true
+      }
+      // 未解锁：记录待补播目标，等首次用户手势后播放。
+      // 注意：不能覆盖已排队的 'welcome' —— 首开时欢迎先入队，随后状态动画
+      // （THINKING/IDLE 等）也会走到这里，若直接赋值会把欢迎目标冲掉，
+      // 导致手势后播放的是时间映射而不是欢迎。
+      if (_deferredAuto !== 'welcome') _deferredAuto = 'timemapping'
+      return false
+    }
 
-      // 循环播放状态：记录当前动作，ticker 检测到动作播完时自动重启
-      if (anim.loop === true && anim.motion) {
-        this._loopState = {
-          group: anim.motion.group,
-          index: typeof anim.motion.index === 'number' ? anim.motion.index : null,
-        }
+    // 当前模型是否“真正配置了可播的欢迎动画”：WELCOME 必须存在且含有效 motion.group
+    // 或 expression。空对象 / 缺字段的残留配置一律算“未设置”，首开会照常触发时间映射。
+    hasEffectiveWelcome() {
+      const cfg = getConfig()
+      const me = cfg && cfg.models && cfg.models[this.currentModelIndex]
+      const w = me && me.animations ? me.animations.WELCOME : null
+      if (!w || typeof w !== 'object') return false
+      const motionOk = !!(w.motion && typeof w.motion.group === 'string' && w.motion.group.length > 0)
+      const exprOk = !!(w.expression && typeof w.expression === 'string' && w.expression.length > 0)
+      return motionOk || exprOk
+    }
+
+    // 首开页面优先播放欢迎状态：使加载期命中的“时间映射”让位给欢迎动画
+    // （避免两者抢触发）。音频未解锁时整段（动作+语音）推迟到首次用户手势后再播；
+    // 已解锁则立即播放。欢迎动作（非循环）播放完毕后，自动把状态交回 IDLE，
+    // 由时间映射接管。
+    async playWelcomeFirstOpen() {
+      const modelList = getConfig()
+      const modelEntry = modelList.models[this.currentModelIndex]
+      // 仅当 WELCOME 配置“有效可播”时才视为有欢迎动画；空/残留配置按无处理
+      const anim = this.hasEffectiveWelcome() && modelEntry && modelEntry.animations ? modelEntry.animations.WELCOME : null
+      // 进入欢迎优先期：挂起时间映射，直到欢迎结束
+      this._welcomePending = true
+      // 记录“本次会话已播欢迎”，刷新不会再触发（会话关闭后清除，重开复现首开）
+      try { window.sessionStorage.setItem('dsh-live2d-welcomed', '1') } catch (e) {}
+      if (!anim || _audioUnlocked) {
+        // 无有效欢迎动画 / 音频已解锁：立即播放（欢迎优先于加载期的时间映射）
+        await this._playWelcomeNow()
+        return
       }
+      // 音频未解锁：整段欢迎（动作+语音）延迟到首次用户手势后播放；欢迎优先
+      // 于时间映射，故直接覆盖其待播目标，并丢弃被推迟的时间映射（欢迎优先）。
+      _deferredAuto = 'welcome'
+      this._timeMappingDeferred = false
+    }
+
+    async _playWelcomeNow() {
+      this._welcomePlayed = true
+      // 用与判定一致的严格口径：空/缺字段的残留 WELCOME 配置视为“无欢迎动画”，
+      // 避免空 {} 被当成有动画而进入只播欢迎分支（导致时间映射也被抑制、啥都不播）。
+      const anim = this.hasEffectiveWelcome() ? (() => {
+        const cfg = getConfig()
+        const me = cfg && cfg.models && cfg.models[this.currentModelIndex]
+        return me && me.animations ? me.animations.WELCOME : null
+      })() : null
+      if (!anim) {
+        // 无有效欢迎动画（如 DeepSeek / 空配置）：优先期结束，交回 IDLE，让时间映射接管
+        this._firstOpenSuppressing = false
+        this._welcomePlayed = false
+        this._welcomePending = false
+        this.currentStateName = 'IDLE'
+        this.checkTimeMappings()
+        return
+      }
+      this.currentStateName = 'WELCOME'
+      // 若欢迎配置只写了 group 没写 index（如 { motion: { group: 'Start' } }），
+      // 默认取第 0 个动作（确定播放，而非整组随机）。
+      let welcomeAnim = anim
+      if (anim.motion && typeof anim.motion.group === 'string' && typeof anim.motion.index !== 'number') {
+        welcomeAnim = { ...anim, motion: { ...anim.motion, index: 0 } }
+      }
+      try {
+        await this._applyAnimConfig(welcomeAnim, 'welcome')
+      } catch {}
+      // 有欢迎动画：首开【只播欢迎】，时间映射全程抑制，停留结束后不再交回时间映射
+      // （_firstOpenSuppressing 保持 true，ticker 与手动调用都不会播时间映射）。刷新页面后
+      // JS 上下文重置且 sessionStorage 已有 welcomed 标记，isFirstOpen=false，不再抑制。
+    }
+
+    // 应用一份动画配置（motion/expression/loop），供状态动画与时间映射共用
+    async _applyAnimConfig(anim, reason) {
+      if (!anim) return
+
+      // 切换状态：先清除旧的循环状态（避免 ticker 继续重启上一个动作）
+      this._loopState = null
 
       if (anim.motion) {
+        // 有动作：记录循环状态（ticker 检测到动作播完时自动重启）
+        if (anim.loop === true) {
+          this._loopState = {
+            group: anim.motion.group,
+            index: typeof anim.motion.index === 'number' ? anim.motion.index : null,
+          }
+        }
         // 支持整组动画：未指定 index 时随机播放组内一个 motion
         if (typeof anim.motion.index === 'number') {
-          await this.triggerMotion(anim.motion.group, anim.motion.index)
-        } else {
-          await this.triggerMotionGroup(anim.motion.group)
+          return await this.playAutoMotion(anim.motion.group, anim.motion.index, reason)
         }
+        await this.triggerMotionGroup(anim.motion.group, reason)
+      } else {
+        // 本状态【没有动作、只有表情】（如 SUCCESS: { expression: 'happy' }）：
+        // 必须显式停掉上一个动作，否则上一个状态若在循环播放（如 SPEAKING loop），
+        // 其动作会继续播放，表现为「已切到完成状态但对话动作还在动」。
+        this._stopCurrentMotion()
       }
       if (anim.expression) {
         this.triggerExpression(anim.expression)
       }
+      return true
+    }
+
+    // ── 时间映射 ──────────────────────────────────────────────────────
+
+    // 当前模型的时间映射列表：[{ start: 'HH:MM', end: 'HH:MM', animation: {...} }]
+    getTimeMappings() {
+      const modelList = getConfig()
+      const modelEntry = modelList.models[this.currentModelIndex]
+      return modelEntry && Array.isArray(modelEntry.timeMappings) ? modelEntry.timeMappings : []
+    }
+
+    // "HH:MM" → 分钟数；非法返回 null
+    // 结果按字符串缓存（"HH:MM" 取值有限），避免 ticker 每轮对同一时间段重复正则解析。
+    _parseTimeToMinutes(str) {
+      if (!str || typeof str !== 'string') return null
+      if (_timeParseCache.has(str)) return _timeParseCache.get(str)
+      const m = str.match(/^(\d{1,2}):(\d{2})$/)
+      let result = null
+      if (m) {
+        const h = parseInt(m[1], 10)
+        const min = parseInt(m[2], 10)
+        if (!isNaN(h) && !isNaN(min) && h <= 23 && min <= 59) result = h * 60 + min
+      }
+      _timeParseCache.set(str, result)
+      return result
+    }
+
+    // 当前时间（分钟数）是否落在映射的时间段内；支持跨午夜（如 22:00–06:00）
+    _timeInRange(mapping, minutes) {
+      const start = this._parseTimeToMinutes(mapping && mapping.start)
+      const end = this._parseTimeToMinutes(mapping && mapping.end)
+      if (start === null || end === null) return false
+      if (start <= end) return minutes >= start && minutes <= end
+      // 跨午夜：22:00–06:00 → 22:00≤t 或 t≤06:00
+      return minutes >= start || minutes <= end
+    }
+
+    // 返回当前命中的时间映射下标；未命中返回 -1
+    findActiveTimeMapping(mappings) {
+      if (!Array.isArray(mappings) || mappings.length === 0) return -1
+      const now = new Date()
+      const minutes = now.getHours() * 60 + now.getMinutes()
+      for (let i = 0; i < mappings.length; i++) {
+        if (this._timeInRange(mappings[i], minutes)) return i
+      }
+      return -1
+    }
+
+    // ticker 周期性调用：空闲状态下，时间进入/离开时间段时自动切换对应动画
+    async checkTimeMappings() {
+      if (!this.model) return
+      // 首开会话：仅播欢迎，完全抑制时间映射（刷新后 _firstOpenSuppressing 为 false，照常）
+      if (this._firstOpenSuppressing) {
+        this._activeTimeMapping = -1
+        this._timeMappingDeferred = false
+        return
+      }
+      // 首开欢迎优先期：等待确认及欢迎动作播完前，不抢触发时间映射
+      if (this._welcomePending || this._welcomePlayed) return
+      // 非空闲状态不参与时间映射（DSH 状态动画优先），且清除已命中的映射
+      if (this.currentStateName !== 'IDLE') {
+        if (this._activeTimeMapping !== -1) this._activeTimeMapping = -1
+        this._timeMappingDeferred = false
+        return
+      }
+      const mappings = this.getTimeMappings()
+      const idx = this.findActiveTimeMapping(mappings)
+      // 已处于该时间段且非“待补播”状态时跳过，避免重复触发
+      if (idx === this._activeTimeMapping && !this._timeMappingDeferred) return
+      this._activeTimeMapping = idx
+      this._timeMappingDeferred = false
+      if (idx >= 0) {
+        // 音频尚未解锁（早于任意用户手势）时，时间映射语音会被自动播放策略静音，
+        // 故整体推迟——记录命中下标，待首次手势解锁后由 unlockAudioOnce 补播（动作+语音一同出声）。
+        if (!_audioUnlocked) {
+          if (this._timeMappingDeferred && this._activeTimeMapping === idx) return
+          this._activeTimeMapping = idx
+          this._timeMappingDeferred = true
+          return
+        }
+        await this._applyAnimConfig(mappings[idx].animation, 'timemapping')
+      } else {
+        // 离开时间段：恢复默认空闲动画
+        const modelList = getConfig()
+        const modelEntry = modelList.models[this.currentModelIndex]
+        const idleAnim = modelEntry && modelEntry.animations ? modelEntry.animations.IDLE : null
+        await this._applyAnimConfig(idleAnim, 'idle')
+      }
     }
 
     // 强制切换：先停止当前正在播放的 motion（含循环中的），再播放新的，避免动画叠加
@@ -546,7 +1095,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     }
 
     // 随机播放某个 motion 组里的一个动作（loop 模式会锁定该 index 持续循环）
-    async triggerMotionGroup(group) {
+    async triggerMotionGroup(group, reason) {
       if (!this.model || !group) return
       try {
         const defs = this.model.internalModel.motionManager.definitions[group] || []
@@ -554,17 +1103,17 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         const index = Math.floor(Math.random() * defs.length)
         // 若处于循环状态且未指定具体 index，锁定本次随机到的 index
         if (this._loopState && this._loopState.index === null) this._loopState.index = index
-        await this.triggerMotion(group, index)
+        await this.triggerMotion(group, index, reason)
       } catch {}
     }
 
-    async triggerMotion(group, index) {
+    async triggerMotion(group, index, reason) {
       if (!this.model) return
       // 强制切换掉正在播放的动画（含循环中的）
       this._stopCurrentMotion()
       try {
         await this.model.motion(group, index)
-      } catch {}
+      } catch (e) {}
     }
 
     triggerExpression(expressionName) {
@@ -637,16 +1186,18 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       await this.loadModel(modelIndex, 0)
       // 持久化当前模型，刷新后保持
       saveActiveModelIndex(modelIndex)
+      // 用户主动切换模型：结束首开“仅播欢迎”抑制，让新模型的时间映射正常生效
+      // （否则在首开窗口内切模型会一直不播时间映射，直到刷新）
+      this._firstOpenSuppressing = false
+      this._welcomePending = false
       this.playAnimation('IDLE')
     }
 
-    getCurrentScale() {
-      const modelList = getConfig()
-      const modelEntry = modelList.models[this.currentModelIndex]
-      return modelEntry && modelEntry.config ? modelEntry.config.scaleX || 1 : 1
-    }
-
     destroy() {
+      if (this._onCanvasClick) {
+        try { document.removeEventListener('click', this._onCanvasClick, true) } catch {}
+        this._onCanvasClick = null
+      }
       if (this._onPointerMove) {
         window.removeEventListener('mousemove', this._onPointerMove)
         this._onPointerMove = null
@@ -673,14 +1224,20 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       modelList.eyeFollow = this.eyeFollow
       saveConfig(modelList)
     }
+
+    // 设置点击命中区域（hit area）开关（保存到全局配置并在引擎中生效）
+    setHitArea(enabled) {
+      this.hitArea = !!enabled
+      const modelList = getConfig()
+      modelList.hitArea = this.hitArea
+      saveConfig(modelList)
+    }
   }
 
   // ══════════════════════════════════════════════════════════════════════
   //  拖动系统
   // ══════════════════════════════════════════════════════════════════════
-
-  // 超过这个像素位移才算拖动（避免手抖把点击误判成拖动）
-  const DRAG_THRESHOLD = 4
+  //  （源码分片：拖动移动与画布大小/控制浮层位置维护）
 
   /**
    * 把归一化位置写回容器。
@@ -733,6 +1290,9 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     const saved = getPosition()
     if (saved && Number.isFinite(saved.x) && Number.isFinite(saved.y)) {
       place(containerEl, saved.x, saved.y)
+    } else {
+      // 无本地存档时使用默认位置
+      place(containerEl, DEFAULT_POSITION.x, DEFAULT_POSITION.y)
     }
 
     const finish = () => {
@@ -740,6 +1300,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         try { handleEl.releasePointerCapture(pointerId) } catch {}
       }
       if (dragging) containerEl.classList.remove('dragging')
+      containerEl.classList.remove('interacting')
       pointerId = null
       dragging = false
     }
@@ -763,6 +1324,8 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       curX = origX
       curY = origY
       containerEl.classList.add('dragging')
+      // 拖拽中锁定控制浮层显示（见主组件的 mousemove 命中检测）
+      containerEl.classList.add('interacting')
       // 捕获指针：拖出容器甚至拖出窗口也不断流
       try { handleEl.setPointerCapture(pointerId) } catch {}
     }
@@ -815,10 +1378,66 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
   // ══════════════════════════════════════════════════════════════════════
   //  DSH 状态检测（轮询 host 端点）
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：DSH 状态订阅：SSE 实时推送 + 轮询兜底）
+  //
+  // 注意：状态必须以「事件」而非「渲染快照」的形式驱动动画。
+  // 若用 useState + useEffect([dshState]) 观察状态，当 SSE 在同一个事件循环里
+  // 连续推送多个状态（例如 THINKING→SPEAKING→SUCCESS），React 18 的自动批处理
+  // 会把多次 setState 合并成一次渲染，useEffect 只能看到最后一个值，中间的
+  // SPEAKING 被丢弃 —— 这正是「输出对话动画不播放」的原因。
+  // 因此这里维护一个有序队列 + 订阅者：每个状态值都会按到达顺序通知一次。
+
+  function createStateFeed() {
+    const listeners = new Set()
+    // 上次推送的状态值，用于忽略重复推送（SSE 重连/轮询回显去重）
+    let lastRaw = null
+    let queue = []
+    let draining = false
+
+    const emit = (state) => {
+      queue.push(state)
+      drain()
+    }
+
+    const drain = () => {
+      if (draining) return
+      draining = true
+      try {
+        while (queue.length > 0) {
+          const state = queue.shift()
+          for (const fn of listeners) {
+            try { fn(state) } catch (e) {}
+          }
+        }
+      } finally {
+        draining = false
+      }
+    }
+
+    return {
+      /** 推送一个状态；与“上一条原始推送”相同则忽略（SSE 重连/轮询回显去重）。 */
+      push(state) {
+        if (!state || state === lastRaw) return
+        lastRaw = state
+        emit(state)
+      },
+      /** 订阅状态变化，返回取消订阅函数。订阅时会立即收到当前状态。 */
+      subscribe(fn) {
+        listeners.add(fn)
+        if (lastRaw) { try { fn(lastRaw) } catch (e) {} }
+        return () => { listeners.delete(fn) }
+      },
+      get current() { return lastRaw },
+      /** SSE 重连后允许重复推送同一状态（重新对齐） */
+      reset() { lastRaw = null },
+    }
+  }
 
   function useStateDetector() {
-    const [dshState, setDshState] = useState(DSHState.IDLE)
-    const pollTimerRef = useRef(null)
+    // feed 在组件生命周期内保持稳定
+    const feedRef = useRef(null)
+    if (!feedRef.current) feedRef.current = createStateFeed()
+    const feed = feedRef.current
 
     useEffect(() => {
       // 优先使用 SSE 实时推送，状态一变更前端立即收到，消除动画触发延迟
@@ -826,15 +1445,13 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       let fallbackTimer = null
       let closed = false
 
-      const apply = (state) => { if (state) setDshState(state) }
-
       // 兜底：先立即拉一次，防止 SSE 连接前错过初始状态
       const bootstrap = async () => {
         try {
           const res = await fetch('/plugins/dsh-live2d/state', { cache: 'no-store' })
           if (res.ok) {
             const data = await res.json()
-            if (data.state) setDshState(data.state)
+            if (data.state) feed.push(data.state)
           }
         } catch {}
       }
@@ -842,10 +1459,14 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
 
       try {
         es = new EventSource('/plugins/dsh-live2d/state/stream')
+        es.onopen = () => {
+          // 重连后允许重新接收与上次相同的状态
+          feed.reset()
+        }
         es.onmessage = (ev) => {
           try {
             const data = JSON.parse(ev.data)
-            if (data.state) apply(data.state)
+            if (data.state) feed.push(data.state)
           } catch {}
         }
         es.onerror = () => {
@@ -864,12 +1485,13 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       }
     }, [])
 
-    return dshState
+    return feed
   }
 
   // ══════════════════════════════════════════════════════════════════════
   //  主组件
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：主组件：画布挂载、拖拽/缩放交互、画布悬浮控制图标）
 
   function Live2DWidget() {
     const containerRef = useRef(null)
@@ -878,7 +1500,9 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     const engineRef = useRef(null)
     const cleanupDragRef = useRef(null)
     const lastStateRef = useRef(DSHState.IDLE)
-    const dshState = useStateDetector()
+    // 状态以事件流方式消费（见 60-state.js 的说明）：不能依赖 React 渲染快照，
+    // 否则同一批次里连续到达的多个状态会被批处理合并、中间状态丢失。
+    const stateFeed = useStateDetector()
 
     // 初始化 Live2D
     useEffect(() => {
@@ -904,15 +1528,78 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         engine.setEyeFollow(enabled)
       }
 
+      // 暴露点击命中区域开关接口给设置页
+      window.__dshLive2DEngineSetHitArea = function(enabled) {
+        engine.setHitArea(enabled)
+      }
+
       engine.init(containerRef.current).then((ok) => {
         if (ok) {
-          engine.playAnimation('IDLE')
           updateControls(containerRef.current, controlsRef.current)
+          // 首开判定：按“浏览器会话”而非 DSH 进程全局。sessionStorage 在关闭标签页后
+          // 清除、刷新仍在，故“首开/重新打开”会优先播放欢迎（并压过加载期命中的时间映射），
+          // 刷新页面不会重复播放欢迎。这样本地预览反复测试都能复现首开行为。
+          let isFirstOpen = false
+          try {
+            isFirstOpen = !window.sessionStorage.getItem('dsh-live2d-welcomed')
+          } catch (e) { isFirstOpen = true }
+          if (isFirstOpen) {
+            // 进入欢迎优先期：临时挂起时间映射，先把欢迎播出来（含语音）。
+            engine._welcomePending = true
+            // 首开会话抑制时间映射的前提：本模型确实配置了【可播】的欢迎动画。
+            // 有有效欢迎动画 → 首开【只播欢迎】，时间映射全程抑制（直到刷新才恢复）；
+            // 无欢迎动画（空配置/未设置，如 DeepSeek）→ 不抑制，首开照常触发满足条件的时间映射（带声音）。
+            const hasWelcome = engine.hasEffectiveWelcome()
+            engine._firstOpenSuppressing = hasWelcome
+            engine.playWelcomeFirstOpen()
+          } else {
+            // 非首开（已播过欢迎）：直接以 IDLE 进入，时间映射照常接管。
+            engine._welcomePending = false
+            engine.playAnimation('IDLE')
+          }
+          // 引擎就绪前到达的状态会被 state-feed 跳过，这里用当前值重新对齐一次
+          const cur = stateFeed.current
+          if (cur && cur !== DSHState.IDLE) {
+            const prev = lastStateRef.current
+            lastStateRef.current = cur
+            const run = async () => {
+              if (prev === DSHState.THINKING && cur !== DSHState.THINKING) {
+                await engine.playAnimation('THINK_END')
+              }
+              await engine.playAnimation(cur)
+            }
+            run()
+          }
         }
       })
 
       cleanupDragRef.current = setupDrag(dragHandleRef.current, containerRef.current, controlsRef.current)
 
+      // 控制浮层（画布大小/拖拽图标）仅在鼠标位于 Live2D 画布上方时显示。
+      // 由于容器与 canvas 都是 pointer-events:none（点击穿透不能动），CSS :hover 无法触发，
+      // 故用全局 mousemove 命中检测画布矩形；拖拽/缩放进行中时锁定显示，避免图标中途消失。
+      const containerEl = containerRef.current
+      const controlsEl = controlsRef.current
+      let hoverRAF = 0
+      const onMouseMove = (e) => {
+        if (hoverRAF) return
+        hoverRAF = window.requestAnimationFrame(() => {
+          hoverRAF = 0
+          // engine.canvas 即画布 DOM 元素本身（见 onResizePointerDown 的用法）
+          const canvasEl = engine.canvas
+          // 画布位于 container 内部，以其实际显示矩形判定鼠标是否悬停其上
+          const rect = (canvasEl || containerEl).getBoundingClientRect()
+          const inside =
+            e.clientX >= rect.left && e.clientX <= rect.right &&
+            e.clientY >= rect.top && e.clientY <= rect.bottom
+          // 拖拽/缩放进行中锁定显示，避免图标中途消失导致操作中断
+          const locked = containerEl.classList.contains('interacting')
+          if (inside || locked) controlsEl.classList.add('show')
+          else controlsEl.classList.remove('show')
+        })
+      }
+      window.addEventListener('mousemove', onMouseMove, true)
+
       // 窗口尺寸变化时把图标夹回视口内（画布可能因此相对移出屏幕）
       const onResize = () => updateControls(containerRef.current, controlsRef.current)
       window.addEventListener('resize', onResize)
@@ -920,30 +1607,70 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       return () => {
         cleanupDragRef.current?.()
         window.removeEventListener('resize', onResize)
+        window.removeEventListener('mousemove', onMouseMove, true)
+        if (hoverRAF) window.cancelAnimationFrame(hoverRAF)
         engine.destroy()
       }
     }, [])
 
-    // 响应 DSH 状态变化，播放动画
+    // 订阅 DSH 状态事件流，按到达顺序播放动画（每个状态都不会被丢弃）。
+    // 关键：这里用订阅而不是 useEffect([dshState]) —— 后者在 React 批处理下只会
+    // 看到最后一个状态，像 THINKING→SPEAKING→SUCCESS 这种连发会丢掉 SPEAKING。
     useEffect(() => {
-      const engine = engineRef.current
-      if (!engine || !engine.ready) return
-
-      const prevState = lastStateRef.current
-      const newState = dshState
-
-      // 思考结束检测：THINKING → 非 THINKING = THINK_END
-      if (prevState === DSHState.THINKING && newState !== DSHState.THINKING) {
-        engine.playAnimation('THINK_END')
+      // 串行化播放：状态连发时按队列顺序逐个 await，避免并发 playAnimation
+      // 互相 _stopCurrentMotion() 把对方掐掉。
+      let chain = Promise.resolve()
+      let disposed = false
+      const enqueue = (task) => {
+        chain = chain.then(async () => {
+          if (disposed) return
+          await task()
+        }).catch(() => {})
       }
 
-      // 播放当前状态的动画
-      if (newState !== prevState) {
-        engine.playAnimation(newState)
-      }
+      // 关键：状态一到就尽快播放（尤其是正文开始时的 SPEAKING），不能为了「补足
+      // 上一个状态的展示时间」而推迟新状态的开始 —— 那会导致 SPEAKING 要等
+      // THINKING 的展示窗口结束才开始，看起来像是「正文都输出完了才触发」。
+      // 正确做法：立即切到新状态；仅当上一个状态被顶得过快（< MIN_DWELL_MS）时，
+      // 在【切换之前】做一次短暂等待来兜底极短状态，正常交互几乎不触发。
+      const MIN_DWELL_MS = 500
+      const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+      // 状态变更序号（每次到达 +1）与「上一个已播放状态」的序号/开始时间，
+      // 用于判断上一个状态是否被快速顶掉（仅在极短状态时兜底等待）。
+      let stateSeq = 0
+      let shownSeq = -1
+      let shownAt = 0
+
+      const unsubscribe = stateFeed.subscribe((newState) => {
+        const engine = engineRef.current
+        if (!engine || !engine.ready) return
+        const prevState = lastStateRef.current
+        if (newState === prevState) return
+        lastStateRef.current = newState
+        stateSeq += 1
+        const mySeq = stateSeq
+
+        enqueue(async () => {
+          // 已播放的状态若展示不足最短时长、且它确实被本次新状态顶掉，
+          // 先补足它（避免「闪现即消失」）。注意：这里等待的是【被顶掉的上一个】，
+          // 不会推迟真正需要立即呈现的 SPEAKING 之前的 THINKING —— 因为 THINKING
+          // 如已展示足够久（思考通常远长于该阈值）则无需等待。
+          if (shownSeq !== -1 && shownSeq !== mySeq) {
+            const elapsed = Date.now() - shownAt
+            if (elapsed < MIN_DWELL_MS) await sleep(MIN_DWELL_MS - elapsed)
+          }
+          // 思考结束过渡：THINKING → 非 THINKING 时先播一次 THINK_END，再进入新状态
+          if (prevState === DSHState.THINKING && newState !== DSHState.THINKING) {
+            await engine.playAnimation('THINK_END')
+          }
+          shownSeq = mySeq
+          shownAt = Date.now()
+          await engine.playAnimation(newState)
+        })
+      })
 
-      lastStateRef.current = newState
-    }, [dshState])
+      return () => { disposed = true; unsubscribe() }
+    }, [stateFeed])
 
     // 滚轮缩放：调整模型 scaleX/scaleY
     const onWheel = useCallback((e) => {
@@ -975,6 +1702,8 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
       const pointerId = e.pointerId
 
       try { e.currentTarget.setPointerCapture(pointerId) } catch {}
+      // 缩放中锁定控制浮层显示（见主组件的 mousemove 命中检测）
+      containerEl.classList.add('interacting')
 
       const move = (ev) => {
         if (ev.pointerId !== pointerId) return
@@ -993,6 +1722,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         window.removeEventListener('pointermove', move)
         window.removeEventListener('pointerup', up)
         window.removeEventListener('pointercancel', up)
+        containerEl.classList.remove('interacting')
         // 松手后把图标夹回视口内（静止状态始终留在网页可见区域）。
         updateControls(containerEl, controlsRef.current, true)
       }
@@ -1004,10 +1734,9 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     return h('div', {
       ref: containerRef,
       id: 'dsh-live2d-container',
-      onWheel: onWheel,
     },
-      // 控制浮层：固定钉在视口右下角，独立于画布。画布可以拖出屏幕，
-      // 但这两个图标始终留在页面内可见可点。
+      // 控制浮层：固定钉在视口右下角，独立于画布。默认隐藏，仅当鼠标悬停在
+      // Live2D 画布上方时才显示（由主组件的 mousemove 命中检测切换 .show）。
       h('div', {
         ref: controlsRef,
         id: 'dsh-live2d-controls',
@@ -1018,11 +1747,13 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
           title: '拖动改变画布大小',
           onPointerDown: onResizePointerDown,
         }),
-        // 拖拽移动图标：只有拖动它才能移动整个看板娘
+        // 拖拽移动图标：只有拖动它才能移动整个看板娘；
+        // 鼠标滚轮也只在这个图标上缩放模型（画布/其他区域不再触发缩放）。
         h('div', {
           ref: dragHandleRef,
           className: 'dsh-live2d-drag',
           title: '拖动移动看板娘；鼠标滚轮缩放模型大小',
+          onWheel: onWheel,
         }, '✥'),
       ),
     )
@@ -1031,6 +1762,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
   // ══════════════════════════════════════════════════════════════════════
   //  设置页组件
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：设置页组件：模型目录、动画映射、时间映射、通用开关）
 
   const cardStyle = {
     listStyle: 'none',
@@ -1108,9 +1840,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         var models = (Array.isArray(prev.models) ? prev.models : []).slice()
         if (!models[modelIdx]) models[modelIdx] = {}
         models[modelIdx] = Object.assign({}, models[modelIdx], patch)
-        var next = Object.assign({}, prev, { models: models })
-        saveConfig(next)
-        return next
+        return Object.assign({}, prev, { models: models })
       })
     }, [])
 
@@ -1123,19 +1853,55 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
         anims[stateName] = animConfig
         model.animations = anims
         models[modelIdx] = model
-        var next = Object.assign({}, prev, { models: models })
-        saveConfig(next)
-        return next
+        return Object.assign({}, prev, { models: models })
       })
     }, [])
 
-    // 修改动画映射时同步强制切换掉正在播放的动画（若修改的是当前激活模型）
-    const updateAnimationWithForceSwitch = useCallback(function(modelIdx, stateName, animConfig) {
-      updateAnimation(modelIdx, stateName, animConfig)
-      if (modelIdx === activeModel && window.__dshLive2DEngineForceSwitch) {
-        window.__dshLive2DEngineForceSwitch(stateName)
-      }
-    }, [activeModel, updateAnimation])
+    // 修改动画映射：仅保存配置，不触发任何播放（避免编辑下拉框时误播一次被修改的动作）。
+    // 真正的生效发生在下次状态切换 / 时间映射命中 / 首开时，无需即时预览。
+
+    // 更新某条时间映射（时间段 + 动画配置）
+    const updateTimeMapping = useCallback(function(modelIdx, tmIndex, patch) {
+      setCfg(function(prev) {
+        var models = (Array.isArray(prev.models) ? prev.models : []).slice()
+        if (!models[modelIdx]) models[modelIdx] = {}
+        var model = Object.assign({}, models[modelIdx])
+        var tms = (Array.isArray(model.timeMappings) ? model.timeMappings : []).slice()
+        if (!tms[tmIndex]) tms[tmIndex] = {}
+        tms[tmIndex] = Object.assign({}, tms[tmIndex], patch)
+        model.timeMappings = tms
+        models[modelIdx] = model
+        return Object.assign({}, prev, { models: models })
+      })
+    }, [])
+
+    // 新增一条时间映射（默认 08:00–12:00，动作组留空）
+    const addTimeMapping = useCallback(function(modelIdx) {
+      setCfg(function(prev) {
+        var models = (Array.isArray(prev.models) ? prev.models : []).slice()
+        if (!models[modelIdx]) models[modelIdx] = {}
+        var model = Object.assign({}, models[modelIdx])
+        var tms = (Array.isArray(model.timeMappings) ? model.timeMappings : []).slice()
+        tms.push({ start: '08:00', end: '12:00', animation: { motion: { group: '' } } })
+        model.timeMappings = tms
+        models[modelIdx] = model
+        return Object.assign({}, prev, { models: models })
+      })
+    }, [])
+
+    // 删除一条时间映射
+    const removeTimeMapping = useCallback(function(modelIdx, tmIndex) {
+      setCfg(function(prev) {
+        var models = (Array.isArray(prev.models) ? prev.models : []).slice()
+        if (!models[modelIdx]) return prev
+        var model = Object.assign({}, models[modelIdx])
+        var tms = (Array.isArray(model.timeMappings) ? model.timeMappings : []).slice()
+        tms.splice(tmIndex, 1)
+        model.timeMappings = tms
+        models[modelIdx] = model
+        return Object.assign({}, prev, { models: models })
+      })
+    }, [])
 
     // 从 model3.json 解析动作组/数量/动作名/表情（host 未提供时的兜底，无感刷新，无按钮）
     const enrichFromModel3 = function(url) {
@@ -1198,10 +1964,11 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
                 expressions: Array.isArray(h.expressions) ? h.expressions : [],
                 // 动画映射：合并用户已有配置与内置默认映射——用户缺失的状态（如新增的 SPEAKING）自动补全，用户已有的仍优先
                 animations: Object.assign({}, h.animations || {}, ex.animations || {}),
+                // 时间映射：保留用户已配置的时间段映射（重新扫描不丢失）
+                timeMappings: Array.isArray(ex.timeMappings) ? ex.timeMappings : [],
               }
             })
             var next = Object.assign({}, prev, { models: merged })
-            saveConfig(next)
             return next
           })
           // 兜底：若 host 未返回 groupMotions（旧版接口/缓存），自行拉取 model3.json 补全
@@ -1213,15 +1980,11 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
                 var prevModels = Array.isArray(prev.models) ? prev.models : []
                 var models = prevModels.map(function(m) {
                   if (m.name !== h.name) return m
-                  var merged2 = Object.assign({}, m, {
+                  return Object.assign({}, m, {
                     groups: meta.groups, groupCounts: meta.groupCounts,
                     groupMotions: meta.groupMotions, expressions: meta.expressions,
                   })
-                  var next2 = Object.assign({}, prev, { models: models.map(function(x) { return x === m ? merged2 : x }) })
-                  return next2
                 })
-                if (models === prevModels) return prev
-                saveConfig(Object.assign({}, prev, { models: models }))
                 return Object.assign({}, prev, { models: models })
               })
             })
@@ -1239,13 +2002,18 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
     // 组件挂载时自动扫描一次
     useEffect(function() { scanModels() }, [scanModels])
 
+    // 配置变化后统一持久化（debounced）：把副作用移出 setCfg 更新函数，
+    // 避免 React 严格模式下更新函数被重复调用时重复写入，也保证引擎侧读到的
+    // 内存缓存（_configCache）与设置页状态一致。
+    useEffect(function() { saveConfig(cfg) }, [cfg])
+
     var safeModels = Array.isArray(cfg.models) ? cfg.models : []
     var currentModelRaw = safeModels[activeModel] || safeModels[0] || {}
     // 保证动画映射所需字段存在（兼容扫描前的旧配置 / 尚未扫描时的占位条目）
     var currentModel = Object.assign(
-      { name: '', url: '', canvasWidth: 300, canvasHeight: 400, config: { x: 0, y: 0, scaleX: 1, scaleY: 1 }, animations: {} },
+      { name: '', url: '', canvasWidth: 300, canvasHeight: 400, config: { x: 0, y: 0, scaleX: 1, scaleY: 1 }, animations: {}, timeMappings: [] },
       currentModelRaw,
-      { groups: Array.isArray(currentModelRaw.groups) ? currentModelRaw.groups : [], groupCounts: (currentModelRaw.groupCounts && typeof currentModelRaw.groupCounts === 'object') ? currentModelRaw.groupCounts : {}, groupMotions: (currentModelRaw.groupMotions && typeof currentModelRaw.groupMotions === 'object') ? currentModelRaw.groupMotions : {}, expressions: Array.isArray(currentModelRaw.expressions) ? currentModelRaw.expressions : [] }
+      { groups: Array.isArray(currentModelRaw.groups) ? currentModelRaw.groups : [], groupCounts: (currentModelRaw.groupCounts && typeof currentModelRaw.groupCounts === 'object') ? currentModelRaw.groupCounts : {}, groupMotions: (currentModelRaw.groupMotions && typeof currentModelRaw.groupMotions === 'object') ? currentModelRaw.groupMotions : {}, expressions: Array.isArray(currentModelRaw.expressions) ? currentModelRaw.expressions : [], timeMappings: Array.isArray(currentModelRaw.timeMappings) ? currentModelRaw.timeMappings : [] }
     )
 
 
@@ -1260,17 +2028,32 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
             checked: !!getConfig().eyeFollow,
             onChange: function(e) {
               var enabled = e.target.checked
-              // 立即同步到引擎并持久化，同时更新 React 状态让受控复选框即时刷新
+              // 立即同步到引擎，并更新 React 状态让受控复选框即时刷新
+              // （持久化由下方 useEffect([cfg]) 统一处理）
               if (window.__dshLive2DEngineSetEyeFollow) window.__dshLive2DEngineSetEyeFollow(enabled)
               setCfg(function(prev) {
-                var next = Object.assign({}, prev, { eyeFollow: enabled })
-                saveConfig(next)
-                return next
+                return Object.assign({}, prev, { eyeFollow: enabled })
               })
             },
           }),
           '眼睛跟随鼠标（模型视线随光标移动）',
         ),
+        h('label', { style: { display: 'flex', alignItems: 'center', gap: 8, marginTop: 6, cursor: 'pointer' } },
+          h('input', {
+            type: 'checkbox',
+            checked: !!getConfig().hitArea,
+            onChange: function(e) {
+              var enabled = e.target.checked
+              // 立即同步到引擎，并更新 React 状态让受控复选框即时刷新
+              // （持久化由下方 useEffect([cfg]) 统一处理）
+              if (window.__dshLive2DEngineSetHitArea) window.__dshLive2DEngineSetHitArea(enabled)
+              setCfg(function(prev) {
+                return Object.assign({}, prev, { hitArea: enabled })
+              })
+            },
+          }),
+          '点击命中区域（点击模型 HitArea 触发 Tap 动画；关闭后点击完全穿透）',
+        ),
       ),
 
       // ── 模型目录 ──────────────────────────────────────────
@@ -1304,8 +2087,9 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
             disabled: scanning,
             style: { padding: '6px 16px', borderRadius: 8, border: '1px solid #60a5fa', background: 'rgba(96,165,250,0.15)', color: 'inherit', cursor: scanning ? 'default' : 'pointer', whiteSpace: 'nowrap' },
           }, scanning ? '扫描中…' : '刷新模型列表'),
+          // 模型扫描/操作提示：显示在「刷新模型列表」按钮右侧
+          importStatus ? h('span', { style: { color: /扫描完成|已复制|已添加|成功/.test(importStatus) ? '#4ade80' : '#f87171', fontSize: 12, whiteSpace: 'nowrap' } }, importStatus) : null,
         ),
-        importStatus ? h('p', { style: { margin: '6px 0 0', color: /扫描完成|已复制|已添加|成功/.test(importStatus) ? '#4ade80' : '#f87171', fontSize: 12 } }, importStatus) : null,
       ),
 
       // ── 模型列表 ──────────────────────────────────────────
@@ -1388,7 +2172,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
             if (loop === true || loop === false) next.loop = loop
             else if (anim.loop) next.loop = anim.loop
             if (!nextGroup && !next.motion && !selExpr && !next.loop) next = {}
-            updateAnimationWithForceSwitch(activeModel, stateName, next)
+            updateAnimation(activeModel, stateName, next)
           }
 
           return h('div', { key: stateName, style: Object.assign({}, rowStyle, { padding: '6px 0', borderBottom: '1px solid rgba(127,127,127,0.15)' }) },
@@ -1432,9 +2216,9 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
                   var val = e.target.value
                   var loop = anim.loop === true
                   if (val) {
-                    updateAnimationWithForceSwitch(activeModel, stateName, selGroup ? { motion: { group: selGroup }, expression: val, loop: loop } : { expression: val, loop: loop })
+                    updateAnimation(activeModel, stateName, selGroup ? { motion: { group: selGroup }, expression: val, loop: loop } : { expression: val, loop: loop })
                   } else {
-                    updateAnimationWithForceSwitch(activeModel, stateName, selGroup ? { motion: { group: selGroup }, loop: loop } : { loop: loop })
+                    updateAnimation(activeModel, stateName, selGroup ? { motion: { group: selGroup }, loop: loop } : { loop: loop })
                   }
                 },
                 style: Object.assign({}, inputStyle, { width: 100, fontSize: 11 }),
@@ -1455,7 +2239,7 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
                     if (selGroup) next.motion = anim.motion ? Object.assign({}, anim.motion) : { group: selGroup }
                     if (selExpr) next.expression = selExpr
                     next.loop = loop
-                    updateAnimationWithForceSwitch(activeModel, stateName, next)
+                    updateAnimation(activeModel, stateName, next)
                   },
                 }),
                 '循环',
@@ -1463,6 +2247,132 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
             ),
           )
         }),
+
+        // ── 时间映射：满足时间段条件时触发对应动画 ──────────────────────
+        h('div', { style: { marginTop: 16, paddingTop: 12, borderTop: '1px solid rgba(127,127,127,0.2)' } },
+          h('div', { style: Object.assign({}, rowStyle, { marginBottom: 6 }) },
+            h('strong', { style: { fontSize: 13 } }, '时间映射'),
+            h('button', {
+              onClick: function() { addTimeMapping(activeModel) },
+              style: { padding: '3px 14px', borderRadius: 6, fontSize: 12, cursor: 'pointer', border: '1px solid #60a5fa', background: 'rgba(96,165,250,0.15)', color: 'inherit', whiteSpace: 'nowrap' },
+            }, '+ 添加时间段'),
+          ),
+          h('p', { style: { margin: '0 0 8px', opacity: 0.65, fontSize: 12 } },
+            '设置时间段与动画：当前时间落在时间段内且模型处于空闲状态时播放对应动画，离开时间段自动恢复空闲动画。支持跨午夜（如 22:00–06:00）。'),
+          (Array.isArray(currentModel.timeMappings) && currentModel.timeMappings.length ? currentModel.timeMappings : []).map(function(tm, ti) {
+            var tAnim = (tm && tm.animation) || {}
+            var tGroup = tAnim.motion ? (tAnim.motion.group || '') : ''
+            var tIndex = (tAnim.motion && typeof tAnim.motion.index === 'number') ? String(tAnim.motion.index) : ''
+            var tExpr = tAnim.expression || ''
+            var tMotionNames = (currentModel.groupMotions && Array.isArray(currentModel.groupMotions[tGroup])) ? currentModel.groupMotions[tGroup] : []
+
+            function applyTimeAnim(next) {
+              updateTimeMapping(activeModel, ti, { animation: next })
+            }
+
+            return h('div', { key: 'tm' + ti, style: Object.assign({}, rowStyle, { padding: '6px 0', borderBottom: '1px solid rgba(127,127,127,0.15)', flexWrap: 'wrap', gap: 6 }) },
+              // 时间段：开始/结束时间上下排列
+              h('div', { style: { display: 'flex', flexDirection: 'column', gap: 3 } },
+                h('input', {
+                  type: 'time',
+                  value: tm && tm.start ? tm.start : '08:00',
+                  onChange: function(e) { updateTimeMapping(activeModel, ti, { start: e.target.value }) },
+                  title: '开始时间（HH:MM）',
+                  style: Object.assign({}, inputStyle, { width: 88, fontSize: 11 }),
+                }),
+                h('input', {
+                  type: 'time',
+                  value: tm && tm.end ? tm.end : '12:00',
+                  onChange: function(e) { updateTimeMapping(activeModel, ti, { end: e.target.value }) },
+                  title: '结束时间（HH:MM）',
+                  style: Object.assign({}, inputStyle, { width: 88, fontSize: 11 }),
+                }),
+              ),
+              // 动作组下拉
+              h('select', {
+                value: tGroup,
+                onChange: function(e) {
+                  var g = e.target.value
+                  var next = {}
+                  if (g) next.motion = { group: g }
+                  if (tExpr) next.expression = tExpr
+                  if (tAnim.loop) next.loop = true
+                  applyTimeAnim(next)
+                },
+                title: '动作组',
+                style: Object.assign({}, inputStyle, { width: 100, fontSize: 11 }),
+              },
+                h('option', { value: '' }, '空'),
+                currentModel.groups.map(function(g) {
+                  return h('option', { key: g, value: g }, g)
+                }),
+              ),
+              // 组内动作下拉
+              h('select', {
+                value: tIndex,
+                disabled: !tGroup,
+                onChange: function(e) {
+                  var val = e.target.value
+                  var next = {}
+                  if (tGroup) {
+                    next.motion = { group: tGroup }
+                    if (val !== '') next.motion.index = parseInt(val, 10) || 0
+                  }
+                  if (tExpr) next.expression = tExpr
+                  if (tAnim.loop) next.loop = true
+                  applyTimeAnim(next)
+                },
+                title: '组内动作（空 = 随机整组）',
+                style: Object.assign({}, inputStyle, { width: 64, fontSize: 11 }),
+              },
+                h('option', { value: '' }, '随机'),
+                tMotionNames.map(function(name, i) {
+                  return h('option', { key: i, value: String(i) }, name)
+                }),
+              ),
+              // 表情下拉
+              h('select', {
+                value: tExpr,
+                onChange: function(e) {
+                  var val = e.target.value
+                  var next = {}
+                  if (tGroup) next.motion = tAnim.motion ? Object.assign({}, tAnim.motion) : { group: tGroup }
+                  if (val) next.expression = val
+                  if (tAnim.loop) next.loop = true
+                  applyTimeAnim(next)
+                },
+                title: '表情',
+                style: Object.assign({}, inputStyle, { width: 88, fontSize: 11 }),
+              },
+                h('option', { value: '' }, '空'),
+                currentModel.expressions.map(function(ex) {
+                  return h('option', { key: ex, value: ex }, ex)
+                }),
+              ),
+              // 循环开关
+              h('label', { style: { display: 'flex', alignItems: 'center', gap: 4, fontSize: 11, cursor: 'pointer', whiteSpace: 'nowrap' }, title: '循环播放：时间段内持续循环该动作' },
+                h('input', {
+                  type: 'checkbox',
+                  checked: tAnim.loop === true,
+                  onChange: function(e) {
+                    var next = {}
+                    if (tGroup) next.motion = tAnim.motion ? Object.assign({}, tAnim.motion) : { group: tGroup }
+                    if (tExpr) next.expression = tExpr
+                    next.loop = e.target.checked
+                    applyTimeAnim(next)
+                  },
+                }),
+                '循环',
+              ),
+              // 删除按钮
+              h('button', {
+                onClick: function() { removeTimeMapping(activeModel, ti) },
+                title: '删除该时间段',
+                style: { padding: '2px 10px', borderRadius: 6, fontSize: 11, cursor: 'pointer', border: '1px solid rgba(248,113,113,0.5)', background: 'transparent', color: 'inherit', whiteSpace: 'nowrap' },
+              }, '删除'),
+            )
+          }),
+        ),
       ) : null,
     )
   }
@@ -1470,10 +2380,17 @@ window.__ModuleLoader__.load({ id: 'dsh-live2d', factory: (require) => {
   // ══════════════════════════════════════════════════════════════════════
   //  插件入口
   // ══════════════════════════════════════════════════════════════════════
+  //  （源码分片：插件入口：向 DSH 注入 shell.overlay 与 settings.section）
 
   function apply(ctx) {
     injectCSS()
 
+    // 尽早开始预加载 Live2D 运行库（约 1MB）。
+    // apply() 由插件系统在客户端启动早期调用，而 shell.overlay 槽位要等 DSH 壳层
+    // 挂载后才渲染 —— 在那之前先并行把库拉下来，可与 DSH 自身启动重叠，
+    // 显著缩短首次打开时「看板娘空白」的等待。ensureLibsLoaded 幂等，后续调用直接复用。
+    ensureLibsLoaded().catch(function() {})
+
     // 注入 shell.overlay：渲染 Live2D 模型
     // slots.inject 的回调必须 RETURN register 返回的 disposer：
     // 它是通过 ctx.effect 安装的，不返回就等于丢弃注销函数，