kmcom-nuxt-layers 1.7.8 → 2.1.6

package/docs/layout-shift-causes.md

@@ -0,0 +1,94 @@
+# Layout Shift Root Causes
+
+Catalogue of layout shift (CLS) issues found and fixed in this monorepo, with root cause and resolution for each.
+
+---
+
+## 1. `Math.random()` SVG gradient ID — `Progress/Circular.vue`
+
+**Cause:** `Math.random()` produces a different value on every call. Server and client generate different IDs for the `linearGradient`, so the `stroke="url(#...)"` reference breaks after hydration.
+
+**Fix:** Replace with Nuxt's `useId()` which produces the same deterministic ID across server and client for a given component instance.
+
+---
+
+## 2. Locale-dependent date formatting — `Blog/Article.vue`
+
+**Cause:** `new Date().toLocaleDateString()` with no locale argument uses the runtime's default locale. Node.js (server) and the browser may have different default locales, producing different date strings.
+
+**Fix:** Pass an explicit locale string: `toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })`.
+
+---
+
+## 3. Year computed independently on server and client — `Mast/Footer.vue`
+
+**Cause:** `new Date().getFullYear()` is evaluated independently on server and client. Around year boundaries (different timezones, late-night requests) the two values can differ.
+
+**Fix:** Use `useState('footer-year', () => new Date().getFullYear())` so the year is serialised in the Nuxt payload and reused by the client without re-computing.
+
+---
+
+## 4. Feature flags all `false` on server — `DiagnosticsPage.vue`
+
+**Cause:** `useFeatures()` detects browser capabilities which are unavailable on the server, so all flags default to `false`. The server renders `✗` for every feature; the client flips many to `true`, causing mismatches on every `v-if`.
+
+**Fix:** Wrap the content in `<ClientOnly>` — browser capability detection is inherently client-only.
+
+---
+
+## 5. Theme composables using `useLocalStorage` — theme layer
+
+**Cause:** `useLocalStorage` reads from localStorage which doesn't exist on the server. The server renders with the default value; the client reads the user's saved preference and produces different output.
+
+**Fix:** Replace `useLocalStorage` with `useState` (SSR-safe, serialised to the Nuxt payload). A `.client.ts` plugin reads localStorage post-hydration and calls the setters to restore preferences — a deliberate two-phase update that avoids the mismatch.
+
+---
+
+## 6. Tailwind 4 `@config` restricting content scanning — `core.css`
+
+**Cause:** The `tailwind.config.js` loaded via `@config` contained a `content:` array pointing only to the core layer's files. In Tailwind 4, this array restricts scanning to those paths, so utilities from `ui`, `layout`, `theme`, etc. layers were absent from the initial CSS bundle. In dev mode, Tailwind discovers them lazily via HMR, causing a visible shift.
+
+**Fix:** Remove the `content:` array from `tailwind.config.js`. Tailwind 4's Vite plugin auto-discovers all Vite-processed files. Also added `@source` globs in `core.css` covering all layer and app directories for belt-and-suspenders eager scanning.
+
+---
+
+## 7. Vite CSS code splitting deferring stylesheets
+
+**Cause:** Vite's default `cssCodeSplit: true` bundles CSS with the JS chunk that imports it. CSS for lazily-loaded components only arrives when that JS chunk is first requested, leaving the initial render unstyled.
+
+**Fix:** Set `cssCodeSplit: false` in the playground app's `vite.build` config to merge all CSS into one bundle loaded at first paint.
+
+---
+
+## 8. `@layer` in a CSS file not processed by Tailwind — `ui.css`, `theme.css`
+
+**Cause:** Using `@layer utilities { ... }` or `@layer base { ... }` inside a CSS file loaded via Nuxt's `css: []` array (not via `@import 'tailwindcss'`) creates a raw CSS cascade layer declaration outside Tailwind's pipeline. The browser processes this as a separate layer, triggering a style recalculation after initial paint.
+
+**Fix:** Replace `@layer` blocks with plain selectors in any CSS file that isn't processed by Tailwind. Only CSS files that contain `@import 'tailwindcss'` should use `@layer`.
+
+**Rule:** Never use `@layer` (or `@utility`) in a file loaded via `css: []` unless it also imports Tailwind.
+
+---
+
+## 9. `NuxtAnnouncer` / `NuxtRouteAnnouncer` inside a CSS grid — `app.vue`
+
+**Cause:** `<NuxtAnnouncer>` and `<NuxtRouteAnnouncer>` were inside the `<NuxtLayout>` slot, making them direct children of the `mastmain` CSS grid. Before their `position: absolute` CSS loaded, they auto-placed as grid rows and pushed the `basesection` down by ~85px. When the CSS loaded and removed them from grid flow, the section jumped back up.
+
+**Fix:** Remove `<NuxtAnnouncer>` and `<NuxtRouteAnnouncer>` entirely — they are boilerplate and not needed in this project.
+
+---
+
+## 10. Layout header hydration mismatch — `ui/layouts/default.vue`
+
+**Cause:** The layout used `resolveComponent('MastHeader')` at runtime to detect whether a header component existed. In Nuxt 4, components are registered via compile-time auto-imports, not via `app.component()`, so `resolveComponent` always returns a string at runtime. Server-side Vue resolves it differently, so the header rendered on the server but not after client hydration — causing the section to shift up by the header height.
+
+**Fix:** Remove the `resolveComponent` guard. The layout always renders `<MastHeader />` and `<MastFooter />` unconditionally; the components themselves handle empty states via `appConfig`.
+
+---
+
+## 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.

