kmcom-nuxt-layers 6.2.1 → 6.4.0

package/docs/MIGRATION-v6.3.0.md

@@ -0,0 +1,234 @@
+# Migration Guide — v6.2.x → v6.3.0
+
+**Audience:** an AI coding agent (or developer) updating a downstream Nuxt app that consumes these
+layers.
+**What changed:** the 2026-10 atomic design audit — components moved to the right level, tokens
+moved into `core`, motion respects reduced motion, modals use `UModal`, and organisms no longer set
+page meta.
+
+Work top to bottom. Each change has a **Detect** step (how to tell whether it applies) and an
+**Apply** step. Skip anything Detect doesn't find. Run the **Verify** checklist before declaring
+done. An app component with the same name as a layer component overrides it, so a change to a layer
+component you've already overridden doesn't apply to you.
+
+## 0. Preconditions
+
+- Update the package to `^6.3.0` and reinstall.
+- Run `npx nuxt prepare` so the new auto-imports are typed.
+
+---
+
+## Required changes
+
+### 1. `MastNav` no longer positions itself
+
+The hamburger button dropped `fixed top-0 right-0`. Where it sits is now the parent's decision.
+
+**Detect:** the app renders `<MastNav` and has no `app/components/Mast/Nav.vue` of its own.
+
+**Apply:** put the old positioning back where you render it, or position it differently:
+
+```vue
+<!-- BEFORE -->
+<MastNav />
+
+<!-- AFTER -->
+<MastNav class="fixed top-0 right-0" />
+```
+
+### 2. Detail organisms no longer set page meta
+
+`NuxtContentDetail` and `GalleryImageDetail` used to call `useSeoMeta`. That moved up into the page
+components (`BlogItemPage`, `PortfolioItemPage`, `GallerySlugPage`, `GalleryImagePage`), so an
+organism never decides page meta.
+
+**Detect:** grep your own pages for `<NuxtContentDetail` or `<GalleryImageDetail`. If you only use
+the layer's `*Page` components, nothing changes for you.
+
+**Apply:** set the meta in your page. For a content item, `useContentItemSeo` does what the
+organism used to do:
+
+```vue
+<script setup lang="ts">
+  const slug = useRoute().params.slug as string
+  // Registers title/description/og:image, then fetches. Call it before any other await.
+  await useContentItemSeo('blog', slug)
+</script>
+
+<template>
+  <NuxtContentDetail collection="blog" :slug />
+</template>
+```
+
+For a gallery image, `galleryImageMeta(item, index)` (auto-imported util) returns the
+`{ title, description, ogImage }` the organism used to set. Pass it to `useSeoMeta` with getters,
+as `GalleryImagePage` does.
+
+### 3. `BaseModal` and `MastNavModal` are built on `UModal`
+
+Same props, emits and slots (`open`, `title`, `description`, `size`, `update:open`, `close`,
+`#header`, default, `#footer="{ dismiss }"`). `UModal` now handles the dialog role, focus trap,
+Escape key and teleport. What can break:
+
+| Before                                                              | After                                                                       |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Rendered in place                                                   | Teleported to `<body>`: scoped or parent-selector CSS no longer reaches it  |
+| `#header` replaced only the title block, so the close button stayed | `#header` replaces the whole header, close button included, so add your own |
+| `.base-modal-*` / `.nav-modal-*` transition classes                 | Gone: `UModal` runs its own transitions                                     |
+| `z-50` (`BaseModal`), `useZIndex('modal')` (`MastNavModal`)         | `z-(--z-modal)` = 400                                                       |
+| `size="full"` = `max-w-full`                                        | `size="full"` = `UModal` `fullscreen`                                       |
+
+**Detect:** grep for `<BaseModal` with a `#header` slot, CSS that targets `base-modal-` or
+`nav-modal-`, and styles that reach into the modal from a parent. If you ship your own
+`app/components/Mast/NavModal.vue`, your override still runs and its `nav-modal` CSS still applies.
+
+**Apply:** put a close button inside a custom `#header`. Move modal styling to the `ui`/`class`
+props or global CSS. Delete dead transition CSS.
+
+### 4. Cursor and grid-debug overlays left `z-9999`
+
+`MotionCursor` now uses `z-(--z-cursor)` = 600, and `LayoutGridDebug` uses `z-(--z-debug)` = 700.
+Both still sit above the layout scale (header 100 … toast 500).
+
+**Detect:** the app has its own elements above `z-index: 600` that should stay _under_ the custom
+cursor, or it relied on the cursor beating something at `z-9999`.
+
+**Apply:** move those elements onto the scale (`z-(--z-modal)`, `z-(--z-toast)`, …), or raise
+`--z-cursor` in your own `:root`.
+
+### 5. `NuxtContentList` `status` is a typed union
+
+`status` changed from `string` to `'idle' | 'pending' | 'success' | 'error'`, and `'error'` now
+renders an error alert instead of the empty message.
+
+**Detect:** typecheck errors on `<NuxtContentList :status=…>`.
+
+**Apply:** pass the `status` from `useAsyncData`/`useFetch` (already that union). To change the error
+UI, use the new `error-message` prop or the `#error` slot.
+
+---
+
+## Recommended — deprecated components
+
+Each one still works in v6.3 and prints a dev-only console warning. They'll be removed in the next
+major.
+
+### 6. `LinksGroup` → `HoverDimGroup`
+
+Renamed and moved to `visual`: it dims any children, not just links. The `tag` prop is unchanged.
+
+**Detect:** grep for `<LinksGroup`.
+
+**Apply:** rename the tag.
+
+```vue
+<!-- BEFORE -->
+<LinksGroup tag="nav">…</LinksGroup>
+<!-- AFTER -->
+<HoverDimGroup tag="nav">…</HoverDimGroup>
+```
+
+### 7. `LinksNamed` → `ULink`
+
+**Detect:** grep for `<LinksNamed`.
+
+**Apply:**
+
+```vue
+<!-- BEFORE -->
+<LinksNamed name="blog-slug" :params="{ slug }" color="primary">Read</LinksNamed>
+<!-- AFTER -->
+<ULink :to="{ name: 'blog-slug', params: { slug } }" class="text-primary">Read</ULink>
+```
+
+### 8. `SiteTitle` / `SiteSubtitle` → `useSite()`
+
+**Detect:** grep for `<SiteTitle` or `<SiteSubtitle`.
+
+**Apply:**
+
+```vue
+<script setup lang="ts">
+  const site = useSite()
+</script>
+
+<template>
+  <span v-for="(word, i) in site.titleWords" :key="i" class="site-word">{{ word }}</span>
+</template>
+```
+
+---
+
+## Behaviour changes — check, usually no code
+
+### 9. Motion respects reduced motion
+
+When the OS asks for reduced motion, or the ThemePicker motion setting is `on`, these now render
+static or paused: `MotionStaggered`, `MotionTextReveal`, `MotionCountUp` (jumps to the end value),
+`MotionMarquee`, `MotionMarqueeText`, `MotionVelocityEffect`, `MotionParallax`,
+`MotionPinnedSection` (items shown, no pin), `MotionHorizontalScroll` (native horizontal scroll),
+the pointer-follow effects (`MotionTilt`, `MotionMagnetic`) and the cursor follower.
+
+**Check:** e2e tests that emulate `prefers-reduced-motion: reduce` and still expect motion.
+
+### 10. `MotionStaggered` now actually reveals its children
+
+Before, `ref`/`class` on the `<slot>` never reached the DOM, so items stayed at `opacity: 0` for
+good. It now staggers its rendered **element** children (text nodes aren't animated) and adds the
+`transitions` layer's `animate-<animation>` class.
+
+**Check:** remove any workaround CSS that forced `.motion-staggered > *` visible.
+
+### 11. `LayoutPage` sets meta with `useSeoMeta`
+
+It used `useHead`. Now `og:title` is always set, and a page's own `useSeoMeta` overrides
+`LayoutPage`'s values instead of adding duplicate tags.
+
+**Check:** nothing to do, unless you relied on the duplicate tags.
+
+### 12. Wider `extends`
+
+`content` now extends `layout` and `visual`, and `scroll` and `navigation` now extend `visual`. An
+app that loads `content` or `navigation` therefore also gets the `layout`/`visual` components and
+composables auto-imported. App components with the same name still win.
+
+**Check:** after `nuxt prepare`, look for auto-import name clashes. The likeliest new one is
+`useReducedMotion` (scroll layer), which `motion-v` also exports.
+
+### 13. Colour and markup tweaks
+
+- `Feeds` (index page) and `FeedsRouteCard` use semantic colours (`bg-elevated`, `text-muted`,
+  `border-default`). Only the RSS/Atom/JSON format hues stay fixed.
+- `MastFooter` copyright: `text-neutral-300` → `text-muted`.
+- `BlogPage`, `GalleryPage` and `PortfolioPage` render through the new `NuxtContentIndexTemplate`
+  (`UPageHeader` + `UPageBody` inside `LayoutSection` > `LayoutGridItem`).
+
+**Check:** visual regression on the feeds page, the footer and the content index pages, in light and
+dark mode.
+
+---
+
+## New — optional
+
+| Addition                              | Where                                      | Use                                                       |
+| ------------------------------------- | ------------------------------------------ | --------------------------------------------------------- |
+| `title`, `description` props          | `BlogPage`, `GalleryPage`, `PortfolioPage` | Override the index heading and meta (defaults unchanged)  |
+| `items` prop                          | `BlogList`, `GalleryGrid`, `PortfolioList` | Pass data in. The component only fetches when it's absent |
+| `error-message` prop, `#error` slot   | `NuxtContentList`                          | Custom error state                                        |
+| `NuxtContentIndexTemplate`            | content                                    | Heading + body skeleton for your own index pages          |
+| `useContentSection(section)`          | content                                    | 404 when `contentLayer.sections.<section>` is `false`     |
+| `useContentItemSeo(collection, slug)` | content                                    | Fetch an item and set its page meta                       |
+| `useReducedMotion()`                  | scroll                                     | `ComputedRef<boolean>`: OS setting + ThemePicker override |
+| `--z-header` … `--z-debug`            | core CSS                                   | Stacking scale: `z-(--z-modal)`                           |
+| Shadow / duration tokens              | core CSS                                   | Moved from `theming`, so they work without it             |
+| `docs/component-levels.md`            | repo                                       | Atomic level of every component                           |
+
+## Verify
+
+- [ ] `npx nuxt prepare && npx nuxi typecheck` is clean.
+- [ ] Nav button is where it was (§1).
+- [ ] Each content item page has the right `<title>` and `og:image` (§2).
+- [ ] Modals open, close on Escape and backdrop, and custom headers have a close button (§3).
+- [ ] The cursor sits above modals and toasts (§4).
+- [ ] No `[navigation] … is deprecated` warnings in the dev console (§6–8).
+- [ ] With reduced motion on, nothing moves and all content is visible (§9–10).

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,3 +1,6 @@
+> **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
 
 **Audience:** an AI coding agent (or developer) updating a downstream Nuxt app that consumes these layers.

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

@@ -0,0 +1,117 @@
+# Component levels
+
+Atomic design level for every UI component under `layers/**/app/components`. Folders stay by
+domain (`Motion/`, `Layout/`); this table is the level record. `tests/vitest/component-levels.test.ts`
+fails when a component is added without a row here, or a row points at a deleted file.
+
+Dependencies point down: atom < molecule < organism < template < page. **behaviour** sits beside
+atom: a slot wrapper that adds behaviour (motion, hover, error capture) and renders whatever it is
+given, so it may wrap any level. `render/shader` pipeline nodes are a render graph, not UI, and are
+left out.
+
+| Level     | Meaning                                          |
+| --------- | ------------------------------------------------ |
+| atom      | One element or vendor primitive                  |
+| behaviour | Slot wrapper adding behaviour, no markup opinion |
+| molecule  | A few atoms doing one job                        |
+| organism  | A standalone section                             |
+| template  | Page-type skeleton: props and slots only         |
+| page      | Binds route and data, fills one template         |
+
+| Component                                                                  | Level     |
+| -------------------------------------------------------------------------- | --------- |
+| `layers/content/app/components/Blog/Article.vue`                           | organism  |
+| `layers/content/app/components/Blog/ItemPage.vue`                          | page      |
+| `layers/content/app/components/Blog/List.vue`                              | organism  |
+| `layers/content/app/components/Blog/Page.vue`                              | page      |
+| `layers/content/app/components/Gallery/Detail.vue`                         | organism  |
+| `layers/content/app/components/Gallery/Grid.vue`                           | organism  |
+| `layers/content/app/components/Gallery/ImageDetail.vue`                    | organism  |
+| `layers/content/app/components/Gallery/ImagePage.vue`                      | page      |
+| `layers/content/app/components/Gallery/Lightbox.vue`                       | organism  |
+| `layers/content/app/components/Gallery/Page.vue`                           | page      |
+| `layers/content/app/components/Gallery/SlugPage.vue`                       | page      |
+| `layers/content/app/components/NuxtContent/Detail.vue`                     | template  |
+| `layers/content/app/components/NuxtContent/IndexTemplate.vue`              | template  |
+| `layers/content/app/components/NuxtContent/List.vue`                       | organism  |
+| `layers/content/app/components/NuxtContent/Surround.vue`                   | molecule  |
+| `layers/content/app/components/NuxtContent/Toc.vue`                        | molecule  |
+| `layers/content/app/components/Portfolio/ColorPalette.vue`                 | organism  |
+| `layers/content/app/components/Portfolio/Detail.vue`                       | organism  |
+| `layers/content/app/components/Portfolio/ItemPage.vue`                     | page      |
+| `layers/content/app/components/Portfolio/List.vue`                         | organism  |
+| `layers/content/app/components/Portfolio/Page.vue`                         | page      |
+| `layers/content/app/components/Portfolio/Typography.vue`                   | organism  |
+| `layers/content/app/components/content/Figure.vue`                         | molecule  |
+| `layers/core/app/components/AppContainer.vue`                              | atom      |
+| `layers/core/app/components/DiagnosticsPage.vue`                           | organism  |
+| `layers/core/app/components/Element.vue`                                   | atom      |
+| `layers/core/app/components/ElementTw.vue`                                 | atom      |
+| `layers/core/app/components/ErrorBoundary.vue`                             | behaviour |
+| `layers/core/app/components/LoadingScreen.vue`                             | organism  |
+| `layers/data/forms/app/components/Form/Contact.vue`                        | organism  |
+| `layers/data/forms/app/components/Form/Field.vue`                          | molecule  |
+| `layers/delivery/feeds/app/components/Feeds/Index.vue`                     | organism  |
+| `layers/delivery/feeds/app/components/Feeds/RouteCard.vue`                 | molecule  |
+| `layers/delivery/scripts/app/components/BaselineStatus.vue`                | atom      |
+| `layers/design-system/theming/app/components/ThemePicker/AccentButton.vue` | atom      |
+| `layers/design-system/theming/app/components/ThemePicker/Colors.vue`       | molecule  |
+| `layers/design-system/theming/app/components/ThemePicker/Menu.vue`         | organism  |
+| `layers/design-system/theming/app/components/ThemePicker/MenuButton.vue`   | atom      |
+| `layers/design-system/typography/app/components/Typography/CodeBlock.vue`  | atom      |
+| `layers/design-system/typography/app/components/Typography/Headline.vue`   | atom      |
+| `layers/design-system/typography/app/components/Typography/QuoteBlock.vue` | molecule  |
+| `layers/design-system/typography/app/components/Typography/RepeatText.vue` | atom      |
+| `layers/design-system/typography/app/components/Typography/TextStroke.vue` | atom      |
+| `layers/design-system/typography/app/components/Typography/index.vue`      | atom      |
+| `layers/design-system/visual/app/components/Accent/Blob.vue`               | atom      |
+| `layers/design-system/visual/app/components/Accent/Scene.vue`              | molecule  |
+| `layers/design-system/visual/app/components/Base/Modal.vue`                | molecule  |
+| `layers/design-system/visual/app/components/Gradient/Background.vue`       | atom      |
+| `layers/design-system/visual/app/components/Gradient/Text.vue`             | atom      |
+| `layers/design-system/visual/app/components/HoverDimGroup.vue`             | behaviour |
+| `layers/design-system/visual/app/components/Media/Picture.vue`             | atom      |
+| `layers/design-system/visual/app/components/Progress/Bar.vue`              | atom      |
+| `layers/design-system/visual/app/components/Progress/Circular.vue`         | atom      |
+| `layers/design-system/visual/app/components/Tint/Overlay.vue`              | atom      |
+| `layers/motion/animations/app/components/Motion/CountUp.vue`               | atom      |
+| `layers/motion/animations/app/components/Motion/Cursor.vue`                | atom      |
+| `layers/motion/animations/app/components/Motion/Magnetic.vue`              | behaviour |
+| `layers/motion/animations/app/components/Motion/Marquee.vue`               | behaviour |
+| `layers/motion/animations/app/components/Motion/MarqueeText.vue`           | molecule  |
+| `layers/motion/animations/app/components/Motion/Staggered.vue`             | behaviour |
+| `layers/motion/animations/app/components/Motion/TextReveal.vue`            | atom      |
+| `layers/motion/animations/app/components/Motion/Tilt.vue`                  | behaviour |
+| `layers/motion/animations/app/components/Motion/VelocityEffect.vue`        | behaviour |
+| `layers/motion/scroll/app/components/Motion/HorizontalScroll.vue`          | behaviour |
+| `layers/motion/scroll/app/components/Motion/Parallax.vue`                  | behaviour |
+| `layers/motion/scroll/app/components/Motion/PinnedSection.vue`             | behaviour |
+| `layers/motion/scroll/app/components/Motion/ScrollLink.vue`                | atom      |
+| `layers/motion/scroll/app/components/Motion/ScrollProgress.vue`            | atom      |
+| `layers/motion/scroll/app/components/Motion/ScrollScene.vue`               | behaviour |
+| `layers/motion/scroll/app/components/Motion/ScrollStats.vue`               | molecule  |
+| `layers/motion/scroll/app/components/Motion/ScrollStep.vue`                | behaviour |
+| `layers/motion/transitions/app/components/Motion/Transition.vue`           | behaviour |
+| `layers/render/canvas/app/components/ShaderCanvas.vue`                     | atom      |
+| `layers/structure/layout/app/components/HStack.vue`                        | atom      |
+| `layers/structure/layout/app/components/Layout/Grid/Debug.vue`             | atom      |
+| `layers/structure/layout/app/components/Layout/Grid/Item.vue`              | atom      |
+| `layers/structure/layout/app/components/Layout/Main.vue`                   | template  |
+| `layers/structure/layout/app/components/Layout/Page/Header.vue`            | organism  |
+| `layers/structure/layout/app/components/Layout/Page/index.vue`             | template  |
+| `layers/structure/layout/app/components/Layout/Section/Gallery.vue`        | organism  |
+| `layers/structure/layout/app/components/Layout/Section/Hero.vue`           | organism  |
+| `layers/structure/layout/app/components/Layout/Section/Split.vue`          | organism  |
+| `layers/structure/layout/app/components/Layout/Section/index.vue`          | organism  |
+| `layers/structure/layout/app/components/Spacer.vue`                        | atom      |
+| `layers/structure/layout/app/components/VStack.vue`                        | atom      |
+| `layers/structure/layout/app/components/ZStack.vue`                        | atom      |
+| `layers/structure/navigation/app/components/Links/Group.vue`               | behaviour |
+| `layers/structure/navigation/app/components/Links/Named.vue`               | atom      |
+| `layers/structure/navigation/app/components/Mast/Footer.vue`               | organism  |
+| `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/Blog/ItemPage.vue

@@ -1,15 +1,10 @@
 <script setup lang="ts">
-  import type { ContentLayerConfig } from '#layers/content/app/types/content'
-
   const { slug } = defineProps<{
     slug: string
   }>()
 
-  const appConfig = useAppConfig()
-  const contentLayer = appConfig.contentLayer as ContentLayerConfig | undefined
-  if (contentLayer?.sections?.blog === false) {
-    throw createError({ statusCode: 404, statusMessage: 'Not Found' })
-  }
+  useContentSection('blog')
+  await useContentItemSeo('blog', slug)
 </script>
 
 <template>