Documentation

Muon Site Engine

Build ultra-premium, enterprise-grade SaaS and corporate websites using a 100% JSON-driven headless architecture. No React or CSS knowledge required.

Zero-Code Workflow

This package allows you to control the entire structure, content, and design of a production-ready website simply by editing two JSON files.


Installation & Setup

To generate a new website, you must have Node.js installed and authenticate with the GitHub Packages Registry.

1 Authenticate with GitHub Packages

To ensure that you can use the Muon Site Engine CLI generator from anywhere on your machine, you must authenticate globally. Follow these steps:

  1. Generate a Personal Access Token (PAT) with read:packages permissions on GitHub.
  2. Open your terminal (Terminal on Mac, or Command Prompt/PowerShell on Windows) and run the following commands to authenticate globally:
    npm config set //npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT_HERE
    npm config set @leoc1992:registry=https://npm.pkg.github.com/

Note: The above commands work seamlessly on both Mac and Windows. They automatically generate a global config file in your user directory:

  • Mac / Linux: Creates ~/.npmrc
  • Windows: Creates %USERPROFILE%\.npmrc (e.g., C:\Users\YourName\.npmrc)

This authenticates your entire system, allowing you to run the CLI from anywhere.

2 Scaffold your Website

Run the automated CLI tool to generate a fresh website project instantly:

npx @leoc1992/site-engine my-awesome-site
cd my-awesome-site
npm install
npm run dev

Your website is now running at http://localhost:5173


AI-Native Architecture

AI Agent Skill Architecture

The Muon Site Engine was engineered from the ground up to be an AI-native website operating system. Because 100% of the UI, layouts, styles, SEO, and popups are defined declaratively via JSON schemas, modern autonomous agents (such as Google Antigravity, Cursor, Windsurf, Claude Code, and Copilot) can architect and modify complex, high-converting websites in seconds with zero hallucination.

1

Standardized Skill Directory

The repo houses .agents/skills/site-engine/SKILL.md which automatically loads engine constraints, section types, and props into the agent's context.

2

Zero-Code JSON Pipeline

Agents modify config.json, theme.json, seo.json, and popups.json without touching or corrupting core React components.

3

Developer Extension Safety

When custom logic is required, agents are instructed to leverage customComponents and slots instead of forking the engine.

The Universal AI Base Prompt Template

When starting a new session or instructing an AI agent to build or modify a website, copy and paste this base prompt. It sets up strict architectural guardrails and ensures the agent outputs production-ready code:

You are building a website using `@leoc1992/site-engine` (a 100% JSON-driven React Website Engine).

Before writing any code or modifying configurations:
1. READ and follow `.agents/skills/site-engine/SKILL.md` and the project guidelines in `.agents/AGENTS.md`.
2. Adhere strictly to the JSON-driven architecture:
   - Do NOT hardcode text, images, links, or styles directly into React section components.
   - Modify `src/config.json` (content/structure), `public/theme.json` (theming/customCss), `src/config/seo.json` (technical SEO), and `src/config/popups.json` (modals/lead capture).
3. If custom React logic or 3rd-party widgets are needed, use developer extensions (`customComponents`, `slots`, and `slotProps`) on `` rather than modifying core engine files.
4. Elevate visual design with engine tokens:
   - Use `cardVariant: "glass"` with frosted blurs, or `cardVariant: "neumorphic"` / `"neumorphic-inset"`.
   - Enable interactive cursor spotlights (`spotlight: true` or `hoverEffect: "spotlight"`).
   - Use kinetic shimmer typography (`shimmer: true`, `gradientPreset: "aurora"`).

--- TASK SPECIFICATION ---
- Company / Project Name: [Insert Name]
- Industry / Vibe: [e.g. Ultra-modern AI Developer Platform, Dark Mode, Sapphire & Cyan accents]
- Target Pages: [e.g. Home (/), Pricing (/pricing), Features (/features), Docs (/docs)]
- Specific Requirements: [e.g. Exit-intent lead capture modal, Google Analytics 4 integration, Mega Menu header]

Anatomy of a High-Converting Engine Prompt

1. Skill & Rule Anchoring: Directs the agent to the exact local markdown skills so it understands token names and valid layout types.
2. JSON Modification Constraints: Stops the agent from overwriting core JSX sections with hardcoded client content.
3. Visual Style Directives: Forces the agent to use modern design layers (glass, neumorphism, aurora mesh) instead of generic flat styles.
4. Scope & Routing Directives: Tells the agent whether to generate a single landing page or a multi-page routing structure via pages.

Task-Specific Prompt Recipes

Use these specialized prompt snippets for specific website building and optimization tasks:

Recipe 1 Enterprise SaaS Platform Generation

Generates complete site configuration, dark theme tokens, mega-navigation, and comparison pricing:

Using `@leoc1992/site-engine`, generate `src/config.json` and `public/theme.json` for "CognitiveMesh AI" — an autonomous workflow orchestration platform.
Requirements:
1. Theme: Dark mode (`#0b0f19` background), cyan (`#06b6d4`) primary, violet (`#8b5cf6`) secondary, `glass` cardVariant.
2. Pages: Home (`/`) with Hero (split layout, kinetic shimmer badge), Bento grid features, social proof stats, and CTA. Pricing (`/pricing`) with 3-tier comparison layout and annual billing toggle.
3. Navigation: Multi-column `mega` menu with "Products", "Solutions", and "Enterprise Guides".
4. Copywriting: Enterprise-grade, technical, and high-converting.

Recipe 2 Zero-Code Technical SEO & Rich Snippets

Optimizes search engine metadata, OpenGraph tags, and Schema.org JSON-LD structured data:

