Next.js Engine — Technical Documentation

src/engine/
│
├── schema/
│   └── types.ts              All TypeScript types for the schema system
│
├── core/
│   ├── resolver.ts              Converts ResponsiveValue props to CSS custom properties
│   ├── StyleCollector.ts        Collects CSS blocks during render, outputs one style tag
│   ├── registry.ts              Maps NodeType strings to React components
│   ├── lazyDetect.ts            Analyses nodes and decides lazy strategy per element
│   ├── SchemaRenderer.tsx       Walks the schema tree and renders each node
│   ├── EngineAPIResolver.ts     Runtime fetch orchestrator with multi-tier auth + version macros
│   ├── EngineAPIConfigParser.ts Parses .EngineAPIConfig/*.api files into EngineAPICompiledConfig
│   ├── schemaAnalyzer.ts        Static analyzer — diagnostics, did-you-mean, a11y, perf warnings
│   ├── validateSchema.ts        Runtime schema validation (lightweight, throws on hard errors)
│   ├── EngineDevice.ts          Server + client device detection (Apple, Samsung, Xiaomi, etc.)
│   └── EngineMobilePatcher.ts   Mobile schema patching — applies MobileSchemaConfig to PageSchema
│
├── hooks/
│   ├── useInView.ts          SSR-safe IntersectionObserver hook
│   └── usePropStyles.ts      Converts engine props to inline CSS (uses resolver)
│
├── providers/
│   └── EngineProvider.tsx    React context: config, handlers, slots, breakpoint hook
│
├── components/
│   ├── primitives.tsx        Box, Stack, Grid, Text, Heading, Section, Button, Card, Spacer, Divider
│   ├── EngineLink.tsx        Styled anchor — delegates routing to EngineNav
│   ├── EngineNav.tsx         Navigation bar + shared anchor-rendering pipeline
│   ├── EngineManim/
│   │   ├── index.ts              Barrel exports
│   │   ├── manimTypes.ts         All 2D + 3D types
│   │   ├── manimCompiler.ts      Shape vectorizer + Float32Array pools
│   │   ├── manimDSLParser.ts     frame() / constraint DSL parser
│   │   ├── manimAnimationRouter.ts  Tier 2.5 animation routing
│   │   ├── EngineManim.tsx       2D component (uses EngineCanvas)
│   │   └── EngineManim3D.tsx     3D component (Three.js GLTF/OBJ)
│   ├── EngineImage.tsx       Smart lazy image with blur-up progressive loading
│   ├── EngineVideo.tsx       Lazy video — src never loads until near viewport
│   ├── EngineHero.tsx        Dedicated hero sections with parallax and overlays
│   ├── EngineSuspense.tsx    Schema-native Suspense with loading presets
│   ├── EngineForms.tsx       Form primitives (Input, Textarea, Checkbox, etc)
│   └── LazyMount.tsx         Generic lazy mount wrapper + LazySection variant
│
├── plugins/
│   ├── engineApiPlugin.js    Next.js webpack plugin — compiles .EngineAPIConfig at build time
│   ├── nencCompiler.js       Static command discovery + split opaque manifest compiler
│   └── nencPlugin.js         Emits NENC artifacts and the single protected command route
├── createPage.tsx            Top-level page factory
└── index.ts                  Public API exports

// You write this in your schema:
props: {
  px: { xs: "1rem", md: "2rem", xl: "3rem" }
}

// The engine generates this CSS once and injects it in a <style> tag:
:root { --e-px-a1b2: 1rem }
@media(min-width:768px)  { :root { --e-px-a1b2: 2rem } }
@media(min-width:1280px) { :root { --e-px-a1b2: 3rem } }

// And applies this inline style to the element:
style={{ paddingLeft: "var(--e-px-a1b2)", paddingRight: "var(--e-px-a1b2)" }}

// Plain value — same at all sizes
gap: "2rem"

// Responsive — different per breakpoint, cascades upward
gap: { xs: "1rem", md: "1.5rem", xl: "2rem" }

{
  type: string,       // component type to render
  key?: string,       // stable React key (recommended for list items)
  props?: object,     // props for the component
  children?: SchemaNode[] | string  // child nodes, or text content
}

{
  type: "box",
  props: {
    vars: {
      "--card-bg": "#1a1a2e",
      "--accent":  "#9bcf3a",
      "--radius":  "12px",
    },
    bg: "var(--card-bg)",
  }
}

        1 (top)
         ┌───┐
2 (left) │   │ 3 (right)
         └───┘
        4 (bottom)

{
  type: "grid",
  props: { columns: 3, gap: "1rem" },
  children: [
    // ... 4 outer cells ...
    {
      type: "box",
      props: {
        sides: [1, 2, 3, 4],   // all four sides
        sideDistance: "32px",  // push 32px outward on every side
        sideType: "margin",    // margin = pushes neighbours (default)
        bg: "#9bcf3a",
      }
    },
    // ... 4 outer cells ...
  ]
}

props: {
  sides: [1, 4],        // top and bottom
  sideDistance: "64px",
}

props: {
  sides: [2, 3],        // left and right sides only
  sideDistance: "2rem",
  sideType: "padding",  // pushes content inward
}

{
  type: "text",
  props: {
    variant: "caption",
    parts: [
      { text: "built with love by " },
      {
        text:   "Kastrick",
        href:   "https://kastricks.com",
        target: "_blank",
        style:  { color: "#555", textDecoration: "none" },
      },
    ],
  },
}

{
  type: "heading",
  props: {
    level: 1,
    content: "Main title",
    subheading: "Supporting line underneath",
  }
}

src: [
  { src: "/video.webm", type: "video/webm" },
  { src: "/video.mp4",  type: "video/mp4" },
]

// Inline string
{ type: "markdown", props: { content: "# Hello\n\nParagraph text." } }

// From a .md file (server-side only — resolved by createPage before render)
{ type: "markdown", props: { filePath: "./content/about.md" } }

{
  type: "markdown",
  props: {
    filePath: "./content/post.md",
    blockAnimation: "slide-up",
    animationDuration: "0.5s",
    animationStagger: 60,
    headingColor: "#9bcf3a",
    bodySize: "1.05rem",
  }
}

interface EngineNavItem {
  label:     string;
  href?:     string;
  target?:   string;
  cprop?:    { link?: { transition?: string; href?: string } };
  active?:   boolean;           // auto-detected from pathname if omitted
  children?: EngineNavItem[];   // renders as dropdown
}

{
  "type": "nav",
  "props": {
    "sticky": true,
    "logo": { "src": "/logo.svg", "href": "/", "alt": "Brand" },
    "items": [
      { "label": "Home",   "href": "/" },
      { "label": "Docs",   "href": "/docs", "cprop": { "link": { "transition": "page-to-page" } } },
      { "label": "GitHub", "href": "https://github.com/...", "target": "_blank" },
      { "label": "More",   "children": [{ "label": "Blog", "href": "/blog" }] }
    ]
  }
}

const resolver = new EngineAPIResolver({ 
	endpoint: "https://api.kastrick.com/&v&/", 
	versionMacros: { v: "v1" } 
});

const res = await resolver.resolveRequest({
	formData: { username: "admin" },
	pageOverrides: { 
		endpoint: "https://api.kastrick.com/&v&/login", // Macros still apply to overrides
		method: "POST" 
	}
});

# .EngineAPIConfig/main.api

[provider.main]
endpoint = "https://api.kastrick.com"
method   = "POST"
cache    = "no-cache"

[provider.main.auth]
type      = "hmac"
secret    = "$API_SECRET"
algorithm = "sha-256"

[provider.cdn]
endpoint = "https://cdn.kastrick.com"
method   = "GET"
cache    = "force-cache"

[versions]
V1 = "/api/v1"
V2 = "/api/v2"

// next.config.js
const withEngineAPI = require("./src/engine/plugins/engineApiPlugin");

module.exports = withEngineAPI({
  // your existing next config
}, {
  configDir:  ".EngineAPIConfig",          // default
  outputFile: ".engine-api-compiled.json", // default
});

import { ensureAPIConfig } from "@/engine";

// In getServerSideProps / Route Handler / Server Component:
const config = await ensureAPIConfig(); // reads + caches on first call

const resolver = new EngineAPIResolver({
  endpoint:      "&V1&/users/login",
  provider:      "main",
  compiledConfig: config,
});

// Simple card with cover image
{
  type: "card",
  props: {
    cover: "/images/hero.jpg",
    coverAlt: "Mountains at sunset",
    coverRatio: "3/2",
    variant: "elevated",
    interactive: true,
  },
  children: [
    { type: "text", props: { variant: "h3", content: "Alpine Trek" } },
    { type: "text", props: { content: "A 5-day route through the high passes." } },
  ]
}

// Horizontal card (media left, content right)
{
  type: "card",
  props: {
    direction: "horizontal",
    cover: "/images/thumb.jpg",
    coverAlt: "Article thumbnail",
    coverWidth: "35%",
    variant: "outlined",
    innerPadding: "1.5rem",
  },
  children: [
    { type: "text", props: { variant: "h4", content: "Getting Started" } },
    { type: "text", props: { content: "Everything you need to know." } },
  ]
}

{
  type: "manim",
  props: {
    cprop: {
      manim: {
        mobjects: [
          { id: "ring",   type: "Circle", radius: 50, strokeColor: "var(--e-accent)", strokeWidth: 3 },
          { id: "square", type: "Square", sideLength: 80, strokeColor: "var(--e-accent)", strokeWidth: 3 },
        ],
        timeline: [
          { action: "Create",    target: "ring",   durationMs: 600 },
          { action: "Transform", origin: "ring",   target: "square", durationMs: 800 },
          { action: "FadeOut",   target: "square", durationMs: 400 },
        ],
        settings: { loop: true, fpsLimit: 60 },
      },
    },
  },
}

{
  type: "manim3d",
  props: {
    cprop: {
      manim3d: {
        src: "/models/character.glb",
        camera: { position: [0, 2, 5], fov: 60, look: { content: "head" } },
        lights: [
          { type: "ambient",     intensity: 0.4 },
          { type: "directional", intensity: 0.8, direction: [1, -1, 0.5] },
        ],
        animation: {
          source: "file",
          clip:   "walk_cycle",
          overrides: [
            {
              bone:   "left.hand",
              mode:   "replace",
              frames: [{ frameStart: 0, frameEnd: 30, transforms: [{ bone: "left.hand", rotate: [0, 45, 0] }] }],
            },
          ],
        },
        settings: { loop: true, fps: 60, shadows: true },
      },
    },
  },
}

# Frame blocks — Blender-style frame ranges
frame (
  frame-start = 120
  frame-end   = 240
) {
  left.hand.rotate  = [0, 45, 0]
  right.leg.rotate  = [30, 0, 0]
  2.tentacle.move   = [10, 0, 0]
}

# Camera constraints (Tier 4)
camera.look.content   = head
camera.focus.distance = 5
camera.position       = [0, 2, 5]

# Light settings
light.sun.direction = [1, -1, 0.5]
light.sun.intensity = 0.9

// In schema:
{ type: "slot", props: { name: "userWidget", fallback: { type: "text", props: { content: "Loading…" } } } }

// In createPage:
createPage({
  schema: MySchema,
  slots: { userWidget: <UserWidget /> }
})

// page.tsx
export default createPage({
  schema: MySchema,
  handlers: {
    openModal: () => setModalOpen(true),
    trackCta:  () => analytics.track("cta_clicked"),
  },
});

// In schema:
{
  type: "button",
  props: { label: "Open", onClick: "openModal" }
}

theme: {
  vars: {
    "--e-accent":    "#7c3aed",
    "--e-bg":        "#0f0f1a",
    "--e-card-bg":   "#1a1a2e",
    "--e-muted":     "#94a3b8",
    "--e-divider":   "rgba(255,255,255,0.08)",
    "--e-skeleton-a":"#1e1e35",   // shimmer dark colour
    "--e-skeleton-b":"#2a2a45",   // shimmer light colour
  },
  fonts: [
    "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&display=swap"
  ],
  globalStyles: `
    body { background: var(--e-bg); font-family: 'Inter', sans-serif; }
  `,
}

import { memo } from "react";
import { registerComponent } from "@/engine";

const PricingCard = memo(function PricingCard({ plan, price, features, children }) {
  return (
    <div className="pricing-card">
      <h3>{plan}</h3>
      <span>{price}</span>
      {children}
    </div>
  );
});

registerComponent("pricing-card", PricingCard);

{
  type: "pricing-card",
  props: { plan: "Pro", price: "$9/mo" },
  children: [
    { type: "text", props: { content: "Unlimited projects" } }
  ]
}

// Existing full-schema form
export default createPage({
  schema: MySchema,
  config: {
    breakpoints: { … },
    contentMaxWidth: "1400px",
    gapBase: "1rem",
  },
  handlers: {
    myHandler: () => { … }
  },
  slots: {
    mySlot: <MyComponent />
  },
});

// Direct schema form
export default createPage({
  meta: { title: "Home" },
  root: { type: "box", children: [] },
});

// Compact local Markdown page form
export default createPage({
  title: "Privacy Policy — Kastrick",
  description: "Kastrick privacy policy.",
  filePath: "@/data/page/privacy.md",
  markdown: {
    headingColor: "#07111f",
    textColor: "#30475f",
    linkColor: "#12304c",
  },
});

export default createPage({
  schema: MySchema,       // Required — the PageSchema definition
  config: {               // Optional — engine config overrides
    breakpoints: { … },
    contentMaxWidth: "1400px",
    gapBase: "1rem",
  },
  handlers: {             // Optional — named event handlers
    myHandler: () => { … }
  },
  slots: {                // Optional — named React node injections
    mySlot: <MyComponent />
  },
});

const SiteChrome = createComponent({
  schema: defineSchema({
    root: {
      type: "box",
      children: [
        { type: "section", children: [] },
        { type: "slot", props: { name: "children" } },
      ],
    },
  }),
});

export default SiteChrome;

import path from "node:path";
import { createPage, defineSchema } from "@/engine";

export default createPage({
  schema: defineSchema({
    root: {
      type: "section",
      children: [
        {
          type: "markdown",
          props: {
            filePath: path.join(process.cwd(), "data/page/privacy.md"),
            headingColor: "#07111f",
            textColor: "#30475f",
            linkColor: "#12304c",
          },
        },
      ],
    },
  }),
});

import { createPage } from "@/engine";

export default createPage({
  meta: {
    title: "Kastrick Terms of Service",
  },
  title: "Terms of Service — Kastrick",
  description: "Kastrick terms of service.",
  filePath: "@/data/page/tos.md",
  markdown: {
    blockAnimation: "slide-up",
  },
});

// schemas/home.schema.ts
import { defineSchema } from "@/engine";

export const HomeSchema = defineSchema({
  meta: { title: "Home" },
  root: { type: "box", children: [] }
});

// app/page.tsx
import { createPage } from "@/engine";
import { HomeSchema } from "@/schemas/home.schema";

export default createPage({ schema: HomeSchema });

// app/page.tsx
import { createPage } from "@/engine";
export default createPage({ schema: HomeSchema });

// pages/index.tsx
import { createPage } from "@/engine";
export default createPage({ schema: HomeSchema });
export const getStaticProps = async () => ({ props: {} });

{
  "compilerOptions": {
    "paths": {
      "@/engine": ["./src/engine/index.ts"],
      "@/engine/*": ["./src/engine/*"]
    }
  }
}

 Tier        Threshold           Typical source
 ──────────  ──────────────────  ─────────────────────────────────────────
 Global      10+ renders OR      Engine baseline, theme vars, layout,
             explicit call       header, footer — CSS on EVERY page
 Group       3–9 renders         Shared components used on several pages,
                                 repeated responsive configs
 Local       1–2 renders         Page-specific overrides, one-off values

// app/layout.tsx
import { EngineGlobalStyles } from "@/engine";

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <EngineGlobalStyles />  {/* ← injects Global-tier CSS early */}
      </head>
      <body>{children}</body>
    </html>
  );
}

