kmcom-nuxt-layers 1.0.2 → 1.1.0

package/README.md

@@ -0,0 +1,44 @@
+# kmcom-nuxt-layers
+
+Composable Nuxt 4 layers for building scalable Vue applications. Pick only the layers you need.
+
+## Quick Start
+
+```bash
+npm install kmcom-nuxt-layers
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    'kmcom-nuxt-layers/layers/core',
+    'kmcom-nuxt-layers/layers/ui',
+    // add more layers as needed
+  ]
+})
+```
+
+## Layers
+
+| Layer | Description |
+|-------|-------------|
+| **core** | Foundation — Nuxt UI, VueUse, Pinia, loading screen, error handling, scroll guard |
+| **ui** | Design system — typography, color, media, branding components |
+| **layout** | Page structure — grids, containers, spacing |
+| **motion** | Animations — GSAP, Locomotive Scroll |
+| **shader** | 3D / WebGPU — Three.js, TresJS |
+| **forms** | Validation — Zod-based form system |
+| **theme** | Theming — color mode, accent colors |
+| **content** | CMS — @nuxt/content, Nuxt Studio |
+
+All layers depend on `core`. Always list `core` first in `extends`.
+
+## Documentation
+
+- **[Usage Guide](docs/USAGE.md)** — installation, configuration examples, layer dependencies
+- **[Architecture](docs/ARCHITECTURE.md)** — internal structure, alias system, dev workflow
+
+## License
+
+ISC

package/docs/ARCHITECTURE.md

