kmcom-nuxt-layers 6.0.0 → 6.2.0

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/docs/adr/0003-modular-step-system-replaces-fluid-clamps.md

@@ -0,0 +1,58 @@
+# 0003 — One modular step scale replaces the fluid type and spacing clamps
+
+Status: accepted (2026-10-20)
+
+## Context
+
+Type and spacing were two unrelated sets of hand-tuned `clamp()` ranges: 13 `text-fluid-*`
+utilities (plus 13 `-cq` copies) snapped by `round(down, …, 0.25rem)`, and 8 `--fluid-space-*`
+tokens (plus 7 `-cq` copies). No ratio linked one size to the next, so every new size was
+another clamp to tune, and the `-cq` sets had no consumers. The reference system (matuzo.at,
+analysed in `matuzo-typography-system-1.md`) gets better proportions from two ratios.
+
+## Decision
+
+Every size is a step on a scale:
+
+- **Type:** `font-size = round(--type-base × 1.26^--step, 0.0625rem)`. Base is `1rem` below
+  48rem and `1.2rem` from 48rem; body is step 1 (20 → 24px). `h1` uses a fluid display step,
+  5 → 7 across 360 → 1280px, cast from a length with `tan(atan2(…, 1rem))`. Utilities are
+  `text-step-sm`, `text-step-0` … `text-step-12`, `text-step-display`.
+- **Space:** `--space-* = --space-base × 1.414^n`, with `--space-base` running 11.3 → 16px
+  across 320 → 1280px — one step of growth, not the reference's two (8 → 16px), so phones keep
+  the old token sizes. The `Spacing` union is unchanged; only the values behind it moved.
+- **Grid:** the `grid` layer's `--fs` shares the type scale's endpoint tokens (`--type-min`,
+  `--type-max`) but stays continuous, so its rhythm unit does not inherit the 48rem jump.
+
+It is a parallel namespace: Tailwind's `--text-*`, Nuxt UI's `--ui-*` and the `html` font-size
+are untouched. Tokens are plain `:root` properties, not `@theme`, so `var(--step)` resolves on
+the element using it.
+
+## Consequences
+
+- The top end is coarser: `TypographyHeadline` levels step down from the fluid display step
+  (97/77/61/48/38/30px at 1280px, 51 → 16px at 320px) instead of the old 144/120/96/76/36/24px,
+  which also overflowed phone widths. Plain h1–h6 use the reading scale (display, 3, 2, 1, 0, 0).
+- Step line heights fall smoothly with size (sm 1.5 … body 1.7, h2/h3 1.2 … display 0.95) and
+  now reach components: `useTypography` only emits `leading-*` when asked.
+- Body text grows from 16px to 20/24px, and body line-height from 1.5 to 1.7. Nuxt UI
+  components with explicit `text-*` sizes are unaffected; anything that inherits body size
+  (card bodies, plain prose) grows. Heading defaults skip `[data-slot]` headings, so Nuxt UI's
+  own titles (UModal, USlideover) inherit instead of jumping to a heading step.
+- Every step jumps ×1.2 at 48rem because the base switches there (h1 ≈ 62 → 75px at 768px).
+- Spacing matches the old tokens on phones and stays close on desktop for xs–xl; 2xl/3xl top out
+  smaller than before (64/90px vs 80/112px).
+- `--space-*` steps are substituted at `:root`, so per-subtree spacing retuning is not
+  supported. Type retuning is: `--type-base` and `--type-scale` are read per element.
+- The display step is normalised by `1rem` and its `vw` term is scaled by root / 16px, so its
+  exponent depends only on viewport width and every size grows with a larger root font size.
+  (Unscaled, the exponent fell as the root grew: h1 was only 1.02× larger at a 24px root.)
+- The old `--heading-text-scale-damp` multiplier is gone. As written it enlarged steps ≥ 7
+  under OS text-scale > 100% instead of damping them; a true damp would break "visibly larger
+  at a larger root".
+- `--fs` stays unregistered: a registered `<length>` holding `rem` on `:root`, read by the
+  root's own line-height, is a dependency cycle in Gecko that freezes the grid unit.
+- Nuxt UI prose is retuned onto the scale (typography `app.config.ts`): prose headings take
+  steps (h1 4, h2 3, h3 2, h4 1) and `p`/`li` keep the body's 1.7 leading. Otherwise the
+  24px copy sat at or above Nuxt UI's fixed `text-2xl`/`text-xl` prose headings. This needs
+  `text-step-*` registered as a font-size group in tailwind-merge (`ui.tv.twMergeConfig`).

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/assets/css/tokens/spacing-fluid.css