import { globalStyleCollector } from "@/engine/core/StyleCollector";

// Force a CSS block to Global — never demoted
globalStyleCollector.addGlobal(`:root { --brand: #9bcf3a; }`);

{ type: "image", props: { src: "/hero.jpg", alt: "Hero", qualityPreset: "sharp" } }

{
  type: "image",
  props: {
    src: "/photo.jpg",
    alt: "Photo",
    qualityMobile: 60,    // mobile (<768px) — smaller file
    qualityDesktop: 88,   // desktop (≥768px) — full quality
  }
}

createPage({
  schema: defineSchema({
    root: {
      type: "canvas",
      props: {
        mode: "2d",
        responsive: true,
        style: { height: "400px" },
        onSetup: "setupCanvas",
        onDraw:  "drawCanvas",
      }
    }
  }),
  handlers: {
    setupCanvas(ctx, canvas) {
      ctx.font = "bold 16px sans-serif";
      return () => { /* cleanup on unmount */ };
    },
    drawCanvas(ctx, canvas, delta) {
      ctx.clearRect(0, 0, canvas.offsetWidth, canvas.offsetHeight);
      ctx.fillText(`Δ ${delta.toFixed(1)}ms`, 16, 32);
    },
  }
});

handlers: {
  setup3D(gl) {
    gl.clearColor(0.05, 0.05, 0.1, 1.0);
    gl.enable(gl.DEPTH_TEST);
    // compile shaders, create VAOs...
    return () => { gl.getExtension("WEBGL_lose_context")?.loseContext(); };
  },
  draw3D(gl, canvas, delta) {
    gl.viewport(0, 0, canvas.width, canvas.height);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
    // draw calls...
  },
}

