kmcom-nuxt-layers 6.3.0 → 6.5.0

package/docs/MIGRATION-v6.4.0.md

@@ -0,0 +1,215 @@
+# Migration Guide — v6.3.x → v6.4.0
+
+**Audience:** an AI coding agent (or developer) updating a downstream Nuxt app that consumes these
+layers.
+**What changed:** the duplicate overlay provider is gone, the nav is plain shared state with a
+configurable trigger and modal, a new `SiteLogo` wordmark, and a per-element display type range.
+Background: [`NAV-LOGO-OVERLAY-PLAN.md`](../NAV-LOGO-OVERLAY-PLAN.md).
+
+Work top to bottom. Each change has a **Detect** step and an **Apply** step; skip anything Detect
+doesn't find. An app component with the same name as a layer component overrides it, so a change
+to a layer component you've overridden doesn't reach you until you delete the override.
+
+## 0. Preconditions
+
+- Update the package to `^6.4.0`, reinstall, run `npx nuxt prepare`.
+
+---
+
+## Required changes
+
+### 1. Remove your own `<UOverlayProvider />`
+
+`UApp` already renders one. A second one made every `useOverlay()`/`createModal` overlay render
+twice (doubled modals, layout shift). `core`'s `app.vue` no longer adds one.
+
+**Detect:** grep your `app.vue` and layouts for `<UOverlayProvider`.
+
+**Apply:** delete it. Keep `<UApp>`.
+
+### 2. Render `<MastNavModal />` once in your layout
+
+`<MastNav>` is only a trigger now. The modal is rendered once by the layout, and every trigger on
+the page opens that one modal.
+
+**Detect:** a layout or page renders `<MastNav` but not `<MastNavModal`.
+
+**Apply:**
+
+```vue
+<!-- app/layouts/default.vue -->
+<template>
+  <MastNav class="fixed top-0 right-0 z-(--z-header)" />
+  <MastNavModal />
+  <slot />
+</template>
+```
+
+### 3. `useMastNav()` returns shared state
+
+| Before (v6.3)                     | After (v6.4)                                        |
+| --------------------------------- | --------------------------------------------------- |
+| `{ open(props?), close, patch }`  | `{ isOpen, open, close, toggle }`                   |
+| An overlay created per app        | `useState('mast-nav:open')`; `isOpen` is read-only  |
+| `open()` called `lockScrolling()` | UModal locks body scroll; `open()` only stops Lenis |
+
+**Detect:** grep for `useMastNav().patch`, `patch(` on the nav, or `open({` with props.
+
+**Apply:** drop the props (the modal reads `mastNav` config and its own props instead), and read
+`isOpen` where you used to track open state yourself.
+
+### 4. `MastNav` is a `UButton`
+
+The trigger was a bare `<button>` with a hamburger icon, an `#icon` slot and an inline
+`z-index` (dropdown layer). It's now a `UButton` whose props come from `mastNav.trigger`, and
+attrs on the component win.
+
+**Detect:** `<MastNav>` with an `#icon` slot, or a fixed trigger that relied on the old inline
+z-index.
+
+**Apply:**
+
+```ts
+// app/app.config.ts
+mastNav: {
+  trigger: { label: 'Menu', icon: undefined, variant: 'ghost', size: 'xl' },
+}
+```
+
+- Replace `#icon` with `trigger.icon` (or `icon="…"` on the component). The default slot now fills
+  the button label.
+- Add `z-(--z-header)` (or your own) to a fixed trigger that has to sit over page content.
+- The default look moved from `p-4` + 28px icon to `UButton` neutral/ghost/xl. Restate `class` if
+  you need the old size.
+
+### 5. Loading screen is opt-in, and `core` renders it
+
+`core`'s `app.vue` now renders `<LoadingScreen />`, so you can delete an `app.vue` that existed only
+to add it. So that every other app doesn't suddenly get a loading screen,
+`coreLayer.loading.enabled` now defaults to **`false`**.
+
+**Detect:** your app shows the loading screen (it renders `<LoadingScreen />` or relied on the
+default being on).
+
+**Apply:**
+
+```ts
+// app/app.config.ts
+coreLayer: { loading: { enabled: true } },
+```
+
+Then delete your `app.vue` if `<LoadingScreen />` was its only difference from `core`'s.
+
+### 6. `mastNav.links` is typed as `MastNavLink[]`
+
+Route `params`/`query` values are `string | number` (the app.config type used to allow
+`unknown`).
+
+**Detect:** typecheck errors in `app.config.ts` under `mastNav.links`.
+
+**Apply:** stringify the offending values.
+
+---
+
+## Behaviour changes — check, usually no code
+
+### 7. The current page's link is active
+
+A link used to be active only when `useState('activeSection')` matched its `id`. It's now also
+active when its `to` resolves to the current route, except on the smooth-scroll index, where every
+link points at `index`. Active links get `aria-current="page"` plus `mastNav.ui.linkActive`. The
+default weight (light → normal) keys off `aria-current`.
+
+### 8. No more scrollbar jump when the nav opens
+
+With classic (non-overlay) scrollbars the page used to widen by the scrollbar on open, because the
+nav hid `html` overflow before the dialog measured the scrollbar. UModal now owns the lock and pads
+`body`, and Lenis stops after it. `useSmoothScroll().lockScrolling()` is unchanged for other
+callers.
+
+### 9. `HoverDimGroup` renders nested fragments
+
+Children inside `<template v-for>` around a `<slot>` (fragments two deep) used to be dropped
+silently. They render and dim now. Check any `HoverDimGroup` that rendered fewer children than
+you passed.
+
+---
+
+## New — optional
+
+### `MastNavModal` styling and slots
+
+The layer keeps the behaviour (dialog, focus trap, Escape, scroll lock, smooth-scroll vs router,
+active link). The look comes from config and slots:
+
+```ts
+// app/app.config.ts: each key you set replaces that default string (no class merging)
+mastNav: {
+  ui: {
+    content: 'bg-default text-default',
+    close: 'absolute right-[5vw] top-[3vh]',
+    nav: 'flex w-full flex-col items-start gap-2 px-12',
+    link: 'cursor-pointer py-3 text-step-4 tracking-wider transition-all',
+    linkActive: 'underline',
+  },
+}
+```
+
+| API                                  | Purpose                                                         |
+| ------------------------------------ | --------------------------------------------------------------- |
+| `ui` prop                            | Per-instance override, merged per key over `mastNav.ui`         |
+| `links` prop                         | Replace `mastNav.links`, e.g. filtered by your page flags       |
+| `open` prop / `update:open`          | Manual control; omit to follow `useMastNav().isOpen`            |
+| `#link="{ link, active, navigate }"` | Replace a link's markup; `navigate()` scrolls/routes and closes |
+| `#close="{ close }"`                 | Replace the close button                                        |
+| `#header`, `#footer`                 | Content above/below the links                                   |
+| `hidden: true` on a link             | Skip it without a custom `links` prop                           |
+
+### `SiteLogo`
+
+`site.title` as a wordmark on the step scale. Replaces the deprecated `SiteTitle`.
+
+```vue
+<SiteLogo />
+<!-- stacked, text-step-1 -->
+<SiteLogo size="display" :stacked="false" />
+<!-- one line -->
+<SiteLogo v-slot="{ words }">…</SiteLogo>
+<!-- your own markup -->
+```
+
+```ts
+// app/app.config.ts: sizes merge per key
+siteLogo: {
+  stacked: true,
+  ui: { root: 'font-display leading-none tracking-tight', word: '' },
+  sizes: { display: 'text-step-display [--display-from:4] [--display-to:9]' },
+}
+```
+
+### Per-element display range
+
+`text-step-display` and plain `h1` now read `--display-from` (step at ≤360px, default 5) and
+`--display-to` (step at ≥1280px, default 7) on the element itself:
+
+```html
+<span class="text-step-display [--display-from:4] [--display-to:9]">…</span>
+<!-- ≈42px at 390px, 154px at 1280px -->
+```
+
+Defaults are unchanged in Chromium, Firefox and WebKit. If you override `--step-display` on an
+element with your own unlayered CSS, that still works; the two numbers are the simpler way.
+
+## Deprecated
+
+`SiteTitle` → `<SiteLogo :stacked="false">`. Removal in the next major, alongside `SiteSubtitle`,
+`LinksNamed` and `LinksGroup`.
+
+## Verify
+
+- [ ] `npx nuxt prepare && npx nuxi typecheck` is clean.
+- [ ] Opening any modal puts exactly one `[role="dialog"]` in the DOM (§1).
+- [ ] The nav trigger opens one modal. Escape and the close button close it, focus returns to the
+      trigger, and the page stays where it was (§2–4, §8).
+- [ ] The current page's link is highlighted (§7).
+- [ ] The loading screen shows only where you enabled it (§5).

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,6 @@
-> **Upgrading to v6.3.0?** See [`MIGRATION-v6.3.0.md`](./MIGRATION-v6.3.0.md). The guides below cover older versions.
+> **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/docs/adr/0003-modular-step-system-replaces-fluid-clamps.md