package/layers/animations/nuxt.config.ts

@@ -0,0 +1,17 @@
+export default defineNuxtConfig({
+  $meta: { name: 'animations' },
+
+  extends: ['../scroll'],
+
+  alias: {
+    '#layers/animations': import.meta.dirname,
+    '#layers/animations/types': `${import.meta.dirname}/app/types`,
+  },
+
+  compatibilityDate: '2026-06-06',
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+})

package/layers/animations/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "kmcom-layer-animations",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts"
+}

package/layers/animations/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../apps/playground/tsconfig.json",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/layers/canvas/app/components/ShaderCanvas.vue

@@ -0,0 +1,125 @@
+<!-- eslint-disable vue/no-boolean-default -->
+<!-- eslint-disable @typescript-eslint/ban-ts-comment -->
+<!-- eslint-disable vue/define-props-destructuring -->
+<!-- eslint-disable @typescript-eslint/no-explicit-any -->
+<script setup lang="ts">
+  // @ts-nocheck - Three.js WebGPU types + TresJS renderer factory
+  import { TresCanvas } from '@tresjs/core'
+  import {
+    ACESFilmicToneMapping,
+    CineonToneMapping,
+    Color,
+    LinearToneMapping,
+    ReinhardToneMapping,
+    SRGBColorSpace,
+    type ToneMapping,
+  } from 'three'
+  import { WebGPURenderer } from 'three/webgpu'
+
+  const props = withDefaults(
+    defineProps<{
+      clearColor?: string
+      toneMapping?: 'aces' | 'reinhard' | 'cineon' | 'linear'
+      outputColorSpace?: 'srgb' | 'linear'
+      shadows?: boolean
+      antialias?: boolean
+      alpha?: boolean
+      preserveDrawingBuffer?: boolean
+      powerPreference?: 'default' | 'high-performance' | 'low-power'
+      windowSize?: boolean
+      /** Use WebGPURenderer (required for node materials / TSL shaders) */
+      webgpu?: boolean
+    }>(),
+    {
+      clearColor: '#000000',
+      toneMapping: 'aces',
+      outputColorSpace: 'srgb',
+      shadows: false,
+      antialias: true,
+      alpha: false,
+      preserveDrawingBuffer: false,
+      powerPreference: 'high-performance',
+      windowSize: true,
+      webgpu: false,
+    }
+  )
+
+  const emit = defineEmits<{
+    ready: [context: any]
+  }>()
+
+  const config = useAppConfig()
+  const shaderConfig = (config.shader || {}) as {
+    toneMapping?: string
+    maxPixelRatio?: number
+  }
+
+  const toneMappingMap: Record<string, ToneMapping> = {
+    aces: ACESFilmicToneMapping,
+    reinhard: ReinhardToneMapping,
+    cineon: CineonToneMapping,
+    linear: LinearToneMapping,
+  }
+
+  const resolvedToneMapping = computed(() => {
+    const key = props.toneMapping || shaderConfig.toneMapping || 'aces'
+    return toneMappingMap[key] ?? ACESFilmicToneMapping
+  })
+
+  const resolvedColorSpace = computed(() => {
+    return props.outputColorSpace === 'srgb' ? SRGBColorSpace : 'srgb-linear'
+  })
+
+  const maxDpr = computed(() => {
+    const configDpr = shaderConfig.maxPixelRatio ?? 2
+    return Math.min(window.devicePixelRatio, configDpr)
+  })
+
+  // WebGPU renderer factory — TresJS v5 calls renderer.init() automatically
+  // when the returned object has isRenderer === true (three/webgpu Renderer base class)
+  const webgpuRendererFactory = props.webgpu
+    ? ({ canvas }: { canvas: any }) => {
+        const r = new WebGPURenderer({
+          canvas: unref(canvas),
+          antialias: props.antialias,
+          powerPreference: props.powerPreference,
+        })
+        r.setPixelRatio(Math.min(window.devicePixelRatio, maxDpr.value))
+        r.setClearColor(new Color(props.clearColor))
+        r.toneMapping = resolvedToneMapping.value
+        r.outputColorSpace = resolvedColorSpace.value
+        return r
+      }
+    : undefined
+
+  function onReady(context: any) {
+    emit('ready', context)
+  }
+</script>
+
+<template>
+  <TresCanvas
+    :clear-color
+    :tone-mapping="resolvedToneMapping"
+    :output-color-space="resolvedColorSpace"
+    :shadows
+    :antialias
+    :alpha
+    :preserve-drawing-buffer
+    :power-preference
+    :window-size
+    :dpr="maxDpr"
+    :renderer="webgpuRendererFactory"
+    class="shader-canvas"
+    @ready="onReady"
+  >
+    <slot />
+  </TresCanvas>
+</template>
+
+<style scoped>
+  .shader-canvas {
+    width: 100%;
+    height: 100%;
+  }
+</style>

