kmcom-nuxt-layers 6.3.0 → 6.5.0

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/motion/scroll/app/plugins/locomotive-scroll.client.ts

@@ -61,10 +61,11 @@ export default defineNuxtPlugin({
     // Without a mounted screen the state stays 'hidden' and GSAP is never touched.
     watch(
       screen,
-      (state) => {
+      (state, previous) => {
         gsap.globalTimeline.paused(state !== 'hidden')
 
-        if (state !== 'leaving') return
+        // Start as the screen leaves, or once it's gone if it skipped 'leaving' (finishNow)
+        if (state === 'visible' || previous === 'leaving') return
         instance.value?.start()
         // Remeasure once the screen's scroll lock is off the page
         requestAnimationFrame(() => {

package/layers/render/canvas/nuxt.config.ts

@@ -167,10 +167,6 @@ export default defineNuxtConfig({
     '#layers/canvas': import.meta.dirname,
   },
 
-  imports: {
-    dirs: [`${import.meta.dirname}/app/composables`],
-  },
-
   vite: {
     plugins: [threeWebGPUSSRStub()],
     optimizeDeps: {

package/layers/render/shader/nuxt.config.ts

@@ -18,8 +18,4 @@ export default defineNuxtConfig({
     '#layers/shader': import.meta.dirname,
     '#layers/shader/types': `${import.meta.dirname}/app/types`,
   },
-
-  imports: {
-    dirs: [`${import.meta.dirname}/app/composables`],
-  },
 })

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/layers/structure/routing/app/middleware/01.maintenance.global.ts

@@ -2,5 +2,8 @@ export default defineNuxtRouteMiddleware((to) => {
   const { isEnabled, allowRoutes } = useMaintenance()
   if (!isEnabled.value) return
   if (allowRoutes.value.some((r) => to.path.startsWith(r))) return
-  return navigateTo(allowRoutes.value[0])
+  const target = allowRoutes.value[0]
+  // No allowed route to send visitors to: show the maintenance state as an error instead
+  if (!target) return abortNavigation(createError({ status: 503 }))
+  return navigateTo(target)
 })

package/layers/structure/routing/app/middleware/02.governance.global.ts

@@ -11,6 +11,6 @@ export default defineNuxtRouteMiddleware((to) => {
 
   if (config.debug) console.log('[routing] resolution', resolution)
 
-  if (resolution.outcome === 'deny') throw createError({ statusCode: 404 })
+  if (resolution.outcome === 'deny') return abortNavigation(createError({ status: 404 }))
   if (resolution.outcome === 'redirect') return navigateTo(resolution.to)
 })

package/layers/structure/routing/nuxt.config.ts

@@ -1,3 +1,5 @@
+import { resolve } from 'node:path'
+
 type RoutePage = {
   file?: string
   meta?: Record<string, unknown>
@@ -21,19 +23,24 @@ export default defineNuxtConfig({
     strict: true,
   },
 
-  hooks: {
-    'pages:extend'(pages: unknown[]) {
-      const cwd = process.cwd()
-      const tag = (list: RoutePage[]) => {
-        for (const page of list) {
-          if (page.file && !page.file.startsWith(cwd)) {
-            page.meta ??= {}
-            page.meta.__fromLayer = true
+  modules: [
+    // Tag pages that don't live in the app's own pages dir. Compared against the app's pages
+    // dir, not process.cwd(): an npm consumer's layer pages sit under <app>/node_modules, which
+    // is inside cwd, so a cwd prefix check never tagged anything.
+    (_options, nuxt) => {
+      const appPagesDir = `${resolve(nuxt.options.srcDir, nuxt.options.dir.pages)}/`
+      nuxt.hook('pages:extend', (pages) => {
+        const tag = (list: RoutePage[]) => {
+          for (const page of list) {
+            if (page.file && !page.file.startsWith(appPagesDir)) {
+              page.meta ??= {}
+              page.meta.__fromLayer = true
+            }
+            if (page.children) tag(page.children)
           }
-          if (page.children) tag(page.children)
         }
-      }
-      tag(pages as unknown as RoutePage[])
+        tag(pages as RoutePage[])
+      })
     },
-  },
+  ],
 })

package/layers/structure/routing/server/api/feature-flags.get.ts

@@ -1,8 +1,10 @@
+import { readServerAppConfig } from '#layers/core/server/utils/app-config'
 import { defineEventHandler } from 'h3'
-import { useAppConfig } from 'nitropack/runtime'
 import type { FeatureValue } from '../../app/types/routing'
 
 export default defineEventHandler(() => {
-  const config = useAppConfig() as { routingLayer?: { features?: Record<string, FeatureValue> } }
+  const config = readServerAppConfig() as {
+    routingLayer?: { features?: Record<string, FeatureValue> }
+  }
   return config.routingLayer?.features ?? {}
 })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kmcom-nuxt-layers",
   "private": false,
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Composable Nuxt 4 layers for building scalable Vue applications",
   "exports": {
     "./layers/core": "./layers/core/nuxt.config.ts",
@@ -57,7 +57,12 @@
     "layers/*/*/providers/*/tsconfig.json",
     "layers/*/*/providers/*/server/**",
     "types/**",
-    "docs/"
+    "docs/",
+    "!**/*.test.ts",
+    "!**/*.spec.ts",
+    "!docs/superpowers/**",
+    "!docs/fallow-refactor/**",
+    "!docs/*AUDIT*"
   ],
   "repository": {
     "type": "git",
@@ -72,6 +77,7 @@
     "packages/*"
   ],
   "peerDependencies": {
+    "@neondatabase/serverless": "^0.10.0",
     "@nuxt/content": "^3.14.0",
     "@nuxt/eslint": "^1.15.2",
     "@nuxt/image": "^2.0.0",
@@ -87,10 +93,15 @@
     "@vueuse/nuxt": "^14.3.0 || ^15.0.0",
     "baseline-status": "^1.1.1",
     "better-sqlite3": "^12.10.0 || ^13.0.0",
+    "drizzle-orm": "^0.45.4",
+    "feed": "^5.2.1",
     "gsap": "^3.15.0",
+    "hookable": "^5.5.3 || ^6.0.0",
     "locomotive-scroll": "^5.0.1",
     "nuxt": "^4.6.1",
+    "nuxt-auth-utils": "^0.5.0",
     "pinia": "^3.0.4 || ^4.1.0",
+    "resend": "^4.0.0",
     "tailwindcss": "^4.3.0",
     "three": ">=0.184.0",
     "v-gsap-nuxt": ">=1.5.12",
@@ -150,6 +161,24 @@
     },
     "baseline-status": {
       "optional": true
+    },
+    "@neondatabase/serverless": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "feed": {
+      "optional": true
+    },
+    "hookable": {
+      "optional": true
+    },
+    "nuxt-auth-utils": {
+      "optional": true
+    },
+    "resend": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -211,7 +240,9 @@
     "vue-tsc": "3.3.13",
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "vite-plus": "1.3.0"
+    "vite-plus": "1.3.0",
+    "node-gyp": "^12.3.0",
+    "skills": "^1.5.23"
   },
   "browserslist": [
     "last 2 Chrome major versions",
@@ -221,8 +252,7 @@
     "extends browserslist-config-baseline"
   ],
   "dependencies": {
-    "node-gyp": "^12.3.0",
-    "skills": "^1.5.23"
+    "@iconify/vue": "^5.0.1"
   },
   "engines": {
     "node": ">=24 <25"