@@ -0,0 +1,196 @@
+# Architecture
+
+Internal documentation for the `kmcom-nuxt-layers` monorepo.
+
+## Monorepo Structure
+
+```
+nuxt-layers/
+├── apps/
+│   └── playground/          # Demo / development Nuxt app
+├── layers/
+│   ├── core/                # Base utilities, plugins, error handling
+│   ├── ui/                  # Typography, color, media primitives
+│   ├── layout/              # Grid, containers, page structure
+│   ├── motion/              # GSAP + Locomotive Scroll animations
+│   ├── shader/              # Three.js / TresJS WebGPU shaders
+│   ├── forms/               # Zod-based form validation
+│   ├── theme/               # Color mode, accent colors, accessibility
+│   └── content/             # @nuxt/content integration, Nuxt Studio
+├── packages/                # Shared utilities (placeholder)
+├── pnpm-workspace.yaml
+├── turbo.json
+└── package.json
+```
+
+**Tooling:** pnpm workspaces for dependency management, Turbo for parallel task orchestration (`build`, `dev`, `lint`, `typecheck`).
+
+## Layer Pattern
+
+Each layer under `layers/` is an independent Nuxt-extendable package. A layer's `package.json` declares `"main": "./nuxt.config.ts"`, making it resolvable by Nuxt's `extends` mechanism.
+
+Typical layer directory structure:
+
+```
+layers/<name>/
+├── nuxt.config.ts           # Layer config (alias, modules, css, plugins)
+├── app.config.ts            # Typed runtime config with defaults
+├── package.json             # name, main, dependencies
+├── app/
+│   ├── assets/css/main.css  # Layer-specific CSS
+│   ├── components/          # Auto-imported Vue components
+│   ├── composables/         # Auto-imported composables
+│   ├── plugins/             # Nuxt plugins
+│   ├── types/               # TypeScript type definitions
+│   └── utils/               # Utility functions
+└── .playground/             # Isolated dev/test app for this layer
+```
+
+## Alias System
+
+Each layer registers a `#layers/<name>` alias pointing to its own root directory via `import.meta.dirname`:
+
+```ts
+// layers/core/nuxt.config.ts
+alias: {
+  '#layers/core': import.meta.dirname,
+}
+```
+
+This allows layers to reference their own files with stable paths that resolve correctly both in the monorepo and when consumed from `node_modules`:
+
+```ts
+css: ['#layers/core/app/assets/css/main.css'],
+plugins: ['#layers/core/app/plugins/init.ts'],
+```
+
+## Layer Dependency Graph
+
+```
+core  (foundation — no dependencies)
+  ├── ui         (typography, color, media)
+  ├── layout     (grid, containers)
+  ├── motion     (GSAP, Locomotive Scroll)
+  ├── shader     (Three.js, TresJS)
+  ├── forms      (Zod validation)
+  ├── theme      (color mode, accents)
+  └── content    (@nuxt/content, Nuxt Studio)
+```
+
+All layers depend on `core`. The `core` layer must always be listed first in `extends`.
+
+## Playground Composition System
+
+The `apps/playground/nuxt.config.ts` supports selective layer loading via the `PLAYGROUND_LAYERS` environment variable.
+
+```bash
+# Load only core + ui
+PLAYGROUND_LAYERS=core,ui pnpm -F playground dev
+
+# Load all layers (default when env var is unset)
+pnpm dev
+```
+
+The `resolveExtendedLayers()` function:
+1. Parses `PLAYGROUND_LAYERS` as a comma-separated list
+2. Auto-includes each layer's dependencies (defined in `LAYER_DEPENDENCIES`)
+3. Returns paths in correct order (dependencies first, following `AVAILABLE_LAYERS` order)
+
+## CSS Cascade
+
+Each layer loads its own CSS via the `css` array in `nuxt.config.ts`:
+
+```ts
+css: ['#layers/<name>/app/assets/css/main.css']
+```
+
+- **core** imports Tailwind CSS 4 and Nuxt UI base styles
+- **theme** uses a separate `theme.css` file for color mode variables
+- Layer CSS is loaded in `extends` order, so core styles are always available to downstream layers
+
+## Component Auto-Import
+
+Nuxt auto-discovers components from all extended layers' `app/components/` directories. No manual registration needed.
+
+The shader layer uses explicit component registration with `global: true` for its WebGPU components:
+
+```ts
+components: [{
+  path: './app/components',
+  pathPrefix: false,
+  global: true,
+}]
+```
+
+## app.config.ts
+
+Each layer provides typed runtime configuration via `app.config.ts` with sensible defaults. Consumers can override any value in their own `app.config.ts`.
+
+Key config namespaces:
+- `coreLayer` — loading screen, error handling, scroll guard, 404 page
+- `motion` — Lenis smooth scroll, GSAP ScrollTrigger integration
+- `themeLayer` — accent colors, default accent
+
+Type augmentation is done via `declare module '@nuxt/schema'` in each layer's `app.config.ts`.
+
+## Git Subtree Management
+
+Layers are managed as git subtrees from separate upstream repositories:
+
+```bash
+# Push layer changes to upstream
+git subtree push --prefix=layers/<layer> <remote-url> main
+
+# Pull updates from upstream
+git subtree pull --prefix=layers/<layer> <remote-url> main --squash
+```
+
+Always commit changes to the monorepo first, then push to upstream if needed.
+
+## Dev Workflow
+
+```bash
+# Start all layers via playground
+pnpm dev
+
+# Start specific layer combinations
+pnpm dev:core          # core only
+pnpm dev:ui            # core + ui
+pnpm dev:layout        # core + ui + layout
+pnpm dev:motion        # core + motion
+
+# Build / lint / typecheck (all packages via Turbo)
+pnpm build
+pnpm lint
+pnpm typecheck
+
+# Layer-specific tasks
+pnpm layer:core        # turbo dev for core
+pnpm build:core        # turbo build for core
+
+# Clean everything
+pnpm clean
+```
+
+## .playground Directories
+
+Each layer has a `.playground/` directory containing a minimal Nuxt app for isolated development and testing of that layer. These are used by the `dev` script in each layer's `package.json`:
+
+```bash
+cd layers/core && pnpm dev   # runs nuxi dev .playground
+```
+
+Some layers (ui, content) support standalone mode via environment variables (`UI_STANDALONE`, `CONTENT_STANDALONE`) which auto-extends core when running outside the monorepo playground.
+
+## Layer Details
+
+| Layer | Description |
+|-------|-------------|
+| **core** | Foundation layer. Nuxt UI, VueUse, device detection, Pinia, loading screen, error handler, scroll guard, feature detection, PWA support (production only). |
+| **ui** | Design system primitives. Typography components (Headline, CodeBlock, QuoteBlock), color system, media/picture component, site branding, breakpoint types. |
+| **layout** | Page structure. Grid systems, containers, spacing, layout compositions with breakpoint-based responsiveness. |
+| **motion** | Animation layer. GSAP with ScrollTrigger, Locomotive Scroll (Lenis) smooth scrolling, motion composables. Transpiles GSAP for SSR. |
+| **shader** | WebGPU/WebGL layer. Three.js + TresJS integration, TSL shader support, post-processing. Includes custom shader utilities and auto-imported shader modules. |
+| **forms** | Form validation layer. Zod schema-based validation, form composables, typed form components. |
+| **theme** | Theming layer. Color mode switching, accent color palette, theme plugin, CSS custom properties for dynamic theming. |
+| **content** | Content management layer. @nuxt/content integration, better-sqlite3 for local content DB, optional Nuxt Studio support. |