package/layers/{shader → canvas}/app/composables/useRendererCapabilities.ts

@@ -1,6 +1,14 @@
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/consistent-type-assertions */
+import {
+  QUALITY_PRESETS,
+  type QualityLevel,
+  type QualitySettings,
+  type RendererBackend,
+  type RendererCapabilities,
+} from '#layers/canvas/types/renderer'
 import type { WebGLRenderer } from 'three'
-import type { QualityLevel, QualitySettings, RendererBackend, RendererCapabilities } from '../types'
-import { QUALITY_PRESETS } from '../types'
 
 /**
  * Detect and expose renderer capabilities

package/layers/{shader → canvas}/app/composables/useShaderTime.ts

@@ -1,8 +1,8 @@
-/* eslint-disable no-restricted-imports */
-import { uniform } from 'three/tsl'
+/* eslint-disable no-restricted-syntax */
 import { computed, onMounted, onUnmounted, ref } from 'vue'
+import { uniform } from 'three/tsl'
 
-export interface ShaderTimeOptions {
+export type ShaderTimeOptions = {
   autoStart?: boolean
   speed?: number
 }

package/layers/canvas/app/types/renderer.ts

@@ -0,0 +1,50 @@
+export type RendererBackend = 'webgpu' | 'webgl'
+export type QualityLevel = 'low' | 'medium' | 'high' | 'ultra'
+export type ToneMappingPreset = 'aces' | 'reinhard' | 'cineon' | 'linear'
+
+export type RendererCapabilities = {
+  backend: RendererBackend
+  maxTextureSize: number
+  maxTextures: number
+  maxVertexUniforms: number
+  maxFragmentUniforms: number
+  floatTextures: boolean
+  anisotropy: number
+  precision: 'lowp' | 'mediump' | 'highp'
+  devicePixelRatio: number
+  isWebGPU: boolean
+}
+
+export type QualitySettings = {
+  pixelRatio: number
+  antialias: boolean
+  shadows: boolean
+  postProcessing: boolean
+}
+
+export const QUALITY_PRESETS: Record<QualityLevel, QualitySettings> = {
+  low: {
+    pixelRatio: 1,
+    antialias: false,
+    shadows: false,
+    postProcessing: false,
+  },
+  medium: {
+    pixelRatio: 1.5,
+    antialias: true,
+    shadows: false,
+    postProcessing: true,
+  },
+  high: {
+    pixelRatio: 2,
+    antialias: true,
+    shadows: true,
+    postProcessing: true,
+  },
+  ultra: {
+    pixelRatio: 2,
+    antialias: true,
+    shadows: true,
+    postProcessing: true,
+  },
+}

package/layers/canvas/nuxt.config.ts

@@ -0,0 +1,189 @@
+import type { Plugin } from 'vite'
+
+/**
+ * Intercepts three.webgpu.js in SSR via the transform hook.
+ *
+ * Unlike resolveId (which isn't reliably called in vite-node dev mode after
+ * the module graph is built), transform IS called for every module evaluation.
+ * We know this because Vite's `define` substitution — which works via transform —
+ * successfully polyfilled `self` in earlier debugging.
+ *
+ * Both `three/webgpu` and `three/tsl` package.json exports resolve to the same
+ * file: three/build/three.webgpu.js. That file accesses `self` and `navigator`
+ * at module scope, crashing SSR startup. We return a lightweight stub instead.
+ */
+function threeWebGPUSSRStub(): Plugin {
+  const tslNoop = `
+const n = new Proxy(function noop() { return n }, {
+  get(_t, k) {
+    if (k === 'then' || k === Symbol.toPrimitive || k === Symbol.iterator || k === Symbol.toStringTag) return undefined
+    return n
+  },
+  apply() { return n },
+  construct() { return Object.create(n) },
+})
+`
+  const tslNames = [
+    // Constructors
+    'float',
+    'vec2',
+    'vec3',
+    'vec4',
+    'color',
+    'mat2',
+    'mat3',
+    'mat4',
+    // Uniforms / attributes
+    'uniform',
+    'attribute',
+    'varying',
+    // Function definition
+    'Fn',
+    // Arithmetic
+    'add',
+    'sub',
+    'mul',
+    'div',
+    'mod',
+    'abs',
+    'sign',
+    'floor',
+    'ceil',
+    'fract',
+    'round',
+    'min',
+    'max',
+    'clamp',
+    'mix',
+    'smoothstep',
+    'pow',
+    'sqrt',
+    'exp',
+    'log',
+    // Trigonometry
+    'sin',
+    'cos',
+    'tan',
+    'asin',
+    'acos',
+    'atan',
+    'atan2',
+    // Vector operations
+    'dot',
+    'cross',
+    'normalize',
+    'length',
+    'distance',
+    'reflect',
+    'refract',
+    // Matrix operations
+    'transpose',
+    'inverse',
+    // Texture
+    'texture',
+    'sampler',
+    // Comparison / selection
+    'lessThan',
+    'lessThanEqual',
+    'greaterThan',
+    'greaterThanEqual',
+    'step',
+    'select',
+    'cond',
+    // Built-in inputs
+    'uv',
+    'time',
+    'EPSILON',
+    'Loop',
+    'positionLocal',
+    'positionWorld',
+    'positionView',
+    'normalLocal',
+    'normalWorld',
+    'normalView',
+    'positionViewDirection',
+    'cameraPosition',
+    // Timers
+    'timerGlobal',
+    'timerLocal',
+    'timerDelta',
+  ]
+
+  const stub =
+    tslNoop +
+    tslNames.map((name) => `export const ${name} = n`).join('\n') +
+    `
+// WebGPU class stubs (used by three/webgpu imports)
+export class MeshBasicNodeMaterial {
+  constructor() { this.colorNode = null; this.side = null }
+}
+export class MeshStandardNodeMaterial {
+  constructor() { this.colorNode = null; this.side = null }
+}
+export class TextureLoader {
+  load() { return null }
+}
+export class UniformNode {}
+export default {}
+`
+
+  return {
+    name: 'three-webgpu-ssr-stub',
+    enforce: 'pre',
+    transform(_code, id, options) {
+      if (!options?.ssr) return null
+      if (!id.includes('three.webgpu.js') && !id.includes('three.tsl.js')) return null
+      return { code: stub, map: null }
+    },
+  }
+}
+
+export default defineNuxtConfig({
+  $meta: {
+    name: 'canvas',
+  },
+
+  compatibilityDate: '2026-06-06',
+
+  extends: ['../core'],
+
+  typescript: {
+    typeCheck: false,
+    strict: true,
+  },
+
+  modules: ['@tresjs/nuxt'],
+
+  tres: {
+    devtools: true,
+  },
+
+  alias: {
+    // More specific alias must be registered first — Vite/Rollup alias
+    // resolution is order-dependent (first prefix match wins), so
+    // '#layers/canvas' would otherwise shadow '#layers/canvas/types'
+    // and resolve it to '<root>/types/...' instead of '<root>/app/types/...'.
+    '#layers/canvas/types': `${import.meta.dirname}/app/types`,
+    '#layers/canvas': import.meta.dirname,
+  },
+
+  imports: {
+    dirs: [`${import.meta.dirname}/app/composables`],
+  },
+
+  vite: {
+    plugins: [threeWebGPUSSRStub()],
+    optimizeDeps: {
+      include: ['three', 'three/webgpu', 'three/tsl'],
+      esbuildOptions: {
+        target: 'esnext',
+      },
+    },
+    build: {
+      target: 'esnext',
+    },
+    ssr: {
+      noExternal: ['three'],
+    },
+  },
+})

package/layers/canvas/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "kmcom-layer-canvas",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "dev": "nuxi dev",
+    "dev:playground": "PLAYGROUND_LAYERS=core,canvas pnpm -F playground dev",
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json"
+  },
+  "dependencies": {
+    "@tresjs/cientos": "catalog:",
+    "@tresjs/core": "catalog:",
+    "@tresjs/nuxt": "catalog:",
+    "@tresjs/post-processing": "catalog:",
+    "@vueuse/core": "catalog:",
+    "three": "catalog:"
+  },
+  "devDependencies": {
+    "@types/three": "catalog:"
+  }
+}

