kmcom-nuxt-layers 6.4.0 → 6.5.0

package/docs/MIGRATION-v6.5.0.md

@@ -0,0 +1,87 @@
+# Migration Guide — v6.4.x → v6.5.0
+
+**Audience:** an AI coding agent (or developer) updating a downstream Nuxt app that consumes these
+layers.
+**What changed:** layers stop making app-wide choices for you, the published package declares the
+dependencies its layers import, and two diagnostic API routes are now dev-only.
+
+Work top to bottom. Each change has a **Detect** step and an **Apply** step; skip anything Detect
+doesn't find.
+
+## 0. Preconditions
+
+- Update the package to `^6.5.0`, reinstall, run `npx nuxt prepare`.
+
+---
+
+## Required changes
+
+### 1. `core` no longer sets `future.compatibilityVersion: 5` or `devtools`
+
+Layer config merges into the app, so `core` was opting every consumer into Nuxt 5 behaviour and
+forcing devtools on. Both are now the app's call.
+
+**Detect:** your app's `nuxt.config.ts` has no `future.compatibilityVersion`.
+
+**Apply:** to keep the behaviour you had on v6.4, add:
+
+```ts
+export default defineNuxtConfig({
+  future: { compatibilityVersion: 5 },
+  devtools: { enabled: true },
+})
+```
+
+### 2. Install the peers for the layers you use
+
+The root package now lists these as optional peer dependencies. They were always imported at
+runtime; previously the app only worked if something else happened to install them.
+
+**Detect:** you extend `mailer`/`forms`, `database`, `auth` or `feeds`.
+
+**Apply:**
+
+| Layer              | Install                                    |
+| ------------------ | ------------------------------------------ |
+| `mailer` / `forms` | `resend hookable` (plus `zod` for `forms`) |
+| `database`         | `drizzle-orm @neondatabase/serverless`     |
+| `auth`             | `nuxt-auth-utils`                          |
+| `feeds`            | `feed`                                     |
+
+---
+
+## Behaviour changes (no action unless you rely on them)
+
+- **`GET /api/forms/status`** returns only `{ configured }` outside dev. `emailFrom`/`emailTo` are
+  dev-only because `emailTo` is the private inbox every contact submission goes to.
+- **`GET /api/metadata/status`** returns 404 outside dev. Each call ran a live search on every
+  provider, spending real API quota.
+- **`GET /api/metadata/search`** rejects an unknown `mediaType` or a non-positive `limit` with a
+  400, and caps `limit` at 50.
+- **`feeds`** now always extends `core` and `content`. The `FEEDS_STANDALONE` env var is gone.
+- **`routing`**: `layerDefaultDeny` now works in npm consumers. Layer pages were never tagged
+  before, so a layer page without a `feature` meta will now be denied if you enabled
+  `layerDefaultDeny`.
+- **`auth`** middleware redirects to `/auth/github` with `external: true`, so client-side
+  navigation reaches the OAuth route instead of the 404 page.
+- **`forms`**: `contactSchema` moved from `app/utils/` to `shared/utils/`. Import it from
+  `#layers/forms/shared/utils/contact-schema` if you imported it by path.
+- **`@nuxt/eslint`** loads only when installed, so apps without it no longer fail outside
+  production.
+- **`feeds`** and **`routing`** server routes now read your `app.config.ts` when Nitro
+  auto-imports are on. They imported `useAppConfig` from `nitropack/runtime`, which never sees
+  it, so feeds were titled "My Site", linked to the request origin (localhost when prerendered)
+  and ignored `feedsLayer`, and `/api/feature-flags` returned `{}`. They now use `site`,
+  `feedsLayer` and `routingLayer.features`. With `experimental.nitroAutoImports: false` (the
+  Nuxt 5 default) Nuxt can't evaluate app.config.ts in Nitro, so they keep the old defaults;
+  set `nitroAutoImports: true` to get your values. Layer server code reads app config through
+  core's `readServerAppConfig()`.
+- **`core` loading screen** stops being a timer. `minDuration` defaults to `0` (was `1500`) and
+  `maxDuration` to `1500` (was `3000`). A new `showAfter` (default `400` ms) keeps the screen
+  hidden on fast loads. The percentage moves at real milestones (hydrated, fonts ready, page
+  loaded) instead of a simulated trickle; `trickleProgress` is gone. Under
+  `prefers-reduced-motion` the screen is hidden and loading ends on mount. `useLoading()` adds
+  `finishNow()` and `skipped`. Set `minDuration: 1500` to keep the old pacing.
+- **`theming`**: the Reduce Motion switch also ends the boot loading screen.
+- **`forms`**: `contactSchema` accepts any non-blank name (was 3+ characters), so short names
+  like Li or Ng get through.