package/docs/USAGE.md

@@ -0,0 +1,175 @@
+# Usage Guide
+
+How to consume `kmcom-nuxt-layers` in your Nuxt 4 project.
+
+## Installation
+
+```bash
+npm install kmcom-nuxt-layers
+```
+
+## Basic Usage
+
+Add layers to the `extends` array in your `nuxt.config.ts`. Each layer is referenced by its filesystem path within the package:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    'kmcom-nuxt-layers/layers/core',
+    'kmcom-nuxt-layers/layers/ui',
+  ]
+})
+```
+
+Nuxt resolves each layer via the `package.json` → `"main": "./nuxt.config.ts"` entry. No import maps or special configuration needed.
+
+## Available Layers
+
+| Layer | Extends Path | Depends On | Required Dependencies |
+|-------|-------------|------------|----------------------|
+| **core** | `kmcom-nuxt-layers/layers/core` | — | `nuxt`, `@nuxt/ui`, `pinia`, `@vueuse/nuxt`, `@nuxtjs/device` |
+| **ui** | `kmcom-nuxt-layers/layers/ui` | core | — |
+| **layout** | `kmcom-nuxt-layers/layers/layout` | core | — |
+| **motion** | `kmcom-nuxt-layers/layers/motion` | core | `gsap`, `locomotive-scroll` |
+| **shader** | `kmcom-nuxt-layers/layers/shader` | core | `three`, `@tresjs/nuxt`, `@tresjs/core`, `@tresjs/cientos`, `@tresjs/post-processing` |
+| **forms** | `kmcom-nuxt-layers/layers/forms` | core | `zod` |
+| **theme** | `kmcom-nuxt-layers/layers/theme` | core | — |
+| **content** | `kmcom-nuxt-layers/layers/content` | core | `@nuxt/content`, `better-sqlite3` |
+
+## Layer Dependency Rules
+
+1. **Always include `core` first** — all other layers depend on it
+2. **Order matters** — list `core` before any layer that depends on it
+3. **Only include what you need** — each layer is independent (apart from the core dependency)
+
+## Layer-Specific Dependencies
+
+Install additional dependencies only for the layers you use:
+
+```bash
+# Motion layer
+npm install gsap locomotive-scroll
+
+# Shader layer
+npm install three @tresjs/nuxt @tresjs/core @tresjs/cientos @tresjs/post-processing
+
+# Forms layer
+npm install zod
+
+# Content layer
+npm install @nuxt/content better-sqlite3
+```
+
+## Configuration Examples
+
+### Core + UI (design system)
+
+```ts
+export default defineNuxtConfig({
+  extends: [
+    'kmcom-nuxt-layers/layers/core',
+    'kmcom-nuxt-layers/layers/ui',
+  ]
+})
+```
+
+### Core + UI + Layout (full page structure)
+
+```ts
+export default defineNuxtConfig({
+  extends: [
+    'kmcom-nuxt-layers/layers/core',
+    'kmcom-nuxt-layers/layers/ui',
+    'kmcom-nuxt-layers/layers/layout',
+  ]
+})
+```
+
+### Core + Motion (animations)
+
+```bash
+npm install gsap locomotive-scroll
+```
+
+```ts
+export default defineNuxtConfig({
+  extends: [
+    'kmcom-nuxt-layers/layers/core',
+    'kmcom-nuxt-layers/layers/motion',
+  ]
+})
+```
+
+### Full Stack
+
+```bash
+npm install gsap locomotive-scroll three @tresjs/nuxt @tresjs/core @tresjs/cientos @tresjs/post-processing zod @nuxt/content better-sqlite3
+```
+
+```ts
+export default defineNuxtConfig({
+  extends: [
+    'kmcom-nuxt-layers/layers/core',
+    'kmcom-nuxt-layers/layers/ui',
+    'kmcom-nuxt-layers/layers/layout',
+    'kmcom-nuxt-layers/layers/motion',
+    'kmcom-nuxt-layers/layers/shader',
+    'kmcom-nuxt-layers/layers/forms',
+    'kmcom-nuxt-layers/layers/theme',
+    'kmcom-nuxt-layers/layers/content',
+  ]
+})
+```
+
+## Overriding Layer Config
+
+Each layer provides typed runtime defaults via `app.config.ts`. Override any value in your own `app.config.ts`:
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  // Core layer overrides
+  coreLayer: {
+    loading: {
+      enabled: false,          // Disable loading screen
+    },
+    scrollGuard: {
+      enabled: false,          // Disable scroll guard
+    },
+  },
+
+  // Motion layer overrides
+  motion: {
+    lenis: {
+      duration: 0.8,           // Faster smooth scroll
+      smoothTouch: true,       // Enable on touch devices
+    },
+  },
+
+  // Theme layer overrides
+  themeLayer: {
+    defaultAccent: 'indigo',   // Change default accent color
+    accents: ['blue', 'indigo', 'violet', 'purple'],  // Limit palette
+  },
+})
+```
+
+### Available Config Namespaces
+
+| Namespace | Layer | Key Options |
+|-----------|-------|-------------|
+| `coreLayer.loading` | core | `enabled`, `minDuration`, `maxDuration`, `background`, `textColor` |
+| `coreLayer.scrollGuard` | core | `enabled`, `strict`, `excludeSelectors`, `debug` |
+| `coreLayer.errors` | core | `logToConsole`, `logToExternal`, `externalUrl` |
+| `coreLayer.notFound` | core | `icon`, `title`, `description`, `showHomeButton`, `actions`, `suggestions` |
+| `motion` | motion | `gsapScrollTrigger`, `lenis.*` (duration, smoothWheel, smoothTouch, etc.) |
+| `themeLayer` | theme | `accents`, `defaultAccent` |
+
+## Optional Modules
+
+Some modules used in the layers are optional or dev-only:
+
+- **`@nuxt/eslint`** — Loaded only in development (`NODE_ENV !== 'production'`). Install if you want layer-provided ESLint config during dev.
+- **`@vite-pwa/nuxt`** — Loaded only in production by the core layer. Install if you want PWA support.
+- **`nuxt-studio`** — Optional peer dependency of the content layer. Install for Nuxt Studio CMS integration.