package/layers/canvas/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../apps/playground/tsconfig.json",
+  "compilerOptions": {
+    "strict": true
+  },
+  "exclude": ["node_modules"]
+}

package/layers/content/app/components/Blog/Article.vue

@@ -1,18 +1,24 @@
 <script setup lang="ts">
-import type { BlogCollectionItem } from '@nuxt/content'
+  import type { BlogCollectionItem } from '@nuxt/content'
 
-const { slug } = defineProps<{
-  slug: string
-}>()
+  const { slug } = defineProps<{
+    slug: string
+  }>()
 
-const asBlog = (item: unknown) => item as BlogCollectionItem
+  const asBlog = (item: unknown) => item as BlogCollectionItem
 </script>
 
 <template>
   <NuxtContentDetail collection="blog" :slug not-found-message="Blog post not found">
     <template #headline="{ item }">
       <div class="flex items-center gap-3 text-sm text-muted">
-        <time v-if="asBlog(item).date">{{ new Date(asBlog(item).date).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }) }}</time>
+        <time v-if="asBlog(item).date">{{
+          new Date(asBlog(item).date).toLocaleDateString('en-US', {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+          })
+        }}</time>
         <UBadge v-if="asBlog(item).badge" color="primary" variant="subtle">
           {{ asBlog(item).badge }}
         </UBadge>

