@ash-qw/dsh-theme-prts 0.1.91 → 0.1.93

package/src/client/particle-field-adapter.js

@@ -326,7 +326,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   const rhodesIndex = Math.max(0, emblemSequence.findIndex(entry => entry.key === 'rhodes-island'))
   const suppliedHeroMask = normalizeEmblemMasks(heroEmblemMask ? [heroEmblemMask] : [], window).get('rhodes-island-hero')
   const empty = { mounted: false, hero: false, side: -1, transition: null, anchor: { horizontalProgress: 0, verticalProgress: 0 }, phase: 'error', error: '徽记资源异常' }
-  if (!document || !window) return { update() {}, inspect: () => empty, dispose() {} }
+  if (!document || !window) return { update() {}, setSchemeTransitionActive() {}, inspect: () => empty, dispose() {} }
 
   let preferences = {}
   let operation
@@ -378,6 +378,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   let side = -1
   let segment = 0
   let transition
+  let traversalOffset = 0
   let pendingSegment
   let transitionStartedAt
   let densityTransition
@@ -394,6 +395,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   let targetPrewarmQueue = []
   let pauseStartedAt
   let hydrationPaused = false
+  let schemeTransitionPaused = false
   let hydrationTimer
   let hydrationFrame
   let hydrationStableFrames = 0
@@ -427,7 +429,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
     : preferences.conversationParticleDensity
   const densityProfile = density => PARTICLE_DENSITY_PROFILES[density] ?? PARTICLE_DENSITY_PROFILES.standard
   const particleRadius = density => densityProfile(density ?? activeDensity()).radius
-  const canRenderFrame = () => documentVisible && canvasVisible && !hydrationPaused && !resizing
+  const canRenderFrame = () => !disposed && documentVisible && canvasVisible && !hydrationPaused && !schemeTransitionPaused && !resizing
   const layoutWidth = () => width
   const layoutHeight = () => height
   const layoutShiftX = () => 0
@@ -554,11 +556,50 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   }
 
 
+  function particleTraversalSpeed(value = preferences) {
+    const numeric = Number(value?.particleTraversalSpeed)
+    return Number.isFinite(numeric) ? clamp(numeric, 0, 2) : 1
+  }
+
+  function currentScrollTop() {
+    return Number(scroller?.scrollTop) || 0
+  }
+
+  function traversalViewport() {
+    return Math.max(1, Number(scroller?.clientHeight) || height)
+  }
+
+  function traversalCoordinate(value = preferences) {
+    return traversalOffset + currentScrollTop() * particleTraversalSpeed(value) / traversalViewport()
+  }
+
   function scrollProgress() {
     if (!scroller) return 0
-    const viewport = Math.max(1, Number(scroller.clientHeight) || height)
-    const raw = (Number(scroller.scrollTop) || 0) / viewport
-    return raw - Math.floor(raw)
+    const coordinate = traversalCoordinate()
+    return coordinate - Math.floor(coordinate)
+  }
+
+  function restoreTraversalFromScroll() {
+    traversalOffset = 0
+    const coordinate = traversalCoordinate()
+    segment = Math.floor(coordinate)
+    side = sideForSegment(segment)
+    pendingSegment = undefined
+    transition = undefined
+    transitionStartedAt = undefined
+  }
+
+  function reanchorTraversal(coordinate = traversalCoordinate()) {
+    if (transition) {
+      const targetSegment = transition.targetSegment
+      side = sideForSegment(targetSegment)
+      transition = undefined
+      transitionStartedAt = undefined
+      commitTransitionTargets(targetSegment, true)
+    }
+    pendingSegment = undefined
+    traversalOffset = coordinate - currentScrollTop() * particleTraversalSpeed() / traversalViewport()
+    if (particles.length) snapParticlesToCurrentLayout()
   }
 
   function anchorFor(sideValue, verticalProgress) {
@@ -1373,6 +1414,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
       return
     }
     const targetSide = sideForSegment(targetSegment)
+    const direction = targetSegment > segment ? 1 : -1
     if (targetSide === side || motionReduced() || phoneStatic()) {
       side = targetSide
       transition = undefined
@@ -1389,7 +1431,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
       ...population,
       fromSide: side,
       toSide: targetSide,
-      direction: targetSegment > segment ? 1 : -1,
+      direction,
       targetSegment,
       progress: 0,
     }
@@ -1398,9 +1440,27 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
     scheduleFrame()
   }
 