EngineScroll (entry point)
    │
    ├── EngineScrollRuntime      — singleton state + subscriber registry
    ├── EngineScrollAnimation    — easing + interpolation
    ├── EngineScrollMovement     — absolute / relative / percent movement
    ├── EngineScrollNavigator    — public navigation API (resolves targets)
    │       ├── EngineScrollPointManager  — named point registry
    │       └── EngineScrollHash         — DOM id fallback
    ├── EngineScrollURL          — #-es? URL protocol parser
    ├── EngineScrollBrowser      — browser abstraction (Firefox compat)
    ├── EngineScrollEasing       — easing function library
    └── EngineScrollProvider     — React context + useEngineScroll hook

// app/layout.tsx
import { EngineScrollProvider } from "@/engine";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <EngineScrollProvider>{children}</EngineScrollProvider>
      </body>
    </html>
  );
}

import { useEngineScroll } from "@/engine";

function NavButton() {
  const scroll = useEngineScroll();
  return (
    <button onClick={() => scroll.move("pricing")}>Go to Pricing</button>
  );
}

import { EngineScrollNavigator } from "@/engine";

// Named semantic point (registered via `point` prop or EngineScrollPointManager)
EngineScrollNavigator.move("#hero");
EngineScrollNavigator.move("#pricing", 2);       // with +2 point offset
EngineScrollNavigator.move("#hero", 0, 400);     // custom duration ms

