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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ash-qw/dsh-theme-prts",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "private": false,
   "type": "module",
   "description": "Unofficial Arknights P.R.T.S.-inspired UI theme for DeepSeek Harness Web and the official desktop client",

package/src/client/background-layout.js

@@ -0,0 +1,59 @@
+import { backgroundPlacement } from '../shared/background-region.js'
+
+export function createBackgroundLayout({window,document}) {
+  const root=document.documentElement
+  const raf=window.requestAnimationFrame?.bind(window) ?? (fn=>window.setTimeout(fn,16))
+  const caf=window.cancelAnimationFrame?.bind(window) ?? window.clearTimeout.bind(window)
+  let state={}, frame, disposed=false, enabled=false, observing=false, operation, sessions
+  const set=(name,value)=>{if(root.style.getPropertyValue(name)!==value) root.style.setProperty(name,value)}
+  const update=()=>{
+    frame=undefined
+    if(disposed||!observing)return
+    const nextOperation=document.querySelector('[data-prts-region="operation"]')
+    const nextSessions=document.querySelector('[data-prts-region="sessions"]')
+    if(operation!==nextOperation || sessions!==nextSessions){
+      resize?.disconnect(); operation=nextOperation;sessions=nextSessions
+      for(const node of [operation,sessions])if(node)resize?.observe(node)
+    }
+    const railWidth=parseFloat(window.getComputedStyle(root).getPropertyValue('--prts-nav-width'))||0
+    for(const slot of ['full','conversation','sidebar']){
+      const entry=state[slot]
+      const node=slot==='sidebar'?sessions:operation
+      const width=slot==='full'?window.innerWidth:(node?.clientWidth||0)+(slot==='sidebar'?railWidth:0)
+      const height=slot==='full'?window.innerHeight:node?.clientHeight||0
+      const active=entry?.region && width>0 && height>0
+      if(active){
+        const p=backgroundPlacement(entry.width,entry.height,width,height,entry.region)
+        set(`--prts-protected-${slot}-x`,`${p.x}px`)
+        set(`--prts-protected-${slot}-y`,`${p.y}px`)
+        if(slot==='sidebar')set('--prts-protected-sidebar-width',`${p.width}px`)
+      }else{
+        root.style.removeProperty(`--prts-protected-${slot}-x`)
+        root.style.removeProperty(`--prts-protected-${slot}-y`)
+        if(slot==='sidebar')root.style.removeProperty('--prts-protected-sidebar-width')
+      }
+    }
+  }
+  function schedule(){if(!disposed && observing && frame===undefined)frame=raf(update)}
+  const resize=window.ResizeObserver?new window.ResizeObserver(schedule):null
+  const mutations=new window.MutationObserver(()=>{
+    if(!operation?.isConnected || !sessions?.isConnected)schedule()
+  })
+  const attributes=new window.MutationObserver(schedule)
+  function clear(){
+    caf(frame);frame=undefined;resize?.disconnect();mutations.disconnect();attributes.disconnect();window.removeEventListener('resize',schedule)
+    operation=undefined;sessions=undefined;observing=false
+    for(const slot of ['full','conversation','sidebar'])for(const axis of ['x','y','width'])root.style.removeProperty(`--prts-protected-${slot}-${axis}`)
+  }
+  function reconcile(){
+    if(disposed || !enabled || !['full','conversation','sidebar'].some(slot=>state[slot]?.region)){clear();return}
+    if(!observing){
+      observing=true
+      mutations.observe(document.body||root,{childList:true,subtree:true})
+      attributes.observe(root,{attributes:true,attributeFilter:['data-prts-background-mode','data-prts-rail-mode']})
+      window.addEventListener('resize',schedule)
+    }
+    schedule()
+  }
+  return {update(value){state=value;reconcile()},setEnabled(value){enabled=value;reconcile()},dispose(){disposed=true;clear()}}
+}

package/src/client/background-region-editor.js

