@koehler8/cms 1.0.0-beta.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Koehler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Vertex CMS
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![GitHub Packages](https://img.shields.io/badge/npm-GitHub%20Packages-brightgreen)](https://github.com/koehler8/cms/packages)
+
+Vertex CMS is a lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support.
+
+## Quick Start
+
+### 1. Create a site repo
+
+```
+my-site/
+  site/
+    config/
+      site.json        # Site metadata and settings
+      shared.json      # Shared content blocks
+      pages/
+        home.json      # Per-page content
+    assets/            # Images and media
+    style.css          # Site-specific overrides (optional)
+  .env
+  package.json
+  vite.config.js
+```
+
+### 2. Install
+
+Configure npm to use GitHub Packages for the `@koehler8` scope:
+
+```
+@koehler8:registry=https://npm.pkg.github.com
+```
+
+Then install:
+
+```bash
+npm install @koehler8/cms vue vue-router vite vite-ssg @vitejs/plugin-vue
+```
+
+### 3. Configure Vite
+
+```js
+// vite.config.js
+import cmsPlugin from '@koehler8/cms/vite';
+
+export default {
+  plugins: [
+    cmsPlugin({
+      siteDir: './site',
+      themes: ['@koehler8/cms-theme-neon'],
+      extensions: ['@koehler8/cms-ext-compliance'],
+    }),
+  ],
+};
+```
+
+### 4. Run
+
+```bash
+npm run dev       # Development server
+npm run build     # Production build
+vite-ssg build    # Static site generation
+```
+
+## Plugin Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `siteDir` | `'./site'` | Path to site content directory |
+| `frameworkRoot` | (auto) | Path to `@koehler8/cms` package root |
+| `locales` | all 15 supported | Array of locale codes to enable |
+| `themes` | `[]` | Theme package names to register |
+| `extensions` | `[]` | Extension package names to register |
+
+## Site Configuration
+
+Site content lives in `site/config/`:
+
+- **`site.json`** -- Site-level metadata (title, description, URL, theme, Google Analytics ID)
+- **`shared.json`** -- Content blocks shared across pages (header, footer, socials)
+- **`pages/*.json`** -- Per-page content keyed by page ID
+
+### Locale Overrides
+
+Place locale-specific configs in `site/config/i18n/{locale}/` mirroring the same structure. They are deep-merged over the base config at runtime.
+
+**Supported locales:** en, fr, es, de, ja, ko, pt, ru, tr, vi, id, zh, th, hi, fil
+
+## Themes
+
+Themes export a manifest with design tokens (palette, typography, surfaces, CTAs, etc.) that are applied as CSS variables at runtime.
+
+- Set `site.theme` in `site.json` to a theme slug
+- Omit it to use the built-in `base` theme
+- External themes are npm packages registered via the `themes` plugin option
+
+See `themes/base/theme.config.js` for the full token structure.
+
+## Extensions
+
+Extensions are npm packages that provide additional components, content defaults, and setup hooks.
+
+Each extension has an `extension.config.json` manifest defining:
+
+- **components** -- Vue components with metadata (name, configKey, allowedPages, requiredContent)
+- **entry / setup** -- Optional initialization hooks
+- **assets** -- CSS and static file references
+- **dependencies** -- Required npm packages
+
+Validate extension manifests with:
+
+```bash
+npx cms-validate-extensions --site-dir ./site
+```
+
+## Built-in Components
+
+| Component | Description |
+|-----------|-------------|
+| `Header` | Site header with navigation |
+| `Footer` / `FooterMinimal` | Full and minimal footer variants |
+| `Hero` | Hero banner section |
+| `About` / `AboutValue` | About and value proposition sections |
+| `Contact` | Contact form (Google Forms backend) |
+| `Team` | Team member grid |
+| `Portfolio` | Portfolio showcase |
+| `Plan` | Pricing/plan comparison |
+| `Principles` | Principles/values section |
+| `Intro` / `IntroGate` | Intro modal and gate |
+| `ComingSoon` / `ComingSoonModal` | Coming soon page and modal |
+| `StickyCTA` | Sticky call-to-action bar |
+| `BackToTop` | Scroll-to-top button |
+| `Preloader` | Page loading indicator |
+| `Spacer15/30/40/60` | Vertical spacing utilities |
+
+### UI Components
+
+- `SbCard` -- Card component
+- `SkeletonPulse` -- Loading skeleton
+- `UnitChip` -- Unit/badge chip
+
+## Composables
+
+| Composable | Description |
+|------------|-------------|
+| `usePageConfig` | Load and cache page configuration |
+| `useComponentResolver` | Resolve and validate component definitions |
+| `usePageMeta` | Apply head/meta tags via @unhead |
+| `useEngagementTracking` | Scroll depth and engagement analytics |
+| `useIntroGate` | Intro modal state management |
+| `useComingSoonConfig` | Coming-soon page configuration |
+| `useLazyImage` | Lazy image loading with IntersectionObserver |
+| `usePromoBackgroundStyles` | Promo section background styling |
+
+## Testing
+
+The framework uses [Vitest](https://vitest.dev/) with happy-dom for unit testing.
+
+```bash
+npm test                # Run all tests
+npm run test:watch      # Watch mode
+npm run test:coverage   # Coverage report
+```
+
+Tests live in `tests/` mirroring the source structure (`tests/utils/`, `tests/composables/`, `tests/themes/`, etc.). See `vitest.config.js` for configuration.
+
+## CLI Commands
+
+```bash
+# Generate favicon.ico, logo.png, og-image.jpg from source assets
+npx cms-generate-public-assets --site-dir ./site
+
+# Validate theme manifests
+npx cms-validate-themes
+
+# Validate extension manifests
+npx cms-validate-extensions --site-dir ./site
+```
+
+## Exports
+
+```js
+import cmsPlugin from '@koehler8/cms/vite';           // Vite plugin
+import { createCmsApp } from '@koehler8/cms/app';      // App factory
+import { loadConfigData } from '@koehler8/cms/utils/loadConfig';
+import { resolveAsset, resolveMedia } from '@koehler8/cms/utils/assetResolver';
+import { useResponsiveImage } from '@koehler8/cms/utils/imageSources';
+// ... and all other utils/*, composables/*, components/*, etc.
+```
+
+## Environment Variables
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `VITE_SHOW_COOKIE_BANNER` | cookieConsent | Enable cookie consent banner |
+| `CMS_SITE_DIR` | generate-public-assets | Site directory path (build scripts) |
+| `FAVICON_BG` / `FAVICON_FG` | generate-public-assets | Favicon background/foreground colors |
+
+## License
+
+MIT

package/bin/cms-generate-public-assets.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Wrapper that runs the framework's generate-public-assets.js from the
+// consuming site repo's CWD. Accepts --site-dir <path> to locate site assets;
+// defaults to ./site.
+
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Parse --site-dir arg
+const args = process.argv.slice(2);
+let siteDir = './site';
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--site-dir' && args[i + 1]) {
+    siteDir = args[i + 1];
+    i++;
+  }
+}
+
+// Expose for the underlying script via env var
+process.env.CMS_SITE_DIR = path.resolve(process.cwd(), siteDir);
+
+// Resolve and import the actual script (it runs on import)
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'generate-public-assets.js');
+await import(pathToFileURL(scriptPath).href);

