@ash-qw/dsh-theme-prts 2.2.0 → 2.3.1

package/src/client/session-card-reveal.js

@@ -0,0 +1,125 @@
+// Reveal the temporarily selected card before mounting the destination conversation.
+// Keep the destination stable through unrelated reflow; retarget smoothly only when needed.
+export function createSessionCardReveal({window, root, sessionId, onDone, onStart}) {
+  let row, scroller, frame, timer, started = false, disposed = false, geometry, destination, stableSince, lastPosition
+  const findRow = () => [...root.querySelectorAll('[data-row-key], [data-session-id]')].find(el =>
+    el.getAttribute('data-row-key') === `session:${sessionId}` || el.getAttribute('data-session-id') === sessionId)
+  const instant = top => {
+    try { scroller.scrollTo({top, behavior: 'instant'}) }
+    catch { scroller.scrollTop = top }
+  }
+  function cancel() {
+    if (disposed) return
+    disposed = true
+    if (scroller && destination !== undefined) instant(scroller.scrollTop)
+    destination = undefined
+    window.cancelAnimationFrame(frame)
+    window.clearTimeout(timer)
+    resize?.disconnect()
+    mutations.disconnect()
+    root.removeEventListener('transitionend', schedule)
+    root.removeEventListener('animationend', schedule)
+    scroller?.removeEventListener('scrollend', scrollEnded)
+  }
+  function scrollEnded() {
+    if (destination !== undefined && Math.abs(scroller.scrollTop - destination) <= 1) destination = undefined
+    schedule()
+  }
+  function schedule() {
+    if (!disposed && frame === undefined) frame = window.requestAnimationFrame(() => { frame = undefined; check() })
+  }
+  function check(final = false) {
+    if (disposed) return
+    const nextRow = findRow()
+    if (!nextRow || (nextRow.getAttribute('data-prts-selection-target') !== 'true' && nextRow.getAttribute('aria-selected') !== 'true')) {
+      stableSince = undefined
+      if (started && !final) schedule()
+      return
+    }
+    const remounted = nextRow !== row
+    if (remounted) {
+      row = nextRow
+      const previousScroller = scroller
+      scroller?.removeEventListener('scrollend', scrollEnded)
+      resize?.disconnect()
+      scroller = undefined
+      for (let node = row.parentElement; node && node !== root.parentElement; node = node.parentElement) {
+        if (/^(auto|scroll)$/.test(window.getComputedStyle(node).overflowY) && node.clientHeight > 0) { scroller = node; break }
+      }
+      if (scroller !== previousScroller) destination = undefined
+      for (let node = row; node && node !== root.parentElement; node = node.parentElement) {
+        for (const animation of node.getAnimations?.() ?? []) {
+          const timing = animation.effect?.getComputedTiming?.()
+          if (animation.playState === 'running' && Number.isFinite(timing?.endTime)) animation.finished.then(schedule, schedule)
+        }
+      }
+      resize?.observe(root)
+      if (scroller) { resize?.observe(scroller); scroller.addEventListener('scrollend', scrollEnded) }
+    }
+    let settled = true
+    const first = !started
+    const reduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
+      || root.ownerDocument.documentElement.getAttribute('data-prts-motion') === 'reduced'
+    if (scroller) {
+      // Read all geometry before writing scrollTop. Offset is independent of smooth-scroll progress.
+      const card = row.getBoundingClientRect(), box = scroller.getBoundingClientRect()
+      const current = scroller.scrollTop, height = scroller.clientHeight
+      const top = card.top - box.top - scroller.clientTop, bottom = card.bottom - box.top - scroller.clientTop
+      const next = [top + current, card.height, height, scroller.scrollHeight]
+      const changed = remounted || !geometry || next.some((v, i) => Math.abs(v - geometry[i]) > 1)
+      if (first || changed || final) {
+        // Evaluate visibility at the pending destination, not at an intermediate animation frame.
+        // Rows below the target may change scrollHeight without invalidating that destination.
+        const base = destination ?? current
+        const offset = next[0], bottomOffset = offset + card.height
+        const limit = Math.max(0, next[3] - height)
+        const nearest = position => Math.max(0, Math.min(limit,
+          offset < position ? offset : bottomOffset > position + height ? bottomOffset - height : position))
+        // A stale endpoint can lie on the other side of a card that is already visible.
+        // Preserve valid endpoints, but correct invalid ones from the actual viewport.
+        const target = Math.abs(nearest(base) - base) > 1 ? nearest(current) : base
+        if (final) {
+          // End any native animation at the nearest visible position before disconnecting.
+          instant(nearest(current))
+          destination = undefined
+        } else if (Math.abs(target - base) > 1) {
+          destination = target
+          if (!reduced && typeof scroller.scrollTo === 'function') scroller.scrollTo({top: target, behavior: 'smooth'})
+          else instant(target)
+        }
+      }
+      settled = !changed && Math.abs(current - (lastPosition ?? current)) <= 1
+        && (destination === undefined || Math.abs(scroller.scrollTop - destination) <= 1)
+      lastPosition = current
+      geometry = next
+    } else if (first || remounted || final) {
+      row.scrollIntoView?.({block:'nearest', inline:'nearest', behavior:'instant'})
+    }
+    for (let node = row; node && node !== root.parentElement; node = node.parentElement) {
+      if ((node.getAnimations?.() ?? []).some(animation => animation.playState === 'running'
+        && Number.isFinite(animation.effect?.getComputedTiming?.().endTime))) settled = false
+    }
+    if (first) {
+      started = true
+      onStart?.()
+      // Bound the pre-navigation wait; finish any remaining scroll before opening.
+      timer = window.setTimeout(() => { check(true); cancel(); onDone() }, 1000)
+    }
+    if (!final) {
+      const now = window.performance.now()
+      if (!settled) stableSince = undefined
+      else stableSince ??= now
+      if (stableSince !== undefined && now - stableSince >= 80) {
+        cancel()
+        onDone()
+      } else schedule()
+    }
+  }
+  const resize = typeof window.ResizeObserver === 'function' ? new window.ResizeObserver(schedule) : undefined
+  const mutations = new window.MutationObserver(schedule)
+  mutations.observe(root, {childList:true, subtree:true, attributes:true, attributeFilter:['aria-selected','aria-expanded','data-prts-selection-target']})
+  root.addEventListener('transitionend', schedule)
+  root.addEventListener('animationend', schedule)
+  schedule()
+  return {cancel, interrupt: cancel}
+}