package/layers/content/app/components/Blog/Card.vue

@@ -1,30 +1,30 @@
 <!-- eslint-disable vue/require-default-prop -->
 <script setup lang="ts">
-const {
-  title,
-  description,
-  date,
-  image,
-  badge,
-  authors = [],
-  to,
-} = defineProps<{
-  title: string
-  description?: string
-  date?: string
-  image?: string
-  badge?: string
-  authors?: { name: string; avatar?: string; url?: string }[]
-  to?: string
-}>()
+  const {
+    title,
+    description,
+    date,
+    image,
+    badge,
+    authors = [],
+    to,
+  } = defineProps<{
+    title: string
+    description?: string
+    date?: string
+    image?: string
+    badge?: string
+    authors?: { name: string; avatar?: string; url?: string }[]
+    to?: string
+  }>()
 
-const postProps = computed(() => ({
-  ...(description !== undefined && { description }),
-  ...(date !== undefined && { date }),
-  ...(image !== undefined && { image }),
-  ...(badge !== undefined && { badge }),
-  ...(to !== undefined && { to }),
-}))
+  const postProps = computed(() => ({
+    ...(description !== undefined && { description }),
+    ...(date !== undefined && { date }),
+    ...(image !== undefined && { image }),
+    ...(badge !== undefined && { badge }),
+    ...(to !== undefined && { to }),
+  }))
 </script>
 
 <template>

package/layers/content/app/components/Blog/List.vue

@@ -1,20 +1,17 @@
+<!-- eslint-disable @typescript-eslint/ban-ts-comment -->
 <script setup lang="ts">
-// @ts-nocheck
-import type { BlogQueryOptions } from '../../types/content'
+  // @ts-nocheck
+  import type { BlogQueryOptions } from '../../types/content'
 
-const { options = {} } = defineProps<{
-  options?: BlogQueryOptions
-}>()
+  const { options = {} } = defineProps<{
+    options?: BlogQueryOptions
+  }>()
 
-const { data: posts, status } = await useBlogPosts(options)
+  const { data: posts, status } = await useBlogPosts(options)
 </script>
 
 <template>
-  <NuxtContentList
-    :status="status"
-    :has-items="!!posts?.length"
-    empty-message="No blog posts found"
-  >
+  <NuxtContentList :status :has-items="!!posts?.length" empty-message="No blog posts found">
     <UBlogPosts orientation="vertical">
       <UBlogPost
         v-for="post in posts"