@@ -0,0 +1,103 @@
+import { backgroundPlacement } from '../shared/background-region.js'
+
+export function backgroundRegionMarkup(slot) {
+  return `<dialog data-prts-region-editor="${slot}" aria-labelledby="prts-region-title-${slot}">
+    <header><div><strong id="prts-region-title-${slot}">保护重要区域</strong><p>拖动框移动，拖动四边或四角缩放。横向优先保留中心，纵向优先保留顶端。</p></div><button type="button" data-prts-region-cancel aria-label="关闭保护区域设置">×</button></header>
+    <div data-prts-region-workspace><section data-prts-region-original><strong>原图与保护框</strong><div data-prts-region-stage><img alt="背景原图" draggable="false"><div data-prts-region-box tabindex="0" role="group" aria-label="保护区域，方向键移动"><span>保护区域</span>${['nw','ne','sw','se','n','e','s','w'].map((corner,i)=>`<button type="button" data-prts-region-handle="${corner}" aria-label="调整${['左上角','右上角','左下角','右下角','上边','右边','下边','左边'][i]}，使用方向键"></button>`).join('')}</div><div data-prts-region-ruler="x"></div><div data-prts-region-ruler="y"></div></div><small>边缘刻度为图片坐标。可用方向键移动，Shift 加速。</small></section>
+    <section data-prts-region-samples><strong>窗口裁剪预览</strong><p>${slot==='sidebar' ? '按当前侧栏高度等比例预览，包含导航栏背景。' : '白框标出保护区域，调整时同步更新。'}</p><div data-prts-region-preview-grid>${(slot==='sidebar' ? [['narrow','较窄侧栏 · 264px'],['wide','较宽侧栏 · 420px']] : [['wide','横向窗口 · 16:9'],['narrow','纵向窗口 · 9:16']]).map(([kind,label])=>`<figure><figcaption>${label}</figcaption><div data-prts-region-preview="${kind}"><i></i></div><small data-prts-region-warning hidden>此比例无法完整显示保护区域：横向保中心，纵向保顶端。</small></figure>`).join('')}</div></section></div>
+    <footer><button type="button" data-prts-region-create>恢复默认框</button><button type="button" data-prts-region-clear>清除保护区域</button><span></span><button type="button" data-prts-region-cancel>取消</button><button type="button" data-prts-region-save>保存</button></footer><p data-prts-region-status role="status"></p>
+  </dialog>`
+}
+export function mountBackgroundRegionEditor({section,window,store}) {
+  let state=store.snapshot(), active, draft=null, revision, imageId, busy=false, disposed=false, drag
+  const clamp=(v,min,max)=>Math.max(min,Math.min(max,v))
+  const defaultRegion=()=>({x:.25,y:.2,width:.5,height:.6})
+  const editor=()=>active && section.querySelector(`[data-prts-region-editor="${active}"]`)
+  function draw(){
+    const el=editor(),entry=state[active];if(!el||!entry)return
+    const box=el.querySelector('[data-prts-region-box]')
+    box.hidden=!draft
+    if(draft)Object.assign(box.style,{left:`${draft.x*100}%`,top:`${draft.y*100}%`,width:`${draft.width*100}%`,height:`${draft.height*100}%`})
+    for(const axis of ['x','y']){
+      const ruler=el.querySelector(`[data-prts-region-ruler="${axis}"]`)
+      ruler.innerHTML=[0,25,50,75,100].filter(v=>!draft||Math.abs(v-draft[axis]*100)>8).map(v=>`<span style="${axis==='x'?'left':'top'}:${v}%">${v}</span>`).join('')
+      if(draft)ruler.innerHTML+=`<b style="${axis==='x'?'left':'top'}:${draft[axis]*100}%">${Math.round(draft[axis]*100)}%</b>`
+    }
+    const previews=[...el.querySelectorAll('[data-prts-region-preview]')]
+    const sidebarHeight=section.ownerDocument.querySelector('[data-prts-region="sessions"]')?.clientHeight||window.innerHeight
+    const railWidth=parseFloat(window.getComputedStyle(section.ownerDocument.documentElement).getPropertyValue('--prts-nav-width'))||0
+    // DSH 0.2.1-rc.2 clamps the sidebar track to 264–420px; use the same scale for both samples.
+    const sidebarScale=Math.min(240/Math.max(1,sidebarHeight),...previews.map(preview=>Math.max(1,preview.parentElement.clientWidth)/((preview.dataset.prtsRegionPreview==='narrow'?264:420)+railWidth)))
+    for(const preview of previews){
+      const narrow=preview.dataset.prtsRegionPreview==='narrow'
+      const w=active==='sidebar'?((narrow?264:420)+railWidth)*sidebarScale:Math.max(1,Math.min(narrow?112:200,preview.parentElement.clientWidth))
+      const h=active==='sidebar'?sidebarHeight*sidebarScale:w*(narrow?16/9:9/16)
+      const p=backgroundPlacement(entry.width,entry.height,w,h,draft)
+      Object.assign(preview.style,{width:`${w}px`,height:`${h}px`,backgroundImage:`url("/prts-theme-api/backgrounds/image/${entry.id}")`,backgroundSize:`${p.width}px ${p.height}px`,backgroundPosition:`${p.x}px ${p.y}px`})
+      const mark=preview.firstElementChild;mark.hidden=!draft
+      if(draft)Object.assign(mark.style,{left:`${p.x+draft.x*p.width}px`,top:`${p.y+draft.y*p.height}px`,width:`${draft.width*p.width}px`,height:`${draft.height*p.height}px`})
+      preview.parentElement.querySelector('[data-prts-region-warning]').hidden=!p.clipped
+    }
+    for(const button of el.querySelectorAll('button'))button.disabled=busy
+  }
+  const resize=window.ResizeObserver ? new window.ResizeObserver(()=>{if(!disposed)draw()}) : null
+  function close(){window.removeEventListener('resize',draw);resize?.disconnect();const el=editor();el?.querySelector('[data-prts-region-stage]').style.removeProperty('cursor');if(el?.open)el.close();if(active)section.querySelector(`[data-prts-background-region-open="${active}"]`)?.focus();active=undefined;drag=undefined}
+  function open(slot){
+    if(busy)return
+    close();const entry=state[slot];if(!entry?.width||!entry?.height)return
+    active=slot;revision=state.revision;imageId=entry.id;draft=entry.region?{...entry.region}:defaultRegion()
+    const el=editor();el.showModal();resize?.observe(el)
+    if(slot==='sidebar'){const sidebar=section.ownerDocument.querySelector('[data-prts-region="sessions"]');if(sidebar)resize?.observe(sidebar)}
+    window.addEventListener('resize',draw)
+    el.querySelector('[data-prts-region-stage]').style.width=`min(100%, ${Math.min(640,360*entry.width/entry.height)}px)`
+    el.querySelector('img').src=`/prts-theme-api/backgrounds/image/${entry.id}`
+    el.querySelector('[data-prts-region-status]').textContent=''
+    draw()
+  }
+  async function save(){
+    if(busy||!active)return
+    const el=editor(),slot=active,region=draft?{...draft}:null
+    busy=true;draw();el.querySelector('[data-prts-region-status]').textContent='正在保存…'
+    try{await store.saveRegion(slot,region,revision);if(!disposed){close();section.querySelector('[data-prts-background-status]').textContent='保护区域已保存，并同步到其他页面。';section.querySelector(`[data-prts-background-region-open="${slot}"]`).focus()}}
+    catch(error){if(!disposed)el.querySelector('[data-prts-region-status]').textContent=error.message+' 请取消后重新打开编辑。'}
+    finally{busy=false;if(!disposed)draw()}
+  }
+  const click=event=>{
+    const openButton=event.target.closest('[data-prts-background-region-open]');if(openButton){open(openButton.dataset.prtsBackgroundRegionOpen);return}
+    if(!active||busy)return
+    if(event.target.closest('[data-prts-region-cancel]'))close()
+    else if(event.target.closest('[data-prts-region-save]'))void save()
+    else if(event.target.closest('[data-prts-region-create]')){draft=defaultRegion();draw();editor().querySelector('[data-prts-region-box]').focus()}
+    else if(event.target.closest('[data-prts-region-clear]')){draft=null;draw()}
+  }
+  const down=event=>{
+    const el=editor(),stage=event.target.closest('[data-prts-region-stage]')
+    if(busy||!draft||!stage||!el?.contains(stage)||!event.target.closest('[data-prts-region-box]')||event.button!==0)return
+    event.preventDefault();const bounds=stage.getBoundingClientRect();if(!bounds.width||!bounds.height)return
+    const x=clamp((event.clientX-bounds.left)/bounds.width,0,1),y=clamp((event.clientY-bounds.top)/bounds.height,0,1)
+    drag={x,y,bounds,initial:{...draft},corner:event.target.dataset.prtsRegionHandle,id:event.pointerId}
+    stage.style.cursor=window.getComputedStyle(event.target).cursor
+    stage.setPointerCapture?.(event.pointerId);draw()
+  }
+  function adjust(initial,dx,dy,corner){
+    if(!corner)return {...initial,x:clamp(initial.x+dx,0,1-initial.width),y:clamp(initial.y+dy,0,1-initial.height)}
+    let left=initial.x,top=initial.y,right=left+initial.width,bottom=top+initial.height
+    if(corner.includes('w'))left=clamp(left+dx,0,right-.01);else if(corner.includes('e'))right=clamp(right+dx,left+.01,1)
+    if(corner.includes('n'))top=clamp(top+dy,0,bottom-.01);else if(corner.includes('s'))bottom=clamp(bottom+dy,top+.01,1)
+    return {x:left,y:top,width:/[ew]/.test(corner)?right-left:initial.width,height:/[ns]/.test(corner)?bottom-top:initial.height}
+  }
+  const move=event=>{if(!drag||event.pointerId!==drag.id)return;draft=adjust(drag.initial,(event.clientX-drag.bounds.left)/drag.bounds.width-drag.x,(event.clientY-drag.bounds.top)/drag.bounds.height-drag.y,drag.corner);draw()}
+  const up=event=>{if(drag&&event.pointerId===drag.id){if(event.type==='pointercancel')draft=drag.initial;drag=undefined;editor()?.querySelector('[data-prts-region-stage]').style.removeProperty('cursor');draw()}}
+  const key=event=>{
+    if(!active||busy)return
+    if(event.key==='Escape'){event.preventDefault();event.stopPropagation();close();return}
+    if(!draft||!event.target.closest('[data-prts-region-box]')||!['ArrowLeft','ArrowRight','ArrowUp','ArrowDown'].includes(event.key))return
+    event.preventDefault();const step=event.shiftKey ? .05 : .01
+    draft=adjust(draft,event.key==='ArrowLeft'?-step:event.key==='ArrowRight'?step:0,event.key==='ArrowUp'?-step:event.key==='ArrowDown'?step:0,event.target.dataset.prtsRegionHandle);draw()
+  }
+  const cancel=event=>{if(event.target.matches('[data-prts-region-editor]')){event.preventDefault();event.stopPropagation();if(!busy)close()}}
+  section.addEventListener('cancel',cancel,true)
+  const handlers={click,pointerdown:down,pointermove:move,pointerup:up,pointercancel:up,keydown:key}
+  for(const [name,fn] of Object.entries(handlers))section.addEventListener(name,fn)
+  return {update(value,mode){state=value;if(active&&(state[active]?.id!==imageId||mode==='off'||(mode==='full')!==(active==='full')))close()},dispose(){disposed=true;close();section.removeEventListener('cancel',cancel,true);for(const [name,fn] of Object.entries(handlers))section.removeEventListener(name,fn)}}
+}