package/docs/MIGRATION.md

@@ -1,4 +1,5 @@
-> **Upgrading?** v6.3 → v6.4: [`MIGRATION-v6.4.0.md`](./MIGRATION-v6.4.0.md) · v6.2 → v6.3:
+> **Upgrading?** v6.4 → v6.5: [`MIGRATION-v6.5.0.md`](./MIGRATION-v6.5.0.md) · v6.3 → v6.4:
+> [`MIGRATION-v6.4.0.md`](./MIGRATION-v6.4.0.md) · v6.2 → v6.3:
 > [`MIGRATION-v6.3.0.md`](./MIGRATION-v6.3.0.md). The guides below cover older versions.
 
 # Agent Migration Guide — Update an app to nuxt-layers v2.2.x

package/docs/USAGE.md

@@ -93,12 +93,21 @@ npm install gsap locomotive-scroll
 # canvas / shader
 npm install three @tresjs/nuxt @tresjs/core @tresjs/cientos @tresjs/post-processing
 
-# forms
-npm install zod
+# forms / mailer
+npm install zod resend hookable
+
+# database
+npm install drizzle-orm @neondatabase/serverless
+
+# auth
+npm install nuxt-auth-utils
 
 # content
 npm install @nuxt/content better-sqlite3
 
+# feeds
+npm install feed
+
 # scripts (baseline-status badge)
 npm install @nuxt/scripts baseline-status
 ```
@@ -188,14 +197,30 @@ export default defineAppConfig({
 
 ### Available Config Namespaces
 
-| 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`                                                  |
+| Namespace               | Layer   | Key Options                                                                              |
+| ----------------------- | ------- | ---------------------------------------------------------------------------------------- |
+| `coreLayer.loading`     | core    | `enabled`, `minDuration`, `maxDuration`, `showAfter`, `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`                                                               |
+
+### Overriding Layer Components
+
+Layer components are auto-imported by file name, and the app always wins: a component in your
+app with the same name replaces the layer's copy everywhere, including where other layers render
+it. These unprefixed names are the ones most likely to collide by accident:
+
+| Component                              | Layer  | Notes                                                          |
+| -------------------------------------- | ------ | -------------------------------------------------------------- |
+| `LoadingScreen`                        | core   | Meant to be overridable (custom boot screen)                   |
+| `ElementTw`                            | core   | Rendered by typography and visual — shadowing changes them too |
+| `Element`, `AppContainer`              | core   | Primitives; pick another name for app components               |
+| `ErrorBoundary`                        | core   | Pick another name for app boundaries                           |
+| `HStack`, `VStack`, `ZStack`, `Spacer` | layout | Primitives; pick another name for app components               |
+
+Override one on purpose by creating the same-named file in your `app/components/`.
 
 ## Optional Modules
 

package/layers/content/app/components/content/Figure.vue

@@ -16,7 +16,7 @@
 
 <template>
   <figure class="my-6">
-    <img :src :alt :width :height class="w-full rounded-lg" />
+    <img :src :alt :width :height loading="lazy" decoding="async" class="w-full rounded-lg" />
     <figcaption v-if="caption" class="text-muted mt-2 text-center text-sm italic">
       {{ caption }}
     </figcaption>

package/layers/content/app/composables/useContentSection.ts

@@ -4,6 +4,6 @@ import type { ContentLayerConfig } from '../types/content'
 export function useContentSection(section: keyof NonNullable<ContentLayerConfig['sections']>) {
   const contentLayer = useAppConfig().contentLayer as ContentLayerConfig | undefined
   if (contentLayer?.sections?.[section] === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+    throw createError({ status: 404, statusText: 'Not Found' })
   }
 }

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

