// ══════════════════════════════════════════════════════════════════════
// KERN v2.0.0 — Node Reference (for LLMs)
//
// Every node type, every prop, every behavior.
// Exhaustive. Scan once, generate correctly.
// ══════════════════════════════════════════════════════════════════════

// ── PAGE NODES ──────────────────────────────────────────────────────
//
// page    → entry point, compiles to default export component
//   name:     string    Component name (default: "Page")
//   route:    string    Output path: route="/features" → features/page.tsx
//   segment:  string    Dynamic segment: segment="[slug]" → [slug]/page.tsx
//   client:   boolean   Adds 'use client' directive
//   async:    boolean   Generates async function with params
//
// layout  → wraps child routes with {children} slot
//   route:    string    Output path (same as page)
//   lang:     string    HTML lang attribute (default: "en")
//
// loading → loading.tsx with animate-pulse
// error   → error.tsx with error+reset props, auto client=true

// ── METADATA ────────────────────────────────────────────────────────
//
// metadata → static Next.js metadata export
//   title:       string
//   description: string
//   keywords:    string
//   ogImage:     string
//
// generateMetadata → dynamic metadata function
//   Children: handler node with code= prop
//   Example: generateMetadata
//              handler code="return { title: params.slug };"

// ── STRUCTURE ───────────────────────────────────────────────────────
//
// row     → <div> with flex (horizontal)
// col     → <div> with flex flex-col (vertical)
// grid    → CSS grid
//   cols:  number   grid-cols (responsive: md:grid-cols-N)
//   gap:   number   gap in pixels (divided by 4 for Tailwind)
//
// section → <section> with optional anchor
//   id:     string   HTML id attribute for anchor links
//   title:  string   Renders <h2> if present, omitted if absent
//
// card    → <div> with border support
//   Styles: border=<color> adds colored border
//
// list    → container with space-y-2
// item    → child of list

// ── TEXT ────────────────────────────────────────────────────────────
//
// text    → renders text in any HTML element
//   value:  string   Static text content
//   bind:   string   Dynamic binding: {variableName}
//   tag:    string   HTML element to use
//     Valid tags: h1 h2 h3 h4 h5 h6 p label span
//     Default: span
//
// Examples:
//   text value="Hello World" tag=h1 {fs:48,fw:800,c:#fff}
//   text bind=userName tag=p {fs:16,c:#a1a1aa}

// ── IMAGE ───────────────────────────────────────────────────────────
//
// image   → next/image component
//   src:      string   Image path or URL
//     "/path.png"    → used as-is
//     "https://..."  → used as-is
//     "name.svg"     → used as-is (has dot)
//     "name"         → becomes /<name>.png (legacy)
//   alt:      string   Alt text (default: src value)
//   width:    number   Width in pixels
//   height:   number   Height in pixels
//   priority: boolean  LCP optimization flag
//   fill:     boolean  Fills parent container (omits width/height)

// ── CODEBLOCK ───────────────────────────────────────────────────────
//
// codeblock → <pre><code> with syntax highlighting class
//   lang:   string   Language class (e.g. kern, typescript, bash)
//   value:  string   Inline code content
//   OR use body child node for multiline:
//     codeblock lang=kern
//       body value="line 1  line 2  line 3"

// ── INTERACTIVE ─────────────────────────────────────────────────────
//
// button  → <button> or next/link
//   text:    string   Button label
//   to:      string   Navigation target (generates Link)
//   onClick: string   Click handler expression
//
// link    → next/link wrapper
//   to:      string   Navigation target
//
// input   → <input> element
//   bind:    string   Two-way data binding
//
// slider  → range input
//   bind:    string   Bound variable
//   min:     number   Minimum value (default: 0)
//   max:     number   Maximum value (default: 100)
//   step:    number   Step size (default: 1)
//
// toggle  → checkbox styled as toggle switch
//   bind:    string   Bound boolean variable

// ── NAVIGATION ──────────────────────────────────────────────────────
//
// tabs    → <nav> with flex
// tab     → <button> inside tabs
//   label:  string   Tab text

// ── DATA FETCHING ───────────────────────────────────────────────────
//
// fetch   → generates await fetch() call, auto-makes page async
//   name:    string   Variable name for result
//   url:     string   Fetch URL
//   options: string   Fetch options (optional)
//
// notFound → conditional notFound() call
//   if:      expr     Condition (e.g. if={{ !product }})
//
// redirect → unconditional redirect
//   to:      string   Target path
//
// import  → custom import statement
//   name:    string   Import name
//   from:    string   Module path
//   default: boolean  Default import (vs named)