@@ -56,3 +56,19 @@ the element using it.
   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`).
+
+## Amendment (v6.4.0): per-element display range
+
+The display step was computed once at `:root`, so retuning it for one element (a hero wordmark)
+meant restating the whole `tan(atan2(clamp(…)))` expression. Its two ends are now plain numbers,
+`--display-from: 5` and `--display-to: 7`, and `text-step-display` and the `h1` base rule
+recompute `--step-display` from them on the element. `class="[--display-from:4]
+[--display-to:9]"` retunes one element without touching the formula.
+
+- At the defaults the middle term reduces to the old `4.2176rem + 3.4784vw·k`; computed sizes
+  are identical (Chromium, Firefox and WebKit, 360–1600px).
+- The accessibility rules above are unchanged: the `tan(atan2(1rem, 16px))` factor keeps the
+  exponent independent of root font size, and the clamp keeps its rem terms.
+- `--step-display` still exists at `:root` (TypographyHeadline levels and theming read it). An
+  unlayered `--step-display` override on an element still beats the utility's, so existing
+  overrides keep working.

package/docs/component-levels.md

@@ -112,5 +112,6 @@ left out.
 | `layers/structure/navigation/app/components/Mast/Header.vue`               | organism  |
 | `layers/structure/navigation/app/components/Mast/Nav.vue`                  | organism  |
 | `layers/structure/navigation/app/components/Mast/NavModal.vue`             | organism  |