@@ -33,10 +33,13 @@ export default defineAppConfig({
     loading: {
       // Opt in: app.vue renders LoadingScreen for every app, so it stays off unless enabled
       enabled: false,
-      // Minimum time (ms, from navigation start) the count runs before reaching 100 (prevents flash)
-      minDuration: 1500,
+      // Minimum time (ms, from navigation start) before the count may reach 100 - 0 finishes
+      // as soon as the work does; raise it only for a deliberate brand moment
+      minDuration: 0,
       // Longest wait (ms, after mount) for fonts and images before finishing anyway
-      maxDuration: 3000,
+      maxDuration: 1500,
+      // Delay (ms, from first paint) before the screen fades in - faster loads never see it
+      showAfter: 400,
       // Small caption above the counter - empty string hides it
       label: 'Loading',
       // Background color
@@ -76,6 +79,7 @@ declare module '@nuxt/schema' {
         enabled?: boolean
         minDuration?: number
         maxDuration?: number
+        showAfter?: number
         label?: string
         background?: string
         textColor?: string

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

@@ -5,16 +5,18 @@
   // Beat on "100" so the finished count registers before the exit starts
   const HOLD_MS = 350
 
-  const { enabled, label, background, textColor, zIndex } = resolveLoadingConfig(
+  const { enabled, label, background, textColor, zIndex, showAfter } = resolveLoadingConfig(
     useAppConfig().coreLayer
   )
 
-  const { isLoading, progress } = useLoading()
+  const { isLoading, progress, skipped } = useLoading()
   // Written only here; everything else reads it through useLoading().screen
   const screen = useState<LoadingScreenState>('core:loading:screen', () => 'hidden')
 
   const visible = ref(enabled)
   if (enabled) screen.value = 'visible'
+  // Leave without the beat or the exit animation: skipped, or done before it ever faded in
+  const instant = ref(false)
 
   const displayProgress = computed(() => Math.floor(progress.value))
 
@@ -35,22 +37,31 @@
     isLoading,
     (loading) => {
       if (loading || !visible.value) return
-      setTimeout(() => {
-        visible.value = false
-        screen.value = 'leaving'
-      }, HOLD_MS)
+      instant.value = skipped.value || performance.now() < showAfter
+      setTimeout(
+        () => {
+          visible.value = false
+          screen.value = 'leaving'
+        },
+        instant.value ? 0 : HOLD_MS
+      )
     },
     { immediate: true }
   )
 </script>
 
 <template>
-  <Transition name="loading-screen" @after-leave="screen = 'hidden'">
+  <Transition name="loading-screen" :css="!instant" @after-leave="screen = 'hidden'">
     <div
       v-if="visible"
       id="loading-screen"
       class="loading-screen"
-      :style="{ backgroundColor: background, color: textColor, zIndex }"
+      :style="{
+        backgroundColor: background,
+        color: textColor,
+        zIndex,
+        '--loading-show-after': `${showAfter}ms`,
+      }"
     >
       <div
         class="loading-content"
@@ -76,6 +87,10 @@
     position: fixed;
     inset: 0;
     container-type: size;
+
+    /* Fast loads never see it: hidden and click-through until showAfter has passed.
+       `backwards`, not `both` - a held end state would block the exit transition below */
+    animation: loading-show 0.2s ease var(--loading-show-after, 0ms) backwards;
   }
 
   .loading-content {
@@ -94,7 +109,8 @@
       sans-serif;
 
     /* `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;
+    animation: loading-enter 0.9s cubic-bezier(0.16, 1, 0.3, 1)
+      calc(var(--loading-show-after, 0ms) + 0.1s) backwards;
   }
 
   .loading-label {
@@ -141,6 +157,13 @@
     }
   }
 
+  @keyframes loading-show {
+    from {
+      visibility: hidden;
+      opacity: 0;
+    }
+  }
+
   @keyframes loading-enter {
     from {
       transform: translateY(0.75rem);
@@ -173,19 +196,10 @@
     opacity: 0;
   }
 
+  /* No screen under reduced motion - the plugin ends loading on mount (finishNow) */
   @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;
+    .loading-screen {
+      display: none;
     }
   }
 </style>

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

@@ -78,11 +78,11 @@ export function useCache() {
     try {
       const cacheNames = await caches.keys()
       await Promise.all(cacheNames.map((name) => caches.delete(name)))
-      if (process.env.NODE_ENV === 'development') {
+      if (import.meta.dev) {
         console.log('[useCache] All caches cleared')
       }
     } catch (error) {
-      if (process.env.NODE_ENV === 'development') {
+      if (import.meta.dev) {
         console.error('[useCache] Failed to clear cache:', error)
       }
     }

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

@@ -73,7 +73,7 @@ export function useErrorLog() {
     }
 
     // Console logging (development only by default)
-    if (config.value.logToConsole && import.meta.dev && process.env.NODE_ENV === 'development') {
+    if (config.value.logToConsole && import.meta.dev) {
       console.group('🔴 Error Logged')
 
       console.error('Error:', errorObj)
@@ -96,7 +96,7 @@ export function useErrorLog() {
     const { externalUrl, externalToken } = config.value
 
     if (!externalUrl) {
-      if (process.env.NODE_ENV === 'development') {
+      if (import.meta.dev) {
         console.warn('Error logging enabled but no externalUrl configured')
       }
       return
@@ -120,7 +120,7 @@ export function useErrorLog() {
       })
     } catch (loggingError) {
       // Don't let logging errors crash the app
-      if (import.meta.dev && process.env.NODE_ENV === 'development') {
+      if (import.meta.dev) {
         console.error('Failed to send error to external service:', loggingError)
       }
     }
@@ -130,7 +130,7 @@ export function useErrorLog() {
    * Log a warning (non-critical error)
    */
   const logWarning = (message: string, context?: ErrorContext) => {
-    if (config.value.logToConsole && import.meta.dev && process.env.NODE_ENV === 'development') {
+    if (config.value.logToConsole && import.meta.dev) {
       console.warn('⚠️  Warning:', message, context)
     }
   }
@@ -139,7 +139,7 @@ export function useErrorLog() {
    * Log info (for debugging)
    */
   const logInfo = (message: string, data?: unknown) => {
-    if (config.value.logToConsole && import.meta.dev && process.env.NODE_ENV === 'development') {
+    if (config.value.logToConsole && import.meta.dev) {
       console.log('ℹ️  Info:', message, data)
     }
   }

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

@@ -1,7 +1,7 @@
 // composables/useLoading.ts
 
 import type { LoadingScreenState } from '../types/loading'
-import { approachProgress, resolveLoadingConfig, trickleProgress } from '../utils/loading'
+import { approachProgress, resolveLoadingConfig } from '../utils/loading'
 
 // Frame-loop state is non-reactive and intentionally module-scope (singleton)
 const _loop = {
@@ -16,9 +16,10 @@ const _loop = {
  * Loading state composable for app initialization and async operations
  *
  * Features:
- * - 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
+ * - Real progress: callers raise the target at real milestones (`updateProgress`) and a per-frame
+ *   loop eases the displayed value toward it, then counts up to 100 once work is done
+ * - Optional `minDuration` hold before 100 (default 0: finish as soon as the work does)
+ * - `finishNow()` ends the boot screen at once, e.g. for reduced motion
  * - Shared state across all component instances
  * - Can be disabled via app.config
  * - Works without UI component (headless)
@@ -30,9 +31,8 @@ export function useLoading() {
   const isLoading = useState('core:loading', () => enabled)
   const progress = useState('core:loading:progress', () => 0)
   const screen = useState<LoadingScreenState>('core:loading:screen', () => 'hidden')
-
-  // Trickle pace follows minDuration: a typical load sits around 60% when it may finish
-  const trickleTau = Math.max(minDuration, 500) * 0.8
+  // Set by finishNow: the boot screen leaves at once, without its beat or exit animation
+  const skipped = useState('core:loading:skipped', () => false)
 
   function tick(now: number): void {
     // Cap at one 30fps frame so a main-thread hitch (hydration, a backgrounded tab) is followed
@@ -40,9 +40,7 @@ export function useLoading() {
     const dt = Math.min((now - _loop.lastTime) / 1000, 1 / 30)
     _loop.lastTime = now
 
-    const elapsed = now - _loop.startedAt
-    _loop.target = Math.max(_loop.target, trickleProgress(elapsed, trickleTau))
-    if (_loop.done && elapsed >= minDuration) _loop.target = 100
+    if (_loop.done && now - _loop.startedAt >= minDuration) _loop.target = 100
 
     progress.value = approachProgress(progress.value, _loop.target, dt)
 
@@ -82,6 +80,15 @@ export function useLoading() {
     _loop.target = Math.max(_loop.target, Math.min(Math.max(value, 0), 99))
   }
 
+  function finishNow(): void {
+    skipped.value = true
+    if (import.meta.client) cancelAnimationFrame(_loop.frame)
+    _loop.frame = 0
+    _loop.done = true
+    progress.value = 100
+    isLoading.value = false
+  }
+
   async function withLoading(fn: () => Promise<void>): Promise<void> {
     startLoading()
     try {
@@ -95,9 +102,11 @@ export function useLoading() {
     isLoading: readonly(isLoading),
     progress: readonly(progress),
     screen: readonly(screen),
+    skipped: readonly(skipped),
     startLoading,
     stopLoading,
     updateProgress,
+    finishNow,
     withLoading,
   }
 }

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

@@ -6,12 +6,13 @@ import { resolveLoadingConfig } from '../utils/loading'
  * Loading screen initialization plugin
  *
  * 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
+ * 1. Starts the count, timed from navigation start, and moves it at real milestones:
+ *    hydrated (50), fonts ready (75)
  * 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).
+ * With `prefers-reduced-motion: reduce` it ends at once instead: CSS hides the screen.
  *
  * Configuration via app.config.ts:
  * - Set `coreLayer.loading.enabled: false` to disable
@@ -26,11 +27,18 @@ export default defineNuxtPlugin({
       return // Disabled, skip initialization
     }
 
-    const { startLoading, stopLoading } = useLoading()
+    const { isLoading, startLoading, stopLoading, updateProgress, finishNow } = useLoading()
 
     // Not awaited: app:mounted handlers run serially, so waiting here would hold up other layers
     nuxtApp.hook('app:mounted', () => {
+      // CSS hides the screen under reduced motion, so don't hold the page (GSAP, scrolling) for it.
+      // After hydration, not in setup: state changes before then would fail to hydrate
+      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return finishNow()
+      // Already ended by another layer, e.g. the theme's Reduce Motion switch
+      if (!isLoading.value) return
       startLoading(0)
+      updateProgress(50)
+      void document.fonts?.ready.then(() => updateProgress(75))
       void Promise.race([
         Promise.all([pageLoaded(), document.fonts?.ready]),
         new Promise((resolve) => setTimeout(resolve, maxDuration)),

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

@@ -6,10 +6,13 @@
 export type LoadingConfig = {
   /** Master toggle - set to false to disable completely */
   enabled: boolean
-  /** Minimum time (ms, from navigation start) the count runs before it may reach 100 */
+  /** Minimum time (ms, from navigation start) before the count may reach 100 - 0 finishes
+   * as soon as the work does */
   minDuration: number
   /** Longest wait (ms, after the app mounts) for fonts and images before finishing anyway */
   maxDuration: number
+  /** Delay (ms, from first paint) before the screen fades in - faster loads never see it */
+  showAfter: number
   /** Small caption above the counter - empty string hides it */
   label: string
   /** Background color */
@@ -46,12 +49,16 @@ export type UseLoadingReturn = {
   progress: Readonly<Ref<number>>
   /** Boot loading screen lifecycle (readonly) */
   screen: Readonly<Ref<LoadingScreenState>>
-  /** Start simulated progress, timed from `since` (a `performance.now()` value; default now) */
+  /** True once `finishNow` has skipped the boot screen (readonly) */
+  skipped: Readonly<Ref<boolean>>
+  /** Start counting from 0, 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
-  /** Raise the progress floor (0-99) - only `stopLoading` completes */
+  /** Raise the target to a real milestone (0-99) - only `stopLoading` completes */
   updateProgress: (value: number) => void
+  /** End the boot screen now, without its beat or exit animation. Call after hydration */
+  finishNow: () => void
   /** Execute async function with loading state */
   withLoading: (fn: () => Promise<void>) => Promise<void>
 }

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

@@ -3,8 +3,9 @@ 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: false,
-  minDuration: 1500,
-  maxDuration: 3000,
+  minDuration: 0,
+  maxDuration: 1500,
+  showAfter: 400,
   label: 'Loading',
   background: '#0a0a0a',
   textColor: '#ffffff',
@@ -18,27 +19,17 @@ export function resolveLoadingConfig(coreLayer: unknown): LoadingConfig {
 }
 
 /*
- * 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.
+ * Pure easing math behind `useLoading`'s progress counter. The target only moves at real
+ * milestones; `approachProgress` runs once per animation frame to move the displayed value
+ * toward it, so the counter climbs smoothly instead of jumping.
  */
 
-/** 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

package/layers/core/nuxt.config.ts

@@ -1,3 +1,15 @@
+import { createRequire } from 'node:module'
+
+// @nuxt/eslint is an optional peer: load it outside production only when the app has it
+// installed, otherwise a consumer without it fails module resolution in dev/test builds.
+const lintModules: string[] = []
+if (process.env.NODE_ENV !== 'production') {
+  try {
+    createRequire(import.meta.url).resolve('@nuxt/eslint')
+    lintModules.push('@nuxt/eslint')
+  } catch {}
+}
+
 // https://nuxt.com/docs/api/configuration/nuxt-config
 export default defineNuxtConfig({
   $meta: {
@@ -15,7 +27,7 @@ export default defineNuxtConfig({
 
   // Base modules (always loaded)
   modules: [
-    ...(process.env.NODE_ENV !== 'production' ? ['@nuxt/eslint'] : []),
+    ...lintModules,
     '@nuxt/ui',
     // '@nuxt/image'
     '@vueuse/nuxt',
@@ -27,24 +39,12 @@ export default defineNuxtConfig({
 
   css: ['#layers/core/app/assets/css/core.css'],
 
-  devtools: {
-    enabled: true,
-
-    vscode: {
-      enabled: true,
-    },
-  },
-
-  // Force light mode for consistent appearance
+  // Follow the OS colour scheme; light when it can't be detected
   colorMode: {
     preference: 'system',
     fallback: 'light',
   },
 
-  future: {
-    compatibilityVersion: 5,
-  },
-
   compatibilityDate: '2026-01-24',
 
   typescript: {

package/layers/core/server/utils/app-config.ts

@@ -0,0 +1,17 @@
+// eslint-disable-next-line no-restricted-imports -- the fallback below is the one place it belongs
+import { useAppConfig as useNitroAppConfig } from 'nitropack/runtime'
+
+/**
+ * The app's merged app.config, read on the server.
+ *
+ * Nuxt hands Nitro its merged `useAppConfig` as an auto-import, so this leaves `useAppConfig`
+ * unimported on purpose. With `experimental.nitroAutoImports: false` (Nuxt 5's default) nothing
+ * is injected and Nuxt can't evaluate app.config.ts in Nitro at all - importing `nuxt/server`
+ * there crashes the server - so fall back to Nitro's own app config, which is empty.
+ */
+export function readServerAppConfig(): Record<string, unknown> {
+  // `typeof` doesn't throw for an identifier that was never injected
+  return typeof useAppConfig === 'function'
+    ? (useAppConfig() as Record<string, unknown>)
+    : (useNitroAppConfig() as Record<string, unknown>)
+}

package/layers/data/auth/app/middleware/auth.ts

@@ -1,4 +1,4 @@
 export default defineNuxtRouteMiddleware(() => {
   const { loggedIn } = useUserSession()
-  if (!loggedIn.value) return navigateTo('/auth/github')
+  if (!loggedIn.value) return navigateTo('/auth/github', { external: true })
 })

package/layers/data/forms/app/components/Form/Contact.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
   import type { FormSubmitEvent } from '@nuxt/ui'
 
-  import { contactSchema, type ContactData } from '../../utils/contact-schema'
+  import { contactSchema, type ContactData } from '../../../shared/utils/contact-schema'
 
   const emit = defineEmits<{
     submit: [data: ContactData]