package/bin/cms-validate-extensions.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+let siteDir = './site';
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--site-dir' && args[i + 1]) {
+    siteDir = args[i + 1];
+    i++;
+  }
+}
+
+process.env.CMS_SITE_DIR = path.resolve(process.cwd(), siteDir);
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'validate-extensions.mjs');
+await import(pathToFileURL(scriptPath).href);

package/bin/cms-validate-themes.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const scriptPath = path.resolve(__dirname, '..', 'scripts', 'validate-themes.mjs');
+await import(pathToFileURL(scriptPath).href);

package/extensions/manifest.schema.json

@@ -0,0 +1,125 @@
+{
+  "$id": "https://raw.githubusercontent.com/koehler8/cms/main/extensions/manifest.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Component Extension Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["slug", "version", "provider", "license", "components"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[A-Za-z0-9.-]+)?$"
+    },
+    "provider": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "format": "uri" },
+        "contact": { "type": "string" }
+      }
+    },
+    "entry": {
+      "type": "string",
+      "pattern": "^\\./"
+    },
+    "setup": {
+      "type": "string",
+      "pattern": "^\\./"
+    },
+    "license": {
+      "type": "string",
+      "minLength": 3
+    },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "label", "description", "configKey"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Za-z0-9]+$"
+          },
+          "module": {
+            "type": "string",
+            "pattern": "^\\./.*$"
+          },
+          "label": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "configKey": {
+            "type": "string",
+            "pattern": "^[a-z][A-Za-z0-9]*$"
+          },
+          "propsInterface": {
+            "type": "string",
+            "pattern": "^\\./"
+          },
+          "slots": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
+            "uniqueItems": true
+          },
+          "events": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "uniqueItems": true
+          },
+          "requiredContent": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+          },
+          "allowedPages": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z0-9_-]+$" },
+            "uniqueItems": true
+          },
+          "minAppVersion": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[A-Za-z0-9.-]+)?$"
+          }
+        }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "styles": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^\\./" },
+          "uniqueItems": true
+        },
+        "static": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^\\./" },
+          "uniqueItems": true
+        }
+      }
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "npm": {
+          "type": "object",
+          "propertyNames": {
+            "pattern": "^[a-z0-9@][a-z0-9@/_-]*$"
+          },
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@koehler8/cms",
+  "version": "1.0.0-beta.5",
+  "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koehler8/cms.git"
+  },
+  "author": "Chris Koehler",
+  "homepage": "https://github.com/koehler8/cms#readme",
+  "bugs": {
+    "url": "https://github.com/koehler8/cms/issues"
+  },
+  "keywords": ["vue", "cms", "vite", "ssg", "theming", "extensions", "config-driven"],
+  "scripts": {
+    "postinstall": "node scripts/patch-lru-cache-tla.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "exports": {
+    "./vite": "./vite-plugin.js",
+    "./app": "./src/main.js",
+    "./utils/loadConfig": "./src/utils/loadConfig.js",
+    "./utils/siteStyles": "./src/utils/siteStyles.js",
+    "./utils/assetResolver": "./src/utils/assetResolver.js",
+    "./utils/*.js": "./src/utils/*.js",
+    "./utils/*": "./src/utils/*.js",
+    "./composables/*.js": "./src/composables/*.js",
+    "./composables/*": "./src/composables/*.js",
+    "./components/*.vue": "./src/components/*.vue",
+    "./components/*.js": "./src/components/*.js",
+    "./components/*": "./src/components/*",
+    "./router": "./src/router/index.js",
+    "./themes/*.js": "./src/themes/*.js",
+    "./themes/*": "./src/themes/*.js",
+    "./extensions/*.js": "./src/extensions/*.js",
+    "./extensions/*": "./src/extensions/*.js",
+    "./constants/*.js": "./src/constants/*.js",
+    "./constants/*": "./src/constants/*.js",
+    "./plugins/*.js": "./src/plugins/*.js",
+    "./plugins/*": "./src/plugins/*.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "cms-generate-public-assets": "./bin/cms-generate-public-assets.js",
+    "cms-validate-themes": "./bin/cms-validate-themes.js",
+    "cms-validate-extensions": "./bin/cms-validate-extensions.js"
+  },
+  "files": [
+    "src",
+    "extensions",
+    "themes",
+    "scripts",
+    "public",
+    "templates",
+    "bin",
+    "vite-plugin.js",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "vite": "^8.0.0",
+    "vite-ssg": "^28.0.0",
+    "vue": "^3.5.0",
+    "vue-router": "^5.0.0"
+  },
+  "dependencies": {
+    "@unhead/vue": "^2.0.19",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "canvas": "^3.2.0",
+    "dotenv": "^17.2.3",
+    "pinia": "^3.0.1",
+    "png-to-ico": "^3.0.1"
+  },
+  "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
+    "happy-dom": "^20.8.9",
+    "vitest": "^4.1.4"
+  }
+}