// Absolute scroll point
EngineScrollNavigator.move(120.5);

// Relative from current position
EngineScrollNavigator.move("current", 5);        // scroll forward 5 points

// Jump to top or bottom
EngineScrollNavigator.move("top");
EngineScrollNavigator.move("bottom");

EngineScroll.configure({
	behavior: "smooth",       // "smooth" | "native" | "instant"
	duration: 420,
	easing: "easeOutCubic",
	interruptible: true,
	reducedMotion: "respect", // "respect" | "reduce" | "ignore"
});

type EngineScrollTarget =
  | number        // absolute scroll point
  | "top"         // scroll to 0
  | "bottom"      // scroll to page maximum
  | "current"     // offset from current position
  | `#${string}`; // named semantic point or DOM id

{ type: "section", props: { point: "hero" } }
// → <section id="hero"> registered in EngineScrollPointManager
// → reachable via EngineScrollNavigator.move("#hero")
// → reachable via URL:  #-es?move=hero

import { EngineScrollPointManager } from "@/engine";

// Register (call from useEffect or similar)
EngineScrollPointManager.register("my-section", point, element);

// Unregister on unmount
EngineScrollPointManager.unregister("my-section");

// Recalculate all positions after layout changes
EngineScrollPointManager.recalculate();

// Query
EngineScrollPointManager.has("my-section");   // boolean
EngineScrollPointManager.get("my-section");   // EngineRegisteredPoint | undefined
EngineScrollPointManager.names();             // string[]

