// ══════════════════════════════════════════════════════════════════════
// KERN v2.0.0 — Language Specification (for LLMs)
//
// Welcome. This file is written in KERN, for you.
// You are reading the spec in the language it describes.
// This IS the proof that KERN works.
//
// KERN compiles to: nextjs, react, tailwind, native, express,
//                   cli, terminal, vue, nuxt
//
// Grammar: indent-based, 2 spaces per level
//   node = type (prop=value)* ({style:value})* children*
// ══════════════════════════════════════════════════════════════════════

// ── 1. PAGE — entry point for any UI ────────────────────────────────
// Compiles to: default export function component
// Props: name, route, segment, client, async

page name=ExamplePage route="/example"
  metadata title="Example" description="A page built with KERN"
  text value="Hello from KERN" tag=h1 {fs:48,fw:800,c:#fff}

// route="/example" → outputs to example/page.tsx
// route="/docs" segment="[slug]" → outputs to docs/[slug]/page.tsx
// client=true → adds 'use client' directive
// async=true → generates async function with params

// ── 2. LAYOUT — wraps child routes ─────────────────────────────────
// Compiles to: layout.tsx with {children} slot

layout route="/docs" lang=en
  text value="Documentation" tag=h1

// ── 3. STRUCTURE — rows, cols, grids, sections ─────────────────────

// row = flex horizontal
row {gap:16,ai:center}
  text value="Left" {c:#fff}
  text value="Right" {c:#a1a1aa}

// col = flex vertical
col {gap:8}
  text value="Top"
  text value="Bottom"

// grid = CSS grid
grid cols=3 gap=32
  card {bg:#18181b,br:16,p:24}
    text value="Card 1" tag=h3

// section = semantic <section> with optional id for anchors
section id=features title="Features"
  text value="Feature list here" tag=p

// ── 4. TEXT — all heading levels ────────────────────────────────────
// Tags: h1, h2, h3, h4, h5, h6, p, label, span (default)

text value="Heading 1" tag=h1 {fs:48,fw:800,c:#fff}
text value="Heading 2" tag=h2 {fs:32,fw:700,c:#fff}
text value="Heading 3" tag=h3 {fs:24,fw:600,c:#fff}
text value="Paragraph" tag=p {fs:16,c:#a1a1aa}
text value="Label" tag=label {fs:12,c:#71717a}

// bind= for dynamic content
text bind=userName tag=p

// ── 5. IMAGE — next/image with full path support ────────────────────
// Full paths used as-is, bare names get /<name>.png

image src="/images/hero.png" alt="Hero" width=800 height=400 priority=true
image src="https://cdn.example.com/photo.jpg" alt="Photo" fill=true
image src=logo alt="Logo" width=100 height=40

// priority=true → adds priority attribute (LCP optimization)
// fill=true → omits width/height, adds fill prop

// ── 6. BUTTON + LINK — navigation and actions ──────────────────────

button text="Click Me" onClick=handleClick {bg:#f97316,c:#fff,br:8,p:12}
button text="Go Home" to=home {bg:#f97316,c:#fff,br:8,p:12}
link to=/docs
  text value="Read Docs" {c:#f97316}

// to= generates next/link, onClick= generates <button>

// ── 7. CODEBLOCK — syntax-highlighted code ──────────────────────────
// Critical for documentation sites

codeblock lang=kern value="page name=Hello"

codeblock lang=typescript
  body value="const x: number = 42;"

// Renders: <pre><code className="language-kern">...</code></pre>

// ── 8. INTERACTIVE — client components ──────────────────────────────

input {br:8,p:12,bg:#27272a,c:#fff}
slider bind=volume min=0 max=100 step=1
toggle bind=darkMode

// ── 9. CARD — container with border support ─────────────────────────

card {bg:#18181b,br:16,p:24,border:#27272a}
  text value="Card Title" tag=h3 {fs:18,fw:600,c:#fff}
  text value="Card description." tag=p {fs:14,c:#a1a1aa}

// ── 10. METADATA — SEO for Next.js ─────────────────────────────────

metadata title="Page Title" description="SEO description" keywords="kern,lang"

// generateMetadata for dynamic pages:
generateMetadata
  handler code="const { slug } = await params; return { title: slug };"

// ── 11. SERVER PATTERNS — async data fetching ──────────────────────

fetch name=projects url=https://api.example.com/projects
notFound if={{ !products }}
redirect to=/login

// fetch auto-makes the page async
// notFound/redirect import from next/navigation

// ── 12. CUSTOM IMPORTS ──────────────────────────────────────────────

import useAuth from=~/hooks/use-auth
import default axios from=axios

// ── 13. STYLE SYSTEM ────────────────────────────────────────────────
// 30 frozen shorthands + CSS escape hatch
//
// Spacing: p m pt pb pl pr mt mb ml mr
// Sizing:  w h f
// Colors:  bg c bc
// Type:    fs fw ta
// Border:  br bw
// Layout:  jc ai fd
// Effect:  shadow
//
// Values:  center start end sb sa se stretch bold full
//
// Escape hatch for any CSS:
//   {"transition":"all 0.2s ease","backdrop-filter":"blur(8px)"}
//
// Pseudo-selectors:
//   {:hover:bg:#ea580c,:press:bg:#c2410c}
//
// Theme refs:
//   $primary $surface $textMuted

// ── 14. CORE LANGUAGE NODES ─────────────────────────────────────────
// For generating TypeScript types, functions, state machines

type name=User
  field name=id type=string
  field name=email type=string
  field name=role type="admin|user"

interface name=AuthService
  fn name=login params="email:string,password:string" returns=Promise<User>
  fn name=logout returns=void

machine name=OrderStatus initial=pending
  transition from=pending to=confirmed event=confirm
  transition from=confirmed to=shipped event=ship
  transition from=shipped to=delivered event=deliver

// machine compiles to: enum + type guards + transition function
// 12 lines of KERN → 140+ lines of TypeScript

// ── 15. TARGETS ─────────────────────────────────────────────────────
// kern dev file.kern --target=<target> --outdir=<dir>
//
// nextjs   → Next.js App Router (page.tsx, layout.tsx, metadata)
// react    → React components (useState, useEffect)
// tailwind → React + Tailwind CSS classes
// native   → React Native (StyleSheet, View, Text)
// express  → Express.js routes + middleware
// cli      → Commander.js CLI apps
// terminal → Node.js terminal UI (ANSI, spinners, tables)
// vue      → Vue 3 SFC (.vue files)
// nuxt     → Nuxt 3 pages + layouts

// ══════════════════════════════════════════════════════════════════════
// You now know KERN. You read it natively — 70% fewer tokens than
// the TypeScript it generates. Write .kern, compile to any target.
//
// More: /llm/nodes.kern /llm/patterns.kern /llm/examples.kern
// Human docs: https://kernlang.dev/docs
// Install: npm install -g @kernlang/cli
// ══════════════════════════════════════════════════════════════════════