kmcom-nuxt-layers 2.2.5 → 2.2.8

package/docs/types-architecture.md

@@ -0,0 +1,234 @@
+# Type System Architecture — `kmcom-nuxt-layers`
+
+## Guiding Principle
+
+Types have two distinct jobs in this monorepo:
+
+- **Internal types** — owned by a single layer, not exported, can change freely
+- **Cross-layer contracts** — shared between two or more layers, or exposed to consuming apps; changes here are breaking changes
+
+The rule: **if only one layer needs it, it lives in that layer. If two or more layers need it, it lives in root `types/`.**
+
+---
+
+## Directory Structure
+
+```
+kmcom-nuxt-layers/
+│
+├── types/                          # Cross-layer contracts & public API
+│   ├── theme.ts                    # Token shapes, mode/palette/contrast enums
+│   ├── motion.ts                   # Shared motion contracts (e.g. scroll lock events)
+│   ├── events.ts                   # Event bus payload types (cross-layer)
+│   ├── runtime.ts                  # runtimeConfig shape types
+│   └── index.ts                    # Public barrel — consuming apps import from here
+│
+├── layers/
+│   ├── core/
+│   │   └── types/
+│   │       ├── device.ts           # Browser/device detection internals
+│   │       ├── network.ts          # Network status types
+│   │       └── index.ts
+│   │
+│   ├── ui/
+│   │   └── types/
+│   │       ├── components.ts       # Component prop shapes
+│   │       ├── typography.ts       # Type scale, font role types
+│   │       └── index.ts
+│   │
+│   ├── layout/
+│   │   └── types/
+│   │       ├── grid.ts             # 18-col grid config types
+│   │       ├── sections.ts         # Section/page component prop shapes
+│   │       └── index.ts
+│   │
+│   ├── motion/
+│   │   └── types/
+│   │       ├── transitions.ts      # Transition component prop shapes
+│   │       ├── scroll.ts           # Scroll composable internals
+│   │       └── index.ts
+│   │
+│   ├── shader/
+│   │   └── types/
+│   │       ├── blocks.ts           # Block category interfaces (Primitives, Generators, etc.)
+│   │       ├── pipeline.ts         # ShaderPipeline / useShaderStage internals
+│   │       ├── colour.ts           # Colour utility types (oklch, hsla, hex, rgb)
+│   │       └── index.ts
+│   │
+│   └── theme/
+│       └── types/
+│           ├── modes.ts            # dark/light/system mode internals
+│           ├── colour.ts           # Accent/palette resolution internals
+│           └── index.ts
+│
+└── package.json
+```
+
+---
+
+## Root `types/` — Cross-Layer Contracts
+
+These are the types that define how layers talk to each other. Treat them as a public API — changes here may require updates across multiple layers and in consuming apps.
+
+### `theme.ts`
+
+Consumed by: `ui`, `layout`, `motion`, `shader`, `theme`
+
+```ts
+export type ColourMode = 'light' | 'dark' | 'system'
+export type ContrastLevel = 'standard' | 'high'
+export type MotionPreference = 'full' | 'reduced' | 'none'
+export type TransparencyPreference = 'full' | 'reduced' | 'none'
+
+export interface ThemeState {
+  mode: ColourMode
+  palette: string // e.g. 'default' | 'ocean' | custom slug
+  contrast: ContrastLevel
+  motion: MotionPreference
+  transparency: TransparencyPreference
+}
+
+export interface ThemeTokens {
+  // Add resolved CSS custom property shapes here as the system matures
+  [key: string]: string
+}
+```
+
+### `events.ts`
+
+Consumed by: any layer using the event bus (e.g. `motion` scroll lock, `core` loading states)
+
+```ts
+export interface ScrollLockEvent {
+  locked: boolean
+  source: string // which layer/component emitted it
+}
+
+export interface LoadingStateEvent {
+  loading: boolean
+  id?: string
+}
+
+// Extend as new cross-layer events are introduced
+export type LayerEvent =
+  | { type: 'scroll:lock'; payload: ScrollLockEvent }
+  | { type: 'loading:state'; payload: LoadingStateEvent }
+```
+
+### `motion.ts`
+
+Consumed by: `motion`, `layout` (section entry animations), `shader` (transition hooks)
+
+```ts
+export interface MotionConfig {
+  duration: number
+  ease: string
+  delay?: number
+}
+
+export interface TransitionConfig extends MotionConfig {
+  enterFrom?: Record<string, string | number>
+  enterTo?: Record<string, string | number>
+  leaveFrom?: Record<string, string | number>
+  leaveTo?: Record<string, string | number>
+}
+```
+
+### `runtime.ts`
+
+Consumed by: `core`, any layer that reads `useRuntimeConfig()`
+
+```ts
+export interface PublicRuntimeConfig {
+  apiBase: string
+  // Extend per project — this is the shared baseline
+}
+```
+
+### `index.ts` — Public Barrel
+
+```ts
+// What consuming apps are allowed to import
+export type {
+  ColourMode,
+  ContrastLevel,
+  MotionPreference,
+  TransparencyPreference,
+  ThemeState,
+} from './theme'
+export type { ScrollLockEvent, LoadingStateEvent, LayerEvent } from './events'
+export type { MotionConfig, TransitionConfig } from './motion'
+export type { PublicRuntimeConfig } from './runtime'
+```
+
+---
+
+## Per-Layer `types/` — Internal Types
+
+Internal types are **not re-exported from root `types/index.ts`**. They are only accessible within their own layer. There is no rule against a layer importing from root `types/` — that's expected — but root `types/` should never import from a layer.
+
+### Dependency direction
+
+```
+consuming app
+      ↓
+  root types/          ← cross-layer contracts
+      ↓
+  layer/types/         ← internal, layer-owned
+```
+
+**Never:** `root types/` ← `layer/types/`
+**Never:** `layer-a/types/` ← `layer-b/types/`
+
+If two layers both need a type that currently lives in one of them — move it to root `types/`.
+
+---
+
+## Recommended Type Packages
+
+### Add now
+
+| Package        | Rationale                                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `type-fest`    | Utility types: `PartialDeep`, `RequireAtLeastOne`, `Simplify`, `SetOptional`. Eliminates most hand-rolled utility types. |
+| `@types/three` | Required for shader layer — Three.js/TSL types for `ShaderNodeObject`, `MeshStandardNodeMaterial`, etc.                  |
+| `csstype`      | Typed CSS properties — useful in the design system and any style object work in UI/Layout layers.                        |
+
+### Consider later
+
+| Package      | Rationale                                                                                                                                            |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `zod`        | Runtime validation for `runtimeConfig` shapes and any API responses in a Data layer. Pairs with `z.infer<>` to derive TypeScript types from schemas. |
+| `ts-pattern` | Exhaustive pattern matching — useful in event bus handlers and shader block routing logic.                                                           |
+
+### Skip
+
+| Package              | Why                                                             |
+| -------------------- | --------------------------------------------------------------- |
+| `io-ts` / `runtypes` | Same space as Zod, less ecosystem momentum, more complex API.   |
+| `@types/gsap`        | GSAP ships its own types — no separate `@types` package needed. |
+
+---
+
+## Migration Checklist
+
+When moving existing types into this structure:
+
+- [ ] Audit all `.ts` files and `.vue` `<script>` blocks for locally defined types
+- [ ] Classify each type: internal (one layer) or cross-layer (two or more)
+- [ ] Move cross-layer types to root `types/` and update all imports
+- [ ] Move internal types to `layer/types/index.ts` and update local imports
+- [ ] Add `type-fest`, `@types/three`, `csstype` to `package.json`
+- [ ] Ensure root `types/index.ts` barrel only exports what consuming apps should see
+- [ ] Verify no layer `types/` files are importing from another layer `types/` — any such coupling should be resolved via root `types/`
+- [ ] Add a TSDoc comment to each type in root `types/` explaining which layers consume it
+
+---
+
+## Conventions
+
+- **Type-only imports:** always use `import type { ... }` for type-only imports to keep the bundle clean
+- **No circular deps:** root `types/` has zero imports from layers; layers may import from root `types/`
+- **TSDoc all root types:** internal types can be lightly documented; root types should always have a JSDoc/TSDoc comment
+- **Barrel per layer:** every `layer/types/` has an `index.ts` — no deep imports into layer type files from outside that layer
+- **Naming:** prefer `interface` for object shapes (extensible), `type` for unions/aliases