interface EngineRegisteredPoint {
  name:    string;
  point:   number;        // scroll point value
  element: HTMLElement;
}

#-es?move=hero
#-es?move=pricing
#-es?move=current&offset=25
#-es?move=120.5
#-es?move=footer&duration=600
#-es?move=top
#-es?move=bottom

<a href="#-es?move=pricing">Go to pricing</a>
<a href="#-es?move=current&offset=10">Scroll down 10 points</a>

import { EngineScrollURL } from "@/engine";

EngineScrollURL.has();      // true when current URL has #-es? command
EngineScrollURL.execute();  // parse + run + clean URL
EngineScrollURL.listen();   // subscribe to hashchange (returns unsubscribe fn)

import { EngineScrollEasing } from "@/engine";

// All accept t ∈ [0,1] and return value in [0,1]
EngineScrollEasing.linear(t)
EngineScrollEasing.easeInQuad(t)
EngineScrollEasing.easeOutQuad(t)
EngineScrollEasing.easeInOutQuad(t)
EngineScrollEasing.easeInCubic(t)
EngineScrollEasing.easeOutCubic(t)
EngineScrollEasing.easeInOutCubic(t)

{
  type: "markdown",
  props: {
    disablepointformarkdownhash:     true,  // disable h1 → point
    disablepointformarkdownhashhash: true,  // disable h2 → point
  }
}