package/src/client/cursor-adapter.js

@@ -69,7 +69,7 @@ export function createCursorAdapter({ document, window, assets }) {
     const target = event.target?.nodeType === 1 ? event.target : event.target?.parentElement
     if (target === resizeTarget && target.style.cursor === resizeApplied) return
     clearResize()
-    if (!target) return
+    if (!target || target.closest('[data-prts-region-stage]')) return
     const cursor = window.getComputedStyle(target).cursor
     const direction = { 'n-resize': 'ns', 's-resize': 'ns', 'ns-resize': 'ns', 'row-resize': 'ns',
       'e-resize': 'ew', 'w-resize': 'ew', 'ew-resize': 'ew', 'col-resize': 'ew',

package/src/client/custom-background.js

@@ -1,3 +1,5 @@
+import { createBackgroundLayout } from './background-layout.js'
+import { mountBackgroundRegionEditor, backgroundRegionMarkup } from './background-region-editor.js'
 import { opacityDialMarkup, mountOpacityDials } from './opacity-dial.js'
 const BACKGROUND_ENDPOINT = '/prts-theme-api/backgrounds'
 const backgroundLabels = { sidebar: '侧边栏', conversation: '会话正文', full: '完整背景' }
@@ -7,10 +9,12 @@ function backgroundImageUrl(entry) {
 export function createBackgroundStore({ window, document }) {
   let state = { revision: -1, sidebar: null, conversation: null, full: null }, disposed = false, events, refreshing
   const listeners = new Set()
+  const layout = createBackgroundLayout({window,document})
   const abort = window.AbortController ? new window.AbortController() : null
   const apply = value => {
     if (disposed || value.revision < state.revision) return
     state = value
+    layout.update(state)
     for (const slot of Object.keys(backgroundLabels)) {
       const url = backgroundImageUrl(state[slot])
       const root = document.documentElement
@@ -48,12 +52,18 @@ export function createBackgroundStore({ window, document }) {
   window.addEventListener('focus', focus)
   return {
     snapshot: () => state, refresh,
+    setEnabled: value => layout.setEnabled(value),
     subscribe(fn) { listeners.add(fn); fn(state); return () => listeners.delete(fn) },
     async save(slot, image, revision = state.revision) {
       try { return await request({ slot, image, revision }) }
       catch (error) { await refresh().catch(() => {}); throw error }
     },
+    async saveRegion(slot, region, revision = state.revision) {
+      try { return await request({ slot, region, revision }) }
+      catch (error) { await refresh().catch(() => {}); throw error }
+    },
     dispose() {
+      layout.dispose()
       document.documentElement.style.removeProperty('--prts-sidebar-image-ratio')
       disposed = true; abort?.abort(); events?.close(); listeners.clear(); window.removeEventListener('focus', focus)
       for (const slot of Object.keys(backgroundLabels)) {
@@ -71,13 +81,16 @@ export function backgroundMarkup(heroContrastControl = '') {
     </div>
     <div data-prts-background-images hidden>${Object.entries(backgroundLabels).map(([slot,label]) => `<article data-prts-background-card="${slot}" hidden>
       <div data-prts-background-card-heading><strong>${label}</strong><button type="button" data-prts-background-remove="${slot}" aria-label="移除${label}图片" hidden>移除</button></div>
-      <button type="button" data-prts-background-upload="${slot}" aria-label="上传或替换${label}"><span data-prts-background-thumbnail="${slot}" aria-hidden="true"></span><span data-prts-background-caption="${slot}">＋ 选择图片</span></button>
+      <div data-prts-background-image-controls="${slot}"><span data-prts-background-thumbnail="${slot}" aria-hidden="true"></span><span data-prts-background-empty>尚未选择图片</span>
+        <div data-prts-background-image-actions><button type="button" data-prts-background-region-open="${slot}" hidden><svg viewBox="0 0 20 20" aria-hidden="true"><path d="M7 3H3v4m10-4h4v4M3 13v4h4m10-4v4h-4"/><rect x="6.5" y="6.5" width="7" height="7" rx="1.5"/></svg><span>保护区域</span></button><button type="button" data-prts-background-upload="${slot}" aria-label="上传或替换${label}"><svg viewBox="0 0 20 20" aria-hidden="true"><rect x="3" y="3" width="14" height="14" rx="3"/><path d="m4 14 4-4 3 3 2-2 4 4"/><circle cx="12.5" cy="7" r="1"/></svg><span data-prts-background-caption="${slot}">选择图片</span></button></div>
+      </div>
+      ${backgroundRegionMarkup(slot)}
       <input type="file" data-prts-background-file="${slot}" accept="image/png,image/jpeg,image/webp,image/avif" hidden>
     </article>`).join('')}</div>
     <label data-prts-background-shade hidden><span>背景淡化 <output></output></span><input type="range" min="0" max="90" step="5" aria-label="背景淡化程度"><small>调高后背景更淡，接近当前主题底色。</small></label>
     <div data-prts-background-hero-setting hidden>${heroContrastControl}</div>
     ${opacityDialMarkup()}
-    <small data-prts-background-help>支持 PNG / JPEG / WebP / AVIF · 最大 10 MB<br>图片居中铺满，切换模式保留素材，并在当前 DSH 实例同步。</small><p data-prts-background-status role="status"></p>
+    <small data-prts-background-help>支持 PNG / JPEG / WebP / AVIF · 最大 10 MB<br>图片铺满，可框选重要区域优先保留。切换模式保留素材，并在当前 DSH 实例同步。</small><p data-prts-background-status role="status"></p>
   </section>`
 }
 export function mountBackgroundSettings({ panel, window, store, onChange }) {
@@ -86,9 +99,11 @@ export function mountBackgroundSettings({ panel, window, store, onChange }) {
   let disposed = false, busy = false, preferences = {}, state = store.snapshot()
   const status = section.querySelector('[data-prts-background-status]')
   const range = section.querySelector('input[type="range"]')
+  const regions = mountBackgroundRegionEditor({section,window,store})
   const dials = mountOpacityDials({ section, window, onChange })
   function render() {
     dials.update(preferences, state)
+    regions.update(state, preferences.backgroundMode || 'off')
     const mode = preferences.backgroundMode || 'off'
     section.querySelector('[data-prts-background-images]').hidden = mode === 'off'
     section.querySelector('[data-prts-background-shade]').hidden = mode === 'off'
@@ -97,10 +112,11 @@ export function mountBackgroundSettings({ panel, window, store, onChange }) {
     for (const slot of Object.keys(backgroundLabels)) {
       const url = backgroundImageUrl(state[slot])
       section.querySelector(`[data-prts-background-card="${slot}"]`).hidden = mode === 'off' || (mode === 'full') !== (slot === 'full')
-      section.querySelector(`[data-prts-background-upload="${slot}"]`).toggleAttribute('data-has-image', Boolean(url))
+      section.querySelector(`[data-prts-background-image-controls="${slot}"]`).toggleAttribute('data-has-image', Boolean(url))
       section.querySelector(`[data-prts-background-thumbnail="${slot}"]`).style.backgroundImage = url ? `url("${url}")` : ''
-      section.querySelector(`[data-prts-background-caption="${slot}"]`).textContent = url ? '替换图片' : '＋ 选择图片'
+      section.querySelector(`[data-prts-background-caption="${slot}"]`).textContent = url ? '替换图片' : '选择图片'
       section.querySelector(`[data-prts-background-remove="${slot}"]`).hidden = !url
+      section.querySelector(`[data-prts-background-region-open="${slot}"]`).hidden = !url
     }
     for (const button of section.querySelectorAll('[data-prts-background-upload], [data-prts-background-remove]')) button.disabled = busy
   }
@@ -139,6 +155,6 @@ export function mountBackgroundSettings({ panel, window, store, onChange }) {
   const unsubscribe = store.subscribe(value => { state = value; render() })
   return {
     update(value) { preferences = value; render() },
-    dispose() { disposed = true; dials.dispose(); unsubscribe(); section.removeEventListener('click', click); section.removeEventListener('change', change); section.removeEventListener('input', input) },
+    dispose() { disposed = true; regions.dispose(); dials.dispose(); unsubscribe(); section.removeEventListener('click', click); section.removeEventListener('change', change); section.removeEventListener('input', input) },
   }
 }

package/src/client/index.js

@@ -179,6 +179,7 @@ export function applyPrtsPlugin(ctx, environment) {
   }
 
   const disposeVisualState = () => {
+    backgroundStore.setEnabled(false)
     particleField.update({ ...preferences, enabled: false })
     startup.stop({ restoreFocus: false })
     stopStartupReadyWatch()
@@ -201,6 +202,7 @@ export function applyPrtsPlugin(ctx, environment) {
       disposeVisualState()
       return
     }
+    backgroundStore.setEnabled(preferences.backgroundMode !== 'off')
     if (!themeAlreadyApplied) theme.apply(preferences)
     operations ||= createOperationsShell({
       document, window, assets, adapter, hostGeometry, customEmblemStore, avatarStore, backgroundStore,

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-transfer.js

@@ -1,3 +1,4 @@
+import { validBackgroundRegion } from '../shared/background-region.js'
 import { DEFAULT_PREFERENCES, normalizePreferences } from './preferences.js'
 
 export const THEME_PACKAGE_LIMIT = 160 * 1024 * 1024
@@ -22,6 +23,7 @@ export function validateThemePackage(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
@@ -72,10 +74,11 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
     const value = { format: 'prts-theme', version: 1, themeVersion, exportedAt: new Date().toISOString(), preferences: { ...getPreferences() } }
     const states = {}
     if (includeAssets) {
-      const backgrounds = {}, avatars = {}, items = [], ids = new Map()
+      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('背景引用无效')
@@ -102,7 +105,7 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
       }
       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, avatars, emblems: { items, hero, conversation } }
+      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('素材在导出期间发生变化，请重试')
       }
@@ -146,7 +149,7 @@ export function createThemeTransfer({ window, getPreferences, savePreferences, c
         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] }, { slot, image: old.backgrounds[slot] })
+        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 })
       }