package/public/img/preloaders/preloader-black.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0" width="34px" height="34px" viewBox="0 0 128 128" xml:space="preserve"><g><path d="M75.4 126.63a11.43 11.43 0 0 1-2.1-22.65 40.9 40.9 0 0 0 30.5-30.6 11.4 11.4 0 1 1 22.27 4.87h.02a63.77 63.77 0 0 1-47.8 48.05v-.02a11.38 11.38 0 0 1-2.93.37z" fill="#000000" fill-opacity="1"/><animateTransform attributeName="transform" type="rotate" from="0 64 64" to="360 64 64" dur="800ms" repeatCount="indefinite"></animateTransform></g></svg>

package/public/img/preloaders/preloader-white.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.0" width="34px" height="34px" viewBox="0 0 128 128" xml:space="preserve"><g><path d="M75.4 126.63a11.43 11.43 0 0 1-2.1-22.65 40.9 40.9 0 0 0 30.5-30.6 11.4 11.4 0 1 1 22.27 4.87h.02a63.77 63.77 0 0 1-47.8 48.05v-.02a11.38 11.38 0 0 1-2.93.37z" fill="#ffffff" fill-opacity="1"/><animateTransform attributeName="transform" type="rotate" from="0 64 64" to="360 64 64" dur="800ms" repeatCount="indefinite"></animateTransform></g></svg>

package/public/robots.txt

@@ -0,0 +1,5 @@
+User-agent: *
+Disallow: /admin
+Disallow: /privacy
+Disallow: /terms
+Disallow: /cookies

package/scripts/check-overflow.mjs

@@ -0,0 +1,33 @@
+import { chromium } from 'playwright';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const distIndex = path.resolve(__dirname, '../dist/index.html');
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 412, height: 915 } });
+await page.goto(`file://${distIndex}`);
+await page.waitForTimeout(2000);
+const result = await page.evaluate(() => ({
+  scrollWidth: document.documentElement.scrollWidth,
+  clientWidth: document.documentElement.clientWidth,
+  bodyScrollWidth: document.body.scrollWidth,
+  bodyClientWidth: document.body.clientWidth,
+  overflowElements: Array.from(document.querySelectorAll('*')).map(el => {
+    const rect = el.getBoundingClientRect();
+    const docWidth = document.documentElement.clientWidth;
+    const overflowX = rect.right > docWidth + 1;
+    return overflowX ? {
+      tag: el.tagName.toLowerCase(),
+      classes: el.className,
+      rectRight: rect.right,
+      rectLeft: rect.left,
+      width: rect.width,
+      text: el.textContent?.trim().slice(0, 120)
+    } : null;
+  }).filter(Boolean)
+}));
+console.log(JSON.stringify(result, null, 2));
+await browser.close();