{
  type: "scroll",
  props: {
    method:             "ease",
    easing:             "ease-in-out",
    scrollDuration:     600,
    pageTransition:     true,
    transitionDuration: 350,
    scrollOffset:       80,
  },
  children: [...]
}

{
  type: "card",
  props: {
    cprop: {
      onHover:  { background: "#1a1a2e", transform: "scale(1.02)" },
      onFocus:  { outline: "2px solid var(--e-accent)", outlineOffset: "3px" },
      onActive: { transform: "scale(0.98)", opacity: "0.9" },
      css:      { userSelect: "none", willChange: "transform" },
    }
  }
}

import { cpropClass } from "@/engine";

// In your own custom components:
function MyComponent({ cprop, className, ...props }) {
  const hoverClass  = cpropClass(cprop);
  const mergedClass = [className, hoverClass].filter(Boolean).join(" ");
  return <div className={mergedClass} {...props} />;
}

Request UA
    │
    ▼
getServerDevice()             ← reads next/headers User-Agent
    │
    ├── isDesktop → renderPage(schema)          ← original schema untouched
    │
    └── isMobile  → applyMobilePatches(schema, mobile)
                        │
                        ▼
                   patchTree()                  ← walks tree, targets named nodes
                        │
                        ▼
                   renderPage(patchedSchema)    ← mobile-specific tree

{
  type: "grid",
  name: "feature-grid",    // ← stable patch target
  props: { columns: 3, gap: "2rem" },
  children: [
    {
      type: "box",
      name: "pricing-hero",
      props: { px: "4rem", py: "6rem" },
    }
  ]
}

export default createPage({
  schema: MySchema,
  mobile: [
    // Entry 1 — hide desktop nav, show mobile menu
    {
      "children#desktop-nav": {
        cprop: { hide: true },          // sets display: none on mobile
      },
    },
    {
      "children#mobile-menu": {
        props: { display: "flex" },
      },
    },
    // Entry 2 — completely replace hero props for mobile
    {
      "children#pricing-hero": {
        "remove-all-prop": true,        // wipe ALL desktop props first
        props: { px: "1rem", py: "2rem" },
      },
    },
    // Entry 3 — change grid columns, wipe cprop only
    {
      "children#feature-grid": {
        "remove-all-cprop": true,       // wipe cprop only, keep other props
        props: { columns: 1 },
        cprop: { onHover: { transform: "none" } },
      },
    },
  ],
});

[engine:mobile] Selector "children#pricng-hero" did not match any node.
                Did you mean "children#pricing-hero"?

import { getServerDevice, useMobileDevice, detectDevice } from "@/engine";

// Server Component / Route Handler / Server Action:
const device = await getServerDevice();
// → { isMobile: true, isTablet: false, isDesktop: false, os: "android", brand: "samsung", type: "samsung" }

// Client-side React hook (SSR-safe, updates after mount):
function MyComponent() {
  const device = useMobileDevice();
  if (device.isMobile) return <MobileLayout />;
  return <DesktopLayout />;
}

// Anywhere — parse a UA string directly:
const info = detectDevice("Mozilla/5.0 (Linux; Android 14; SM-S928B) ...");

import { EngineBrowser } from "@/engine";

// Browser identity
EngineBrowser.is.chrome     // boolean
EngineBrowser.is.firefox    // boolean
EngineBrowser.is.safari     // boolean
EngineBrowser.is.edge       // boolean
EngineBrowser.is.opera      // boolean
EngineBrowser.is.brave      // boolean
EngineBrowser.is.osmium     // boolean  ← yes, Osmium is detected
EngineBrowser.is.chromium   // any Chromium-based browser
EngineBrowser.is.mobile     // touch-primary device
EngineBrowser.is.desktop    // mouse-primary device