package/src/client/sidebar-control-adapter.js

@@ -1,3 +1,4 @@
+import { createSessionCardReveal } from './session-card-reveal.js'
 import { createSessionSummaryPreview, scrollSummaryTitle } from './session-summary-preview.js'
 import { ensureFacilityGraphic, ensureFacilityTextureDefs, renderFacilityGraphic } from './facility-vector.js'
 import { createSessionLifelineAnimator } from './session-lifeline.js'
@@ -353,7 +354,11 @@ export function createSidebarControlAdapter({ document, window, sessions, worksp
     queueScan()
   }
   function interruptSelectionTarget(event) {
-    if (event.target.closest?.('[data-prts-session-row]')) clearSelectionTarget()
+    if (event.target.closest?.('[data-prts-session-row]')) {
+      cancelPendingNavigation()
+      cancelReveal()
+      clearSelectionTarget()
+    }
   }
   function setSelectionTarget(id) {
     clearSelectionTarget()
@@ -362,27 +367,41 @@ export function createSidebarControlAdapter({ document, window, sessions, worksp
     document.addEventListener('pointerdown', interruptSelectionTarget, true)
   }
 
-  let pendingReveal, revealTimer, revealFrame, revealSettleTimer
+  let pendingReveal, revealTimer
   let navigationFrame, navigationGeneration = 0
   function cancelPendingNavigation() {
     navigationGeneration++
     window.cancelAnimationFrame?.(navigationFrame)
   }
   function cancelReveal() {
+    pendingReveal?.tracker?.cancel()
     pendingReveal = undefined
     window.clearTimeout(revealTimer)
-    window.clearTimeout(revealSettleTimer)
-    window.cancelAnimationFrame?.(revealFrame)
+    for (const type of ['wheel','touchmove','pointerdown','keydown']) document.removeEventListener(type, interruptReveal, true)
   }
-  function revealSessionCard(sessionId) {
+  function interruptReveal(event) {
+    if (!event.target?.closest?.('[data-prts-region="sessions"]')) return
+    if (event.type === 'keydown' && !['ArrowUp','ArrowDown','PageUp','PageDown','Home','End',' '].includes(event.key)) return
+    cancelPendingNavigation()
     cancelReveal()
-    pendingReveal = {sessionId, attempts: 0}
-    revealTimer = window.setTimeout(cancelReveal, 4000)
+    clearSelectionTarget()
+  }
+  function revealSessionCard(sessionId, onDone) {
+    pendingReveal?.tracker?.interrupt()
+    cancelReveal()
+    pendingReveal = {sessionId, onDone}
+    revealTimer = window.setTimeout(finishReveal, 4000)
+    for (const type of ['wheel','touchmove','pointerdown','keydown']) document.addEventListener(type, interruptReveal, {capture:true, passive:true})
     const root = document?.querySelector?.('[data-prts-region="sessions"] [data-slot="sidebar.workspaces"]')
     syncSessionReveal(root)
     queueScan()
     return Boolean(pendingReveal?.expanding)
   }
+  function finishReveal() {
+    const onDone = pendingReveal?.onDone
+    cancelReveal()
+    onDone?.()
+  }
   function syncSessionReveal(root) {
     if (!pendingReveal || !root) return
     const {sessionId} = pendingReveal
@@ -390,30 +409,14 @@ export function createSidebarControlAdapter({ document, window, sessions, worksp
     const row = rows.find(el => el.getAttribute('data-row-key') === `session:${sessionId}`
       || el.getAttribute('data-session-id') === sessionId)
     if (row) {
-      if (pendingReveal.scrolling) return
-      const request = pendingReveal
-      request.scrolling = true
-      // Let React finish mounting and let the host's row glide settle before scrolling.
-      revealFrame = window.requestAnimationFrame(async () => {
-        const reduced = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches
-        const animations = []
-        if (!reduced) for (let node = row; node && node !== root; node = node.parentElement) {
-          for (const animation of node.getAnimations?.() ?? []) {
-            const timing = animation.effect?.getComputedTiming?.()
-            if (animation.playState === 'running' && Number.isFinite(timing?.endTime)) animations.push(animation.finished)
-          }
-        }
-        if (animations.length) await Promise.race([
-          Promise.allSettled(animations),
-          new Promise(resolve => { revealSettleTimer = window.setTimeout(resolve, 300) }),
-        ])
-        if (pendingReveal !== request || !row.isConnected) return
-        row.scrollIntoView?.({block:'nearest', inline:'nearest', behavior:reduced ? 'instant' : 'smooth'})
-        cancelReveal()
-      })
+      if (!pendingReveal.tracker) {
+        const request = pendingReveal
+        request.tracker = createSessionCardReveal({window, root, sessionId, onStart: () => window.clearTimeout(revealTimer), onDone: () => {
+          if (pendingReveal === request) finishReveal()
+        }})
+      }
       return
     }
-    if (++pendingReveal.attempts > 40) { cancelReveal(); return }
     const items = snapshotOf(workspaces?.list)?.items ?? []
     const owner = items.find(item => item.sessionIds?.includes(sessionId))
     const key = owner?.workspaceId ?? ''
@@ -439,7 +442,6 @@ export function createSidebarControlAdapter({ document, window, sessions, worksp
     closeNavigationPreview()
     cancelPendingNavigation()
     setSelectionTarget(sessionId)
-    revealSessionCard(sessionId)
     const generation = navigationGeneration
     const navigate = () => {
       if (generation !== navigationGeneration || !adapterActive) return
@@ -462,11 +464,14 @@ export function createSidebarControlAdapter({ document, window, sessions, worksp
       if (row) row.click?.()
       else clearSelectionTarget()
     }
-    // Paint selection and expansion before the host synchronously mounts another conversation.
-    // Already-expanded workspaces need this too: queueScan has not applied selection yet.
-    navigationFrame = window.requestAnimationFrame(() => {
-      if (generation !== navigationGeneration) return
-      navigationFrame = window.requestAnimationFrame(navigate)
+    // Finish sidebar motion first, then paint its final position before the host can block.
+    revealSessionCard(sessionId, () => {
+      if (generation !== navigationGeneration || !adapterActive) return
+      setSelectionTarget(sessionId)
+      navigationFrame = window.requestAnimationFrame(() => {
+        if (generation !== navigationGeneration) return
+        navigationFrame = window.requestAnimationFrame(navigate)
+      })
     })
   }
 

package/src/client/theme-controller-v2.js

@@ -72,7 +72,7 @@ function resolveScheme(value) {
   return identity.includes('dark') || identity.includes('night') ? 'dark' : 'light'
 }
 
-export function createThemeController({ document, window, cssText, service, cursorAssets, onTransitionStateChange = () => {} }) {
+export function createThemeController({ document, window, cssText, service, cursorAssets, onTransitionStateChange = () => {}, onSchemeChange = () => {} }) {
   if (!document || !window) {
     const gesture = { update() {}, finish() {}, cancel() {} }
     return { apply() {}, sync() {}, refresh() {}, setTheme() {}, beginThemeTransition() { return gesture }, toggle() {}, dispose() {} }
@@ -153,6 +153,7 @@ export function createThemeController({ document, window, cssText, service, curs
     if (disposed) return
     const next = resolveScheme(value)
     root.dataset.prtsScheme = next
+    onSchemeChange(next)
     return next
   }
 

package/src/client/theme-settings-workbench.js

@@ -1,3 +1,4 @@
+import { themeTransferMarkup, mountThemeTransfer } from './theme-transfer-panel.js'
 import { backgroundMarkup, mountBackgroundSettings } from './custom-background.js'
 import { avatarMarkup, mountAvatarSettings } from './custom-avatar.js'
 import { customEmblemMarkup, mountCustomEmblemEditor } from './custom-emblem.js'
@@ -38,7 +39,9 @@ function previewSetting(key, label, description) {
 }
 
 function settingButtons(key, label, options) {
-  const note = key === 'composerGlass'
+  const note = key === 'heroContrast'
+      ? '<small data-prts-setting-note>为新会话徽记添加柔光衬底，使它在背景图片上更清晰。</small>'
+      : key === 'composerGlass'
       ? '<small data-prts-setting-note>增强输入框的背景模糊与轻微折射，关闭时使用原有材质</small>'
       : key === 'bakerLoading'
       ? '<small data-prts-setting-note>每轮正文生成时显示三点动画，完成后显示全文；中断时保留已收到的内容</small>'
@@ -59,7 +62,7 @@ function settingButtons(key, label, options) {
       : key === 'sessionFlowPalette'
         ? '<small data-prts-setting-note>同时适配日间与夜间模式</small>'
       : ''
-  if (['composerGlass', 'bakerLoading', 'motion', 'cursor', 'railDefaultHidden', 'sessionFlow', 'sessionGlow', 'bakerGroupAvatars', 'conversationEmblem', 'sessionPreview', 'aiToolsEnabled', 'previewOngoing', 'previewTools', 'previewWarning', 'previewDone', 'previewDoubleClick', 'previewFollowOngoing', 'previewFollowWarning'].includes(key)) return `<div data-prts-setting-row="${key}">
+  if (['heroContrast', 'composerGlass', 'bakerLoading', 'motion', 'cursor', 'railDefaultHidden', 'sessionFlow', 'sessionGlow', 'bakerGroupAvatars', 'conversationEmblem', 'sessionPreview', 'aiToolsEnabled', 'previewOngoing', 'previewTools', 'previewWarning', 'previewDone', 'previewDoubleClick', 'previewFollowOngoing', 'previewFollowWarning'].includes(key)) return `<div data-prts-setting-row="${key}">
     <span><strong>${label}</strong>${note}</span>
     <button type="button" role="switch" aria-label="${label}" aria-checked="false" data-prts-setting-switch="${key}" ${key === 'cursor' ? 'data-prts-cursor-switch' : ''}><span aria-hidden="true"></span></button>
   </div>`
@@ -134,9 +137,10 @@ export function themeSettingsMarkup() {
               <span><strong>设置未保存</strong><small>未能保存到 DSH，可能存在连接中断、配置冲突或当前访问不支持持久保存。重试将重新提交本次修改。</small></span>
               <button type="button" data-prts-retry-save>重试保存</button>
             </div>
+            <button type="button" data-prts-transfer-open data-prts-footer-action aria-haspopup="dialog" aria-expanded="false"><svg viewBox="0 0 20 20" aria-hidden="true"><path d="M6 14V3m-3 3 3-3 3 3M14 6v11m-3-3 3 3 3-3"/></svg><span>导入与导出</span></button>
             <div data-prts-reset-zone>
 
-              <button type="button" data-prts-reset-visual title="恢复全部主题设置" aria-label="恢复全部主题设置">恢复默认</button>
+              <button type="button" data-prts-reset-visual data-prts-footer-action title="恢复全部主题设置" aria-label="恢复全部主题设置"><svg viewBox="0 0 20 20" aria-hidden="true"><path d="M4 7a6.5 6.5 0 1 1-.4 5M4 3v4h4"/></svg><span>恢复默认</span></button>
               <div data-prts-reset-confirm hidden role="group" aria-label="确认恢复全部主题设置">
                 <span>重置全部分类的主题设置，保留主题开关、启动动画和徽记配置。</span>
                 <button type="button" data-prts-reset-confirm-action>确认恢复</button>
@@ -144,6 +148,7 @@ export function themeSettingsMarkup() {
               </div>
             </div>
           </footer>
+          ${themeTransferMarkup()}
         </div>
         <div data-prts-theme-settings-scroll>
           <section data-prts-settings-section="appearance" role="tabpanel" id="prts-page-appearance" aria-labelledby="prts-tab-appearance" tabindex="0">
@@ -159,7 +164,7 @@ export function themeSettingsMarkup() {
           </section>
           </section>
           <section data-prts-settings-section="background" role="tabpanel" id="prts-page-background" aria-labelledby="prts-tab-background" tabindex="0" hidden>
-            ${backgroundMarkup()}
+            ${backgroundMarkup(settingButtons('heroContrast', '新会话徽记增强', []))}
             <div data-prts-composer-glass-setting>${settingButtons('composerGlass', '输入框增强毛玻璃', [])}</div>
             <small data-prts-composer-glass-required hidden>自定义背景下，输入框增强毛玻璃始终开启。</small>
           </section>
@@ -262,7 +267,7 @@ export function createThemeSettingsOverlay({
   trigger,
   panel,
   backdrop,
-  customEmblemStore, avatarStore, backgroundStore,
+  customEmblemStore, avatarStore, backgroundStore, themeTransfer,
   onOpen = () => {},
   onPreferenceChange = () => {},
   onPreferencePreview = () => {},
@@ -270,6 +275,7 @@ export function createThemeSettingsOverlay({
   onRetrySave = () => {},
 }) {
   const window = document?.defaultView
+  const transferEditor = mountThemeTransfer({ panel, window, transfer: themeTransfer })
   const backgroundEditor = mountBackgroundSettings({panel,window,store:backgroundStore,onChange:onPreferenceChange})
   const avatarEditor = mountAvatarSettings({panel,window,store:avatarStore})
   const customEditor = mountCustomEmblemEditor({ panel, window, store: customEmblemStore })
@@ -749,6 +755,7 @@ export function createThemeSettingsOverlay({
       panel.querySelector('[data-prts-baker-options]').hidden = preferences?.conversationStyle !== 'deck-chat'
       panel.querySelector('[data-prts-avatars]').hidden = preferences?.conversationStyle !== 'deck-chat'
       const customBackground = preferences.backgroundMode !== 'off'
+      panel.querySelector('[data-prts-background-hero-setting]').hidden = !customBackground
       panel.querySelector('[data-prts-composer-glass-setting]').hidden = customBackground
       panel.querySelector('[data-prts-composer-glass-required]').hidden = !customBackground
       backgroundEditor.update(preferences)
@@ -766,6 +773,7 @@ export function createThemeSettingsOverlay({
     close: () => setOpen(false),
     toggle,
     dispose() {
+      transferEditor.dispose()
       customEditor.dispose()
       avatarEditor.dispose()
       backgroundEditor.dispose()

package/src/client/theme-transfer-panel.js

@@ -0,0 +1,98 @@
+import { THEME_PACKAGE_LIMIT, validateThemePackage, describeThemePackage } from './theme-transfer.js'
+
+export function themeTransferMarkup() {
+  return `<dialog data-prts-transfer-dialog aria-labelledby="prts-transfer-title">
+    <section data-prts-transfer>
+      <header data-prts-transfer-heading><div><small>P.R.T.S. / 主题文件</small><h2 id="prts-transfer-title">导入与导出</h2></div><button type="button" data-prts-transfer-close aria-label="关闭导入与导出">×</button></header>
+      <div data-prts-transfer-columns>
+        <section data-prts-transfer-card>
+          <h3>导出主题</h3><p>保存一份主题，备份或带到另一台设备。</p>
+          <label data-prts-transfer-option><input type="checkbox" data-prts-transfer-assets checked><span>包含自定义素材<small>背景、头像和徽记，保留编辑参数与排列。</small></span></label>
+          <small>取消勾选，仅导出主题设置。</small>
+          <button type="button" data-prts-transfer-export>导出主题文件 <span aria-hidden="true">↓</span></button>
+        </section>
+        <section data-prts-transfer-card>
+          <h3>导入主题</h3><p>选择已导出的文件，确认内容后应用。</p>
+          <div data-prts-transfer-file-hint><span aria-hidden="true">↑</span><small>.prts-theme.json · 最大 160 MB</small></div>
+          <button type="button" data-prts-transfer-choose>选择主题文件</button>
+          <input type="file" accept=".prts-theme.json,application/json" aria-label="导入主题文件" data-prts-transfer-file hidden>
+        </section>
+      </div>
+      <div data-prts-transfer-preview hidden>
+        <strong>确认导入</strong><p data-prts-transfer-summary></p>
+        <small>应用前会下载当前配置备份，请保留备份文件。</small>
+        <div data-prts-transfer-buttons><button type="button" data-prts-transfer-apply>确认导入</button><button type="button" data-prts-transfer-cancel>取消</button></div>
+      </div>
+      <div data-prts-transfer-recovery hidden><small>恢复将替换最近一次导入后所做的修改。</small><button type="button" data-prts-transfer-restore>恢复导入前配置</button></div>
+      <p data-prts-transfer-status role="status" aria-live="polite"></p>
+    </section>
+  </dialog>`
+}
+
+export function mountThemeTransfer({ panel, window, transfer }) {
+  const section = panel.querySelector('[data-prts-transfer]')
+  if (!section || !transfer) return { dispose() {} }
+  const dialog = panel.querySelector('[data-prts-transfer-dialog]')
+  const trigger = panel.querySelector('[data-prts-transfer-open]')
+  const open = () => { dialog.showModal(); trigger?.setAttribute('aria-expanded', 'true'); get('close').focus() }
+  const close = () => { if (busy) return; dialog.close(); trigger?.setAttribute('aria-expanded', 'false'); trigger?.focus() }
+  const keydown = event => { if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); close() } }
+  const cancel = event => { if (event.target === dialog) { event.preventDefault(); event.stopPropagation(); close() } }
+  const get = name => section.querySelector(`[data-prts-transfer-${name}]`)
+  let pending, busy = false, disposed = false, generation = 0
+  const render = () => {
+    if (disposed) return
+    get('preview').hidden = !pending
+    get('recovery').hidden = !transfer.hasBackup
+    for (const control of section.querySelectorAll('button,input')) control.disabled = busy
+    // Prevent local editors from racing a multi-service import; other clients use revision checks.
+    for (const page of panel.querySelectorAll('[data-prts-settings-section]')) if (!page.contains(section)) page.inert = busy
+  }
+  async function run(task) {
+    if (busy) return
+    busy = true; get('status').textContent = '正在处理，请稍候…'; render()
+    try { get('status').textContent = await task() }
+    catch (error) { if (!disposed) get('status').textContent = error.message }
+    finally { busy = false; render() }
+  }
+  const change = event => {
+    if (event.target !== get('file')) return
+    const file = event.target.files?.[0], selected = ++generation
+    pending = undefined; render()
+    if (!file) return
+    void run(async () => {
+      if (file.size > THEME_PACKAGE_LIMIT) throw Error('主题文件不能超过 160 MB')
+      const text = await new Promise((resolve, reject) => {
+        const reader = new window.FileReader()
+        reader.onload = () => resolve(reader.result); reader.onerror = () => reject(Error('无法读取主题文件')); reader.readAsText(file)
+      })
+      let value
+      try { value = JSON.parse(text) } catch { throw Error('主题文件不是有效的 JSON') }
+      validateThemePackage(value)
+      if (disposed || selected !== generation) return ''
+      pending = value
+      get('summary').textContent = describeThemePackage(value)
+      return '已读取文件，请确认导入内容。'
+    })
+  }
+  const click = event => {
+    const button = event.target.closest?.('button')
+    if (button === get('close')) close()
+    if (button === get('choose')) get('file').click()
+    if (button === get('export')) void run(async () => {
+      const value = await transfer.export(get('assets').checked)
+      transfer.download(value)
+      return '已发起下载，请确认主题文件已保存。'
+    })
+    if (button === get('apply') && pending) void run(async () => {
+      await transfer.import(pending); pending = undefined; get('file').value = ''
+      return '主题已导入并保存。'
+    })
+    if (button === get('cancel')) { pending = undefined; get('file').value = ''; get('status').textContent = ''; render() }
+    if (button === get('restore')) void run(async () => { await transfer.restore(); return '已恢复导入前配置。' })
+  }
+  trigger?.addEventListener('click', open)
+  dialog.addEventListener('keydown', keydown); dialog.addEventListener('cancel', cancel)
+  section.addEventListener('change', change); section.addEventListener('click', click); render()
+  return { dispose() { disposed = true; generation++; if (dialog.open) dialog.close(); trigger?.removeEventListener('click', open); dialog.removeEventListener('keydown', keydown); dialog.removeEventListener('cancel', cancel); section.removeEventListener('change', change); section.removeEventListener('click', click) } }
+}

package/src/client/theme-transfer.js

@@ -0,0 +1,170 @@
+import { validBackgroundRegion } from '../shared/background-region.js'
+import { DEFAULT_PREFERENCES, normalizePreferences } from './preferences.js'
+
+export const THEME_PACKAGE_LIMIT = 160 * 1024 * 1024
+const transferSlots = ['full', 'sidebar', 'conversation']
+const transferRoles = ['user', 'assistant']
+const transferBuiltins = ['rhodes-island', 'lungmen', 'penguin-logistics', 'rhine-lab', 'reunion']
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const encodedImage = (value, limit) => typeof value === 'string' && value.length > 0 && value.length <= Math.ceil(limit / 3) * 4 && value.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(value)
+
+export function validateThemePackage(value) {
+  if (!record(value) || value.format !== 'prts-theme' || value.version !== 1) throw Error('不支持的主题文件格式或版本')
+  if (!record(value.preferences) || !Object.keys(value.preferences).some(key => key !== 'version' && Object.hasOwn(DEFAULT_PREFERENCES, key))) throw Error('主题文件缺少设置')
+  if (!Number.isInteger(value.preferences.version) || value.preferences.version < 1 || value.preferences.version > DEFAULT_PREFERENCES.version) throw Error('不支持此设置版本，请更新主题后重试')
+  const normalized = normalizePreferences(value.preferences)
+  for (const [key, input] of Object.entries(value.preferences)) {
+    if (!Object.hasOwn(DEFAULT_PREFERENCES, key) || key === 'version') continue
+    if (typeof input !== typeof DEFAULT_PREFERENCES[key] || (typeof input === 'number' && !Number.isFinite(input))) throw Error(`设置 ${key} 的类型无效`)
+    // Current-format files must not silently turn malformed settings into defaults.
+    if (value.preferences.version === DEFAULT_PREFERENCES.version && normalized[key] !== input) throw Error(`设置 ${key} 的值无效`)
+  }
+  if (value.assets === undefined) return value
+  const a = value.assets
+  if (!record(a) || !record(a.backgrounds) || !record(a.avatars) || !record(a.emblems)) throw Error('主题素材数据不完整')
+  for (const slot of transferSlots) if (a.backgrounds[slot] !== null && !encodedImage(a.backgrounds[slot], 10 * 1024 * 1024)) throw Error('背景图片数据无效')
+  if (a.backgroundRegions !== undefined && (!record(a.backgroundRegions) || transferSlots.some(slot => !validBackgroundRegion(a.backgroundRegions[slot] ?? null)))) throw Error('背景保护区域无效')
+  for (const role of transferRoles) {
+    const avatar = a.avatars[role]
+    if (avatar === null) continue
+    const crop = avatar?.crop
+    if (!record(avatar) || !encodedImage(avatar.image, 5 * 1024 * 1024) || !record(crop)
+      || !Number.isFinite(crop.zoom) || crop.zoom < 1 || crop.zoom > 4
+      || !Number.isFinite(crop.x) || crop.x < 0 || crop.x > 1 || !Number.isFinite(crop.y) || crop.y < 0 || crop.y > 1) throw Error('头像数据或裁剪参数无效')
+  }
+  const { items, hero, conversation } = a.emblems
+  if (!Array.isArray(items) || items.length > 13 || !Array.isArray(conversation) || conversation.length < 1 || conversation.length > 12) throw Error('徽记数量无效')
+  for (const item of items) {
+    if (!record(item) || item.format !== 'prts-emblem' || item.version !== 1 || typeof item.label !== 'string' || !item.label.trim() || item.label.length > 100 || !record(item.params) || !encodedImage(item.image, 8 * 1024 * 1024)) throw Error('徽记素材无效')
+  }
+  const validEntry = entry => record(entry) && (entry.kind === 'builtin' ? transferBuiltins.includes(entry.key) : entry.kind === 'custom' && Number.isInteger(entry.asset) && entry.asset >= 0 && entry.asset < items.length && typeof entry.label === 'string' && entry.label.length <= 100)
+  if ((hero !== null && (!validEntry(hero) || hero.kind !== 'custom')) || !conversation.every(validEntry)) throw Error('徽记引用无效')
+  return value
+}
+
+export function mergeThemePreferences(current, imported) {
+  const normalized = normalizePreferences(imported)
+  const patch = Object.fromEntries(Object.keys(DEFAULT_PREFERENCES).filter(key => key !== 'version' && Object.hasOwn(imported, key)).map(key => [key, normalized[key]]))
+  return normalizePreferences({ ...current, ...patch, version: DEFAULT_PREFERENCES.version })
+}
+
+export function describeThemePackage(value) {
+  const count = Object.keys(value.preferences).filter(key => key !== 'version' && Object.hasOwn(DEFAULT_PREFERENCES, key)).length
+  if (!value.assets) return `${count} 项主题设置；不包含素材，将保留当前背景、头像和徽记。`
+  const a = value.assets
+  return `${count} 项主题设置、${transferSlots.filter(k => a.backgrounds[k]).length} 张背景、${transferRoles.filter(k => a.avatars[k]).length} 个头像、${a.emblems.items.length} 个自定义徽记。将替换当前素材及徽记排列，空项恢复为默认。`
+}
+
+export function createThemeTransfer({ window, getPreferences, savePreferences, checkWritable, checkExport = checkWritable, themeVersion }) {
+  let busy = false, backup
+  const request = async (path, data) => {
+    const response = await window.fetch('/prts-theme-api/' + path, { credentials: 'same-origin',
+      ...(data === undefined ? {} : { method: 'POST', headers: { 'content-type': 'application/json', 'x-prts-request': '1' }, body: JSON.stringify(data) }) })
+    const result = await response.json()
+    if (!response.ok) throw Error(result.error || '无法连接主题素材服务')
+    return result
+  }
+  const readImage = blob => new Promise((resolve, reject) => {
+    const reader = new window.FileReader()
+    reader.onload = () => resolve(String(reader.result).split(',')[1])
+    reader.onerror = () => reject(Error('无法读取背景图片'))
+    reader.readAsDataURL(blob)
+  })
+  async function capture(includeAssets) {
+    const value = { format: 'prts-theme', version: 1, themeVersion, exportedAt: new Date().toISOString(), preferences: { ...getPreferences() } }
+    const states = {}
+    if (includeAssets) {
+      const backgrounds = {}, backgroundRegions = {}, avatars = {}, items = [], ids = new Map()
+      states.backgrounds = await request('backgrounds/configuration')
+      for (const slot of transferSlots) {
+        const entry = states.backgrounds[slot]
+        backgroundRegions[slot] = entry?.region ?? null
+        backgrounds[slot] = null
+        if (entry) {
+          if (!/^[a-f0-9-]{36}$/.test(entry.id)) throw Error('背景引用无效')
+          const response = await window.fetch('/prts-theme-api/backgrounds/image/' + entry.id, { credentials: 'same-origin' })
+          if (!response.ok) throw Error('无法导出背景图片')
+          backgrounds[slot] = await readImage(await response.blob())
+        }
+      }
+      states.avatars = await request('avatars/configuration')
+      for (const role of transferRoles) {
+        const source = await request('avatars/edit/' + role)
+        if (source.revision !== states.avatars.revision) throw Error('头像已变化，请重新导出')
+        avatars[role] = source.image ? { image: source.image, crop: source.crop } : null
+      }
+      states.emblems = await request('emblems/configuration')
+      async function reference(entry) {
+        if (!entry) return null
+        if (entry.kind === 'builtin') return { kind: 'builtin', key: entry.key, label: entry.label }
+        if (!ids.has(entry.draftId)) {
+          ids.set(entry.draftId, items.length)
+          items.push(await request('emblems/draft/' + encodeURIComponent(entry.draftId) + '/export'))
+        }
+        return { kind: 'custom', asset: ids.get(entry.draftId), label: entry.label }
+      }
+      const hero = await reference(states.emblems.configuration.hero), conversation = []
+      for (const entry of states.emblems.configuration.conversation) conversation.push(await reference(entry))
+      value.assets = { backgrounds, backgroundRegions, avatars, emblems: { items, hero, conversation } }
+      for (const kind of ['backgrounds', 'avatars', 'emblems']) {
+        if ((await request(kind + '/configuration')).revision !== states[kind].revision) throw Error('素材在导出期间发生变化，请重试')
+      }
+    }
+    if (JSON.stringify(value.preferences) !== JSON.stringify(getPreferences())) throw Error('设置在导出期间发生变化，请重试')
+    validateThemePackage(value)
+    return { value, states }
+  }
+  async function exclusive(fn) {
+    if (busy) throw Error('正在处理主题文件，请稍候')
+    busy = true
+    try { return await fn() } finally { busy = false }
+  }
+  function download(value, name = 'theme') {
+    const blob = new window.Blob([JSON.stringify(value)], { type: 'application/json' })
+    if (blob.size > THEME_PACKAGE_LIMIT) throw Error('主题文件超过 160 MB，请减少素材后重试')
+    const url = window.URL.createObjectURL(blob), link = window.document.createElement('a')
+    link.href = url; link.download = `prts-${name}-${new Date().toISOString().replace(/[:.]/g, '-')}.prts-theme.json`
+    window.document.body.append(link); link.click(); link.remove()
+    window.setTimeout(() => window.URL.revokeObjectURL(url), 1000)
+  }
+  async function apply(value) {
+    validateThemePackage(value)
+    const preferenceRevision = checkWritable()
+    const before = await capture(Boolean(value.assets))
+    backup = before.value
+    download(backup, 'before-import')
+    const undo = [], revisions = Object.fromEntries(Object.entries(before.states).map(([key, state]) => [key, state.revision]))
+    const write = async (kind, data, previous) => {
+      const result = await request(kind + '/configuration', { ...data, revision: revisions[kind] })
+      revisions[kind] = result.revision
+      undo.push(async () => {
+        const restored = await request(kind + '/configuration', { ...previous, revision: revisions[kind] })
+        revisions[kind] = restored.revision
+      })
+    }
+    try {
+      if (value.assets) {
+        const a = value.assets, old = before.value.assets, drafts = []
+        // Generate every custom draft before changing the active configuration.
+        for (const item of a.emblems.items) drafts.push(await request('emblems/import', item))
+        const entry = (ref, index) => ref === null ? null : ref.kind === 'builtin' ? ref : { kind: 'custom', key: 'import-' + index + '-' + drafts[ref.asset].draftId, label: ref.label, draftId: drafts[ref.asset].draftId }
+        const configuration = { version: 2, hero: entry(a.emblems.hero, 'hero'), conversation: a.emblems.conversation.map(entry) }
+        for (const slot of transferSlots) await write('backgrounds', { slot, image: a.backgrounds[slot], region: a.backgroundRegions?.[slot] ?? null }, { slot, image: old.backgrounds[slot], region: old.backgroundRegions?.[slot] ?? null })
+        for (const role of transferRoles) await write('avatars', { role, image: a.avatars[role]?.image ?? null, crop: a.avatars[role]?.crop }, { role, image: old.avatars[role]?.image ?? null, crop: old.avatars[role]?.crop })
+        await write('emblems', { configuration }, { configuration: before.states.emblems.configuration })
+      }
+      await savePreferences(mergeThemePreferences(before.value.preferences, value.preferences), preferenceRevision)
+    } catch (error) {
+      let failures = 0
+      for (const restore of undo.reverse()) { try { await restore() } catch { failures++ } }
+      throw Error(`${error.message}。${failures ? '部分素材未能自动恢复。' : '已回退已确认写入的素材。'}若连接中断，请检查实际状态；导入前备份已发起下载，可重新导入恢复。`)
+    }
+  }
+  return {
+    export: includeAssets => exclusive(async () => { checkExport(); return (await capture(includeAssets)).value }),
+    import: value => exclusive(() => apply(value)),
+    restore: () => exclusive(() => { if (!backup) throw Error('没有可恢复的备份'); return apply(backup) }),
+    get hasBackup() { return Boolean(backup) },
+    download,
+  }
+}