@@ -1,25 +1,30 @@
 /**
- * Fluid spacing scale — clamp() + cqi container-relative variant, same
- * pattern as layers/typography's fluid type scale (see typography.css).
+ * Fluid spacing scale — one ratio, same idea as typography.css's type scale:
+ *   space = --space-base × --space-scale ^ n
+ * 1.414 ≈ 2^(1/2), so two steps double a gap. --space-base runs 11.3px at ≤320px to 16px
+ * at ≥1280px — one step of growth (√2), not the reference's two (8 → 16px), so phones keep
+ * the old fluid tokens' sizes (xs 8 · md 16 · xl 32 · 3xl 64px at 320px). The rem term in the
+ * middle keeps it zoom-safe (WCAG 1.4.4).
  * Backs the `Spacing` token (layers/core/app/types/tokens.ts) consumed by
- * useLayoutAttrs(). --fluid-space-none is 0, not clamp() — no scaling needed.
+ * useLayoutAttrs(). --space-none is 0, not a step.
+ * Plain :root properties, not @theme: --space-* is not a Tailwind namespace, and
+ * xs/md/xl declared there would risk colliding with --container-* size names.
+ *
+ * Trap: each step substitutes --space-base here at :root, so overriding --space-base
+ * on a subtree does NOT change --space-md inside it. Per-subtree spacing retuning is
+ * not a supported extension point (type retuning is — see typography.css).
  */
 :root {
-  --fluid-space-none: 0px;
-  --fluid-space-xs: clamp(0.5rem, 0.46rem + 0.2vi, 0.625rem);
-  --fluid-space-sm: clamp(0.75rem, 0.7rem + 0.25vi, 1rem);
-  --fluid-space-md: clamp(1rem, 0.9rem + 0.5vi, 1.5rem);
-  --fluid-space-lg: clamp(1.5rem, 1.3rem + 1vi, 2.5rem);
-  --fluid-space-xl: clamp(2rem, 1.7rem + 1.5vi, 3.5rem);
-  --fluid-space-2xl: clamp(3rem, 2.4rem + 3vi, 5rem);
-  --fluid-space-3xl: clamp(4rem, 3rem + 5vi, 7rem);
+  --space-scale: 1.414;
+  --space-base: clamp(0.7071rem, 0.6095rem + 0.4882vw, 1rem);
 
-  /* Container-relative counterparts (cqi) — opt-in inside a `container-type` ancestor. */
-  --fluid-space-xs-cq: clamp(0.5rem, 0.46rem + 2cqi, 0.625rem);
-  --fluid-space-sm-cq: clamp(0.75rem, 0.65rem + 2.5cqi, 1rem);
-  --fluid-space-md-cq: clamp(1rem, 0.8rem + 5cqi, 1.5rem);
-  --fluid-space-lg-cq: clamp(1.5rem, 1.1rem + 10cqi, 2.5rem);
-  --fluid-space-xl-cq: clamp(2rem, 1.4rem + 15cqi, 3.5rem);
-  --fluid-space-2xl-cq: clamp(3rem, 2rem + 25cqi, 5rem);
-  --fluid-space-3xl-cq: clamp(4rem, 2.5rem + 37.5cqi, 7rem);
+  /* n = −1 … 5 */
+  --space-none: 0px;
+  --space-xs: calc(var(--space-base) * pow(var(--space-scale), -1));
+  --space-sm: calc(var(--space-base) * pow(var(--space-scale), 0));
+  --space-md: calc(var(--space-base) * pow(var(--space-scale), 1));
+  --space-lg: calc(var(--space-base) * pow(var(--space-scale), 2));
+  --space-xl: calc(var(--space-base) * pow(var(--space-scale), 3));
+  --space-2xl: calc(var(--space-base) * pow(var(--space-scale), 4));
+  --space-3xl: calc(var(--space-base) * pow(var(--space-scale), 5));
 }