// Feature support (selection — see BrowserSupports for full list)
EngineBrowser.supports.viewTransitions    // View Transitions API
EngineBrowser.supports.containerQueries  // CSS @container
EngineBrowser.supports.cssHas            // CSS :has()
EngineBrowser.supports.reducedMotion     // prefers-reduced-motion: reduce
EngineBrowser.supports.prefersDark       // prefers-color-scheme: dark
EngineBrowser.supports.webgl2            // WebGL 2
EngineBrowser.supports.clipboard         // Clipboard API present
EngineBrowser.supports.clipboardRead     // clipboard.readText available
EngineBrowser.supports.clipboardWrite    // clipboard.writeText available
EngineBrowser.supports.camera            // getUserMedia video
EngineBrowser.supports.microphone        // getUserMedia audio
EngineBrowser.supports.screenCapture     // getDisplayMedia
EngineBrowser.supports.speechSynthesis   // TTS available
EngineBrowser.supports.speechRecognition // STT available
EngineBrowser.supports.wakeLock          // Screen Wake Lock API
EngineBrowser.supports.notifications     // Web Notifications API
EngineBrowser.supports.fullscreen        // Fullscreen API
EngineBrowser.supports.networkInfo       // Network Information API
EngineBrowser.supports.battery           // Battery Status API
EngineBrowser.supports.webAuthn          // WebAuthn / Passkeys
EngineBrowser.supports.fileSystemAccess  // showOpenFilePicker (Chrome/Edge)
EngineBrowser.supports.badgeApi          // navigator.setAppBadge (PWA)

EngineBrowser.run({
  safari:  () => applySafariScrollFix(),
  firefox: () => applyFirefoxFix(),
  default: () => {},
});

const cls = EngineBrowser.pick({
  safari:  "scroll-ios",
  default: "scroll-standard",
});

// Write plain text (falls back to execCommand on old WebViews)
const ok = await EngineBrowser.clipboard.copy("Hello, world!");

// Write HTML + plain-text fallback (Chrome 86+, Edge 86+)
await EngineBrowser.clipboard.copyHtml("<b>Bold</b>", "Bold");

// Read plain text — may prompt for "clipboard-read" permission in Chrome
const text = await EngineBrowser.clipboard.paste();

// Read raw ClipboardItems — for images, mixed content
const items = await EngineBrowser.clipboard.read();
for (const item of items) {
  if (item.types.includes("image/png")) {
    const blob = await item.getType("image/png");
  }
}

// Check permissions before reading
if (await EngineBrowser.clipboard.canRead()) {
  const items = await EngineBrowser.clipboard.read();
}

// Native OS share sheet
await EngineBrowser.interact.share({ title: "Check this", url: location.href });

// Desktop/mobile notification (auto-requests permission on first call)
await EngineBrowser.interact.notify("Upload complete", {
  body: "Your file has been saved.",
  icon: "/icon-192.png",
});

// Vibrate (mobile only)
EngineBrowser.interact.vibrate(200);            // 200ms single buzz
EngineBrowser.interact.vibrate([100, 50, 100]); // buzz-pause-buzz pattern

// File picker (File System Access API or hidden <input> fallback)
const files = await EngineBrowser.interact.pickFile({ accept: "image/*", multiple: true });

// Trigger file download
EngineBrowser.interact.download("export.json", JSON.stringify(data), "application/json");
EngineBrowser.interact.download("photo.png", imageBlob);

// Fullscreen
await EngineBrowser.interact.fullscreen();        // default: document.documentElement
await EngineBrowser.interact.fullscreen(videoEl); // specific element
await EngineBrowser.interact.exitFullscreen();

// Screen Wake Lock — keeps display on (recipe apps, workout trackers, kiosk)
const lock = await EngineBrowser.interact.wakeLock();
// ... later:
await lock?.release();

// Geolocation — clean Promise wrapper over the callback API
const pos = await EngineBrowser.interact.location({ enableHighAccuracy: true });
if (pos) console.log(pos.coords.latitude, pos.coords.longitude);

// Lock screen orientation (requires fullscreen on most browsers)
await EngineBrowser.interact.lockOrientation("portrait");

// PWA app badge
await EngineBrowser.interact.badge(3);      // show "3" on app icon
await EngineBrowser.interact.clearBadge();  // remove badge

// Camera — front or rear
const stream = await EngineBrowser.media.camera({ facing: "environment" });
if (stream) {
  videoEl.srcObject = stream;
  // always stop when done to release the device and kill the indicator light:
  EngineBrowser.media.stop(stream);
}

// Microphone
const audioStream = await EngineBrowser.media.microphone();

// Screen capture — shows browser's built-in screen/window/tab picker
const screenStream = await EngineBrowser.media.screen();

// Text-to-speech — resolves when finished
await EngineBrowser.speech.speak("Hello!", { lang: "en-US", rate: 1.1, pitch: 1 });

// Stop mid-speech
EngineBrowser.speech.stopSpeaking();
EngineBrowser.speech.isSpeaking(); // boolean

// Speech-to-text — returns final transcript or null
const text = await EngineBrowser.speech.listen(
  { lang: "en-US" },
  (partial) => console.log("Interim:", partial), // optional live transcript callback
);
if (text) handleVoiceCommand(text);

