@zenithbuild/core 0.4.2 → 0.4.5

package/compiler/finalize/finalizeOutput.ts

@@ -106,17 +106,29 @@ export function finalizeOutput(
  * Verify HTML contains no raw {expression} syntax
  * 
  * This is a critical check - browser must never see raw expressions
+ * 
+ * Excludes:
+ * - Content inside <pre>, <code> tags (display code samples)
+ * - Content that looks like HTML tags (from entity decoding)
+ * - Comments
+ * - Data attributes
  */
 function verifyNoRawExpressions(html: string, filePath: string): string[] {
   const errors: string[] = []
-  
+
+  // Remove content inside <pre> and <code> tags before checking
+  // These are code samples that may contain { } legitimately
+  let htmlToCheck = html
+    .replace(/<pre[^>]*>[\s\S]*?<\/pre>/gi, '')
+    .replace(/<code[^>]*>[\s\S]*?<\/code>/gi, '')
+
   // Check for raw {expression} patterns (not data-zen-* attributes)
   // Allow data-zen-text, data-zen-attr-* but not raw { }
   const rawExpressionPattern = /\{[^}]*\}/g
-  const matches = html.match(rawExpressionPattern)
-  
+  const matches = htmlToCheck.match(rawExpressionPattern)
+
   if (matches && matches.length > 0) {
-    // Filter out false positives (comments, data attributes, etc.)
+    // Filter out false positives
     const actualExpressions = matches.filter(match => {
       // Exclude if it's in a comment
       if (html.includes(`<!--${match}`) || html.includes(`${match}-->`)) {
@@ -126,10 +138,27 @@ function verifyNoRawExpressions(html: string, filePath: string): string[] {
       if (match.includes('data-zen-')) {
         return false
       }
+      // Exclude if it contains HTML tags (likely from entity decoding in display content)
+      // Real expressions don't start with < inside braces
+      if (match.match(/^\{[\s]*</)) {
+        return false
+      }
+      // Exclude if it looks like display content containing HTML (spans, divs, etc)
+      if (/<[a-zA-Z]/.test(match)) {
+        return false
+      }
+      // Exclude CSS-like content (common in style attributes)
+      if (match.includes(';') && match.includes(':')) {
+        return false
+      }
+      // Exclude if it's a single closing tag pattern (from multiline display)
+      if (/^\{[\s]*<\//.test(match)) {
+        return false
+      }
       // This looks like a raw expression
       return true
     })
-    
+
     if (actualExpressions.length > 0) {
       errors.push(
         `HTML contains raw expressions that were not compiled: ${actualExpressions.join(', ')}\n` +
@@ -138,7 +167,7 @@ function verifyNoRawExpressions(html: string, filePath: string): string[] {
       )
     }
   }
-  
+
   return errors
 }
 
@@ -152,12 +181,12 @@ export function finalizeOutputOrThrow(
   compiled: CompiledTemplate
 ): FinalizedOutput {
   const output = finalizeOutput(ir, compiled)
-  
+
   if (output.hasErrors) {
     const errorMessage = output.errors.join('\n\n')
     throw new Error(`Compilation failed:\n\n${errorMessage}`)
   }
-  
+
   return output
 }
 

package/compiler/index.ts

@@ -3,6 +3,8 @@ import { parseTemplate } from './parse/parseTemplate'
 import { parseScript } from './parse/parseScript'
 import { transformTemplate } from './transform/transformTemplate'
 import { finalizeOutputOrThrow } from './finalize/finalizeOutput'
+import { validateInvariants } from './validate/invariants'
+import { InvariantError } from './errors/compilerError'
 import type { ZenIR, StyleIR } from './ir/types'
 import type { CompiledTemplate } from './output/types'
 import type { FinalizedOutput } from './finalize/finalizeOutput'
@@ -22,7 +24,13 @@ export function compileZen(filePath: string): {
 /**
  * Compile Zen source string into IR and CompiledTemplate
  */
-export function compileZenSource(source: string, filePath: string): {
+export function compileZenSource(
+  source: string,
+  filePath: string,
+  options?: {
+    componentsDir?: string
+  }
+): {
   ir: ZenIR
   compiled: CompiledTemplate
   finalized?: FinalizedOutput
@@ -34,27 +42,40 @@ export function compileZenSource(source: string, filePath: string): {
   const script = parseScript(source)
 
   // Parse styles
-  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi
+  const styleRegex = /\u003cstyle[^\u003e]*\u003e([\s\S]*?)\u003c\/style\u003e/gi
   const styles: StyleIR[] = []
   let match
   while ((match = styleRegex.exec(source)) !== null) {
     if (match[1]) styles.push({ raw: match[1].trim() })
   }
 
-  const ir: ZenIR = {
+  let ir: ZenIR = {
     filePath,
     template,
     script,
     styles
   }
 
+  // Resolve components if components directory is provided
+  if (options?.componentsDir) {
+    const { discoverComponents } = require('./discovery/componentDiscovery')
+    const { resolveComponentsInIR } = require('./transform/componentResolver')
+
+    // Component resolution may throw InvariantError — let it propagate
+    const components = discoverComponents(options.componentsDir)
+    ir = resolveComponentsInIR(ir, components)
+  }
+
+  // Validate all compiler invariants after resolution
+  // Throws InvariantError if any invariant is violated
+  validateInvariants(ir, filePath)
+
   const compiled = transformTemplate(ir)
 
   try {
     const finalized = finalizeOutputOrThrow(ir, compiled)
     return { ir, compiled, finalized }
   } catch (error: any) {
-    throw new Error(`Failed to finalize output for ${filePath}:\n${error.message}`)
+    throw new Error(`Failed to finalize output for ${filePath}:\\n${error.message}`)
   }
 }
-

package/compiler/ir/types.ts

@@ -23,6 +23,10 @@ export type TemplateNode =
   | ElementNode
   | TextNode
   | ExpressionNode
+  | ComponentNode
+  | ConditionalFragmentNode  // JSX ternary: {cond ? <A /> : <B />}
+  | OptionalFragmentNode     // JSX logical AND: {cond && <A />}
+  | LoopFragmentNode         // JSX map: {items.map(i => <li>...</li>)}
 
 export type ElementNode = {
   type: 'element'
@@ -33,6 +37,15 @@ export type ElementNode = {
   loopContext?: LoopContext  // Phase 7: Inherited loop context from parent map expressions
 }
 
+export type ComponentNode = {
+  type: 'component'
+  name: string
+  attributes: AttributeIR[]
+  children: TemplateNode[]
+  location: SourceLocation
+  loopContext?: LoopContext
+}
+
 export type TextNode = {
   type: 'text'
   value: string
@@ -46,6 +59,58 @@ export type ExpressionNode = {
   loopContext?: LoopContext  // Phase 7: Loop context for expressions inside map iterations
 }
 
+/**
+ * Conditional Fragment Node
+ * 
+ * Represents ternary expressions with JSX branches: {cond ? <A /> : <B />}
+ * 
+ * BOTH branches are compiled at compile time.
+ * Runtime toggles visibility — never creates DOM.
+ */
+export type ConditionalFragmentNode = {
+  type: 'conditional-fragment'
+  condition: string           // The condition expression code
+  consequent: TemplateNode[]  // Precompiled "true" branch
+  alternate: TemplateNode[]   // Precompiled "false" branch
+  location: SourceLocation
+  loopContext?: LoopContext
+}
+
+/**
+ * Optional Fragment Node
+ * 
+ * Represents logical AND expressions with JSX: {cond && <A />}
+ * 
+ * Fragment is compiled at compile time.
+ * Runtime toggles mount/unmount based on condition.
+ */
+export type OptionalFragmentNode = {
+  type: 'optional-fragment'
+  condition: string           // The condition expression code
+  fragment: TemplateNode[]    // Precompiled fragment
+  location: SourceLocation
+  loopContext?: LoopContext
+}
+
+/**
+ * Loop Fragment Node
+ * 
+ * Represents .map() expressions with JSX body: {items.map(i => <li>...</li>)}
+ * 
+ * Desugars to @for loop semantics at compile time.
+ * Body is compiled once, instantiated per item at runtime.
+ * Node identity is compiler-owned via stable keys.
+ */
+export type LoopFragmentNode = {
+  type: 'loop-fragment'
+  source: string              // Array expression (e.g., 'items')
+  itemVar: string             // Loop variable (e.g., 'item')
+  indexVar?: string           // Optional index variable
+  body: TemplateNode[]        // Precompiled loop body template
+  location: SourceLocation
+  loopContext: LoopContext    // Extended with this loop's variables
+}
+
 export type AttributeIR = {
   name: string
   value: string | ExpressionIR
@@ -82,3 +147,4 @@ export type SourceLocation = {
   column: number
 }
 
+

package/compiler/parse/parseTemplate.ts

@@ -7,10 +7,12 @@
 
 import { parse, parseFragment } from 'parse5'
 import type { TemplateIR, TemplateNode, ElementNode, TextNode, ExpressionNode, AttributeIR, ExpressionIR, SourceLocation, LoopContext } from '../ir/types'
-import { CompilerError } from '../errors/compilerError'
+import { CompilerError, InvariantError } from '../errors/compilerError'
 import { parseScript } from './parseScript'
 import { detectMapExpression, extractLoopVariables, referencesLoopVariable } from './detectMapExpressions'
 import { shouldAttachLoopContext, mergeLoopContext, extractLoopContextFromExpression } from './trackLoopContext'
+import { INVARIANT } from '../validate/invariants'
+import { lowerFragments } from '../transform/fragmentLowering'
 
 // Generate stable IDs for expressions
 let expressionIdCounter = 0
@@ -362,6 +364,29 @@ function parseNode(
     const location = getLocation(node, originalHtml)
     const tag = node.tagName?.toLowerCase() || node.nodeName
 
+    // Extract original tag name from source HTML to preserve casing (parse5 lowercases everything)
+    let originalTag = node.tagName || node.nodeName
+    if (node.sourceCodeLocation && node.sourceCodeLocation.startOffset !== undefined) {
+      const startOffset = node.sourceCodeLocation.startOffset
+      // Find the tag name in original HTML (after '<')
+      const tagMatch = originalHtml.slice(startOffset).match(/^<([a-zA-Z][a-zA-Z0-9._-]*)/)
+      if (tagMatch && tagMatch[1]) {
+        originalTag = tagMatch[1]
+      }
+    }
+
+    // INV005: <template> tags are forbidden — use compound components instead
+    if (tag === 'template') {
+      throw new InvariantError(
+        INVARIANT.TEMPLATE_TAG,
+        `<template> tags are forbidden in Zenith. Use compound components (e.g., Card.Header) for named slots.`,
+        'Named slots use compound component pattern (Card.Header), not <template> tags.',
+        'unknown', // filePath passed to parseTemplate
+        location.line,
+        location.column
+      )
+    }
+
     // Parse attributes
     const attributes: AttributeIR[] = []
     if (node.attrs) {
@@ -373,6 +398,18 @@ function parseNode(
           }
           : location
 
+        // INV006: slot="" attributes are forbidden — use compound components instead
+        if (attr.name === 'slot') {
+          throw new InvariantError(
+            INVARIANT.SLOT_ATTRIBUTE,
+            `slot="${attr.value || ''}" attribute is forbidden. Use compound components (e.g., Card.Header) for named slots.`,
+            'Named slots use compound component pattern (Card.Header), not slot="" attributes.',
+            'unknown',
+            attrLocation.line,
+            attrLocation.column
+          )
+        }
+
         // Handle :attr="expr" syntax (colon-prefixed reactive attributes)
         let attrName = attr.name
         let attrValue = attr.value || ''
@@ -474,13 +511,29 @@ function parseNode(
       }
     }
 
-    return {
-      type: 'element',
-      tag,
-      attributes,
-      children,
-      location,
-      loopContext: elementLoopContext  // Phase 7: Inherited loop context for child processing
+    // Check if this is a custom component (starts with uppercase)
+    const isComponent = originalTag.length > 0 && originalTag[0] === originalTag[0].toUpperCase()
+
+    if (isComponent) {
+      // This is a component node
+      return {
+        type: 'component',
+        name: originalTag,
+        attributes,
+        children,
+        location,
+        loopContext: elementLoopContext
+      }
+    } else {
+      // This is a regular HTML element
+      return {
+        type: 'element',
+        tag,
+        attributes,
+        children,
+        location,
+        loopContext: elementLoopContext
+      }
     }
   }
 
@@ -517,9 +570,13 @@ export function parseTemplate(html: string, filePath: string): TemplateIR {
       }
     }
 
+    // Phase 8: Lower JSX expressions to structural fragments
+    // This transforms expressions like {cond ? <A /> : <B />} into ConditionalFragmentNode
+    const loweredNodes = lowerFragments(nodes, filePath, expressions)
+
     return {
       raw: templateHtml,
-      nodes,
+      nodes: loweredNodes,
       expressions
     }
   } catch (error: any) {

package/compiler/runtime/generateDOM.ts

@@ -4,7 +4,16 @@
  * Generates JavaScript code that creates DOM elements from template nodes
  */
 
-import type { TemplateNode, ElementNode, TextNode, ExpressionNode, ExpressionIR } from '../ir/types'
+import type {
+  TemplateNode,
+  ElementNode,
+  TextNode,
+  ExpressionNode,
+  ExpressionIR,
+  ConditionalFragmentNode,
+  OptionalFragmentNode,
+  LoopFragmentNode
+} from '../ir/types'
 
 /**
  * Generate DOM creation code from a template node
@@ -95,6 +104,98 @@ ${indent}}\n`
 
       return { code, varName }
     }
+
+    case 'component': {
+      // Components should be resolved before reaching DOM generation
+      // If we get here, it means component resolution failed
+      throw new Error(`[Zenith] Unresolved component: ${(node as any).name}. Components must be resolved before DOM generation.`)
+    }
+
+    case 'conditional-fragment': {
+      // Conditional fragment: {condition ? <A /> : <B />}
+      // Both branches are precompiled, runtime toggles visibility
+      const condNode = node as ConditionalFragmentNode
+      const containerVar = varName
+      const conditionId = `cond_${varCounter.count++}`
+
+      let code = `${indent}const ${containerVar} = document.createDocumentFragment();\n`
+      code += `${indent}const ${conditionId}_result = (function() { with (state) { return ${condNode.condition}; } })();\n`
+
+      // Generate consequent branch
+      code += `${indent}if (${conditionId}_result) {\n`
+      for (const child of condNode.consequent) {
+        const childResult = generateDOMCode(child, expressions, indent + '  ', varCounter)
+        code += `${childResult.code}\n`
+        code += `${indent}  ${containerVar}.appendChild(${childResult.varName});\n`
+      }
+      code += `${indent}} else {\n`
+
+      // Generate alternate branch
+      for (const child of condNode.alternate) {
+        const childResult = generateDOMCode(child, expressions, indent + '  ', varCounter)
+        code += `${childResult.code}\n`
+        code += `${indent}  ${containerVar}.appendChild(${childResult.varName});\n`
+      }
+      code += `${indent}}\n`
+
+      return { code, varName: containerVar }
+    }
+
+    case 'optional-fragment': {
+      // Optional fragment: {condition && <A />}
+      // Fragment is precompiled, runtime mounts/unmounts based on condition
+      const optNode = node as OptionalFragmentNode
+      const containerVar = varName
+      const conditionId = `opt_${varCounter.count++}`
+
+      let code = `${indent}const ${containerVar} = document.createDocumentFragment();\n`
+      code += `${indent}const ${conditionId}_result = (function() { with (state) { return ${optNode.condition}; } })();\n`
+      code += `${indent}if (${conditionId}_result) {\n`
+
+      for (const child of optNode.fragment) {
+        const childResult = generateDOMCode(child, expressions, indent + '  ', varCounter)
+        code += `${childResult.code}\n`
+        code += `${indent}  ${containerVar}.appendChild(${childResult.varName});\n`
+      }
+
+      code += `${indent}}\n`
+
+      return { code, varName: containerVar }
+    }
+
+    case 'loop-fragment': {
+      // Loop fragment: {items.map(item => <li>...</li>)}
+      // Body is precompiled once, instantiated per item at runtime
+      const loopNode = node as LoopFragmentNode
+      const containerVar = varName
+      const loopId = `loop_${varCounter.count++}`
+
+      let code = `${indent}const ${containerVar} = document.createDocumentFragment();\n`
+      code += `${indent}const ${loopId}_items = (function() { with (state) { return ${loopNode.source}; } })() || [];\n`
+
+      // Loop parameters
+      const itemVar = loopNode.itemVar
+      const indexVar = loopNode.indexVar || `${loopId}_idx`
+
+      code += `${indent}${loopId}_items.forEach(function(${itemVar}, ${indexVar}) {\n`
+
+      // Generate loop body with loop context variables in scope
+      for (const child of loopNode.body) {
+        const childResult = generateDOMCode(child, expressions, indent + '  ', varCounter)
+        // Inject loop variables into the child code
+        let childCode = childResult.code
+        code += `${childCode}\n`
+        code += `${indent}  ${containerVar}.appendChild(${childResult.varName});\n`
+      }
+
+      code += `${indent}});\n`
+
+      return { code, varName: containerVar }
+    }
+
+    default: {
+      throw new Error(`[Zenith] Unknown node type: ${(node as any).type}`)
+    }
   }
 }
 

package/compiler/runtime/transformIR.ts

@@ -197,8 +197,8 @@ if (typeof window !== 'undefined') {
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', autoHydrate);
   } else {
-    // DOM already loaded, run on next tick to ensure all scripts are executed
-    setTimeout(autoHydrate, 0);
+    // DOM already loaded, hydrate immediately
+    autoHydrate();
   }
 })();
 `

package/compiler/ssg-build.ts

@@ -20,6 +20,7 @@ import { discoverPages, generateRouteDefinition } from "../router/manifest"
 import { analyzePageSource, getAnalysisSummary, getBuildOutputType, type PageAnalysis } from "./build-analyzer"
 import { generateBundleJS } from "../runtime/bundle-generator"
 import { loadContent } from "../cli/utils/content"
+import { compileCss, resolveGlobalsCss } from "./css"
 
 // ============================================
 // Types
@@ -292,12 +293,23 @@ export function buildSSG(options: SSGBuildOptions): void {
 
     console.log('')
 
-    // Load global styles
+    // Compile global styles (Tailwind CSS)
     let globalStyles = ''
-    const globalCssPath = path.join(baseDir, 'styles', 'global.css')
-    if (fs.existsSync(globalCssPath)) {
-        globalStyles = fs.readFileSync(globalCssPath, 'utf-8')
-        console.log('📦 Loaded global.css')
+    const globalsCssPath = resolveGlobalsCss(baseDir)
+    if (globalsCssPath) {
+        console.log('📦 Compiling CSS:', path.relative(baseDir, globalsCssPath))
+        const cssOutputPath = path.join(outDir, 'assets', 'styles.css')
+        const result = compileCss({
+            input: globalsCssPath,
+            output: cssOutputPath,
+            minify: true
+        })
+        if (result.success) {
+            globalStyles = result.css
+            console.log(`📦 Generated assets/styles.css (${result.duration}ms)`)
+        } else {
+            console.error('❌ CSS compilation failed:', result.error)
+        }
     }
 
     // Write bundle.js if any pages need hydration
@@ -307,12 +319,6 @@ export function buildSSG(options: SSGBuildOptions): void {
         console.log('📦 Generated assets/bundle.js')
     }
 
-    // Write global styles
-    if (globalStyles) {
-        fs.writeFileSync(path.join(outDir, 'assets', 'styles.css'), globalStyles)
-        console.log('📦 Generated assets/styles.css')
-    }
-
     // Write each page
     for (const page of compiledPages) {
         // Create output directory