package/layers/animations/app/components/Motion/CountUp.vue

@@ -21,7 +21,7 @@
     as?: string
   }>()
 
-  const el = ref<HTMLElement | null>(null)
+  const el = useTemplateRef<HTMLElement>('el')
   const { displayValue, isComplete } = useCountUp(el, {
     to,
     from,

package/layers/animations/app/components/Motion/Magnetic.vue

@@ -11,7 +11,7 @@
     stiffness?: number
   }>()
 
-  const el = ref<HTMLElement | null>(null)
+  const el = useTemplateRef<HTMLElement>('el')
   const { isActive } = useMagneticElement(el, { strength, radius, damping, stiffness })
 </script>
 

package/layers/animations/app/components/Motion/Marquee.vue

@@ -52,8 +52,9 @@
   const { gsap } = useGsap()
   const { velocity: scrollVelocity, direction: scrollDirection } = useSmoothScroll()
 
-  const containerRef = ref<HTMLElement | null>(null)
-  const contentRef = ref<HTMLElement | null>(null)
+  const containerRef = useTemplateRef<HTMLElement>('containerRef')
+  const contentRef = useTemplateRef<HTMLElement>('contentRef')
+
   const tweenRef = ref<gsap.core.Tween | null>(null)
 
   const isPaused = ref(false)

package/layers/animations/app/components/Motion/MarqueeText.vue

@@ -35,7 +35,8 @@
   const { gsap, ScrollTrigger } = useGsap()
   const { velocityFactor } = useMarqueeVelocity({ damping, stiffness, velocityMapping })
 
-  const containerRef = ref<HTMLElement[]>([])
+  const containerRef = useTemplateRef<HTMLElement[]>('containerRef')
+
   const copyRefs = ref<HTMLSpanElement[]>([])
 
   const { copyWidths, calculatedCopies } = useMarqueeCopies(
@@ -130,7 +131,7 @@
       :style="parallaxStyle"
     >
       <div
-        :class="`${scrollerClassName} font-styles-logo flex py-2 text-center font-sans text-4xl font-medium tracking-[-0.02em] whitespace-nowrap text-neutral drop-shadow md:text-[5rem] md:leading-[5rem]`"
+        :class="`${scrollerClassName} font-styles-logo flex py-2 text-center font-sans text-4xl font-medium tracking-[-0.02em] whitespace-nowrap text-neutral drop-shadow md:text-[5rem] md:leading-20`"
         :style="{ transform: `translateX(${scrollTransforms[index] ?? '0px'})`, ...scrollerStyle }"
       >
         <span

package/layers/animations/app/components/Motion/Tilt.vue

@@ -11,7 +11,7 @@
     stiffness?: number
   }>()
 
-  const el = ref<HTMLElement | null>(null)
+  const el = useTemplateRef<HTMLElement>('el')
   useTiltEffect(el, { maxTilt, perspective, damping, stiffness })
 </script>
 

package/layers/animations/app/composables/useCountUp.ts

@@ -10,7 +10,10 @@ type UseCountUpOptions = {
   once?: boolean
 }
 
-export function useCountUp(elementRef: MaybeRefOrGetter<HTMLElement | null>, opts: UseCountUpOptions) {
+export function useCountUp(
+  elementRef: MaybeRefOrGetter<HTMLElement | null>,
+  opts: UseCountUpOptions
+) {
   const { gsap, ScrollTrigger } = useGsap()
 
   const displayValue = ref(String(opts.from ?? 0))

package/layers/animations/app/composables/useMagneticElement.ts

@@ -5,7 +5,7 @@ export function useMagneticElement(
     radius?: number
     damping?: number
     stiffness?: number
-  } = {},
+  } = {}
 ) {
   const { gsap } = useGsap()
   const { elementX, elementY, elementWidth, elementHeight } = useMouseInElement(elementRef)
@@ -27,12 +27,10 @@ export function useMagneticElement(
     let targetX = 0
     let targetY = 0
 
+    isActive.value = dist < radius
     if (dist < radius) {
-      isActive.value = true
       targetX = dx * strength
       targetY = dy * strength
-    } else {
-      isActive.value = false
     }
 
     currentX.value += (targetX - currentX.value) * stiffness

package/layers/animations/app/composables/useMarqueeCopies.ts

@@ -1,9 +1,9 @@
-import type { MaybeRef } from 'vue'
+import type { MaybeRef, ShallowRef } from 'vue'
 
 export function useMarqueeCopies(
-  containerRefs: Ref<HTMLElement[]>,
+  containerRefs: Readonly<ShallowRef<HTMLElement[] | null>>,
   copyRefs: Ref<HTMLSpanElement[]>,
-  rowCount: MaybeRef<number>,
+  rowCount: MaybeRef<number>
 ) {
   const copyWidths = ref<number[]>([])
   const calculatedCopies = ref<number[]>([])
@@ -14,7 +14,7 @@ export function useMarqueeCopies(
     const n = unref(rowCount)
     for (let i = 0; i < n; i++) {
       const copy = copyRefs.value[i]
-      const container = containerRefs.value[i]
+      const container = containerRefs.value?.[i]
       if (!copy || !container) continue
       const singleWidth = copy.offsetWidth
       if (singleWidth === 0) continue

package/layers/animations/app/composables/useTiltEffect.ts

@@ -5,7 +5,7 @@ export function useTiltEffect(
     perspective?: number
     damping?: number
     stiffness?: number
-  } = {},
+  } = {}
 ) {
   const { gsap } = useGsap()
   const { elementX, elementY, elementWidth, elementHeight, isOutside } =

package/layers/animations/app/types/animations.ts

@@ -0,0 +1,8 @@
+export type UseCountUpOptions = {
+  to: number
+  from?: number
+  duration?: number
+  ease?: string
+  format?: (n: number) => string
+  once?: boolean
+}

package/layers/animations/app/types/index.ts

@@ -0,0 +1 @@
+export type * from './animations'

package/layers/animations/package.json

@@ -2,5 +2,8 @@
   "name": "kmcom-layer-animations",
   "version": "0.0.1",
   "type": "module",
-  "main": "./nuxt.config.ts"
+  "main": "./nuxt.config.ts",
+  "scripts": {
+    "lint": "eslint ."
+  }
 }

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

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { TresCanvas } from '@tresjs/core'
+  import { TresCanvas, type TresContext, type TresRendererSetupContext } from '@tresjs/core'
   import {
     ACESFilmicToneMapping,
     CineonToneMapping,
@@ -37,7 +37,7 @@
   }>()
 
   const emit = defineEmits<{
-    ready: [context: any]
+    ready: [context: TresContext]
   }>()
 
   const config = useAppConfig()
@@ -69,7 +69,7 @@
 
   // WebGPU renderer factory — TresJS v5 calls renderer.init() automatically
   // when the returned object has isRenderer === true (three/webgpu Renderer base class)
-  function webgpuRendererFactory({ canvas }: { canvas: any }) {
+  function webgpuRendererFactory({ canvas }: TresRendererSetupContext) {
     const r = new WebGPURenderer({
       canvas: unref(canvas),
       antialias,
@@ -85,7 +85,7 @@
 
   const rendererBinding = computed(() => (webgpu ? { renderer: webgpuRendererFactory } : {}))
 
-  function onReady(context: any) {
+  function onReady(context: TresContext) {
     emit('ready', context)
   }
 </script>

package/layers/canvas/app/composables/useRendererCapabilities.ts

@@ -1,3 +1,5 @@
+import type { WebGPURenderer } from 'three/webgpu'
+import type { WebGLRenderer } from 'three'
 import {
   QUALITY_PRESETS,
   type QualityLevel,
@@ -12,7 +14,7 @@ export function useRendererCapabilities() {
   const capabilities = ref<RendererCapabilities | null>(null)
   const isReady = ref(false)
 
-  function detectFromRenderer(renderer: any) {
+  function detectFromRenderer(renderer: WebGPURenderer | WebGLRenderer) {
     const isWebGPU = renderer.constructor?.name === 'WebGPURenderer'
     const glCaps = renderer.capabilities
 
@@ -29,19 +31,21 @@ export function useRendererCapabilities() {
         devicePixelRatio: renderer.getPixelRatio?.() ?? 1,
         isWebGPU: true,
       }
-    } else {
-      capabilities.value = {
-        backend: 'webgl',
-        maxTextureSize: glCaps.maxTextureSize,
-        maxTextures: glCaps.maxTextures,
-        maxVertexUniforms: glCaps.maxVertexUniforms,
-        maxFragmentUniforms: glCaps.maxFragmentUniforms,
-        floatTextures: glCaps.isWebGL2 || false,
-        anisotropy: glCaps.getMaxAnisotropy(),
-        precision: glCaps.precision as 'lowp' | 'mediump' | 'highp',
-        devicePixelRatio: renderer.getPixelRatio(),
-        isWebGPU: false,
-      }
+      isReady.value = true
+      return
+    }
+
+    capabilities.value = {
+      backend: 'webgl',
+      maxTextureSize: glCaps.maxTextureSize,
+      maxTextures: glCaps.maxTextures,
+      maxVertexUniforms: glCaps.maxVertexUniforms,
+      maxFragmentUniforms: glCaps.maxFragmentUniforms,
+      floatTextures: glCaps.isWebGL2 || false,
+      anisotropy: glCaps.getMaxAnisotropy(),
+      precision: glCaps.precision as 'lowp' | 'mediump' | 'highp',
+      devicePixelRatio: renderer.getPixelRatio(),
+      isWebGPU: false,
     }
 
     isReady.value = true
@@ -70,7 +74,7 @@ export async function checkWebGPUSupport(): Promise<boolean> {
   }
 
   try {
-    const adapter = await (navigator as any).gpu.requestAdapter()
+    const adapter = await navigator.gpu.requestAdapter()
     return adapter !== null
   } catch {
     return false

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

@@ -0,0 +1 @@
+export * from './renderer'

package/layers/canvas/package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "nuxi dev",
     "dev:playground": "PLAYGROUND_LAYERS=core,canvas pnpm -F playground dev",
-    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json"
+    "typecheck": "vue-tsc --noEmit -p ../../tsconfig.typecheck.json",
+    "lint": "eslint ."
   },
   "dependencies": {
     "@tresjs/cientos": "catalog:",

package/layers/canvas/tsconfig.json

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

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

@@ -1,12 +1,12 @@
 <script setup lang="ts">
   const {
     title,
-    description,
-    date,
-    image,
-    badge,
+    description = undefined,
+    date = undefined,
+    image = undefined,
+    badge = undefined,
     authors = [],
-    to,
+    to = undefined,
   } = defineProps<{
     title: string
     description?: string

package/layers/content/app/components/Gallery/AmbientImage.vue

@@ -2,9 +2,9 @@
   const {
     src,
     alt = '',
-    width,
-    height,
-    caption,
+    width = undefined,
+    height = undefined,
+    caption = undefined,
   } = defineProps<{
     src: string
     alt?: string

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

@@ -1,11 +1,11 @@
 <script setup lang="ts">
   const {
     title,
-    description,
-    coverImage,
+    description = undefined,
+    coverImage = undefined,
     imageCount = 0,
     tags = [],
-    to,
+    to = undefined,
   } = defineProps<{
     title: string
     description?: string

package/layers/content/app/components/Gallery/Lightbox.vue

@@ -57,7 +57,11 @@
           color="neutral"
           variant="ghost"
           class="absolute top-4 right-4 text-white"
-          @click="() => { open = false }"
+          @click="
+            () => {
+              open = false
+            }
+          "
         />
 
         <!-- Prev -->

package/layers/content/app/components/NuxtContent/Detail.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
   import type { PageCollections } from '@nuxt/content'
+  import type { ContentSurroundLink } from '@nuxt/ui'
 
   const {
     collection,
@@ -16,6 +17,9 @@
   const { data: item, status } = await useCollectionItem(collection, slug)
   const { data: surround } = await useCollectionSurround(collection, slug)
 
+  const surroundLinks = computed(
+    () => (surround.value ?? undefined) as ContentSurroundLink[] | undefined
+  )
   const itemImage = computed(() => (item.value as { image?: string } | null)?.image)
 
   useSeoMeta({
@@ -47,7 +51,7 @@
         <slot name="after-content" :item />
 
         <USeparator class="my-8" />
-        <NuxtContentSurround :surround="surround as any" />
+        <NuxtContentSurround :surround="surroundLinks" />
       </UPageBody>
 
       <template v-if="!hideToc" #right>

package/layers/content/app/components/NuxtContent/Surround.vue

@@ -1,13 +1,15 @@
 <script setup lang="ts">
-  const { surround } = defineProps<{
-    surround?: unknown[]
+  import type { ContentSurroundLink } from '@nuxt/ui'
+
+  const { surround = undefined } = defineProps<{
+    surround?: ContentSurroundLink[]
   }>()
 </script>
 
 <template>
   <UContentSurround
     v-if="surround"
-    :surround="surround as any"
+    :surround
     prev-icon="i-lucide-arrow-left"
     next-icon="i-lucide-arrow-right"
   />

package/layers/content/app/components/NuxtContent/Toc.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
   import type { TocLink } from '@nuxt/content'
 
-  const { links, title = 'Table of Contents' } = defineProps<{
+  const { links = undefined, title = 'Table of Contents' } = defineProps<{
     links?: TocLink[]
     title?: string
   }>()

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

@@ -1,12 +1,12 @@
 <script setup lang="ts">
   const {
     title,
-    description,
-    image,
+    description = undefined,
+    image = undefined,
     tags = [],
-    client,
-    year,
-    to,
+    client = undefined,
+    year = undefined,
+    to = undefined,
   } = defineProps<{
     title: string
     description?: string

package/layers/content/app/components/content/Figure.vue

@@ -2,9 +2,9 @@
   const {
     src,
     alt = '',
-    caption,
-    width,
-    height,
+    caption = undefined,
+    width = undefined,
+    height = undefined,
   } = defineProps<{
     src: string
     alt?: string