@zenithbuild/core 0.6.2 → 1.1.0

package/compiler/transform/fragmentLowering.ts

@@ -56,11 +56,22 @@ function lowerNode(
         case 'expression':
             return lowerExpressionNode(node, filePath, expressions)
 
-        case 'element':
+        case 'element': {
+            // Check if this is a <for> element directive
+            if (node.tag === 'for') {
+                return lowerForElement(node, filePath, expressions)
+            }
+            
+            // Check if this is an <html-content> element directive
+            if (node.tag === 'html-content') {
+                return lowerHtmlContentElement(node, filePath, expressions)
+            }
+            
             return {
                 ...node,
                 children: lowerFragments(node.children, filePath, expressions)
             }
+        }
 
         case 'component':
             return {
@@ -276,6 +287,147 @@ function lowerInlineFragment(
     return node
 }
 
+/**
+ * Lower <for> element directive to LoopFragmentNode
+ * 
+ * Syntax: <for each="item" in="items">...body...</for>
+ * Or:     <for each="item, index" in="items">...body...</for>
+ * 
+ * This is compile-time sugar for {items.map(item => ...)}
+ */
+function lowerForElement(
+    node: import('../ir/types').ElementNode,
+    filePath: string,
+    expressions: ExpressionIR[]
+): LoopFragmentNode {
+    // Extract 'each' and 'in' attributes
+    const eachAttr = node.attributes.find(a => a.name === 'each')
+    const inAttr = node.attributes.find(a => a.name === 'in')
+    
+    if (!eachAttr || typeof eachAttr.value !== 'string') {
+        throw new InvariantError(
+            'ZEN001',
+            `<for> element requires an 'each' attribute specifying the item variable`,
+            'Usage: <for each="item" in="items">...body...</for>',
+            filePath,
+            node.location.line,
+            node.location.column
+        )
+    }
+    
+    if (!inAttr || typeof inAttr.value !== 'string') {
+        throw new InvariantError(
+            'ZEN001',
+            `<for> element requires an 'in' attribute specifying the source array`,
+            'Usage: <for each="item" in="items">...body...</for>',
+            filePath,
+            node.location.line,
+            node.location.column
+        )
+    }
+    
+    // Parse item variable (may include index: "item, index" or "item, i")
+    const eachValue = eachAttr.value.trim()
+    let itemVar: string
+    let indexVar: string | undefined
+    
+    if (eachValue.includes(',')) {
+        const parts = eachValue.split(',').map(p => p.trim())
+        itemVar = parts[0]!
+        indexVar = parts[1]
+    } else {
+        itemVar = eachValue
+    }
+    
+    const source = inAttr.value.trim()
+    
+    // Create loop context for the body
+    const loopVariables = [itemVar]
+    if (indexVar) {
+        loopVariables.push(indexVar)
+    }
+    
+    const bodyLoopContext: LoopContext = {
+        variables: node.loopContext
+            ? [...node.loopContext.variables, ...loopVariables]
+            : loopVariables,
+        mapSource: source
+    }
+    
+    // Lower children with loop context
+    const body = node.children.map(child => {
+        // Recursively lower children
+        const lowered = lowerNode(child, filePath, expressions)
+        // Attach loop context to children that need it
+        if ('loopContext' in lowered) {
+            return { ...lowered, loopContext: bodyLoopContext }
+        }
+        return lowered
+    })
+    
+    return {
+        type: 'loop-fragment',
+        source,
+        itemVar,
+        indexVar,
+        body,
+        location: node.location,
+        loopContext: bodyLoopContext
+    }
+}
+
+/**
+ * Lower <html-content> element directive
+ * 
+ * Syntax: <html-content content="expr" />
+ * 
+ * This renders the expression value as raw HTML (innerHTML).
+ * Use with caution - only for trusted content like icons defined in code.
+ */
+function lowerHtmlContentElement(
+    node: import('../ir/types').ElementNode,
+    filePath: string,
+    expressions: ExpressionIR[]
+): TemplateNode {
+    // Extract 'content' attribute
+    const contentAttr = node.attributes.find(a => a.name === 'content')
+    
+    if (!contentAttr || typeof contentAttr.value !== 'string') {
+        throw new InvariantError(
+            'ZEN001',
+            `<html-content> element requires a 'content' attribute specifying the expression`,
+            'Usage: <html-content content="item.html" />',
+            filePath,
+            node.location.line,
+            node.location.column
+        )
+    }
+    
+    const exprCode = contentAttr.value.trim()
+    
+    // Generate expression ID and register the expression
+    const exprId = `expr_${expressions.length}`
+    const exprIR: ExpressionIR = {
+        id: exprId,
+        code: exprCode,
+        location: node.location
+    }
+    expressions.push(exprIR)
+    
+    // Create a span element with data-zen-html attribute for raw HTML binding
+    return {
+        type: 'element',
+        tag: 'span',
+        attributes: [
+            { name: 'data-zen-html', value: exprIR, location: node.location, loopContext: node.loopContext },
+            { name: 'style', value: 'display: contents;', location: node.location }
+        ],
+        children: [],
+        location: node.location,
+        loopContext: node.loopContext
+    }
+}
+
 /**
  * Parse JSX code string into TemplateNode[]
  * 

package/compiler/transform/generateBindings.ts

@@ -6,6 +6,11 @@
 
 import type { Binding } from '../output/types'
 
+/**
+ * Valid binding types
+ */
+const VALID_BINDING_TYPES = new Set(['text', 'attribute', 'loop', 'conditional', 'optional'])
+
 /**
  * Validate bindings structure
  */
@@ -15,19 +20,35 @@ export function validateBindings(bindings: Binding[]): void {
       throw new Error(`Invalid binding: ${JSON.stringify(binding)}`)
     }
     
-    if (binding.type !== 'text' && binding.type !== 'attribute') {
+    if (!VALID_BINDING_TYPES.has(binding.type)) {
       throw new Error(`Invalid binding type: ${binding.type}`)
     }
     
-    if (binding.type === 'text' && binding.target !== 'data-zen-text') {
-      throw new Error(`Text binding must have target 'data-zen-text', got: ${binding.target}`)
-    }
-    
-    if (binding.type === 'attribute' && !binding.target.startsWith('data-zen-attr-')) {
-      // This is handled in transformNode, but validate here too
-      // Actually, the target should be the attribute name (e.g., "class")
-      // and we prepend "data-zen-attr-" when generating HTML
-      // So this validation is correct
+    // Validate specific binding types
+    switch (binding.type) {
+      case 'text':
+        if (binding.target !== 'data-zen-text') {
+          throw new Error(`Text binding must have target 'data-zen-text', got: ${binding.target}`)
+        }
+        break
+      case 'loop':
+        if (binding.target !== 'data-zen-loop') {
+          throw new Error(`Loop binding must have target 'data-zen-loop', got: ${binding.target}`)
+        }
+        break
+      case 'conditional':
+        if (binding.target !== 'data-zen-cond') {
+          throw new Error(`Conditional binding must have target 'data-zen-cond', got: ${binding.target}`)
+        }
+        break
+      case 'optional':
+        if (binding.target !== 'data-zen-opt') {
+          throw new Error(`Optional binding must have target 'data-zen-opt', got: ${binding.target}`)
+        }
+        break
+      case 'attribute':
+        // Attribute bindings can have various targets
+        break
     }
   }
 }

package/compiler/transform/transformNode.ts

@@ -2,11 +2,30 @@
  * Transform Template Nodes
  * 
  * Transforms IR nodes into HTML strings and collects bindings
+ * 
+ * Phase 8: Supports fragment node types (loop-fragment, conditional-fragment, optional-fragment)
  */
 
-import type { TemplateNode, ElementNode, TextNode, ExpressionNode, ExpressionIR, LoopContext } from '../ir/types'
+import type { 
+  TemplateNode, 
+  ElementNode, 
+  TextNode, 
+  ExpressionNode, 
+  ExpressionIR, 
+  LoopContext,
+  LoopFragmentNode,
+  ConditionalFragmentNode,
+  OptionalFragmentNode,
+  ComponentNode
+} from '../ir/types'
 import type { Binding } from '../output/types'
 
+let loopIdCounter = 0
+
+function generateLoopId(): string {
+  return `loop_${loopIdCounter++}`
+}
+
 let bindingIdCounter = 0
 
 function generateBindingId(): string {
@@ -105,6 +124,100 @@ export function transformNode(
 
         return `<${tag}${attrStr}>${childrenHtml}</${tag}>`
       }
+
+      case 'loop-fragment': {
+        // Loop fragment: {items.map(item => <li>...</li>)} or <for each="item" in="items">
+        // For SSR/SSG, we render one instance of the body as a template
+        // The runtime will hydrate and expand this for each actual item
+        const loopNode = node as LoopFragmentNode
+        const loopId = generateLoopId()
+        const activeLoopContext = loopNode.loopContext || loopContext
+
+        // Create a binding for the loop expression
+        bindings.push({
+          id: loopId,
+          type: 'loop',
+          target: 'data-zen-loop',
+          expression: loopNode.source,
+          location: loopNode.location,
+          loopContext: activeLoopContext,
+          loopMeta: {
+            itemVar: loopNode.itemVar,
+            indexVar: loopNode.indexVar,
+            bodyTemplate: loopNode.body
+          }
+        })
+
+        // Generate the loop body template HTML
+        // For SSR, we render ONE visible instance of the body as a template/placeholder
+        // The runtime will clone this for each item in the array
+        const bodyHtml = loopNode.body.map(child => transform(child, activeLoopContext)).join('')
+        
+        // Render container with body visible for SSR (not in hidden <template>)
+        // Runtime will clear and re-render with actual data
+        return `<div data-zen-loop="${loopId}" data-zen-source="${escapeHtml(loopNode.source)}" data-zen-item="${loopNode.itemVar}"${loopNode.indexVar ? ` data-zen-index="${loopNode.indexVar}"` : ''} style="display: contents;">${bodyHtml}</div>`
+      }
+
+      case 'conditional-fragment': {
+        // Conditional fragment: {cond ? <A /> : <B />}
+        // Both branches are pre-rendered, runtime toggles visibility
+        const condNode = node as ConditionalFragmentNode
+        const condId = generateBindingId()
+        const activeLoopContext = condNode.loopContext || loopContext
+
+        bindings.push({
+          id: condId,
+          type: 'conditional',
+          target: 'data-zen-cond',
+          expression: condNode.condition,
+          location: condNode.location,
+          loopContext: activeLoopContext
+        })
+
+        // Render both branches
+        const consequentHtml = condNode.consequent.map(child => transform(child, activeLoopContext)).join('')
+        const alternateHtml = condNode.alternate.map(child => transform(child, activeLoopContext)).join('')
+
+        return `<div data-zen-cond="${condId}" data-zen-cond-true style="display: contents;">${consequentHtml}</div><div data-zen-cond="${condId}" data-zen-cond-false style="display: none;">${alternateHtml}</div>`
+      }
+
+      case 'optional-fragment': {
+        // Optional fragment: {cond && <A />}
+        // Fragment is pre-rendered, runtime toggles mount/unmount
+        const optNode = node as OptionalFragmentNode
+        const optId = generateBindingId()
+        const activeLoopContext = optNode.loopContext || loopContext
+
+        bindings.push({
+          id: optId,
+          type: 'optional',
+          target: 'data-zen-opt',
+          expression: optNode.condition,
+          location: optNode.location,
+          loopContext: activeLoopContext
+        })
+
+        const fragmentHtml = optNode.fragment.map(child => transform(child, activeLoopContext)).join('')
+
+        return `<div data-zen-opt="${optId}" style="display: contents;">${fragmentHtml}</div>`
+      }
+
+      case 'component': {
+        // Component node - should have been resolved before reaching here
+        // This is a fallback for unresolved components
+        const compNode = node as ComponentNode
+        console.warn(`[Zenith] Unresolved component in transformNode: ${compNode.name}`)
+        
+        // Render children as a fragment
+        const childrenHtml = compNode.children.map(child => transform(child, loopContext)).join('')
+        return `<!-- unresolved: ${compNode.name} -->${childrenHtml}`
+      }
+
+      default: {
+        // Handle any unknown node types
+        console.warn(`[Zenith] Unknown node type in transformNode: ${(node as any).type}`)
+        return ''
+      }
     }
   }
 

package/core/config/index.ts

@@ -2,6 +2,9 @@
  * Zenith Config
  * 
  * Public exports for zenith/config
+ * 
+ * Core exports ONLY generic plugin infrastructure.
+ * Plugin-specific types are owned by their respective plugins.
  */
 
 export { defineConfig } from './types';
@@ -9,8 +12,7 @@ export type {
     ZenithConfig,
     ZenithPlugin,
     PluginContext,
-    ContentSourceConfig,
-    ContentPluginOptions,
-    ContentItem
+    PluginData
 } from './types';
 export { loadZenithConfig, hasZenithConfig } from './loader';
+

package/core/config/types.ts

@@ -2,71 +2,101 @@
  * Zenith Config Types
  * 
  * Configuration interfaces for zenith.config.ts
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * HOOK OWNERSHIP RULE (CANONICAL)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Core may ONLY define types that are universally valid in all Zenith applications.
+ * Plugin-specific types MUST be owned by their respective plugins.
+ * 
+ * ✅ ALLOWED in Core:
+ *    - ZenithConfig, ZenithPlugin, PluginContext (generic plugin infrastructure)
+ *    - Universal lifecycle hooks (onMount, onUnmount)
+ *    - Reactivity primitives (signal, effect, etc.)
+ * 
+ * ❌ PROHIBITED in Core:
+ *    - Content plugin types (ContentItem, ContentSourceConfig, etc.)
+ *    - Router plugin types (RouteState, NavigationGuard, etc.)
+ *    - Documentation plugin types
+ *    - Any type that exists only because a plugin exists
+ * 
+ * If removing a plugin would make a type meaningless, that type belongs to the plugin.
+ * ═══════════════════════════════════════════════════════════════════════════════
  */
 
+import type { CLIBridgeAPI } from '../plugins/bridge';
+
 // ============================================
-// Content Plugin Types
+// Core Plugin Types (Generic Infrastructure)
 // ============================================
 
 /**
- * Configuration for a content source
+ * Generic data record for plugin data exchange
+ * Plugins define their own specific types internally
  */
-export interface ContentSourceConfig {
-    /** Root directory relative to project root (e.g., "../zenith-docs" or "content") */
-    root: string;
-    /** Folders to include from the root (e.g., ["documentation"]). Defaults to all. */
-    include?: string[];
-    /** Folders to exclude from the root (e.g., ["changelog"]) */
-    exclude?: string[];
-}
-
-/**
- * Options for the content plugin
- */
-export interface ContentPluginOptions {
-    /** Named content sources mapped to their configuration */
-    sources?: Record<string, ContentSourceConfig>;
-    /** Legacy: Single content directory (deprecated, use sources instead) */
-    contentDir?: string;
-}
-
-// ============================================
-// Core Plugin Types
-// ============================================
+export type PluginData = Record<string, unknown[]>;
 
 /**
  * Context passed to plugins during setup
+ * 
+ * This is intentionally generic - plugins define their own data shapes.
+ * Core provides the stage, plugins bring the actors.
  */
 export interface PluginContext {
     /** Absolute path to project root */
     projectRoot: string;
-    /** Set content data for the runtime */
-    setContentData: (data: Record<string, ContentItem[]>) => void;
+
+    /** 
+     * Set plugin data for the runtime
+     * 
+     * Generic setter - plugins define their own data structures.
+     * The runtime stores this data and makes it available to components.
+     * 
+     * @example
+     * // Content plugin uses it for content items
+     * ctx.setPluginData('content', contentItems);
+     * 
+     * // Analytics plugin uses it for tracking config
+     * ctx.setPluginData('analytics', analyticsConfig);
+     */
+    setPluginData: (namespace: string, data: unknown[]) => void;
+
     /** Additional options passed from config */
     options?: Record<string, unknown>;
 }
 
-/**
- * A content item loaded from a source
- */
-export interface ContentItem {
-    id?: string | number;
-    slug?: string | null;
-    collection?: string | null;
-    content?: string | null;
-    [key: string]: unknown;
-}
-
 /**
  * A Zenith plugin definition
+ * 
+ * Plugins are self-contained, removable extensions.
+ * Core must build and run identically with or without any plugin installed.
  */
 export interface ZenithPlugin {
     /** Unique plugin name */
     name: string;
+
     /** Setup function called during initialization */
     setup: (ctx: PluginContext) => void | Promise<void>;
+
     /** Plugin-specific configuration (preserved for reference) */
     config?: unknown;
+
+    /**
+     * Optional CLI registration
+     * 
+     * Plugin receives the CLI bridge API to register namespaced hooks.
+     * CLI lifecycle hooks: 'cli:*' (owned by CLI)
+     * Plugin hooks: '<namespace>:*' (owned by plugin)
+     * 
+     * @example
+     * registerCLI(api) {
+     *   api.on('cli:runtime:collect', (ctx) => {
+     *     return { namespace: 'myPlugin', payload: ctx.getPluginData('myPlugin') }
+     *   })
+     * }
+     */
+    registerCLI?: (api: CLIBridgeAPI) => void;
 }
 
 // ============================================