Generate a comprehensive `src/config/seo.json` for `@leoc1992/site-engine`:
1. Site: titleTemplate: "%s | QuantumFlow AI", canonical baseUrl: "https://quantumflow.ai", OpenGraph image, Twitter card summary_large_image.
2. Structured Data: Organization schema with logo and contactPoint; WebSite SearchAction schema.
3. Page Overrides: Detailed meta title, description, and FAQPage schema for `/faq`; Product/Offer schema for `/pricing`.
4. Analytics: Google Analytics 4 (G-XXXXXXXXXX) and Microsoft Clarity (clarity_project_id).

Recipe 3 Exit-Intent & High-Converting Popups

Configures lead-generation and exit modals with frequency capping and route suppression:

Add a high-converting exit-intent modal in `src/config/popups.json` using the `@leoc1992/site-engine` popups schema:
1. ID: "exit-lead-magnet", variant: "glass", trigger: "exitIntent" (sensitivity: 25px, fallbackDelayMs: 25000).
2. Frequency: maxImpressions: 2, cooldownDays: 5, oncePerSession: true, stopOnConversion: true.
3. Targeting: includeRoutes: ["/", "/pricing", "/features*"], excludeRoutes: ["/checkout", "/dashboard/*"].
4. Content: Badge: "Exclusive Sandbox", Title: "Deploy 50 Autonomous Agents Free", CTA: "Claim Instant Sandbox".

Recipe 4 Developer React Slots & Component Injection

Injects custom interactive React components into JSON-driven sections without forking the engine:

In my `@leoc1992/site-engine` Next.js/Vite app:
1. Show me how to use the `slots` prop on `` to inject a custom interactive 3D Three.js canvas into the hero section (`hero-media` slot).
2. Show how to use `customComponents` to replace the contact section with a multi-step Typeform-like interactive quote estimator while consuming theme tokens via `useThemeTokens()`.

Prompt Blueprint Matrix by Industry