package/layers/core/app/components/Element.test.ts

@@ -69,8 +69,8 @@ describe('Element', () => {
       props: { m: 'md', p: 'lg' },
     })
     const style = wrapper.attributes('style') ?? ''
-    expect(style).toContain('margin: var(--fluid-space-md)')
-    expect(style).toContain('padding: var(--fluid-space-lg)')
+    expect(style).toContain('margin: var(--space-md)')
+    expect(style).toContain('padding: var(--space-lg)')
   })
 
   it('passes componentProps to the resolved component, past a colliding prop name', () => {

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/useLayoutAttrs.test.ts

@@ -1,21 +1,51 @@
+import { readFileSync } from 'node:fs'
+
 import { describe, expect, it } from 'vite-plus/test'
 
+import type { Spacing } from '../types/tokens'
 import { useLayoutAttrs } from './useLayoutAttrs'
 
+// spacingVar() builds the custom-property name by string interpolation, so a token
+// with no matching declaration resolves to an undefined var() — silent in CSS.
+describe('useLayoutAttrs spacing tokens', () => {
+  const css = readFileSync(
+    new URL('../assets/css/tokens/spacing-fluid.css', import.meta.url),
+    'utf8'
+  )
+  // Record, not an array, so typecheck fails if the Spacing union gains a member.
+  const tokens: Record<Exclude<Spacing, 'none'>, true> = {
+    xs: true,
+    sm: true,
+    md: true,
+    lg: true,
+    xl: true,
+    '2xl': true,
+    '3xl': true,
+  }
+
+  it('resolves every token to a property spacing-fluid.css declares', () => {
+    for (const token of Object.keys(tokens) as Spacing[]) {
+      const { style } = useLayoutAttrs(() => ({ gap: token }))
+      const name = /^var\((--[\w-]+)\)$/.exec(String(style.value.gap))?.[1]
+      expect(css).toMatch(new RegExp(`^\\s*${name}:`, 'm'))
+    }
+  })
+})
+
 describe('useLayoutAttrs margin support', () => {
   it('sets margin from a static token', () => {
     const { style } = useLayoutAttrs(() => ({ m: 'md' }))
-    expect(style.value.margin).toBe('var(--fluid-space-md)')
+    expect(style.value.margin).toBe('var(--space-md)')
   })
 
   it('sets marginInline from px-equivalent mx', () => {
     const { style } = useLayoutAttrs(() => ({ mx: 'lg' }))
-    expect(style.value.marginInline).toBe('var(--fluid-space-lg)')
+    expect(style.value.marginInline).toBe('var(--space-lg)')
   })
 
   it('sets marginBlock from my', () => {
     const { style } = useLayoutAttrs(() => ({ my: 'sm' }))
-    expect(style.value.marginBlock).toBe('var(--fluid-space-sm)')
+    expect(style.value.marginBlock).toBe('var(--space-sm)')
   })
 
   it('resolves none to 0px for margin', () => {
@@ -38,8 +68,8 @@ describe('useLayoutAttrs margin support', () => {
       p: 'lg',
     }))
     expect(style.value).toEqual({
-      gap: 'var(--fluid-space-md)',
-      padding: 'var(--fluid-space-lg)',
+      gap: 'var(--space-md)',
+      padding: 'var(--space-lg)',
       alignItems: 'center',
       justifyContent: 'space-between',
     })

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

@@ -47,7 +47,7 @@ function resolveDefault<T>(value: ResponsiveValue<T> | T | undefined): T | undef
 }
 
 function spacingVar(token: Spacing): string {
-  return token === 'none' ? '0px' : `var(--fluid-space-${token})`
+  return token === 'none' ? '0px' : `var(--space-${token})`
 }
 
 function applySpacing(

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,