+| `layers/structure/navigation/app/components/Site/Logo.vue`                 | atom      |
 | `layers/structure/navigation/app/components/Site/Subtitle.vue`             | atom      |
 | `layers/structure/navigation/app/components/Site/Title.vue`                | atom      |

package/docs/layout-shift-causes.md

@@ -86,9 +86,27 @@ Catalogue of layout shift (CLS) issues found and fixed in this monorepo, with ro
 
 ---
 
+## 11. Duplicate `UOverlayProvider` — `core/app.vue`
+
+**Cause:** `core`'s `app.vue` rendered `<UOverlayProvider />` inside `<UApp>`, which already renders one. Both read the same `useOverlay()` state, so every `useOverlay().create()` overlay (including the old `createModal`-based nav) rendered twice: a doubled modal and a layout shift on open.
+
+**Fix:** Delete the extra provider (v6.4.0). `UApp` owns overlays and toasts.
+
+---
+
+## 12. Nav modal hid the scrollbar before Reka measured it — `useMastNav`
+
+**Cause:** `useMastNav().open()` called `lockScrolling()` (`html { overflow: hidden }`) before the modal opened. Reka's body scroll lock then measured a 0px scrollbar and added no padding, so with classic (non-overlay) scrollbars the page widened by the scrollbar width on open.
+
+**Fix:** Let UModal/Reka own the overflow lock (it pads `body` for the scrollbar) and stop Lenis on the next tick, after Reka has measured (v6.4.0). A stopped Lenis sets `overflow: clip` on `html`, so the order matters.
+
+---
+
 ## Key Rules Going Forward
 
 - Never use `@layer` / `@utility` in CSS files loaded via `css: []` — use plain selectors instead.
 - Never use runtime `resolveComponent` to conditionally render components in Nuxt 4 — components are compile-time, not runtime-registered.
 - Use `useState` (not `useLocalStorage`) for any value rendered during SSR that might differ between server and client.
 - Keep accessibility-only elements (`aria-live` regions, announcers) outside CSS grid containers to prevent them participating in grid flow.
+- Never add a `<UOverlayProvider />` next to `<UApp>` — `UApp` renders one.
+- When a dialog locks scroll, don't hide `html` overflow first: the lock has to measure the scrollbar to compensate for it.

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

@@ -31,12 +31,15 @@ export default defineAppConfig({
 
     // Loading screen configuration (initial app load only)
     loading: {
-      // Master toggle - set to false to disable completely
-      enabled: true,
-      // Minimum time (ms, from navigation start) the count runs before reaching 100 (prevents flash)
-      minDuration: 1500,
+      // Opt in: app.vue renders LoadingScreen for every app, so it stays off unless enabled
+      enabled: false,
+      // 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/app.vue

@@ -1,9 +1,10 @@
 <template>
+  <!-- UApp already renders UOverlayProvider; a second one rendered every overlay twice. -->
   <UApp>
+    <LoadingScreen />
     <NuxtLoadingIndicator />
     <NuxtLayout>
       <NuxtPage />
     </NuxtLayout>
-    <UOverlayProvider />
   </UApp>
 </template>

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)
     }
   }