// ── CONDITIONAL ─────────────────────────────────────────────────────
//
// conditional → renders children only when condition is true
//   if:    string   Condition expression
//   Example: conditional if={{ user.isAdmin }}

// ── COMPONENT ───────────────────────────────────────────────────────
//
// component → renders a custom component
//   ref:     string   Component name (gets imported)
//   bind:    string   Value binding
//   props:   string   Comma-separated prop pass-through
//   Any other props passed as JSX attributes

// ── PROGRESS ────────────────────────────────────────────────────────
//
// progress → progress bar with label
//   label:   string   Display label
//   current: number   Current value
//   target:  number   Target/max value
//   unit:    string   Unit display (e.g. "kcal", "g")
//   color:   string   Bar color

// ── DIVIDER ─────────────────────────────────────────────────────────
//
// divider → horizontal line (h-px)

// ── ICON ────────────────────────────────────────────────────────────
//
// icon → Icon component
//   name:  string   Icon name

// ── BACKEND (Express target) ────────────────────────────────────────
//
// server     → Express app entry
//   name:    string   App name
//   port:    number   Port number
//
// route      → Express route
//   method:  string   HTTP method (get, post, put, delete)
//   path:    string   URL path pattern
//
// middleware → Express middleware
//   name:    string   Middleware name
//   handler: string   Handler function name
//
// handler    → route handler code
//   Uses <<< >>> for multiline code blocks
//
// schema     → request validation
//   body:    string   JSON schema for request body
//
// stream     → SSE endpoint
// spawn      → child_process
// timer      → setTimeout with AbortController

// ── CLI (cli target) ────────────────────────────────────────────────
//
// cli        → Commander.js app
//   name:     string   App name
//   version:  string   Version string
//
// command    → CLI command
//   name:     string   Command name
//   description: string
//
// arg        → positional argument
//   name:     string
//   type:     string   (string, number)
//   required: boolean
//
// flag       → CLI flag/option
//   name:     string
//   alias:    string   Short alias (e.g. "v" for --verbose)
//   type:     string   (string, number, boolean)
//   default:  any      Default value

// ── TERMINAL (terminal target) ──────────────────────────────────────
//
// gradient   → ANSI gradient text
//   text:    string
//   colors:  array    ANSI color codes
//
// box        → bordered box
//   color:   number   ANSI color
//
// spinner    → loading spinner
//   message: string
//   color:   number
//
// scoreboard → table display
//   title:   string
//   winner:  string
//   Children: metric nodes
//
// separator  → horizontal separator line
//   width:   number

// ── CORE LANGUAGE ───────────────────────────────────────────────────
//
// type       → TypeScript type/interface generation
//   name:    string
//   Children: field nodes
//
// interface  → TypeScript interface
//   name:    string
//   Children: fn nodes
//
// field      → type field
//   name:    string
//   type:    string   TypeScript type expression
//
// fn         → function declaration
//   name:    string
//   params:  string   Parameter list
//   returns: string   Return type
//
// machine    → state machine
//   name:    string
//   initial: string   Initial state
//   Children: transition nodes
//   Output: enum + type guards + transition function
//
// transition → state machine transition
//   from:    string   Source state
//   to:      string   Target state
//   event:   string   Trigger event name
//
// event      → event declaration
//   name:    string
//
// config     → configuration object
// store      → state store
// error      → error type
// module     → module declaration
// export     → export declaration

// ── REACT (react target extras) ─────────────────────────────────────
//
// hook       → custom React hook
// provider   → context provider wrapper
// effect     → useEffect block
// memo       → useMemo wrapper
// callback   → useCallback wrapper
// ref        → useRef
// context    → createContext
// cleanup    → effect cleanup function
// prop       → component prop declaration
// returns    → hook return value

// ── TEMPLATE SYSTEM ─────────────────────────────────────────────────
//
// template   → reusable node template definition
//   name:    string
//   Children: slot nodes for customization
//
// slot       → template customization point
//   name:    string
//
// body       → multiline content block
//   value:   string   Content
//   Uses <<< >>> for multiline:
//     body <<<
//       multiline content here
//     >>>

// ══════════════════════════════════════════════════════════════════════
// Every node above is a valid KERN node type.
// Combine them with style shorthands: {bg:#18181b,c:#fff,p:24,br:12}
// See /llm/spec.kern for the full style shorthand reference.
// ══════════════════════════════════════════════════════════════════════