kmcom-nuxt-layers 6.1.0 → 6.2.1

package/docs/USAGE.md

@@ -188,14 +188,14 @@ export default defineAppConfig({
 
 ### Available Config Namespaces
 
-| Namespace               | Layer   | Key Options                                                                |
-| ----------------------- | ------- | -------------------------------------------------------------------------- |
-| `coreLayer.loading`     | core    | `enabled`, `minDuration`, `maxDuration`, `background`, `textColor`         |
-| `coreLayer.scrollGuard` | core    | `enabled`, `strict`, `excludeSelectors`, `debug`                           |
-| `coreLayer.errors`      | core    | `logToConsole`, `logToExternal`, `externalUrl`                             |
-| `coreLayer.notFound`    | core    | `icon`, `title`, `description`, `showHomeButton`, `actions`, `suggestions` |
-| `motion`                | motion  | `gsapScrollTrigger`, `lenis.*` (duration, smoothWheel, smoothTouch, etc.)  |
-| `themeLayer`            | theming | `accents`, `defaultAccent`                                                 |
+| Namespace               | Layer   | Key Options                                                                 |
+| ----------------------- | ------- | --------------------------------------------------------------------------- |
+| `coreLayer.loading`     | core    | `enabled`, `minDuration`, `maxDuration`, `label`, `background`, `textColor` |
+| `coreLayer.scrollGuard` | core    | `enabled`, `strict`, `excludeSelectors`, `debug`                            |
+| `coreLayer.errors`      | core    | `logToConsole`, `logToExternal`, `externalUrl`                              |
+| `coreLayer.notFound`    | core    | `icon`, `title`, `description`, `showHomeButton`, `actions`, `suggestions`  |
+| `motion`                | motion  | `gsapScrollTrigger`, `lenis.*` (duration, smoothWheel, smoothTouch, etc.)   |
+| `themeLayer`            | theming | `accents`, `defaultAccent`                                                  |
 
 ## Optional Modules
 

package/layers/core/app/app.config.ts

@@ -33,10 +33,12 @@ export default defineAppConfig({
     loading: {
       // Master toggle - set to false to disable completely
       enabled: true,
-      // Minimum time to display loading screen (prevents flash)
-      minDuration: 3000, // Temporarily increased for testing
-      // Maximum time for simulated progress
+      // Minimum time (ms, from navigation start) the count runs before reaching 100 (prevents flash)
+      minDuration: 1500,
+      // Longest wait (ms, after mount) for fonts and images before finishing anyway
       maxDuration: 3000,
+      // Small caption above the counter - empty string hides it
+      label: 'Loading',
       // Background color
       background: '#0a0a0a',
       // Progress text color
@@ -74,6 +76,7 @@ declare module '@nuxt/schema' {
         enabled?: boolean
         minDuration?: number
         maxDuration?: number
+        label?: string
         background?: string
         textColor?: string
         zIndex?: number

package/layers/core/app/components/LoadingScreen.vue

@@ -1,105 +1,88 @@
 <script setup lang="ts">
-  interface LoadingConfig {
-    enabled?: boolean
-    minDuration?: number
-    maxDuration?: number
-    background?: string
-    textColor?: string
-    zIndex?: number
-  }
+  import type { LoadingScreenState } from '../types/loading'
+  import { resolveLoadingConfig } from '../utils/loading'
 
-  const { isLoading, progress } = useLoading()
-  const config = useAppConfig()
+  // Beat on "100" so the finished count registers before the exit starts
+  const HOLD_MS = 350
+
+  const { enabled, label, background, textColor, zIndex } = resolveLoadingConfig(
+    useAppConfig().coreLayer
+  )
 
-  // Type-safe access to loading config
-  const loadingConfig = computed(() => {
-    const coreLayer = config.coreLayer as { loading?: LoadingConfig }
-    return coreLayer?.loading || {}
-  })
+  const { isLoading, progress } = useLoading()
+  // Written only here; everything else reads it through useLoading().screen
+  const screen = useState<LoadingScreenState>('core:loading:screen', () => 'hidden')
 
-  const minDuration = computed(() => loadingConfig.value?.minDuration || 500)
-  const background = computed(() => loadingConfig.value?.background || '#0a0a0a')
-  const textColor = computed(() => loadingConfig.value?.textColor || '#ffffff')
-  const zIndex = computed(() => loadingConfig.value?.zIndex || 10000)
+  const visible = ref(enabled)
+  if (enabled) screen.value = 'visible'
 
-  // Rounded progress for display
-  const displayProgress = computed(() => Math.round(progress.value))
+  const displayProgress = computed(() => Math.floor(progress.value))
 
-  // Control visibility
-  const visible = ref(true)
-  const hasFinished = ref(false)
+  if (enabled) {
+    useHead({
+      // Lock page scroll from the SSR'd first paint until the exit begins
+      htmlAttrs: {
+        style: computed(() => (screen.value === 'visible' ? 'overflow: hidden' : '')),
+      },
+      // Nothing dismisses the screen without JS - don't let it trap the page
+      noscript: [
+        { innerHTML: '<style>#loading-screen{display:none}html{overflow:auto!important}</style>' },
+      ],
+    })
+  }
 
-  // Watch for loading completion
   watch(
-    [isLoading, progress],
-    ([loading, prog]) => {
-      if (!loading && prog >= 100 && !hasFinished.value) {
-        hasFinished.value = true
-
-        setTimeout(() => {
-          visible.value = false
-        }, minDuration.value)
-      }
+    isLoading,
+    (loading) => {
+      if (loading || !visible.value) return
+      setTimeout(() => {
+        visible.value = false
+        screen.value = 'leaving'
+      }, HOLD_MS)
     },
     { immediate: true }
   )
 </script>
 
 <template>
-  <Transition name="fade">
+  <Transition name="loading-screen" @after-leave="screen = 'hidden'">
     <div
       v-if="visible"
       id="loading-screen"
-      :style="{
-        backgroundColor: background,
-        zIndex: zIndex,
-      }"
+      class="loading-screen"
+      :style="{ backgroundColor: background, color: textColor, zIndex }"
     >
-      <div class="loading-container">
-        <div class="loading-progress" :style="{ color: textColor }">
-          {{ displayProgress }}
-        </div>
+      <div
+        class="loading-content"
+        role="progressbar"
+        :aria-label="label || 'Loading'"
+        aria-valuemin="0"
+        aria-valuemax="100"
+        :aria-valuenow="displayProgress"
+      >
+        <span v-if="label" class="loading-label" aria-hidden="true">{{ label }}</span>
+        <span class="loading-progress" aria-hidden="true"
+          >{{ displayProgress }}<span class="loading-unit">%</span></span
+        >
       </div>
+      <div class="loading-bar" :style="{ transform: `scaleX(${progress / 100})` }" />
     </div>
   </Transition>
 </template>
 
 <style scoped>
-  /* stylelint-disable selector-max-id */
-  .fade-enter-active,
-  .fade-leave-active {
-    transition: opacity 2s cubic-bezier(0.4, 0, 0.2, 1);
-  }
-
-  .fade-enter-from,
-  .fade-leave-to {
-    opacity: 0;
+  .loading-screen {
+    display: grid;
+    position: fixed;
+    inset: 0;
+    container-type: size;
   }
 
-  #loading-screen {
+  .loading-content {
     display: flex;
-    position: fixed;
-    top: 0;
-    left: 0;
     flex-direction: column;
-    justify-content: center;
     align-items: center;
-    width: 100%;
-    height: 100vh;
-  }
-
-  .loading-container {
-    display: grid;
-    container-type: size;
-    width: 100%;
-    height: 100vh;
-  }
-
-  .loading-progress {
     place-self: center;
-    font-weight: 900;
-    font-stretch: ultra-expanded;
-    font-size: clamp(3rem, 35cqw + 1rem, 18rem);
     font-family:
       system-ui,
       -apple-system,
@@ -109,15 +92,98 @@
       'Helvetica Neue',
       Arial,
       sans-serif;
-    text-align: center;
-    /* stylelint-disable-next-line function-disallowed-list */
-    text-shadow: 0 0 20px rgb(0 0 0 / 0.3);
+    /* `backwards`, not `both` - a held end state would block the exit transition below */
+    animation: loading-enter 0.9s cubic-bezier(0.16, 1, 0.3, 1) 0.1s backwards;
+  }
+
+  .loading-label {
+    margin-bottom: 1em;
+    font-weight: 500;
+    font-size: clamp(0.75rem, 1cqw + 0.5rem, 1rem);
+    letter-spacing: 0.3em;
+    text-transform: uppercase;
+    opacity: 0.6;
+  }
+
+  .loading-progress {
+    font-weight: 900;
+    font-stretch: ultra-expanded;
+    font-size: clamp(3rem, 35cqw + 1rem, 18rem);
+    line-height: 0.8;
+    /* Equal-width digits - the counter doesn't jitter as it ticks */
+    font-variant-numeric: tabular-nums;
+  }
+
+  .loading-unit {
+    margin-left: 0.08em;
+    font-weight: 500;
+    font-size: 0.2em;
+    vertical-align: top;
+    opacity: 0.6;
+  }
+
+  .loading-bar {
+    position: absolute;
+    inset: auto 0 0;
+    height: 2px;
+    transform-origin: left;
+    background-color: currentcolor;
+    opacity: 0.5;
   }
 
   @media (width >= 768px) {
-    .loading-progress {
+    .loading-content {
+      align-items: flex-start;
       place-self: end start;
       padding: 2rem;
     }
   }
+
+  @keyframes loading-enter {
+    from {
+      transform: translateY(0.75rem);
+      opacity: 0;
+    }
+  }
+
+  /* Exit: the count lifts away first, then the screen fades to reveal the page */
+  .loading-screen-leave-active {
+    transition: opacity 0.8s cubic-bezier(0.65, 0, 0.35, 1) 0.2s;
+  }
+
+  .loading-screen-leave-to {
+    opacity: 0;
+  }
+
+  .loading-screen-leave-active .loading-content,
+  .loading-screen-leave-active .loading-bar {
+    transition:
+      opacity 0.4s ease-in,
+      transform 0.5s cubic-bezier(0.7, 0, 0.84, 0);
+  }
+
+  .loading-screen-leave-to .loading-content {
+    transform: translateY(-1.5rem);
+    opacity: 0;
+  }
+
+  .loading-screen-leave-to .loading-bar {
+    opacity: 0;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .loading-content {
+      animation-name: loading-fade-in;
+    }
+
+    .loading-screen-leave-to .loading-content {
+      transform: none;
+    }
+  }
+
+  @keyframes loading-fade-in {
+    from {
+      opacity: 0;
+    }
+  }
 </style>

package/layers/core/app/composables/useLoading.ts

@@ -1,65 +1,85 @@
 // composables/useLoading.ts
 
-// Timer IDs are non-reactive and intentionally module-scope (singleton)
-const _timers = {
-  progressInterval: null as ReturnType<typeof setInterval> | null,
-  progressTimeout: null as ReturnType<typeof setTimeout> | null,
+import type { LoadingScreenState } from '../types/loading'
+import { approachProgress, resolveLoadingConfig, trickleProgress } from '../utils/loading'
+
+// Frame-loop state is non-reactive and intentionally module-scope (singleton)
+const _loop = {
+  frame: 0,
+  lastTime: 0,
+  startedAt: 0,
+  target: 0,
+  done: false,
 }
 
 /**
  * Loading state composable for app initialization and async operations
  *
  * Features:
- * - Simulated progress (0-90% auto, then waits)
+ * - Smooth progress: a per-frame loop eases the displayed value toward a simulated target that
+ *   slows as it nears 90%, then counts up to 100 once work is done
+ * - Holds below 100 until `minDuration` has passed, so fast loads don't flash
  * - Shared state across all component instances
  * - Can be disabled via app.config
  * - Works without UI component (headless)
  *
- * @param id - Optional scoped loading ID (for future multi-loading support)
  * @returns Loading state and control methods
  */
 export function useLoading() {
-  const appConfig = useAppConfig()
-  const loadingConfig = (appConfig.coreLayer as { loading?: { enabled?: boolean } } | undefined)
-    ?.loading
-  const isLoading = useState('core:loading', () => loadingConfig?.enabled !== false)
+  const { enabled, minDuration } = resolveLoadingConfig(useAppConfig().coreLayer)
+  const isLoading = useState('core:loading', () => enabled)
   const progress = useState('core:loading:progress', () => 0)
+  const screen = useState<LoadingScreenState>('core:loading:screen', () => 'hidden')
 
-  function startLoading(): void {
-    isLoading.value = true
-    progress.value = 0
+  // Trickle pace follows minDuration: a typical load sits around 60% when it may finish
+  const trickleTau = Math.max(minDuration, 500) * 0.8
 
-    if (_timers.progressInterval) clearInterval(_timers.progressInterval)
-    if (_timers.progressTimeout) clearTimeout(_timers.progressTimeout)
+  function tick(now: number): void {
+    // Cap at one 30fps frame so a main-thread hitch (hydration, a backgrounded tab) is followed
+    // by a quick count, not a leap
+    const dt = Math.min((now - _loop.lastTime) / 1000, 1 / 30)
+    _loop.lastTime = now
 
-    _timers.progressInterval = setInterval(() => {
-      if (progress.value < 90) {
-        const increment = Math.random() * 5 + 3
-        progress.value = Math.min(progress.value + increment, 90)
-        return
-      }
-      if (_timers.progressInterval) {
-        clearInterval(_timers.progressInterval)
-        _timers.progressInterval = null
-      }
-    }, 150)
-  }
+    const elapsed = now - _loop.startedAt
+    _loop.target = Math.max(_loop.target, trickleProgress(elapsed, trickleTau))
+    if (_loop.done && elapsed >= minDuration) _loop.target = 100
 
-  function stopLoading(): void {
-    if (_timers.progressInterval) {
-      clearInterval(_timers.progressInterval)
-      _timers.progressInterval = null
+    progress.value = approachProgress(progress.value, _loop.target, dt)
+
+    if (progress.value >= 100) {
+      _loop.frame = 0
+      isLoading.value = false
+      return
     }
+    _loop.frame = requestAnimationFrame(tick)
+  }
 
-    progress.value = 100
+  function run(): void {
+    if (!import.meta.client || _loop.frame) return
+    _loop.lastTime = performance.now()
+    _loop.frame = requestAnimationFrame(tick)
+  }
 
-    _timers.progressTimeout = setTimeout(() => {
-      isLoading.value = false
-    }, 100)
+  function startLoading(since?: number): void {
+    isLoading.value = true
+    progress.value = 0
+
+    if (!import.meta.client) return
+    cancelAnimationFrame(_loop.frame)
+    _loop.frame = 0
+    _loop.startedAt = since ?? performance.now()
+    _loop.target = 0
+    _loop.done = false
+    run()
+  }
+
+  function stopLoading(): void {
+    _loop.done = true
+    if (isLoading.value) run()
   }
 
   function updateProgress(value: number): void {
-    progress.value = Math.min(Math.max(value, 0), 100)
+    _loop.target = Math.max(_loop.target, Math.min(Math.max(value, 0), 99))
   }
 
   async function withLoading(fn: () => Promise<void>): Promise<void> {
@@ -74,6 +94,7 @@ export function useLoading() {
   return {
     isLoading: readonly(isLoading),
     progress: readonly(progress),
+    screen: readonly(screen),
     startLoading,
     stopLoading,
     updateProgress,

package/layers/core/app/plugins/loading.client.ts

@@ -1,24 +1,17 @@
 // plugins/loading.client.ts
 
-type LoadingConfig = {
-  enabled?: boolean
-  minDuration?: number
-  maxDuration?: number
-  background?: string
-  textColor?: string
-  zIndex?: number
-}
-
-type CoreLayerConfig = {
-  loading?: LoadingConfig
-}
+import { resolveLoadingConfig } from '../utils/loading'
 
 /**
  * Loading screen initialization plugin
  *
- * Runs on app mount (client-side only) to:
- * 1. Start simulated progress on page load
- * 2. Stop loading when app is fully mounted and hydrated
+ * Client-side only. Once the app has mounted (hydration done) it:
+ * 1. Starts the progress count, timed from navigation start - the SSR'd screen has been up
+ *    since first paint, so the count catches up smoothly rather than starting late
+ * 2. Waits for fonts and the initial page's images, capped at `maxDuration`
+ * 3. Marks loading done - the count then finishes to 100 before the screen exits
+ *
+ * Starting after mount keeps the counter at the SSR'd 0 through hydration (no mismatch).
  *
  * Configuration via app.config.ts:
  * - Set `coreLayer.loading.enabled: false` to disable
@@ -26,26 +19,27 @@ type CoreLayerConfig = {
 export default defineNuxtPlugin({
   name: 'core:loading',
   setup(nuxtApp) {
-    const config = useAppConfig()
-    const coreLayer = config.coreLayer as CoreLayerConfig | undefined
+    const { enabled, maxDuration } = resolveLoadingConfig(useAppConfig().coreLayer)
 
     // Check if loading is enabled
-    if (coreLayer?.loading?.enabled === false) {
+    if (!enabled) {
       return // Disabled, skip initialization
     }
 
     const { startLoading, stopLoading } = useLoading()
 
-    // Start loading immediately on plugin load
-    startLoading()
-
-    // Stop loading when app is fully mounted
+    // Not awaited: app:mounted handlers run serially, so waiting here would hold up other layers
     nuxtApp.hook('app:mounted', () => {
-      // Add a small delay to ensure LoadingScreen component has mounted
-      // and is visible before we stop loading
-      setTimeout(() => {
-        stopLoading()
-      }, 500) // 500ms delay to ensure component is visible
+      startLoading(0)
+      void Promise.race([
+        Promise.all([pageLoaded(), document.fonts?.ready]),
+        new Promise((resolve) => setTimeout(resolve, maxDuration)),
+      ]).then(stopLoading)
     })
   },
 })
+
+function pageLoaded(): Promise<unknown> {
+  if (document.readyState === 'complete') return Promise.resolve()
+  return new Promise((resolve) => window.addEventListener('load', resolve, { once: true }))
+}

package/layers/core/app/types/loading.ts

@@ -6,10 +6,12 @@
 export type LoadingConfig = {
   /** Master toggle - set to false to disable completely */
   enabled: boolean
-  /** Minimum time to display loading screen (prevents flash) */
+  /** Minimum time (ms, from navigation start) the count runs before it may reach 100 */
   minDuration: number
-  /** Maximum time for simulated progress */
+  /** Longest wait (ms, after the app mounts) for fonts and images before finishing anyway */
   maxDuration: number
+  /** Small caption above the counter - empty string hides it */
+  label: string
   /** Background color */
   background: string
   /** Progress text color */
@@ -18,6 +20,12 @@ export type LoadingConfig = {
   zIndex: number
 }
 
+/**
+ * Boot loading screen lifecycle, shared so other layers can hold their own motion until the
+ * page is revealed: covering the page → playing its exit → gone (or never mounted)
+ */
+export type LoadingScreenState = 'visible' | 'leaving' | 'hidden'
+
 /**
  * Loading state interface
  */
@@ -32,15 +40,17 @@ export type LoadingState = {
  * Loading composable return interface
  */
 export type UseLoadingReturn = {
-  /** Current loading state (readonly) */
+  /** True until the displayed progress has counted up to 100 (readonly) */
   isLoading: Readonly<Ref<boolean>>
-  /** Progress percentage 0-100 (readonly) */
+  /** Displayed progress 0-100, eased every frame - never jumps or moves backwards (readonly) */
   progress: Readonly<Ref<number>>
-  /** Start loading with simulated progress */
-  startLoading: () => void
-  /** Stop loading and jump to 100% */
+  /** Boot loading screen lifecycle (readonly) */
+  screen: Readonly<Ref<LoadingScreenState>>
+  /** Start simulated progress, timed from `since` (a `performance.now()` value; default now) */
+  startLoading: (since?: number) => void
+  /** Mark work done - the count finishes to 100 once `minDuration` has passed */
   stopLoading: () => void
-  /** Manually update progress (0-100) */
+  /** Raise the progress floor (0-99) - only `stopLoading` completes */
   updateProgress: (value: number) => void
   /** Execute async function with loading state */
   withLoading: (fn: () => Promise<void>) => Promise<void>

package/layers/core/app/utils/index.ts

@@ -6,5 +6,6 @@
 
 export * from './browserInfo'
 export * from './featureClasses'
+export * from './loading'
 export * from './scrollGuardClamp'
 export * from './styleToTailwindClasses'

package/layers/core/app/utils/loading.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vite-plus/test'
+
+import { approachProgress, resolveLoadingConfig, trickleProgress } from './loading'
+
+const FRAME = 1 / 60
+
+describe('resolveLoadingConfig', () => {
+  it('fills unset keys with defaults but keeps falsy values that were set', () => {
+    expect(resolveLoadingConfig(undefined)).toMatchObject({ enabled: true, minDuration: 1500 })
+    expect(resolveLoadingConfig({ loading: { minDuration: 0, label: '' } })).toMatchObject({
+      enabled: true,
+      minDuration: 0,
+      label: '',
+    })
+  })
+})
+
+describe('trickleProgress', () => {
+  it('starts at 0, rises with time, and stays below the cap', () => {
+    expect(trickleProgress(0, 1200)).toBe(0)
+    expect(trickleProgress(-500, 1200)).toBe(0)
+    expect(trickleProgress(1200, 1200)).toBeGreaterThan(trickleProgress(600, 1200))
+    expect(trickleProgress(60_000, 1200)).toBeLessThanOrEqual(90)
+  })
+})
+
+describe('approachProgress', () => {
+  it('counts 0 → 100 in small per-frame steps and lands exactly on the target', () => {
+    let current = 0
+    let frames = 0
+    while (current < 100) {
+      const next = approachProgress(current, 100, FRAME)
+      expect(next).toBeGreaterThan(current)
+      expect(Math.floor(next) - Math.floor(current)).toBeLessThanOrEqual(3)
+      current = next
+      frames++
+    }
+    expect(current).toBe(100)
+    // A visible count of at least ~0.7s, not a jump
+    expect(frames).toBeGreaterThan(40)
+  })
+
+  it('never moves backwards or overshoots', () => {
+    expect(approachProgress(60, 40, FRAME)).toBe(60)
+    expect(approachProgress(0, 90, -0.008)).toBe(0)
+    expect(approachProgress(99.9, 100, 1)).toBe(100)
+  })
+})

package/layers/core/app/utils/loading.ts

@@ -0,0 +1,53 @@
+import type { LoadingConfig } from '../types/loading'
+
+/** Fallbacks for keys app.config leaves unset - core's app.config ships the same values. */
+const LOADING_DEFAULTS: LoadingConfig = {
+  enabled: true,
+  minDuration: 1500,
+  maxDuration: 3000,
+  label: 'Loading',
+  background: '#0a0a0a',
+  textColor: '#ffffff',
+  zIndex: 10000,
+}
+
+/** Reads `coreLayer.loading` from app config, filling unset keys with the defaults. */
+export function resolveLoadingConfig(coreLayer: unknown): LoadingConfig {
+  const loading = (coreLayer as { loading?: Partial<LoadingConfig> } | undefined)?.loading
+  return { ...LOADING_DEFAULTS, ...loading }
+}
+
+/*
+ * Pure easing math behind `useLoading`'s progress counter. `useLoading` runs these once per
+ * animation frame: `trickleProgress` moves the target, `approachProgress` moves the displayed
+ * value toward it, so the counter climbs smoothly instead of jumping between random values.
+ */
+
+/** Simulated progress stays below this until loading actually finishes. */
+const TRICKLE_CAP = 90
+/** Time constant (s) of the displayed value's exponential ease toward its target. */
+const EASE = 0.15
+/** Speed band (%/s) for the displayed value: no crawling at the tail, no leaps on big jumps. */
+const MIN_SPEED = 24
+const MAX_SPEED = 140
+
+/**
+ * Simulated progress `elapsed` ms after loading started: quick at first, then slowing as it
+ * approaches the cap. `tau` (ms) sets the pace — ~63% of the cap is reached after `tau`.
+ */
+export function trickleProgress(elapsed: number, tau: number): number {
+  return TRICKLE_CAP * (1 - Math.exp(-Math.max(elapsed, 0) / tau))
+}
+
+/**
+ * Advances `current` toward `target` over `dt` seconds. Eases out as the gap closes, within the
+ * speed band, and never moves backwards or past `target`. A rAF timestamp can precede the
+ * `performance.now()` the loop started from, so `dt <= 0` is a no-op rather than a step back.
+ */
+export function approachProgress(current: number, target: number, dt: number): number {
+  const gap = target - current
+  if (gap <= 0 || dt <= 0) return current
+  const eased = gap * (1 - Math.exp(-dt / EASE))
+  const step = Math.min(Math.max(eased, MIN_SPEED * dt), MAX_SPEED * dt)
+  return Math.min(current + step, target)
+}

package/layers/motion/scroll/app/plugins/locomotive-scroll.client.ts

@@ -1,3 +1,4 @@
+import { gsap } from 'gsap'
 import { ScrollTrigger } from 'gsap/ScrollTrigger'
 import LocomotiveScroll from 'locomotive-scroll'
 
@@ -15,10 +16,19 @@ export default defineNuxtPlugin({
     })
 
     const instance = shallowRef<LocomotiveScroll | null>(null)
+    const { screen } = useLoading()
+
+    // Under the loading screen Lenis must be stopped, not just left un-started: an unstopped
+    // Lenis still takes wheel/touch input and replays it as a jump once it starts
+    function holdForLoadingScreen(scroll: LocomotiveScroll) {
+      if (screen.value === 'visible') scroll.lenisInstance?.stop()
+    }
 
     function init() {
       if (instance.value) return
       instance.value = new LocomotiveScroll({
+        // Under core's boot loading screen, wait for its exit to start (watcher below)
+        autoStart: screen.value !== 'visible',
         lenisOptions: {
           lerp: 0.1,
           smoothWheel: true,
@@ -33,6 +43,7 @@ export default defineNuxtPlugin({
           ScrollTrigger.update()
         },
       })
+      holdForLoadingScreen(instance.value)
 
       // ScrollTriggers created before Lenis exists (page:finish can fire first)
       // refresh against a null instance — remeasure once real layout settles.
@@ -45,6 +56,25 @@ export default defineNuxtPlugin({
       instance.value = null
     }
 
+    // Hold motion until core's boot loading screen reveals the page: GSAP stays paused while the
+    // screen is up, so entrance animations play once it's gone; scrolling unlocks as it exits.
+    // Without a mounted screen the state stays 'hidden' and GSAP is never touched.
+    watch(
+      screen,
+      (state) => {
+        gsap.globalTimeline.paused(state !== 'hidden')
+
+        if (state !== 'leaving') return
+        instance.value?.start()
+        // Remeasure once the screen's scroll lock is off the page
+        requestAnimationFrame(() => {
+          instance.value?.resize()
+          ScrollTrigger.refresh()
+        })
+      },
+      { immediate: screen.value !== 'hidden' }
+    )
+
     const router = useRouter()
     const appConfig = useAppConfig()
     const scrollConfig = appConfig.scroll as { smoothScroll?: boolean | string[] } | undefined

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kmcom-nuxt-layers",
   "private": false,
-  "version": "6.1.0",
+  "version": "6.2.1",
   "description": "Composable Nuxt 4 layers for building scalable Vue applications",
   "exports": {
     "./layers/core": "./layers/core/nuxt.config.ts",