EngineBrowser.speech.stopListening();

// Available TTS voices (may be empty on first call — loads async in some browsers)
const voices = EngineBrowser.speech.voices();
const japanese = voices.find(v => v.lang === "ja-JP");
await EngineBrowser.speech.speak("こんにちは", { voice: japanese });

// Snapshot
const { online, type, downlink, rtt, saveData } = EngineBrowser.network.status();

// Subscribe to changes — returns an unsubscribe function
const unsubscribe = EngineBrowser.network.onchange((status) => {
  if (!status.online) showOfflineBanner();
  if (status.type === "2g" || status.saveData) enableDataSaverMode();
});

// Cleanup
unsubscribe();

import { useBrowser } from "@/engine";

function MyComponent() {
  const browser = useBrowser();  // SSR-safe, updates after mount
  if (browser.is.safari) return <SafariVariant />;
  return <StandardVariant />;
}

{
  type: "box",
  props: {
    // Engine shorthands
    bg:  "#111",
    px:  "2rem",
    // Direct CSS — just write the property name
    transform:     "rotate(-3deg)",
    filter:        "blur(4px)",
    clipPath:      "polygon(0 0, 100% 0, 100% 80%, 0 100%)",
    mixBlendMode:  "multiply",
    willChange:    "transform",
    animation:     "fadeIn 0.4s ease forwards",
    aspectRatio:   "16/9",
    gridColumn:    "1 / -1",
    userSelect:    "none",
    // Also works as responsive values
    transform:     { xs: "scale(0.9)", md: "scale(1)" },
  }
}

cprop: {
  onHover:     { background: "#1a1a2e", transform: "scale(1.02)" },
  onFocus:     { outline: "2px solid var(--e-accent)", outlineOffset: "3px" },
  onActive:    { transform: "scale(0.97)", opacity: 0.9 },
  onChecked:   { background: "var(--e-accent)" },
  onDisabled:  { opacity: 0.4, cursor: "not-allowed" },
}

import { validatePageSchema, validateSchema } from "@/engine";

// In your page or CI:
const result = validatePageSchema(mySchema);
// → console.warn in dev for each issue
// → result.valid, result.errors[]

// Validate just a node tree:
const result = validateSchema(mySchema.root);

import { analyzeSchema, isSchemaValid } from "@/engine";

const result = analyzeSchema(MySchema);

console.log(result.formatted);
// [schema:root.children[2]] EngineError(E001): Unknown node type "txt".
//     hint: Did you mean "text"?
// [schema:root.children[5].props] EngineWarn(W001): Image node is missing an "alt" prop.
//     hint: Add alt="" for decorative images or a descriptive string for meaningful ones.

console.log(result.errors);   // number of error-severity diagnostics
console.log(result.warnings); // number of warn-severity diagnostics

// Guard before rendering:
if (!isSchemaValid(MySchema)) throw new Error("Schema has errors");

interface EngineDiagnostic {
  severity: "error" | "warn" | "info";
  code:     string;   // "E001", "W003", etc.
  message:  string;
  path:     string;   // e.g. "root.children[2].children[0]"
  hint?:    string;   // optional fix suggestion
}

import { staticClass } from "@/engine";

// Inside your own custom components:
const layoutClass = staticClass({
  width:     "100%",
  maxWidth:  "1200px",
  marginLeft:  "auto",
  marginRight: "auto",
});
// → "e-s-a1b2c3"  (injected as .e-s-a1b2c3{width:100%;max-width:1200px;...})
// If another component calls staticClass with the same props, the same class
// name is returned and no duplicate CSS rule is emitted.

import { EngineSEO } from "@/engine";

const engineseo = EngineSEO.create({
	site: { name: "Kastrick", url: "https://kastrick.example" },
	page: { title: "Next.js Engine", description: "Schema-driven Next.js rendering.", path: "/engine" },
	structuredData: "auto",
});

engineseo.set.preview.customImage("/social/engine.png");
export const generateMetadata = engineseo.generateMetadata;

// app/some-page/page.tsx
import type { Metadata } from "next";
import { generateEngineMetadata } from "@/engine";
import { myPageSchema } from "./schema";

export async function generateMetadata(): Promise<Metadata> {
  return generateEngineMetadata(myPageSchema);
  // or just the meta: generateEngineMetadata({ title: "…", ogImage: "…" })
}

export default createPage(myPageSchema);