package/layers/content/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "content",
+  "name": "kmcom-layer-content",
   "type": "module",
   "version": "0.0.1",
   "main": "./nuxt.config.ts",

package/layers/core/nuxt.config.ts

@@ -10,7 +10,7 @@ export default defineNuxtConfig({
 
   // Base modules (always loaded)
   modules: [
-    '@nuxt/eslint',
+    ...(process.env.NODE_ENV !== 'production' ? ['@nuxt/eslint'] : []),
     '@nuxt/ui',
     // '@nuxt/image'
     '@vueuse/nuxt',

package/layers/core/package.json

@@ -1,7 +1,6 @@
 {
-  "name": "@layers/core",
+  "name": "kmcom-layer-core",
   "version": "0.0.1",
-  "private": true,
   "type": "module",
   "main": "./nuxt.config.ts",
   "scripts": {

package/layers/forms/package.json

@@ -1,7 +1,6 @@
 {
-  "name": "@layers/forms",
+  "name": "kmcom-layer-forms",
   "version": "0.0.1",
-  "private": true,
   "type": "module",
   "main": "./nuxt.config.ts",
   "scripts": {

package/layers/layout/package.json

@@ -1,8 +1,7 @@
 {
-  "name": "layout",
+  "name": "kmcom-layer-layout",
   "type": "module",
   "version": "0.0.1",
-  "private": true,
   "main": "./nuxt.config.ts",
   "scripts": {
     "dev": "nuxi dev .playground",

package/layers/motion/package.json

@@ -1,7 +1,6 @@
 {
-  "name": "motion",
+  "name": "kmcom-layer-motion",
   "version": "0.0.1",
-  "private": true,
   "type": "module",
   "main": "./nuxt.config.ts",
   "scripts": {

package/layers/shader/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@nuxt-layers/shader",
+  "name": "kmcom-layer-shader",
   "version": "0.0.1",
   "type": "module",
   "main": "./nuxt.config.ts",

package/layers/theme/package.json

@@ -1,7 +1,6 @@
 {
-  "name": "@layers/theme",
+  "name": "kmcom-layer-theme",
   "version": "0.0.1",
-  "private": true,
   "type": "module",
   "main": "./nuxt.config.ts",
   "scripts": {

package/layers/ui/nuxt.config.ts

@@ -12,7 +12,7 @@ export default defineNuxtConfig({
   },
 
   modules: [
-    '@nuxt/eslint',
+    ...(process.env.NODE_ENV !== 'production' ? ['@nuxt/eslint'] : []),
     '@nuxt/ui',
     // '@nuxt/image'
   ],

package/layers/ui/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "ui",
+  "name": "kmcom-layer-ui",
   "type": "module",
   "version": "0.0.1",
   "main": "./nuxt.config.ts",

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "kmcom-nuxt-layers",
   "private": false,
-  "version": "1.0.2",
-  "description": "",
+  "version": "1.1.0",
+  "description": "Composable Nuxt 4 layers for building scalable Vue applications",
+  "files": [
+    "layers/*/nuxt.config.ts",
+    "layers/*/app.config.ts",
+    "layers/*/package.json",
+    "layers/*/tsconfig.json",
+    "layers/*/app/**",
+    "docs/"
+  ],
   "keywords": [],
   "author": "Kieran Mansfield",
   "license": "ISC",
@@ -15,7 +23,65 @@
     "nuxt": "^4.0.0",
     "@nuxt/ui": "^4.0.0",
     "pinia": "^3.0.0",
-    "@vueuse/nuxt": "^14.0.0"
+    "@vueuse/nuxt": "^14.0.0",
+    "@nuxtjs/device": "^4.0.0",
+    "gsap": "^3.12.0",
+    "locomotive-scroll": "^5.0.0",
+    "three": "^0.170.0",
+    "@tresjs/nuxt": "^5.0.0",
+    "@tresjs/core": "^5.0.0",
+    "@tresjs/cientos": "^5.0.0",
+    "@tresjs/post-processing": "^3.0.0",
+    "zod": "^3.20.0",
+    "@nuxt/content": "^3.0.0",
+    "better-sqlite3": "^12.0.0",
+    "@nuxt/eslint": "^1.0.0",
+    "@vite-pwa/nuxt": "^1.0.0",
+    "nuxt-studio": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nuxtjs/device": {
+      "optional": true
+    },
+    "gsap": {
+      "optional": true
+    },
+    "locomotive-scroll": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    },
+    "@tresjs/nuxt": {
+      "optional": true
+    },
+    "@tresjs/core": {
+      "optional": true
+    },
+    "@tresjs/cientos": {
+      "optional": true
+    },
+    "@tresjs/post-processing": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "@nuxt/content": {
+      "optional": true
+    },
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@nuxt/eslint": {
+      "optional": true
+    },
+    "@vite-pwa/nuxt": {
+      "optional": true
+    },
+    "nuxt-studio": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@commitlint/cli": "^20.4.1",

package/.claude/rules/nuxt-layers.md

@@ -1,23 +0,0 @@
----
-paths:
-  - "layers/**/*"
----
-
-# Nuxt Layers Development
-
-## Layer Structure
-Each layer is an independent package that extends Nuxt apps with:
-- Components (`components/`)
-- Composables (`composables/`)
-- Utilities (`utils/`)
-- Nuxt config (`nuxt.config.ts`)
-
-## Best Practices
-- Layers should be self-contained and composable
-- Avoid circular dependencies between layers
-- Test changes against the playground app
-
-## Layer Dependencies
-- `ui` → depends on nothing
-- `layout` → may use `ui` components
-- `core` → base utilities, no UI dependencies

package/.claude/rules/typescript.md

@@ -1,16 +0,0 @@
----
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
----
-
-# TypeScript Conventions
-
-## Style
-- No semicolons, single quotes, ES5 trailing commas
-- Max line length: 100 characters
-
-## Type Definitions
-- Prefer interfaces for object shapes
-- Use type aliases for unions/intersections
-- Export types alongside implementations