+  function retargetTransition(targetSegment) {
+    if (!transition || targetSegment === transition.targetSegment) return
+    const population = prepareTransitionTargets(targetSegment)
+    if (!population.toCount) {
+      reportState({ phase: 'error', error: '徽记资源异常' })
+      return
+    }
+    transition = {
+      ...transition,
+      ...population,
+      toSide: sideForSegment(targetSegment),
+      direction: targetSegment >= segment ? 1 : -1,
+      targetSegment,
+    }
+    pendingSegment = undefined
+  }
+
   function resetTraversal() {
     side = -1
     segment = 0
+    traversalOffset = -currentScrollTop() * particleTraversalSpeed() / traversalViewport()
     pendingSegment = undefined
     queuedDensityCount = undefined
     queuedTargetRefresh = false
@@ -1430,6 +1490,9 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
     heroMarker = undefined
     heroActive = false
     scroller?.removeAttribute('data-prts-hero-active')
+    side = -1
+    segment = 0
+    traversalOffset = -currentScrollTop() * particleTraversalSpeed() / traversalViewport()
     pendingSegment = undefined
     queuedDensityCount = undefined
     queuedTargetRefresh = false
@@ -1474,9 +1537,8 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
       scheduleFrame()
       return
     }
-    const viewport = Math.max(1, Number(scroller.clientHeight) || height)
-    const desiredSegment = Math.floor(((Number(scroller.scrollTop) || 0) + 1) / viewport)
-    if (transition) pendingSegment = desiredSegment
+    const desiredSegment = Math.floor(traversalCoordinate())
+    if (transition) retargetTransition(desiredSegment)
     else if (desiredSegment !== segment) startTransition(desiredSegment)
     scheduleFrame()
   }
@@ -1649,6 +1711,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
     targetCache.clear()
     initializeFieldSize()
     syncHeroState()
