kmcom-nuxt-layers 6.3.0 → 6.4.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.md

@@ -1,4 +1,5 @@
-> **Upgrading to v6.3.0?** See [`MIGRATION-v6.3.0.md`](./MIGRATION-v6.3.0.md). The guides below cover older versions.
+> **Upgrading?** 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/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/core/app/app.config.ts

@@ -31,8 +31,8 @@ export default defineAppConfig({
 
     // Loading screen configuration (initial app load only)
     loading: {
-      // Master toggle - set to false to disable completely
-      enabled: true,
+      // 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,
       // Longest wait (ms, after mount) for fonts and images before finishing anyway

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

@@ -6,9 +6,9 @@ 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(undefined)).toMatchObject({ enabled: false, minDuration: 1500 })
     expect(resolveLoadingConfig({ loading: { minDuration: 0, label: '' } })).toMatchObject({
-      enabled: true,
+      enabled: false,
       minDuration: 0,
       label: '',
     })

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

@@ -2,7 +2,7 @@ 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,
+  enabled: false,
   minDuration: 1500,
   maxDuration: 3000,
   label: 'Loading',

package/layers/design-system/typography/app/assets/css/typography.css

@@ -31,12 +31,25 @@
   --type-scale: 1.26;
   --type-snap: 0.0625rem; /* rounding interval: rem so it scales with the root; never px, never 0 */
 
-  /* Fluid display step, 5 → 7 across 360 → 1280px. tan(atan2(length, 1rem)) casts the
-     length to the unitless exponent pow() needs; normalised by 1rem (not 1px) so the
-     exponent stays 5 → 7 whatever the user's root font size; the vw term is scaled by root / 16px so a
-     larger root doesn't lower the exponent at a given width (h1 stays visibly larger). */
+  /* Fluid display step: --display-from at ≤360px → --display-to at ≥1280px (57.5 = 920px / 16).
+     tan(atan2(length, 1rem)) casts the length to the unitless exponent pow() needs; normalised
+     by 1rem (not 1px) so the exponent doesn't move with the user's root font size; the vw term
+     is scaled by root / 16px so a larger root doesn't lower it at a given width (h1 stays
+     visibly larger). Defaults reduce to clamp(5rem, 4.2176rem + 3.4784vw·k, 7rem).
+     --step-display resolves var() here at :root, so overriding --display-from/to on a subtree
+     only reaches elements that recompute it: text-step-display and h1 do. */
+  --display-from: 5;
+  --display-to: 7;
   --step-display: tan(
-    atan2(clamp(5rem, 4.2176rem + 3.4784vw * tan(atan2(1rem, 16px)), 7rem), 1rem)
+    atan2(
+      clamp(
+        var(--display-from) * 1rem,
+        var(--display-from) * 1rem + (var(--display-to) - var(--display-from)) * (100vw - 360px) *
+          tan(atan2(1rem, 16px)) / 57.5,
+        var(--display-to) * 1rem
+      ),
+      1rem
+    )
   );
 }
 
@@ -252,6 +265,18 @@
 }
 
 @utility text-step-display {
+  /* Recomputed here so [--display-from:4] [--display-to:9] on the element takes effect */
+  --step-display: tan(
+    atan2(
+      clamp(
+        var(--display-from) * 1rem,
+        var(--display-from) * 1rem + (var(--display-to) - var(--display-from)) * (100vw - 360px) *
+          tan(atan2(1rem, 16px)) / 57.5,
+        var(--display-to) * 1rem
+      ),
+      1rem
+    )
+  );
   --step: var(--step-display);
 
   font-size: calc(var(--type-base) * pow(var(--type-scale), var(--step)));
@@ -283,6 +308,17 @@
 
   /* Same expressions as the text-step-* utilities. h1 uses the display step. */
   h1:where(:not([data-slot])) {
+    --step-display: tan(
+      atan2(
+        clamp(
+          var(--display-from) * 1rem,
+          var(--display-from) * 1rem + (var(--display-to) - var(--display-from)) * (100vw - 360px) *
+            tan(atan2(1rem, 16px)) / 57.5,
+          var(--display-to) * 1rem
+        ),
+        1rem
+      )
+    );
     --step: var(--step-display);
 
     font-size: calc(var(--type-base) * pow(var(--type-scale), var(--step)));

package/layers/design-system/visual/app/components/HoverDimGroup.test.ts

@@ -0,0 +1,38 @@
+import { mount } from '@vue/test-utils'
+import { defineComponent } from 'vue'
+import { describe, expect, it } from 'vite-plus/test'
+
+import HoverDimGroup from './HoverDimGroup.vue'
+
+// Same template shape as MastNavModal: <template v-for> around a <slot> with fallback content,
+// which compiles to fragments nested two deep
+const Parent = defineComponent({
+  components: { HoverDimGroup },
+  data: () => ({ ids: ['a', 'b', 'c'] }),
+  template: `
+    <HoverDimGroup tag="nav">
+      <template v-for="id in ids" :key="id">
+        <slot name="link" :id="id"><button>{{ id }}</button></slot>
+      </template>
+    </HoverDimGroup>`,
+})
+
+describe('HoverDimGroup', () => {
+  it('renders and dims children nested in v-for and slot fragments', async () => {
+    const wrapper = mount(Parent)
+    const items = wrapper.findAll('nav > button')
+    expect(items.map((b) => b.text())).toEqual(['a', 'b', 'c'])
+
+    await items[0]?.trigger('mouseenter')
+    expect(items.map((b) => b.attributes('style'))).toEqual([
+      expect.stringContaining('opacity: 1'),
+      expect.stringContaining('opacity: 0.3'),
+      expect.stringContaining('opacity: 0.3'),
+    ])
+  })
+
+  it('uses slot content when the parent passes it', () => {
+    const wrapper = mount(Parent, { slots: { link: '<a href="#">x</a>' } })
+    expect(wrapper.findAll('nav > a')).toHaveLength(3)
+  })
+})

package/layers/design-system/visual/app/components/HoverDimGroup.vue

@@ -12,10 +12,18 @@
     setup(props, { slots, attrs }) {
       const hoveredIndex = ref<number | null>(null)
 
+      // v-for over slots nests fragments (v-for → slot → element), so flatten all the way down
+      const flatten = (nodes: VNode[]): VNode[] =>
+        nodes.flatMap((node) =>
+          node.type === Fragment && Array.isArray(node.children)
+            ? flatten(node.children as VNode[])
+            : [node]
+        )
+
       return () => {
-        const children = (slots.default?.() ?? [])
-          .flatMap((node) => (node.type === Fragment ? (node.children as VNode[]) : [node]))
-          .filter((node) => typeof node.type === 'string' || typeof node.type === 'object')
+        const children = flatten(slots.default?.() ?? []).filter(
+          (node) => typeof node.type === 'string' || typeof node.type === 'object'
+        )
 
         const styledChildren = children.map((vnode, index) =>
           cloneVNode(vnode, {

package/layers/structure/navigation/app/app.config.ts

@@ -1,5 +1,7 @@
 import type { SiteConfig } from '#layers/core/app/types/site'
 
+import type { MastNavLink, MastNavTrigger, MastNavUi, SiteLogoConfig } from './types/nav'
+
 export default defineAppConfig({
   site: {
     title: '',
@@ -7,29 +9,50 @@ export default defineAppConfig({
     description: '',
   } satisfies SiteConfig,
   mastNav: {
-    links: [] as Array<{
-      id: string
-      label: string
-      to:
-        | string
-        | { name: string; params?: Record<string, unknown>; query?: Record<string, unknown> }
-    }>,
+    links: [] as MastNavLink[],
     scrollBehaviour: 'router' as 'smooth-scroll' | 'router',
+    // UButton props for <MastNav>; attrs on the component win
+    trigger: {
+      icon: 'lucide:menu',
+      color: 'neutral',
+      variant: 'ghost',
+      size: 'xl',
+    } as MastNavTrigger,
+    ui: {
+      content: 'bg-default text-default',
+      close: 'absolute top-4 right-4',
+      nav: 'flex flex-col items-center gap-2',
+      // Weight keys off aria-current so active and inactive never carry two font-* classes
+      link: 'cursor-pointer border-0 bg-transparent px-4 py-3 text-3xl tracking-widest uppercase transition-all font-light aria-[current=page]:font-normal',
+      linkActive: '',
+    } satisfies MastNavUi,
   },
+  siteLogo: {
+    stacked: true,
+    ui: { root: 'font-display leading-none tracking-tight', word: '' },
+    sizes: {
+      sm: 'text-step-1',
+      md: 'text-step-4',
+      lg: 'text-step-6',
+      display: 'text-step-display',
+    },
+  } satisfies SiteLogoConfig,
 })
 
 declare module '@nuxt/schema' {
   interface AppConfigInput {
     // `site` is already typed by core's own AppConfigInput augmentation — no need to redeclare it.
     mastNav?: {
-      links?: Array<{
-        id: string
-        label: string
-        to:
-          | string
-          | { name: string; params?: Record<string, unknown>; query?: Record<string, unknown> }
-      }>
+      links?: MastNavLink[]
       scrollBehaviour?: 'smooth-scroll' | 'router'
+      trigger?: MastNavTrigger
+      ui?: Partial<MastNavUi>
+    }
+    siteLogo?: {
+      stacked?: boolean
+      ui?: Partial<SiteLogoConfig['ui']>
+      /** Merged per key, so a site can retune one size without restating the others. */
+      sizes?: Partial<SiteLogoConfig['sizes']>
     }
   }
 }

package/layers/structure/navigation/app/components/Mast/Nav.vue

@@ -1,19 +1,20 @@
 <script setup lang="ts">
-  // Positioning is the parent's call (e.g. `<MastNav class="fixed top-0 right-0" />`); the
-  // z-index stays here so the trigger always sits on the dropdown layer.
+  import type { ButtonProps } from '@nuxt/ui'
+
+  // A UButton styled by `mastNav.trigger` in app.config; attrs (class, label, icon…) win.
+  // Positioning is the parent's call, e.g. `<MastNav class="fixed top-0 right-0" />`.
+  defineOptions({ inheritAttrs: false })
+
   const { open } = useMastNav()
-  const z = useGridConfig().useZIndex('dropdown')
+  // app.config types the trigger loosely (see MastNavTrigger); UButton validates the values
+  const trigger = ((useAppConfig().mastNav as { trigger?: unknown } | undefined)?.trigger ??
+    {}) as ButtonProps
 </script>
 
 <template>
-  <button
-    aria-label="Open navigation menu"
-    class="flex cursor-pointer items-center justify-center border-0 bg-transparent p-4"
-    :style="{ zIndex: z }"
-    @click="() => open()"
-  >
-    <slot name="icon">
-      <UIcon name="lucide:menu" class="size-7" />
-    </slot>
-  </button>
+  <UButton aria-label="Open navigation menu" v-bind="{ ...trigger, ...$attrs }" @click="open">
+    <template v-if="$slots.default" #default>
+      <slot />
+    </template>
+  </UButton>
 </template>

package/layers/structure/navigation/app/components/Mast/NavModal.vue

@@ -1,19 +1,61 @@
 <script setup lang="ts">
-  import type { MastNavLink } from '../../types/nav'
+  import type { MastNavLink, MastNavUi } from '../../types/nav'
 
-  const { open } = defineProps<{ open?: boolean }>()
+  // Render once, in the layout. Behaviour lives here (dialog, scroll lock via useMastNav,
+  // smooth-scroll vs router, active link); the look comes from `mastNav.ui`, `ui` and slots.
+  const {
+    open = undefined,
+    links = undefined,
+    ui = undefined,
+  } = defineProps<{
+    /** Manual control; omit to follow useMastNav().isOpen. */
+    open?: boolean
+    /** Replaces `mastNav.links`, e.g. filtered by the site's own page flags. */
+    links?: MastNavLink[]
+    /** Per-key override of `mastNav.ui` (strings replace, no class merging). */
+    ui?: Partial<MastNavUi>
+  }>()
   const emit = defineEmits<{
     'update:open': [value: boolean]
     close: []
   }>()
 
-  const { links, scrollBehaviour } = useAppConfig().mastNav as {
+  const config = useAppConfig().mastNav as {
     links: MastNavLink[]
-    scrollBehaviour: string
+    scrollBehaviour: 'smooth-scroll' | 'router'
+    ui: MastNavUi
   }
+  const classes = computed(() => ({ ...config.ui, ...ui }))
+  const visibleLinks = computed(() => (links ?? config.links).filter((link) => !link.hidden))
+
   const activeSection = useState<string>('activeSection', () => '')
   const route = useRoute()
-  const { close: closeNav } = useMastNav()
+  const router = useRouter()
+  const { isOpen, close: closeNav } = useMastNav()
+  // On the smooth-scroll index every link routes to index, so only the section counts there
+  const smoothOnIndex = computed(
+    () => config.scrollBehaviour === 'smooth-scroll' && route.name === 'index'
+  )
+
+  function matchesRoute(link: MastNavLink) {
+    try {
+      return router.resolve(link.to).path === route.path
+    } catch {
+      return false // a named route that doesn't exist
+    }
+  }
+
+  const activeIds = computed(
+    () =>
+      new Set(
+        visibleLinks.value
+          .filter(
+            (link) =>
+              activeSection.value === link.id || (!smoothOnIndex.value && matchesRoute(link))
+          )
+          .map((link) => link.id)
+      )
+  )
 
   function dismiss() {
     emit('update:open', false)
@@ -21,8 +63,8 @@
     closeNav()
   }
 
-  function handleNav(link: MastNavLink) {
-    if (scrollBehaviour === 'smooth-scroll' && route.name === 'index') {
+  function navigate(link: MastNavLink) {
+    if (smoothOnIndex.value) {
       try {
         useSmoothScroll().scrollTo(`#${link.id}`)
       } catch {}
@@ -37,35 +79,48 @@
   <!-- UModal supplies the dialog role, focus trap, Escape and portal; the title stays
        visually hidden because the content slot replaces the header. -->
   <UModal
-    :open
+    :open="open ?? isOpen"
     fullscreen
     title="Site navigation"
-    :ui="{ overlay: 'z-(--z-modal)', content: 'bg-default text-default z-(--z-modal)' }"
+    :ui="{ overlay: 'z-(--z-modal)', content: `${classes.content} z-(--z-modal)` }"
     @update:open="(value) => !value && dismiss()"
   >
     <template #content>
       <div class="relative flex h-full flex-col items-center justify-center">
-        <UButton
-          icon="lucide:x"
-          color="neutral"
-          variant="ghost"
-          size="xl"
-          aria-label="Close navigation"
-          class="absolute top-4 right-4"
-          @click="dismiss"
-        />
+        <slot name="close" :close="dismiss">
+          <UButton
+            icon="lucide:x"
+            color="neutral"
+            variant="ghost"
+            size="xl"
+            aria-label="Close navigation"
+            :class="classes.close"
+            @click="dismiss"
+          />
+        </slot>
 
-        <HoverDimGroup tag="nav" class="flex flex-col items-center gap-2">
-          <button
-            v-for="link in links"
-            :key="link.id"
-            class="cursor-pointer border-0 bg-transparent px-4 py-3 text-3xl tracking-widest uppercase transition-all"
-            :class="activeSection === link.id ? 'font-normal' : 'font-light'"
-            @click="() => handleNav(link)"
-          >
-            {{ link.label }}
-          </button>
+        <slot name="header" />
+
+        <HoverDimGroup tag="nav" :class="classes.nav">
+          <template v-for="link in visibleLinks" :key="link.id">
+            <slot
+              name="link"
+              :link
+              :active="activeIds.has(link.id)"
+              :navigate="() => navigate(link)"
+            >
+              <button
+                :class="[classes.link, activeIds.has(link.id) && classes.linkActive]"
+                :aria-current="activeIds.has(link.id) ? 'page' : undefined"
+                @click="() => navigate(link)"
+              >
+                {{ link.label }}
+              </button>
+            </slot>
+          </template>
         </HoverDimGroup>
+
+        <slot name="footer" />
       </div>
     </template>
   </UModal>

package/layers/structure/navigation/app/components/Site/Logo.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+  import type { SiteLogoConfig, SiteLogoSize } from '../../types/nav'
+
+  // The site wordmark from `site.title`, sized on the step scale. Look comes from `siteLogo` in
+  // app.config; `ui` overrides per instance. Replaces the deprecated SiteTitle/SiteSubtitle.
+  const {
+    as = 'span',
+    size = 'sm',
+    stacked = undefined,
+    ui = undefined,
+  } = defineProps<{
+    as?: string
+    size?: SiteLogoSize
+    /** One word per line. Defaults to `siteLogo.stacked`. */
+    stacked?: boolean
+    ui?: Partial<SiteLogoConfig['ui']>
+  }>()
+
+  const config = useAppConfig().siteLogo as SiteLogoConfig
+  const site = useSite()
+  const isStacked = computed(() => stacked ?? config.stacked)
+</script>
+
+<template>
+  <component :is="as" :class="[ui?.root ?? config.ui.root, config.sizes[size]]">
+    <slot :words="site.titleWords" :title="site.title">
+      <span
+        v-for="(word, i) in site.titleWords"
+        :key="i"
+        :class="[isStacked && 'block', ui?.word ?? config.ui.word]"
+        >{{ word }}{{ !isStacked && i < site.titleWords.length - 1 ? ' ' : '' }}</span
+      >
+    </slot>
+  </component>
+</template>

package/layers/structure/navigation/app/components/Site/Title.vue

@@ -1,11 +1,11 @@
 <script setup lang="ts">
   /**
-   * @deprecated Render `useSite().titleWords` directly. Unused in this repo and KMCOMv5;
-   * remove in the next major.
+   * @deprecated Use `<SiteLogo :stacked="false">` (or `useSite().titleWords`). Remove in the
+   * next major.
    */
   if (import.meta.dev)
     // eslint-disable-next-line no-console -- one-time deprecation notice, dev only
-    console.warn('[navigation] <SiteTitle> is deprecated — render useSite().titleWords directly.')
+    console.warn('[navigation] <SiteTitle> is deprecated — use <SiteLogo>.')
 
   const site = useSite()
 </script>

package/layers/structure/navigation/app/composables/mastNav.ts

@@ -1,15 +1,40 @@
-import MastNavModal from '../components/Mast/NavModal.vue'
-import { createModal } from '../utils/createModal'
+/**
+ * Shared open state for the site nav. Plain `useState`, not an overlay: layouts and triggers read
+ * `isOpen`, and `<MastNavModal />` (rendered once by the layout) binds to it. Any number of
+ * `<MastNav>` triggers share the one modal.
+ *
+ * Scroll lock: UModal (Reka) locks body scroll and pads for the scrollbar, so this only stops
+ * Lenis — and only after Reka has measured. Hiding overflow first (lockScrolling) left Reka
+ * measuring a 0px scrollbar, and the page widened by the scrollbar on open.
+ */
+export function useMastNav() {
+  const isOpen = useState('mast-nav:open', () => false)
 
-export const useMastNav = createModal(MastNavModal, {
-  onOpen: () => {
+  function smoothScroll() {
     try {
-      useSmoothScroll().lockScrolling()
-    } catch {}
-  },
-  onClose: () => {
-    try {
-      useSmoothScroll().unlockScrolling()
-    } catch {}
-  },
-})
+      return useSmoothScroll().locomotiveScroll
+    } catch {
+      return undefined
+    }
+  }
+
+  function open() {
+    const scroll = smoothScroll()
+    isOpen.value = true
+    if (import.meta.client) nextTick(() => scroll?.value?.stop())
+  }
+
+  function close() {
+    const scroll = smoothScroll()
+    isOpen.value = false
+    if (!import.meta.client) return
+    scroll?.value?.start()
+    // Lenis/Locomotive measure the page while stopped; resize after restart so they resync
+    scroll?.value?.lenisInstance?.resize()
+    requestAnimationFrame(() => scroll?.value?.resize())
+  }
+
+  const toggle = () => (isOpen.value ? close() : open())
+
+  return { isOpen: readonly(isOpen), open, close, toggle }
+}

package/layers/structure/navigation/app/types/nav.ts

@@ -8,4 +8,38 @@ export type MastNavLink = {
         params?: Record<string, string | number>
         query?: Record<string, string | number>
       }
+  /** Skip the link without passing a custom `links` prop. */
+  hidden?: boolean
+}
+
+/**
+ * UButton props for the MastNav trigger. Plain strings: Nuxt UI's ButtonProps is derived from the
+ * resolved app config, so using it inside app.config.ts would be a type cycle.
+ */
+export type MastNavTrigger = {
+  label?: string
+  icon?: string
+  trailingIcon?: string
+  color?: string
+  variant?: string
+  size?: string
+  square?: boolean
+  class?: string
+}
+
+/** Class strings for MastNavModal's parts. Merged per key over app.config; strings replace. */
+export type MastNavUi = {
+  content: string
+  close: string
+  nav: string
+  link: string
+  linkActive: string
+}
+
+export type SiteLogoSize = 'sm' | 'md' | 'lg' | 'display'
+
+export type SiteLogoConfig = {
+  stacked: boolean
+  ui: { root: string; word: string }
+  sizes: Record<SiteLogoSize, string>
 }

package/package.json

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