Industry / Use Case Recommended Theme & Colors Card Variant & FX Key Sections & Layouts
AI & Developer Tools Dark mode (#090d16), Cyan (#38bdf8), Indigo (#818cf8) glass (blur: 20px), spotlight: true Hero (split), Bento Grid (features), Terminal / Code, CTA
Enterprise Fintech Dark mode (#0b132b), Emerald (#10b981), Slate (#94a3b8) neumorphic, shimmer: true Hero (centered), Security Badges, Comparison Table, FAQ
Creative Agency Light mode (#fcfcfd), Coral (#f43f5e), Violet (#8b5cf6) glass, hoverEffect: "lift" Hero (fullscreen video), Masonry Gallery, Team Cards, Contact
B2B SaaS / Analytics Light mode (#f8fafc), Sapphire (#0f52ba), Amber (#f59e0b) elevated, spotlight: true Hero (split), Metric Counters, 3-Tier Pricing, Popups

File Structure

Once scaffolded, your project is highly minimized. You only need to care about the two highlighted JSON files.

my-awesome-site/
├── .npmrc               <-- Pre-configured for GitHub Packages
├── AI_INSTRUCTIONS.md   <-- AI Assistant rules
├── MUON_COMPONENTS_DOCS.html <-- Offline component schema docs
├── package.json
├── public/
│   ├── favicon.ico
│   └── theme.json       <-- Edit this for Colors, Fonts, & Design
└── src/
    ├── App.jsx
    ├── config.json      <-- Edit this to Build Your Website
    └── main.jsx

Understanding config.json

The config.json file controls what appears on your website. It is divided into two main parts: the site metadata and the sections array.

{
  "site": {
    "title": "My Company",
    "seo": {
      "title": "My Company | Premium Services",
      "description": "We deliver excellence.",
      "keywords": ["saas", "enterprise"]
    }
  },
  "sections": [
    // Your website structural blocks go here
  ]
}

Multi-Page Routing

The engine natively supports React Router. If you want to build a multi-page website (instead of a Single-Page App), you can replace the sections array with a pages object mapping to different routes.

{
  "site": {
    "title": "My Company",
  },
  "pages": {
    "/": {
      "seo": { "title": "Home" },
      "sections": [
        { "id": "hero-1", "type": "hero", "content": {...} }
      ]
    },
    "/pricing": {
      "seo": { "title": "Pricing" },
      "sections": [
        { "id": "pricing-1", "type": "pricing", "content": {...} }
      ]
    }
  }
}

Note: You can link between these pages seamlessly in the Header's navLinks or CTA button href properties.

Managing Sections

The sections array in config.json dictates the exact visual order of blocks on your webpage. The engine renders this array sequentially.

Add

Insert a new JSON object into the array. Provide an id, type, and content.

Remove

Delete the JSON object entirely from the array. The component is instantly removed.

Reorder

Move the JSON object up or down within the array to change its physical position on the page.

"sections": [
  {
    "id": "header-1",
    "type": "header",
    "layout": "glass",
    "content": { ... }
  },
  {
    "id": "hero-1",
    "type": "hero",
    "layout": "split",
    "content": { ... }
  }
]

Theming & Design (theme.json)

The theme.json file acts as the universal design system for the website. The engine uses this to dynamically generate CSS variables and a custom Material UI theme.

1. Auto Dark & Light Mode

You can set the theme mode to "light", "dark", or "system". If set to system, the website will natively sync with the user's OS preference.

{
  "theme": {
    "mode": "system",
    "colors": {
      "primary": "#4f46e5",
      "secondary": "#ec4899"
    }
  }
}

2. Custom Font Uploads

You can bypass Google Fonts entirely by hosting your own fonts in the public/fonts/ directory and registering them in fontFaces.

{
  "typography": {
    "fontFaces": [
      {
        "fontFamily": "ClashDisplay",
        "url": "/fonts/ClashDisplay-Bold.woff2",
        "format": "woff2",
        "weight": 700
      }
    ],
    "fontFamilyHeading": "ClashDisplay, sans-serif"
  }
}

3. Glassmorphism Effects

You can switch the global card design from solid cards to frosted glass by using the glass variant.

{
  "shape": {
    "cardVariant": "glass",
    "glassBlur": "16px",
    "glassOpacity": 0.15
  }
}

4. Micro-Interactions

Enable physics-based interactions like magnetic buttons and a custom trailing cursor.

{
  "interactions": {
    "customCursor": true,
    "magneticButtons": true
  }
}

5. Granular Style Overrides (styleOverrides)

Fine-tune margins, paddings, and styles for specific section IDs, CSS classes, or built-in Material UI components directly in JSON.

{
  "styleOverrides": {
    "#hero-section": {
      "paddingTop": "120px",
      "paddingBottom": "100px"
    },
    ".feature-card": {
      "padding": "36px",
      "marginBottom": "24px"
    },
    "MuiButton": {
      "borderRadius": "999px",
      "textTransform": "none"
    },
    "MuiCard": {
      "borderRadius": "24px"
    }
  }
}

6. Raw Custom CSS (customCss)

Inject raw CSS strings, keyframe animations, media queries, and responsive style rules without touching source code.

{
  "customCss": "/* Custom Glowing Pulsing Keyframe */\n@keyframes pulseGlow {\n  0%, 100% { box-shadow: 0 0 20px rgba(79, 70, 229, 0.4); }\n  50% { box-shadow: 0 0 40px rgba(79, 70, 229, 0.8); }\n}\n\n.glow-button {\n  animation: pulseGlow 3s infinite ease-in-out;\n}\n\n@media (max-width: 768px) {\n  .custom-section { padding-top: 48px !important; }\n}"
}

Component Reference

Every object in the sections array must specify a type. Below is the documentation for all available types and their configurable properties.

Header

"type": "header"

The top navigation bar. Includes a logo, navigation links, and a Call-To-Action (CTA) button. Automatically handles mobile responsiveness with a hamburger menu.

AI Context: Include exactly ONE header at the very top of the sections array for site navigation.

Available Layouts: "default", "sticky", "glass", "centered"

Overrides: Explicitly set "background": "var(--token-color-paper)" or a hex code to override transparency.

Dropdowns & Mega Menus: Add "type": "mega" and a "megaMenu" object inside navLinks for desktop flyout columns and mobile accordion sub-menus.

{
  "id": "main-header",
  "type": "header",
  "layout": "glass",
  "background": "var(--token-color-paper)",
  "content": {
    "logoText": "MyBrand",
    "logoImage": "/logo.png",
    "navLinks": [
      { "label": "Home", "href": "/" },
      {
        "label": "Services",
        "type": "mega",
        "megaMenu": {
          "columns": [
            {
              "title": "Solutions",
              "links": [
                { "label": "Cloud Engineering", "href": "/cloud" },
                { "label": "AI Solutions", "href": "/ai" }
              ]
            }
          ],
          "featured": {
            "title": "Case Study: 10x Scale",
            "image": "/featured.jpg",
            "href": "/case-study"
          }
        }
      },
      { "label": "Pricing", "href": "/pricing" }
    ],
    "ctaButton": { "label": "Get Started", "href": "/contact", "variant": "contained" }
  }
}

Hero

"type": "hero"

The main landing section at the top of a webpage. High impact, designed to grab attention immediately.

AI Context: Use this as the very first section of the homepage (after the header) to introduce the core value proposition and drive a primary call to action.

Available Layouts: "split" (Text left, image right), "center" (Text centered)

Backgrounds: "mesh", "grid", or color tokens.

{
  "id": "hero-1",
  "type": "hero",
  "layout": "split",
  "background": "mesh",
  "content": {
    "badge": "New Release 2.0",
    "title": "Build Faster",
    "subtitle": "The ultimate tool for developers.",
    "primaryCta": { "label": "Start Free Trial", "href": "#pricing" },
    "secondaryCta": { "label": "Read Docs", "href": "#docs" },
    "image": "https://images.unsplash.com/photo-xxx"
  }
}

About

"type": "about"

Introduce your company, mission, or vision.

AI Context: Use this section when you need a split layout (image on one side, text/mission/vision on the other) with optional statistics.

Available Layouts: "split", "default"

{
  "id": "about-1",
  "type": "about",
  "layout": "split",
  "content": {
    "title": "Our Mission",
    "description": "We are dedicated to building the future of the web.",
    "image": "https://images.unsplash.com/photo-xxx",
    "stats": [
      { "value": "10+", "label": "Years Experience" },
      { "value": "500+", "label": "Clients" }
    ]
  }
}

Features

"type": "features"

Displays a list of product features, value propositions, or services.

AI Context: Use this extensively to highlight product capabilities in a grid of 3 or 4 columns. It's the bread-and-butter of SaaS landing pages.

Available Layouts: "grid" (Standard cards), "bento" (Asymmetrical grid), "tabs" (Interactive left/right)

{
  "id": "features-1",
  "type": "features",
  "layout": "bento",
  "content": {
    "title": "Why Choose Us",
    "subtitle": "Everything you need to succeed.",
    "items": [
      {
        "icon": "cloud", // Lucide-react icon name
        "title": "Cloud Sync",
        "description": "Always backed up securely."
      }
    ]
  }
}

Clients

"type": "clients"

Display logos of companies you have worked with to establish trust.

AI Context: Place this immediately after the hero section (or bottom of page) to provide social proof.

Available Layouts: "grid", "marquee" (infinite horizontal scroll)

{
  "id": "clients-1",
  "type": "clients",
  "layout": "marquee",
  "content": {
    "title": "Trusted by industry leaders",
    "logos": [
      { "name": "Company A", "image": "/logo-a.png" },
      { "name": "Company B", "image": "/logo-b.png" }
    ]
  }
}

Pricing

"type": "pricing"

Displays subscription tiers or service packages.

AI Context: Use this to display standard 3-tier SaaS pricing models.

Available Layouts: "cards"

{
  "id": "pricing-1",
  "type": "pricing",
  "layout": "cards",
  "content": {
    "title": "Simple Pricing",
    "plans": [
      {
        "name": "Pro",
        "price": "$29",
        "period": "/mo",
        "popular": true, // Elevates and highlights this card
        "features": ["Feature A", "Feature B"],
        "cta": "Buy Now"
      }
    ]
  }
}

Stats

"type": "stats"

Highlight numerical achievements, user counts, or operational metrics.

AI Context: Great for building credibility right above the footer or below the features section.

Available Layouts: "grid"

{
  "id": "stats-1",
  "type": "stats",
  "layout": "grid",
  "content": {
    "title": "By the numbers",
    "items": [
      { "value": "10M+", "label": "Active Users" },
      { "value": "99.9%", "label": "Uptime" }
    ]
  }
}

Team

"type": "team"

Introduce your team members, founders, or board of directors.

AI Context: Standard grid layout for an "About Us" page or agency site to show the faces behind the company.

Available Layouts: "grid"

{
  "id": "team-1",
  "type": "team",
  "layout": "grid",
  "content": {
    "title": "Meet the Team",
    "members": [
      {
        "name": "Alice Smith",
        "role": "CEO",
        "image": "https://images.unsplash.com/photo-xxx",
        "social": { "twitter": "#", "linkedin": "#" }
      }
    ]
  }
}

Testimonials

"type": "testimonials"

Social proof and client reviews.

AI Context: Include this to build trust. Marquee layout is best for SaaS, grid is best for agencies.

Available Layouts: "grid", "carousel", "marquee"

{
  "id": "testimonials-1",
  "type": "testimonials",
  "layout": "marquee",
  "content": {
    "title": "Loved by thousands",
    "items": [
      {
        "quote": "This product changed my life completely.",
        "author": "Jane Doe",
        "role": "CEO, Startup"
      }
    ]
  }
}

Timeline

"type": "timeline"

Display a chronological company history, roadmap, or process steps.

AI Context: Use for "How it works" steps (1, 2, 3) or company history.

Available Layouts: "vertical"

{
  "id": "timeline-1",
  "type": "timeline",
  "layout": "vertical",
  "content": {
    "title": "Our Journey",
    "events": [
      {
        "year": "2024",
        "title": "Company Founded",
        "description": "Started in a garage."
      }
    ]
  }
}

Articles

"type": "articles"

Display a blog feed, recent news articles, or press releases.

AI Context: Great for adding a "Latest News" section near the bottom of a homepage.

Available Layouts: "grid", "list"

{
  "id": "articles-1",
  "type": "articles",
  "layout": "grid",
  "content": {
    "title": "Latest News",
    "posts": [
      {
        "title": "Understanding the Cloud",
        "excerpt": "A brief guide to...",
        "date": "Oct 12, 2026",
        "image": "https://images.unsplash.com/...",
        "link": "/blog/cloud"
      }
    ]
  }
}

FAQ

"type": "faq"

Frequently Asked Questions using accessible, expandable accordions.

AI Context: Include this to address common objections before a CTA.

Available Layouts: "default" (Stacked list), "grid" (2-column layout)

{
  "id": "faq-1",
  "type": "faq",
  "layout": "default",
  "content": {
    "title": "Common Questions",
    "items": [
      {
        "question": "How do I sign up?",
        "answer": "Click the button in the header."
      }
    ]
  }
}

CTA (Call To Action)

"type": "cta"

High-conversion block intended to drive users to sign up or contact sales, typically placed just before the footer.

AI Context: The ultimate conversion point. Use right above the footer or Newsletter block.

Available Layouts: "default", "split"

{
  "id": "cta-1",
  "type": "cta",
  "layout": "default",
  "background": "gradient",
  "content": {
    "title": "Ready to get started?",
    "subtitle": "Join thousands of users today.",
    "primaryCta": { "label": "Start Trial", "href": "/signup" }
  }
}

Newsletter

"type": "newsletter"

Email capture form block for lead generation.

AI Context: Use this block if the user specifically mentions lead capture, subscriptions, or mailing lists.

Available Layouts: "center"

{
  "id": "newsletter-1",
  "type": "newsletter",
  "layout": "center",
  "content": {
    "title": "Subscribe to our Newsletter",
    "subtitle": "Get weekly updates and tips.",
    "buttonLabel": "Subscribe"
  }
}

Contact

"type": "contact"

Displays contact information and a functional contact form UI.

AI Context: Typically used on a dedicated /contact page.

Available Layouts: "split", "center"

{
  "id": "contact-1",
  "type": "contact",
  "layout": "split",
  "content": {
    "title": "Get in Touch",
    "email": "[email protected]",
    "phone": "+1 234 567 8900",
    "address": "123 Main St, City"
  }
}

Bento Grids

"type": "bento"

Create asymmetrical "Apple-style" layouts using colSpan and rowSpan.

AI Context: Extremely popular modern design trend. Use this instead of standard grids if the user asks for a "modern Apple-like feel".

{
  "id": "bento-1",
  "type": "bento",
  "layout": { "columns": 3 },
  "content": {
    "blocks": [
      { "title": "Large Feature", "colSpan": 2, "rowSpan": 2 },
      { "title": "Small Stat", "colSpan": 1, "rowSpan": 1 }
    ]
  }
}

Comparison Tables

"type": "comparison"

Build SaaS feature matrices (Us vs Them, Free vs Pro) with sticky headers.

AI Context: Use this below the Pricing section for deep-dive feature comparisons.

{
  "id": "comparison-1",
  "type": "comparison",
  "content": {
    "columns": [{ "title": "Feature" }, { "title": "Pro" }],
    "rows": [
      { "label": "API Access", "values": [true] }
    ]
  }
}

Content Tabs

"type": "tabs"

Interactive switchers for grouping use-cases without long scrolling.

AI Context: Excellent for pages with "Solutions for X, Y, Z" to avoid overwhelming the user.

{
  "id": "tabs-1",
  "type": "tabs",
  "content": {
    "tabs": [
      { "label": "Developers", "title": "Built for Code", "image": "/dev.jpg" },
      { "label": "Designers", "title": "Pixel Perfect", "image": "/design.jpg" }
    ]
  }
}

Interactive Maps

"type": "map"

Easily embed Google Maps or OpenStreetMap iframes in a styled glass container.

AI Context: Use on local business websites or Contact pages to show physical locations.

{
  "id": "map-1",
  "type": "map",
  "content": {
    "title": "Visit Us",
    "embedUrl": "https://www.google.com/maps/embed?..."
  }
}

Infinite Marquees

"type": "marquee"

Seamless looping tickers for logos, keywords, or stock prices.

AI Context: Use this as a dynamic divider between large sections, or for client logos.

{
  "id": "marquee-1",
  "type": "marquee",
  "content": {
    "speed": "fast",
    "direction": "left",
    "items": [
      { "image": "/logo1.png" },
      { "text": "BREAKING NEWS" }
    ]
  }
}

3D WebGL (Spline)

"type": "spline"

Embed interactive 3D Spline experiences alongside your text.

AI Context: Add a massive wow factor to landing pages. Use this in a split layout next to a Hero or Feature block.

{
  "id": "spline-1",
  "type": "spline",
  "content": {
    "title": "Interactive 3D",
    "splineUrl": "https://my.spline.design/xxxx/"
  }
}

🎬 Global Video Modals

Any button in the entire engine can trigger a cinematic, full-screen YouTube Lightbox Modal without writing a single line of JavaScript. Just set the button's href to #video-YOUTUBE_ID.

{
  "label": "Watch Trailer",
  "href": "#video-dQw4w9WgXcQ"
}

Forms & Integrations

The contact and newsletter components support out-of-the-box data capture via Web3Forms or generic webhooks (like Zapier, Make, or your own custom API).

1. Web3Forms (Email Delivery)

Web3Forms allows you to receive form submissions directly to your email without any backend server. Simply get a free Access Key from their website.

{
  "type": "contact",
  "content": {
    "title": "Contact Us",
    "formIntegration": {
      "provider": "web3forms",
      "accessKey": "YOUR_WEB3FORMS_ACCESS_KEY"
    }
  }
}

2. Generic Webhooks (Zapier / Custom APIs)

If you want to send data to Zapier, Make.com, or your own database, use the webhook provider. The engine will send a POST request with the JSON payload.

{
  "type": "newsletter",
  "content": {
    "title": "Subscribe",
    "formIntegration": {
      "provider": "webhook",
      "endpoint": "https://hooks.zapier.com/hooks/catch/123456/"
    }
  }
}

Rich Media Backgrounds

Any major section (like hero or features) supports a backgroundMedia object to inject looping videos, interactive 3D Spline scenes, or WebGL shaders natively behind your content.

1. Cinematic Video Backgrounds

Set the type to video to autoplay an mp4 or webm silently behind the text.

{
  "type": "hero",
  "backgroundMedia": {
    "type": "video",
    "url": "/assets/my-cinematic-bg.mp4",
    "opacity": 0.5,
    "overlayColor": "#000000"
  },
  "content": {
    "title": "Welcome to the Future"
  }
}

2. Interactive 3D (Spline & WebGL)

Set the type to iframe to seamlessly embed a 3D scene from Spline. The engine automatically handles pointer-events so it doesn't block scrolling.

{
  "type": "hero",
  "backgroundMedia": {
    "type": "iframe",
    "url": "https://my.spline.design/your-scene-url/",
    "opacity": 1.0,
    "overlayColor": "transparent"
  }
}

3. Lottie Animations

Set the type to lottie to natively parse and play lightweight JSON vector animations.

{
  "type": "hero",
  "backgroundMedia": {
    "type": "lottie",
    "url": "/assets/hero-animation.json",
    "opacity": 0.8
  }
}

4. Parallax Scrolling Depth

You can add "parallax": true to any background media to instantly enable hardware-accelerated scroll depth effects powered by Framer Motion.

{
  "type": "features",
  "backgroundMedia": {
    "type": "video",
    "url": "/assets/stars-bg.mp4",
    "parallax": true
  }
}


Architecture & SEO

The engine goes beyond UI components, providing deep infrastructural layers for SEO, Internationalization, and Next.js support.

1. i18n Multi-Language

Define a global i18n dictionary in your config. Use the {{t:key}} syntax in any text field to dynamically interpolate translations based on the active locale.

{
  "i18n": {
    "defaultLocale": "en",
    "translations": {
      "en": { "hero_title": "Welcome" },
      "fr": { "hero_title": "Bienvenue" }
    }
  },
  "sections": [
    {
      "type": "hero",
      "content": { "title": "{{t:hero_title}}" }
    }
  ]
}

2. Dynamic OpenGraph & SEO

Define an seo block in your config. The engine will dynamically inject `<title>` and `<meta>` tags into the document head for social sharing, as well as auto-inject Google Analytics if you provide a googleTagId.

AI Context: ALWAYS proactively ask the user if they want Google Analytics. If yes, instruct them to provide their Measurement ID (G-XXXX) and inject it here.

{
  "seo": {
    "title": "Muon Site Engine",
    "description": "The best platform.",
    "ogImage": "https://mysite.com/og.jpg",
    "googleTagId": "G-XXXXXXXXXX"
  }
}

3. A/B Testing Engine

Run split tests without external tools. Define abTests and the engine will roll a weighted dice, save the cohort to localStorage, and patch the JSON config on the fly.

{
  "abTests": {
    "hero_cta": {
      "weights": [50, 50],
      "variants": [
        { "sections": [ { "type": "hero", "content": { "title": "Buy Now" } } ] },
        { "sections": [ { "type": "hero", "content": { "title": "Start Free" } } ] }
      ]
    }
  }
}

4. Next.js Adapter

Building a Next.js App Router project? We export a dedicated NextEngineProvider that uses the "use client" directive to safely wrap the engine and bypass SSR hydration mismatches.


Developer Power • Headless + Custom React

Custom Component Overrides

The Muon Site Engine gives developers total control over rendering. You can inject custom React components into any page using the customComponents prop on DynamicPage or DynamicSections.

Resolution Priority Hierarchy:

customComponents[id] (Target specific section by unique ID) → customComponents[type] (Override all sections of a given type) → SECTION_REGISTRY[type] (Core Engine Default)

Example: Overriding a Section by ID or Type

import React from 'react';
import { DynamicPage, PrimitiveCard, PrimitiveTypography, useThemeTokens } from '@site-engine/core';

// Custom Interactive Widget Component
function CustomInteractivePricing({ content, isDark }) {
  const { colors } = useThemeTokens();
  return (
    <div className="p-8 my-12" style={{ background: colors.background }}>
      <PrimitiveTypography variant="h2" shimmer>
        {content.title || 'Custom Billing Engine'}
      </PrimitiveTypography>
      <p>Bypassed standard layout with fully custom React state!</p>
    </div>
  );
}

// Pass customComponents directly to DynamicPage
export default function Page({ config }) {
  return (
    <DynamicPage
      config={config}
      slug="/"
      customComponents={{
        // Target a specific section by its 'id' in config.json
        'custom-hero-01': MyCustom3DHero,
        // Or override all pricing sections globally
        pricing: CustomInteractivePricing,
      }}
    />
  );
}

Slots & Render Props Injection

Want to use the built-in sections but inject custom UI elements (like an interactive annual billing switch, email validation form, or 3D badge) without replacing the whole section? Use Slots and SlotProps.

Component Available Slots Description
HeroSection badge, actions, media, background Inject custom CTAs, 3D canvas, or glowing badge overlays.
PricingSection billingToggle, planFooter, planBadge Inject custom currency switchers or annual/monthly toggles.
CTASection form, actions, background Inject custom multi-step lead capture or Hubspot forms.
PrimitiveCard header, footer, media Composable card header/footer subcomponents.
PrimitiveContainer top, bottom, background Full section backdrop overlays or divider decorations.

Example: Injecting a Slot into Pricing

<DynamicPage
  config={config}
  slug="/pricing"
  slots={{
    pricing: {
      billingToggle: (
        <div className="flex justify-center items-center gap-3 my-6">
          <span className="text-sm font-semibold">Monthly</span>
          <Switch onChange={(e) => setIsAnnual(e.target.checked)} />
          <span className="text-sm font-semibold text-indigo-600">Annual (Save 20%)</span>
        </div>
      )
    }
  }}
/>

useThemeTokens Hook API

The useThemeTokens() hook provides instant, reactive access to computed palette colors, typography fonts, shape radii, glassmorphism tokens, and neumorphic box shadows.

import { useThemeTokens } from '@site-engine/core';

export function CustomCard() {
  const { colors, typography, shapes, effects, isDark } = useThemeTokens();

  return (
    <div
      style={{
        background: colors.cardBackground,
        borderRadius: shapes.borderRadius,
        boxShadow: effects.neumorphic,
        border: effects.glassBorder,
        padding: shapes.cardPadding,
        fontFamily: typography.bodyFont,
      }}
    >
      <h3 style={{ color: colors.primary, fontFamily: typography.headingFont }}>
        Token Synchronized Card
      </h3>
    </div>
  );
}

Visual FX • Modern Aesthetics

Interactive Cursor Spotlight Cards

Replicate the signature Linear, Raycast, and Apple glowing card effect. When the cursor hovers and moves over the card, an ambient radial glow follows the cursor position with hardware-accelerated precision.

Single Spotlight

PrimitiveCard Spotlight

Add spotlight={true} or hoverEffect="spotlight" directly to any PrimitiveCard.

<PrimitiveCard spotlight spotlightColor="rgba(99, 102, 241, 0.25)">
  <h4>Interactive Card</h4>
</PrimitiveCard>
Grid Spotlight

PrimitiveSpotlight Wrapper

Wrap entire grids with PrimitiveSpotlight to track coordinates across all child cards simultaneously.

<PrimitiveSpotlight>
  <PrimitiveGrid columns={3}>
    <PrimitiveCard spotlight>Card 1</PrimitiveCard>
    <PrimitiveCard spotlight>Card 2</PrimitiveCard>
  </PrimitiveGrid>
</PrimitiveSpotlight>

Kinetic Shimmer & Gradient Typography

Turn static text into eye-catching, high-converting focal points with kinetic shimmer shine animations and curated gradient presets.

Preset: aurora

Cyan → Blue → Slate

Preset: sunset

Neon Crimson → Peach

Preset: cyberpunk

Fuchsia → Purple → Sky Blue

Preset: gold

Metallic Lustrous Gold

Preset: silver

Platinum Chrome

Preset: ocean

Emerald → Deep Cyan

// Shimmer Animated Heading
<PrimitiveTypography variant="h1" shimmer>
  Next-Gen Cloud Architecture
</PrimitiveTypography>

// Aurora Gradient Heading
<PrimitiveTypography variant="h2" gradient gradientPreset="aurora">
  Supercharged Developer Engine
</PrimitiveTypography>

Neumorphic & Inset Styling

Create soft, tactile, embossed interfaces with extruded or recessed shadows tailored for both Light and Dark themes.

Extruded Neumorphic

variant="neumorphic"

<PrimitiveCard variant="neumorphic">
  <p>Soft Extruded Surface</p>
</PrimitiveCard>

Inset / Recessed Neumorphic

variant="neumorphic-inset" or inset={true}

<PrimitiveCard variant="neumorphic-inset">
  <p>Recessed Surface Well</p>
</PrimitiveCard>

Enhanced Glassmorphism

Achieve Apple-level frosted glass with specular border illumination, multi-layer backdrop blurs, and gradient transparency.

{
  "theme": {
    "shape": {
      "cardVariant": "glass",
      "glassBlur": "20px",
      "glassOpacity": 0.5
    }
  }
}

Aurora Mesh & Spotlight Backdrops

Set section backdrops to fluid multi-color ambient radial meshes using background="aurora" or glowing top beams with background="spotlight" in PrimitiveContainer.

<PrimitiveContainer background="aurora" paddingY="120px">
  <HeroSection content={heroContent} />
</PrimitiveContainer>
Enterprise Subsystem

Enterprise JSON-Driven SEO Subsystem

The Muon Site Engine provides a 100% JSON-driven Technical SEO, Analytics, and Structured Data engine. An external SEO team or marketing agency can configure, optimize, and audit meta tags, JSON-LD schemas, webmaster verifications, and analytics trackers without modifying any React source code.

1

Decoupled SEO JSON

Provide an independent seo.json or embed directly inside config.json under the seo key.

2

Schema.org JSON-LD

Automated generation of Organization, LocalBusiness, WebSite (SearchAction), BreadcrumbList, FAQPage, and Product schemas.

3

Zero-Latency Trackers

Asynchronous, non-blocking injection of GA4, GTM, Meta Pixel, Microsoft Clarity, and custom tracking scripts.

1. Complete seo.json Configuration

Pass an SEO config file directly to <EngineProvider seo={seoJson}> or <DynamicPage seo={seoJson}>:

{
  "$schema": "https://muoninfotech.com/schemas/website-os.seo.json",
  "site": {
    "siteName": "QuantumFlow AI",
    "baseUrl": "https://quantumflow.ai",
    "titleTemplate": "%s | QuantumFlow AI",
    "defaultTitle": "QuantumFlow AI - Next-Gen Autonomous Enterprise Platform",
    "defaultDescription": "Orchestrate multi-agent workflows, autonomous services, and observability.",
    "defaultOgImage": "https://quantumflow.ai/og-banner.jpg",
    "themeColor": "#0f172a",
    "language": "en",
    "robots": "index, follow, max-image-preview:large",
    "keywords": ["AI Platform", "Autonomous Agents", "Enterprise Intelligence"]
  },
  "verification": {
    "google": "google-site-verification-token",
    "bing": "bing-verification-token",
    "yandex": "yandex-token",
    "pinterest": "pinterest-meta-key",
    "facebookDomain": "facebook-domain-verification-token"
  },
  "analytics": {
    "googleAnalytics": {
      "measurementId": "G-XXXXXXXXXX",
      "anonymizeIp": true,
      "sendPageView": true
    },
    "googleTagManager": {
      "containerId": "GTM-XXXXXXX"
    },
    "metaPixel": {
      "pixelId": "123456789012345"
    },
    "microsoftClarity": {
      "projectId": "clarity_sample_id"
    }
  },
  "structuredData": {
    "organization": {
      "type": "Corporation",
      "name": "QuantumFlow AI Inc.",
      "url": "https://quantumflow.ai",
      "logo": "https://quantumflow.ai/logo.png",
      "sameAs": [
        "https://twitter.com/quantumflow",
        "https://linkedin.com/company/quantumflow"
      ]
    },
    "enableSearchAction": true
  },
  "pages": {
    "/": {
      "title": "QuantumFlow AI - Autonomous Enterprise Intelligence",
      "description": "Unified platform to design and deploy autonomous multi-agent systems.",
      "canonical": "https://quantumflow.ai/"
    },
    "/pricing": {
      "title": "Predictable Enterprise Pricing",
      "description": "Transparent tiers from startup scale to dedicated clusters.",
      "structuredData": {
        "product": {
          "name": "QuantumFlow Enterprise Cluster",
          "price": "499.00",
          "priceCurrency": "USD",
          "brand": "QuantumFlow AI"
        }
      }
    },
    "/faq": {
      "title": "Frequently Asked Questions",
      "description": "Compliance, security, SOC2, latency, and integration FAQ.",
      "autoFaqSchema": true
    }
  }
}

2. OpenGraph, Twitter Cards & Reactive Head Injection

When a user navigates between routes, SEOMetadata automatically updates the document title, canonical link, OpenGraph tags (og:title, og:description, og:image, og:url), and Twitter Cards (twitter:card, twitter:site) synchronously.

import { EngineProvider, DynamicPage } from '@leoc1992/site-engine';
import config from './config.json';
import seoConfig from './seo.json';

export default function App() {
  return (
    <EngineProvider config={config} seo={seoConfig}>
      <DynamicPage />
    </EngineProvider>
  );
}

3. Schema.org JSON-LD Builders

The engine automatically creates rich, search-engine ready JSON-LD payloads for Google Search Rich Results:

Schema Type JSON Configuration Google Search Impact
Organization / Corporation structuredData.organization Brand Knowledge Graph card with logo and social links
LocalBusiness structuredData.localBusiness Google Maps & Local Pack integration with address & phone
WebSite (SearchAction) structuredData.enableSearchAction: true Direct Google Sitelinks Searchbox in search results
BreadcrumbList Automatic on all subpage routes Hierarchical navigation crumbs in search snippets
FAQPage faqItems or autoFaqSchema: true Expandable rich FAQ dropdowns under search listing
Product / Offer pages["/pricing"].structuredData.product Pricing, currency, and availability rich badges

4. Analytics, GTM, Meta Pixel & Clarity

Trackers are safely loaded with async script injection. Single-page route transitions trigger automatic virtual pageviews across all configured measurement IDs:

import { trackPageView, initAnalytics } from '@leoc1992/site-engine';

// Track custom page transition manually if needed
trackPageView('/custom-route', 'Custom Page Title');

5. Sitemap & Robots.txt Generators

Export static sitemap.xml and robots.txt strings directly from your build pipeline or Next.js / Vite API route:

import { generateSitemap, generateRobotsTxt } from '@leoc1992/site-engine';
import seoConfig from './src/config/seo.json';

// Generate sitemap.xml
const sitemapXml = generateSitemap(seoConfig);

// Generate robots.txt
const robotsTxt = generateRobotsTxt(seoConfig, {
  disallow: ['/admin', '/dashboard/private']
});

New in v1.11.0

JSON-Driven Popups & Exit-Intent Subsystem

Turn departing visitors into leads and customers with zero custom code. The engine features a fully integrated modal and trigger system capable of detecting cursor velocity, window boundary exit, scroll depth, and idle timeouts, paired with client-side impression capping and cooldown persistence.

Exit-Intent Tracking

Tracks cursor velocity toward top viewport boundary on desktop and visibility change on mobile devices.

Frequency Capping

Configurable impression limits, cooldowns in days/hours, session suppression, and permanent conversion locking.

Visual Stunners & Slots

Built-in glassmorphism and neumorphism modal styles with full developer slot override capability.

1. Popups JSON Specification

Popups can be defined directly inside config.json under the popups array or passed via <EngineProvider popups={popupsJson}> / <DynamicPage popups={popupsJson}>:

[
  {
    "id": "exit-lead-magnet",
    "enabled": true,
    "type": "leadCapture",
    "variant": "glass",
    "trigger": {
      "type": "exitIntent",
      "sensitivity": 20,
      "fallbackDelayMs": 20000
    },
    "frequency": {
      "maxImpressions": 2,
      "storage": "local",
      "cooldownDays": 7,
      "oncePerSession": true,
      "stopOnConversion": true
    },
    "targeting": {
      "includeRoutes": ["/", "/pricing", "/features*"],
      "excludeRoutes": ["/checkout", "/dashboard/*"],
      "device": "all"
    },
    "content": {
      "badge": "Limited Time Offer",
      "title": "Before you leave — Claim 30 Days Free Sandbox Access",
      "description": "Join 5,000+ AI engineers deploying autonomous workflows with sub-millisecond orchestration.",
      "image": "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?auto=format&fit=crop&w=600&q=80",
      "inputPlaceholder": "Enter your work email",
      "ctaText": "Claim Free Access",
      "secondaryCtaText": "No thanks, I'll explore later",
      "disclaimer": "No credit card required. Instant sandbox provisioning."
    },
    "animation": {
      "backdropBlur": "16px"
    }
  }
]

2. Supported Trigger Types

Choose from four reactive trigger mechanisms:

Trigger Type Parameters Description
exitIntent sensitivity (px), fallbackDelayMs (ms) Fires when mouse departs top of viewport or user switches browser tabs on mobile.
timeDelay delayMs (ms) Fires after the visitor spends N milliseconds on the page.
scrollDepth percentage (%) Fires once the visitor scrolls past a percentage (e.g. 50% or 75%) of the document height.
inactivity timeoutMs (ms) Fires when no mouse, keyboard, or scroll movement is detected for N milliseconds.

3. Frequency Capping & Target Rules

Prevent user fatigue by enforcing intelligent suppression rules:

  • maxImpressions: Maximum number of times the popup can ever be displayed to a single browser.
  • cooldownDays / cooldownHours: Minimum delay before the popup is eligible to reappear.
  • oncePerSession: Restricts display to at most once per active browser session.
  • stopOnConversion: Permanently locks and suppresses the popup once the user submits the form or clicks CTA.
  • includeRoutes / excludeRoutes: Target specific URL routes with wildcard pattern matching (e.g. ["/features*"]).

4. Developer Custom Slot Overrides

Need to replace the modal UI with a custom React component while retaining the engine's exit-intent detection and frequency engine? Use the slots prop:

import React from 'react';
import { DynamicPage } from '@leoc1992/site-engine';
import config from './src/config/config.json';
import popups from './src/config/popups.json';

function CustomExitModal({ popup, onClose, onConvert }) {
  return (
    <div className="bg-slate-950 p-8 rounded-3xl border border-indigo-500/30 text-white max-w-md">
      <h3 className="text-2xl font-black">{popup.content.title}</h3>
      <p className="text-slate-400 mt-2">{popup.content.description}</p>
      <button onClick={() => { onConvert(popup.id); onClose(); }} className="mt-4 px-6 py-3 bg-indigo-600 rounded-xl">
        Claim Voucher
      </button>
    </div>
  );
}

export default function App() {
  return (
    <DynamicPage
      customConfig={config}
      popups={popups}
      slots={{
        'popup-exit-lead-magnet': CustomExitModal
      }}
    />
  );
}

Future Enhancements Coming Soon

We are constantly evolving the Muon Site Engine to be the most powerful, highly-customizable JSON-driven platform on the web. Below is our comprehensive roadmap for upcoming features.

CMS Integration

  • • Contentful/Sanity Connectors: Direct fetch support for headless CMS content.
  • • Blog Engines: Markdown/MDX parser integration for long-form content.

E-Commerce Ready

  • • Stripe Integration: Native buy buttons and pricing table checkout links.
  • • Product Grids: Specialized components for displaying SKUs, prices, and reviews.
  • • Slide-Out Cart: Global context cart drawer for multi-page shopping.