@zenithbuild/core 0.4.7 → 0.5.0

package/cli/commands/dev.ts

@@ -1,5 +1,6 @@
 import path from 'path'
 import fs from 'fs'
+import os from 'os'
 import { serve, type ServerWebSocket } from 'bun'
 import { requireProject } from '../utils/project'
 import * as logger from '../utils/logger'
@@ -29,6 +30,53 @@ interface CompiledPage {
 
 const pageCache = new Map<string, CompiledPage>()
 
+/**
+ * Bundle page script using Bun's bundler to resolve npm imports at compile time.
+ * This allows ES module imports like `import { gsap } from 'gsap'` to work.
+ */
+async function bundlePageScript(script: string, projectRoot: string): Promise<string> {
+    // If no import statements, return as-is
+    if (!script.includes('import ')) {
+        return script
+    }
+
+    // Create a temporary file for bundling
+    const tempDir = os.tmpdir()
+    const tempFile = path.join(tempDir, `zenith-bundle-${Date.now()}.js`)
+
+    try {
+        // Write script to temp file
+        fs.writeFileSync(tempFile, script, 'utf-8')
+
+        // Use Bun.build to bundle with npm resolution
+        const result = await Bun.build({
+            entrypoints: [tempFile],
+            target: 'browser',
+            format: 'esm',
+            minify: false,
+            // Resolve modules from the project's node_modules
+            external: [], // Bundle everything
+        })
+
+        if (!result.success || !result.outputs[0]) {
+            console.error('[Zenith] Bundle errors:', result.logs)
+            return script // Fall back to original
+        }
+
+        // Get the bundled output
+        const bundledCode = await result.outputs[0].text()
+        return bundledCode
+    } catch (error: any) {
+        console.error('[Zenith] Failed to bundle page script:', error.message)
+        return script // Fall back to original
+    } finally {
+        // Clean up temp file
+        try {
+            fs.unlinkSync(tempFile)
+        } catch { }
+    }
+}
+
 export async function dev(options: DevOptions = {}): Promise<void> {
     const project = requireProject()
     const port = options.port || parseInt(process.env.PORT || '3000', 10)
@@ -105,7 +153,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     /**
      * Compile a .zen page in memory
      */
-    function compilePageInMemory(pagePath: string): CompiledPage | null {
+    async function compilePageInMemory(pagePath: string): Promise<CompiledPage | null> {
         try {
             const layoutsDir = path.join(pagesDir, '../layouts')
             const componentsDir = path.join(pagesDir, '../components')
@@ -117,16 +165,19 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
             if (layoutToUse) processedSource = processLayout(source, layoutToUse)
 
-            const result = compileZenSource(processedSource, pagePath, {
+            const result = await compileZenSource(processedSource, pagePath, {
                 componentsDir: fs.existsSync(componentsDir) ? componentsDir : undefined
             })
             if (!result.finalized) throw new Error('Compilation failed')
 
             const routeDef = generateRouteDefinition(pagePath, pagesDir)
 
+            // Bundle the script to resolve npm imports at compile time
+            const bundledScript = await bundlePageScript(result.finalized.js, rootDir)
+
             return {
                 html: result.finalized.html,
-                script: result.finalized.js,
+                script: bundledScript,
                 styles: result.finalized.styles,
                 route: routeDef.path,
                 lastModified: Date.now()
@@ -189,7 +240,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
     const server = serve({
         port,
-        fetch(req, server) {
+        async fetch(req, server) {
             const startTime = performance.now()
             const url = new URL(req.url)
             const pathname = url.pathname
@@ -246,7 +297,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
                 const stat = fs.statSync(pagePath)
 
                 if (!cached || stat.mtimeMs > cached.lastModified) {
-                    cached = compilePageInMemory(pagePath) || undefined
+                    cached = await compilePageInMemory(pagePath) || undefined
                     if (cached) pageCache.set(pagePath, cached)
                 }
                 const compileEnd = performance.now()
@@ -327,7 +378,8 @@ function generateDevHTML(page: CompiledPage, contentData: any = {}): string {
     // Escape </script> sequences in JSON content to prevent breaking the script tag
     const contentJson = JSON.stringify(contentData).replace(/<\//g, '<\\/')
     const contentTag = `<script>window.__ZENITH_CONTENT__ = ${contentJson};</script>`
-    const scriptTag = `<script>\n${page.script}\n</script>`
+    // Use type="module" to support ES6 imports from npm packages
+    const scriptTag = `<script type="module">\n${page.script}\n</script>`
     const allScripts = `${runtimeTag}\n${contentTag}\n${scriptTag}`
     return page.html.includes('</body>')
         ? page.html.replace('</body>', `${allScripts}\n</body>`)

package/compiler/finalize/finalizeOutput.ts

@@ -39,10 +39,10 @@ export interface FinalizedOutput {
  * @param compiled - Compiled template from Phase 2
  * @returns Finalized output
  */
-export function finalizeOutput(
+export async function finalizeOutput(
   ir: ZenIR,
   compiled: CompiledTemplate
-): FinalizedOutput {
+): Promise<FinalizedOutput> {
   const errors: string[] = []
 
   // 1. Validate all expressions (Phase 8/9/10 requirement)
@@ -77,7 +77,7 @@ export function finalizeOutput(
   // 3. Generate runtime code
   let runtimeCode: RuntimeCode
   try {
-    runtimeCode = transformIR(ir)
+    runtimeCode = await transformIR(ir)
   } catch (error: any) {
     errors.push(`Runtime generation failed: ${error.message}`)
     return {
@@ -176,11 +176,11 @@ function verifyNoRawExpressions(html: string, filePath: string): string[] {
  * 
  * Throws if validation fails (build must fail on errors)
  */
-export function finalizeOutputOrThrow(
+export async function finalizeOutputOrThrow(
   ir: ZenIR,
   compiled: CompiledTemplate
-): FinalizedOutput {
-  const output = finalizeOutput(ir, compiled)
+): Promise<FinalizedOutput> {
+  const output = await finalizeOutput(ir, compiled)
 
   if (output.hasErrors) {
     const errorMessage = output.errors.join('\n\n')

package/compiler/index.ts

@@ -12,11 +12,11 @@ import type { FinalizedOutput } from './finalize/finalizeOutput'
 /**
  * Compile a .zen file into IR and CompiledTemplate
  */
-export function compileZen(filePath: string): {
+export async function compileZen(filePath: string): Promise<{
   ir: ZenIR
   compiled: CompiledTemplate
   finalized?: FinalizedOutput
-} {
+}> {
   const source = readFileSync(filePath, 'utf-8')
   return compileZenSource(source, filePath)
 }
@@ -24,17 +24,17 @@ export function compileZen(filePath: string): {
 /**
  * Compile Zen source string into IR and CompiledTemplate
  */
-export function compileZenSource(
+export async function compileZenSource(
   source: string,
   filePath: string,
   options?: {
     componentsDir?: string
   }
-): {
+): Promise<{
   ir: ZenIR
   compiled: CompiledTemplate
   finalized?: FinalizedOutput
-} {
+}> {
   // Parse template
   const template = parseTemplate(source, filePath)
 
@@ -42,7 +42,7 @@ export function compileZenSource(
   const script = parseScript(source)
 
   // Parse styles
-  const styleRegex = /\u003cstyle[^\u003e]*\u003e([\s\S]*?)\u003c\/style\u003e/gi
+  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi
   const styles: StyleIR[] = []
   let match
   while ((match = styleRegex.exec(source)) !== null) {
@@ -74,9 +74,10 @@ export function compileZenSource(
   const compiled = transformTemplate(ir)
 
   try {
-    const finalized = finalizeOutputOrThrow(ir, compiled)
+    const finalized = await finalizeOutputOrThrow(ir, compiled)
     return { ir, compiled, finalized }
   } catch (error: any) {
     throw new Error(`Failed to finalize output for ${filePath}:\\n${error.message}`)
   }
 }
+

package/compiler/ir/types.ts

@@ -6,6 +6,17 @@
  * without any runtime execution or transformation.
  */
 
+/**
+ * Structured ES module import metadata
+ * Parsed from component scripts, used for deterministic bundling
+ */
+export interface ScriptImport {
+  source: string         // Module specifier, e.g. 'gsap'
+  specifiers: string     // Import clause, e.g. '{ gsap }' or 'gsap' or ''
+  typeOnly: boolean      // TypeScript type-only import
+  sideEffect: boolean    // Side-effect import (no specifiers)
+}
+
 /**
  * Component Script IR - represents a component's script block
  * Used for collecting and bundling component scripts
@@ -15,6 +26,7 @@ export type ComponentScriptIR = {
   script: string                         // Raw script content
   props: string[]                        // Declared props
   scriptAttributes: Record<string, string>  // Script attributes (setup, lang)
+  imports: ScriptImport[]                // Parsed npm imports for bundling
 }
 
 export type ZenIR = {

package/compiler/runtime/transformIR.ts

@@ -4,14 +4,14 @@
  * Phase 4: Transform ZenIR into runtime-ready JavaScript code with full reactivity
  */
 
-import type { ZenIR } from '../ir/types'
+import type { ZenIR, ScriptImport } from '../ir/types'
 import { generateExpressionWrappers } from './wrapExpression'
 import { generateDOMFunction } from './generateDOM'
 import { generateHydrationRuntime, generateExpressionRegistry } from './generateHydrationBundle'
 import { analyzeAllExpressions } from './dataExposure'
 import { generateNavigationRuntime } from './navigation'
 import { extractStateDeclarations, extractProps, transformStateDeclarations } from '../parse/scriptAnalysis'
-import { transformAllComponentScripts } from '../transform/componentScriptTransformer'
+import { transformAllComponentScripts, emitImports } from '../transform/componentScriptTransformer'
 
 export interface RuntimeCode {
   expressions: string  // Expression wrapper functions
@@ -26,7 +26,7 @@ export interface RuntimeCode {
 /**
  * Transform ZenIR into runtime JavaScript code
  */
-export function transformIR(ir: ZenIR): RuntimeCode {
+export async function transformIR(ir: ZenIR): Promise<RuntimeCode> {
   // Phase 6: Analyze expression dependencies for explicit data exposure
   const expressionDependencies = analyzeAllExpressions(
     ir.template.expressions,
@@ -71,8 +71,8 @@ export function transformIR(ir: ZenIR): RuntimeCode {
   // Transform script (remove state and prop declarations, they're handled by runtime)
   const scriptCode = transformStateDeclarations(scriptContent)
 
-  // Transform component scripts for instance-scoped execution
-  const componentScriptCode = transformAllComponentScripts(ir.componentScripts || [])
+  // Transform component scripts for instance-scoped execution (async)
+  const componentScriptResult = await transformAllComponentScripts(ir.componentScripts || [])
 
   // Generate complete runtime bundle
   const bundle = generateRuntimeBundle({
@@ -83,7 +83,8 @@ export function transformIR(ir: ZenIR): RuntimeCode {
     stylesCode,
     scriptCode,
     stateInitCode,
-    componentScriptCode  // Component factories
+    componentScriptCode: componentScriptResult.code,
+    npmImports: componentScriptResult.imports
   })
 
   return {
@@ -109,14 +110,20 @@ function generateRuntimeBundle(parts: {
   scriptCode: string
   stateInitCode: string
   componentScriptCode: string  // Component factories
+  npmImports: ScriptImport[]   // Structured npm imports from component scripts
 }): string {
   // Extract function declarations from script code to register on window
   const functionRegistrations = extractFunctionRegistrations(parts.scriptCode)
 
+  // Generate npm imports header (hoisted, deduplicated, deterministic)
+  const npmImportsHeader = parts.npmImports.length > 0
+    ? `// NPM Imports (hoisted from component scripts)\n${emitImports(parts.npmImports)}\n\n`
+    : ''
+
   return `// Zenith Runtime Bundle (Phase 5)
 // Generated at compile time - no .zen parsing in browser
 
-${parts.expressions}
+${npmImportsHeader}${parts.expressions}
 
 ${parts.expressionRegistry}
 

package/compiler/spa-build.ts

@@ -43,11 +43,11 @@ interface SPABuildOptions {
 /**
  * Compile a single page file
  */
-function compilePage(
+async function compilePage(
   pagePath: string,
   pagesDir: string,
   baseDir: string = process.cwd()
-): CompiledPage {
+): Promise<CompiledPage> {
   try {
     const layoutsDir = path.join(baseDir, 'app', 'layouts')
     const layouts = discoverLayouts(layoutsDir)
@@ -63,7 +63,7 @@ function compilePage(
     }
 
     // Use new compiler pipeline on the processed source
-    const result = compileZenSource(processedSource, pagePath)
+    const result = await compileZenSource(processedSource, pagePath)
 
     if (!result.finalized) {
       throw new Error(`Compilation failed: No finalized output`)
@@ -843,7 +843,7 @@ function generateHTMLShell(
 /**
  * Build SPA from pages directory
  */
-export function buildSPA(options: SPABuildOptions): void {
+export async function buildSPA(options: SPABuildOptions): Promise<void> {
   const { pagesDir, outDir, baseDir } = options
 
   // Clean output directory
@@ -870,7 +870,7 @@ export function buildSPA(options: SPABuildOptions): void {
     console.log(`[Zenith Build] Compiling: ${path.relative(pagesDir, pageFile)}`)
 
     try {
-      const compiled = compilePage(pageFile, pagesDir)
+      const compiled = await compilePage(pageFile, pagesDir)
       compiledPages.push(compiled)
     } catch (error) {
       console.error(`[Zenith Build] Error compiling ${pageFile}:`, error)

package/compiler/ssg-build.ts

@@ -65,11 +65,11 @@ export interface SSGBuildOptions {
 /**
  * Compile a single page file for SSG output
  */
-function compilePage(
+async function compilePage(
     pagePath: string,
     pagesDir: string,
     baseDir: string = process.cwd()
-): CompiledPage {
+): Promise<CompiledPage> {
     const source = fs.readFileSync(pagePath, 'utf-8')
 
     // Analyze page requirements
@@ -88,7 +88,7 @@ function compilePage(
     }
 
     // Compile with new pipeline
-    const result = compileZenSource(processedSource, pagePath)
+    const result = await compileZenSource(processedSource, pagePath)
 
     if (!result.finalized) {
         throw new Error(`Compilation failed for ${pagePath}: No finalized output`)
@@ -239,7 +239,7 @@ ${page.pageScript}
 /**
  * Build all pages using SSG approach
  */
-export function buildSSG(options: SSGBuildOptions): void {
+export async function buildSSG(options: SSGBuildOptions): Promise<void> {
     const { pagesDir, outDir, baseDir = path.dirname(pagesDir) } = options
     const contentDir = path.join(baseDir, 'content')
     const contentData = loadContent(contentDir)
@@ -275,7 +275,7 @@ export function buildSSG(options: SSGBuildOptions): void {
         console.log(`   Compiling: ${relativePath}`)
 
         try {
-            const compiled = compilePage(pageFile, pagesDir, baseDir)
+            const compiled = await compilePage(pageFile, pagesDir, baseDir)
             compiledPages.push(compiled)
 
             if (compiled.analysis.needsHydration) {
@@ -356,7 +356,7 @@ export function buildSSG(options: SSGBuildOptions): void {
         const custom404Path = path.join(pagesDir, candidate)
         if (fs.existsSync(custom404Path)) {
             try {
-                const compiled = compilePage(custom404Path, pagesDir, baseDir)
+                const compiled = await compilePage(custom404Path, pagesDir, baseDir)
                 const html = generatePageHTML(compiled, globalStyles, contentData)
                 fs.writeFileSync(path.join(outDir, '404.html'), html)
                 console.log('📦 Generated 404.html (custom)')

package/compiler/transform/componentScriptTransformer.ts

@@ -5,13 +5,24 @@
  * Uses namespace binding pattern for cleaner output:
  *   const { signal, effect, onMount, ... } = __inst;
  * 
- * Then rewrites zen* prefixed calls to unprefixed:
- *   zenSignal(v)  → signal(v)
- *   zenEffect(fn) → effect(fn)
- *   zenOnMount(fn) → onMount(fn)
+ * Uses es-module-lexer to parse imports:
+ * - .zen imports are stripped (compile-time resolved)
+ * - npm imports are extracted as structured metadata for bundling
+ * 
+ * IMPORTANT: No regex-based import parsing.
  */
 
-import type { ComponentScriptIR } from '../ir/types'
+import { init, parse } from 'es-module-lexer'
+import type { ComponentScriptIR, ScriptImport } from '../ir/types'
+
+// Initialize es-module-lexer (must be called before parsing)
+let lexerInitialized = false
+async function ensureLexerInit(): Promise<void> {
+    if (!lexerInitialized) {
+        await init
+        lexerInitialized = true
+    }
+}
 
 /**
  * Namespace bindings - destructured from the instance
@@ -38,32 +49,102 @@ const ZEN_PREFIX_MAPPINGS: Record<string, string> = {
     'zenOnUnmount': 'onUnmount',
 }
 
+/**
+ * Result of script transformation including extracted imports
+ */
+export interface TransformResult {
+    script: string           // Transformed script (imports removed)
+    imports: ScriptImport[]  // Structured npm imports to hoist
+}
+
+/**
+ * Parse and extract imports from script content using es-module-lexer
+ * 
+ * @param scriptContent - Raw script content
+ * @returns Object with imports array and script with imports stripped
+ */
+export async function parseAndExtractImports(scriptContent: string): Promise<{
+    imports: ScriptImport[]
+    strippedCode: string
+}> {
+    await ensureLexerInit()
+
+    const imports: ScriptImport[] = []
+    const [parsedImports] = parse(scriptContent)
+
+    // Sort imports by start position (descending) for safe removal
+    const sortedImports = [...parsedImports].sort((a, b) => b.ss - a.ss)
+
+    let strippedCode = scriptContent
+
+    for (const imp of sortedImports) {
+        const source = imp.n || ''  // Module specifier
+        const importStatement = scriptContent.slice(imp.ss, imp.se)
+
+        // Skip .zen file imports (compile-time resolved) - just strip them
+        if (source.endsWith('.zen')) {
+            strippedCode = strippedCode.slice(0, imp.ss) + strippedCode.slice(imp.se)
+            continue
+        }
+
+        // Skip relative imports (compile-time resolved) - just strip them
+        if (source.startsWith('./') || source.startsWith('../')) {
+            strippedCode = strippedCode.slice(0, imp.ss) + strippedCode.slice(imp.se)
+            continue
+        }
+
+        // This is an npm/external import - extract as structured metadata
+        const isTypeOnly = importStatement.startsWith('import type')
+        const isSideEffect = imp.ss === imp.se || !importStatement.includes(' from ')
+
+        // Extract specifiers from the import statement
+        let specifiers = ''
+        if (!isSideEffect) {
+            const fromIndex = importStatement.indexOf(' from ')
+            if (fromIndex !== -1) {
+                // Get everything between 'import' (or 'import type') and 'from'
+                const start = isTypeOnly ? 'import type '.length : 'import '.length
+                specifiers = importStatement.slice(start, fromIndex).trim()
+            }
+        }
+
+        imports.push({
+            source,
+            specifiers,
+            typeOnly: isTypeOnly,
+            sideEffect: isSideEffect
+        })
+
+        // Strip the import from the code (it will be hoisted to bundle top)
+        strippedCode = strippedCode.slice(0, imp.ss) + strippedCode.slice(imp.se)
+    }
+
+    // Clean up any leftover empty lines from stripped imports
+    strippedCode = strippedCode.replace(/^\s*\n/gm, '')
+
+    // Reverse imports array since we processed in reverse order
+    imports.reverse()
+
+    return { imports, strippedCode }
+}
+
 /**
  * Transform a component's script content for instance-scoped execution
  * 
  * @param componentName - Name of the component
  * @param scriptContent - Raw script content from the component
  * @param props - Declared prop names
- * @returns Transformed script ready for bundling
+ * @returns TransformResult with transformed script and extracted imports
  */
-export function transformComponentScript(
+export async function transformComponentScript(
     componentName: string,
     scriptContent: string,
     props: string[]
-): string {
-    let transformed = scriptContent
-
-    // Strip import statements for .zen files (resolved at compile time)
-    transformed = transformed.replace(
-        /import\s+\w+\s+from\s+['"][^'"]*\.zen['"];?\s*/g,
-        ''
-    )
+): Promise<TransformResult> {
+    // Parse and extract imports using es-module-lexer
+    const { imports, strippedCode } = await parseAndExtractImports(scriptContent)
 
-    // Strip any other relative imports (components are inlined)
-    transformed = transformed.replace(
-        /import\s+{[^}]*}\s+from\s+['"][^'"]+['"];?\s*/g,
-        ''
-    )
+    let transformed = strippedCode
 
     // Rewrite zen* prefixed calls to unprefixed (uses namespace bindings)
     for (const [zenName, unprefixedName] of Object.entries(ZEN_PREFIX_MAPPINGS)) {
@@ -72,7 +153,10 @@ export function transformComponentScript(
         transformed = transformed.replace(regex, `${unprefixedName}(`)
     }
 
-    return transformed.trim()
+    return {
+        script: transformed.trim(),
+        imports
+    }
 }
 
 /**
@@ -119,29 +203,81 @@ __zenith.defineComponent('${componentName}', function(props, rootElement) {
 `
 }
 
+/**
+ * Result of transforming all component scripts
+ */
+export interface TransformAllResult {
+    code: string             // Combined factory code
+    imports: ScriptImport[]  // All collected npm imports (deduplicated)
+}
+
+/**
+ * Deduplicate imports by (source + specifiers + typeOnly) tuple
+ * Returns deterministically sorted imports
+ */
+function deduplicateImports(imports: ScriptImport[]): ScriptImport[] {
+    const seen = new Map<string, ScriptImport>()
+
+    for (const imp of imports) {
+        const key = `${imp.source}|${imp.specifiers}|${imp.typeOnly}`
+        if (!seen.has(key)) {
+            seen.set(key, imp)
+        }
+    }
+
+    // Sort by source for deterministic output
+    return Array.from(seen.values()).sort((a, b) => a.source.localeCompare(b.source))
+}
+
+/**
+ * Emit import statements from structured metadata
+ */
+export function emitImports(imports: ScriptImport[]): string {
+    const deduplicated = deduplicateImports(imports)
+
+    return deduplicated.map(imp => {
+        if (imp.sideEffect) {
+            return `import '${imp.source}';`
+        }
+        const typePrefix = imp.typeOnly ? 'type ' : ''
+        return `import ${typePrefix}${imp.specifiers} from '${imp.source}';`
+    }).join('\n')
+}
+
 /**
  * Transform all component scripts from collected ComponentScriptIR
  * 
  * @param componentScripts - Array of component script IRs
- * @returns Combined JavaScript code for all component factories
+ * @returns TransformAllResult with combined code and deduplicated imports
  */
-export function transformAllComponentScripts(
+export async function transformAllComponentScripts(
     componentScripts: ComponentScriptIR[]
-): string {
+): Promise<TransformAllResult> {
     if (!componentScripts || componentScripts.length === 0) {
-        return ''
+        return { code: '', imports: [] }
     }
 
-    const factories = componentScripts
-        .filter(comp => comp.script && comp.script.trim().length > 0)
-        .map(comp => {
-            const transformed = transformComponentScript(
-                comp.name,
-                comp.script,
-                comp.props
-            )
-            return generateComponentFactory(comp.name, transformed, comp.props)
-        })
+    const allImports: ScriptImport[] = []
+
+    const factories = await Promise.all(
+        componentScripts
+            .filter(comp => comp.script && comp.script.trim().length > 0)
+            .map(async comp => {
+                const result = await transformComponentScript(
+                    comp.name,
+                    comp.script,
+                    comp.props
+                )
+
+                // Collect imports
+                allImports.push(...result.imports)
 
-    return factories.join('\n')
+                return generateComponentFactory(comp.name, result.script, comp.props)
+            })
+    )
+
+    return {
+        code: factories.join('\n'),
+        imports: deduplicateImports(allImports)
+    }
 }

package/dist/cli.js

@@ -13,6 +13,10 @@
 #!/usr/bin/env bun
 #!/usr/bin/env bun
 #!/usr/bin/env bun
+#!/usr/bin/env bun
+#!/usr/bin/env bun
+#!/usr/bin/env bun
+#!/usr/bin/env bun
 // @bun
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;