+    if (!heroActive) restoreTraversalFromScroll()
     if (!particles.length && maskRecords.length) buildParticles()
     if (context && particles.length) {
       syncCanvasBackingStore()
@@ -1714,8 +1777,19 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
   if (!mediaQuery?.addEventListener) mediaQuery?.addListener?.(mediaListener)
   document.addEventListener?.('visibilitychange', onVisibilityChange)
   return {
+    setSchemeTransitionActive(active) {
+      const next = Boolean(active)
+      if (schemeTransitionPaused === next) return
+      schemeTransitionPaused = next
+      updateFrameGate()
+    },
     update(nextPreferences = {}) {
       const previousPreferences = preferences
+      const traversalSpeedChanged = previousPreferences.particleTraversalSpeed !== undefined
+        && particleTraversalSpeed(previousPreferences) !== particleTraversalSpeed(nextPreferences)
+      const preservedTraversalCoordinate = traversalSpeedChanged && scroller && !heroActive
+        ? traversalCoordinate(previousPreferences)
+        : undefined
       preferences = nextPreferences
       disposed = false
       if (!preferences.enabled) {
@@ -1734,6 +1808,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
       const activeDensityChanged = previousActiveDensity !== undefined && previousActiveDensity !== activeDensity()
       reportState({ requestedPattern: 'orthogonal' })
       if (particles.length && activeDensityChanged) scheduleDensityReassembly(targetParticleCount(), true)
+      if (preservedTraversalCoordinate !== undefined && scroller && !heroActive) reanchorTraversal(preservedTraversalCoordinate)
       if (!mutationObserver && window.MutationObserver && document.body) {
         const observationRoot = document.querySelector('[data-slot="root"]')
           ?? document.querySelector('[data-prts-region="frame"]')
@@ -1771,6 +1846,10 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
         emblemKey: (heroActive || transition?.fromHero ? heroEmblem() : emblemForSegment(segment))?.key,
         nextEmblemKey: transition ? emblemForSegment(transition.targetSegment)?.key : null,
         segment,
+        traversalSpeed: particleTraversalSpeed(),
+        traversalOffset,
+        traversalCoordinate: traversalCoordinate(),
+        traversalProgress: scrollProgress(),
         transition: transition ? {
           fromSide: transition.fromSide,
           toSide: transition.toSide,
@@ -1787,6 +1866,7 @@ export function createParticleFieldAdapter({ document, window, emblem = '', embl
         firstFrameReady: canvas?.hasAttribute('data-prts-particle-ready') === true,
         hydrationPaused,
         sleeping: Boolean(context && particles.length && frame === undefined && canRenderFrame() && !motionReduced() && !phoneStatic()),
+        schemeTransitionPaused,
         pointer: {
           active: pointerActive,
           clientX: pointerClientX,

package/src/client/preferences.js

@@ -10,8 +10,13 @@ export const CONVERSATION_SCALE_FOCUS_CONTRAST_MAX = 100
 export const CONVERSATION_SCALE_FOCUS_CONTRAST_STEP = 10
 export const CONVERSATION_SCALE_FOCUS_CONTRAST_DEFAULT = 70
 
+export const PARTICLE_TRAVERSAL_SPEED_MIN = 0
+export const PARTICLE_TRAVERSAL_SPEED_MAX = 2
+export const PARTICLE_TRAVERSAL_SPEED_STEP = 0.25
+export const PARTICLE_TRAVERSAL_SPEED_DEFAULT = 1
+
 export const DEFAULT_PREFERENCES = Object.freeze({
-  version: 6,
+  version: 8,
   enabled: false,
   preset: 'standard-tactical',
   texture: 'full',
@@ -20,7 +25,9 @@ export const DEFAULT_PREFERENCES = Object.freeze({
   bootAnimation: true,
   conversationParticleDensity: 'sparse',
   heroParticleDensity: 'light',
+  particleTraversalSpeed: PARTICLE_TRAVERSAL_SPEED_DEFAULT,
   particlePattern: 'orthogonal',
+  railDefaultHidden: false,
   conversationScaleMaxDistance: CONVERSATION_SCALE_DISTANCE_DEFAULT,
   conversationScaleFocusContrast: CONVERSATION_SCALE_FOCUS_CONTRAST_DEFAULT,
 })
@@ -60,10 +67,10 @@ export const PARTICLE_DETAIL_LEVELS = Object.freeze({
 })
 export const PREFERENCE_GROUPS = Object.freeze({
   background: Object.freeze(['texture']),
-  particles: Object.freeze(['conversationParticleDensity', 'heroParticleDensity']),
+  particles: Object.freeze(['conversationParticleDensity', 'heroParticleDensity', 'particleTraversalSpeed']),
   material: Object.freeze(['glass']),
   accessibility: Object.freeze(['motion', 'bootAnimation']),
-  navigation: Object.freeze(['conversationScaleMaxDistance', 'conversationScaleFocusContrast']),
+  navigation: Object.freeze(['railDefaultHidden', 'conversationScaleMaxDistance', 'conversationScaleFocusContrast']),
 })
 
 const TEXTURES = new Set(['off', 'restrained', 'full'])
@@ -114,6 +121,13 @@ function scaleFocusContrastOr(value, fallback) {
   return Math.round(clamped / CONVERSATION_SCALE_FOCUS_CONTRAST_STEP) * CONVERSATION_SCALE_FOCUS_CONTRAST_STEP
 }
 
+function particleTraversalSpeedOr(value, fallback) {
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric)) return fallback
+  const clamped = Math.min(PARTICLE_TRAVERSAL_SPEED_MAX, Math.max(PARTICLE_TRAVERSAL_SPEED_MIN, numeric))
+  return Math.round(clamped / PARTICLE_TRAVERSAL_SPEED_STEP) * PARTICLE_TRAVERSAL_SPEED_STEP
+}
+
 function normalizeGlass(input) {
   if (input.glassEnabled === false || input.glass === 'off') return 'off'
   if (input.glass === 'liquid') return 'clear'
@@ -141,7 +155,7 @@ export function normalizePreferences(value) {
   const particlePreset = VISUAL_PRESETS[input.preset] ?? DEFAULT_PREFERENCES
   const legacyDensities = legacyParticleDensities(input)
   const normalized = {
-    version: 6,
+    version: 8,
     enabled: booleanOr(input.enabled, DEFAULT_PREFERENCES.enabled),
     preset: enumOr(migratedPreset, PRESETS, DEFAULT_PREFERENCES.preset),
     texture: enumOr(input.texture, TEXTURES, DEFAULT_PREFERENCES.texture),
@@ -150,7 +164,12 @@ export function normalizePreferences(value) {
     bootAnimation: booleanOr(input.bootAnimation, DEFAULT_PREFERENCES.bootAnimation),
     conversationParticleDensity: enumOr(legacyDensities.conversation, PARTICLE_DENSITIES, particlePreset.conversationParticleDensity),
     heroParticleDensity: enumOr(legacyDensities.hero, PARTICLE_DENSITIES, particlePreset.heroParticleDensity),
+    particleTraversalSpeed: particleTraversalSpeedOr(
+      input.particleTraversalSpeed,
+      DEFAULT_PREFERENCES.particleTraversalSpeed,
+    ),
     particlePattern: 'orthogonal',
+    railDefaultHidden: booleanOr(input.railDefaultHidden, DEFAULT_PREFERENCES.railDefaultHidden),
     conversationScaleMaxDistance: scaleDistanceOr(
       input.conversationScaleMaxDistance,
       DEFAULT_PREFERENCES.conversationScaleMaxDistance,
@@ -205,7 +224,7 @@ export function loadPreferences(storage) {
     const raw = storage?.getItem(PRTS_STORAGE_KEY)
     if (raw === null || raw === undefined) return { ...DEFAULT_PREFERENCES }
     const parsed = JSON.parse(raw)
-    if (![1, 2, 3, 4, 5, 6].includes(parsed?.version)) return { ...DEFAULT_PREFERENCES }
+    if (![1, 2, 3, 4, 5, 6, 7, 8].includes(parsed?.version)) return { ...DEFAULT_PREFERENCES }
     return normalizePreferences(parsed)
   } catch {
     return { ...DEFAULT_PREFERENCES }