@zenithbuild/core 0.4.6 → 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/discovery/componentDiscovery.ts

@@ -26,6 +26,8 @@ export interface ComponentMetadata {
     slots: SlotDefinition[]
     props: string[]       // Declared props
     styles: string[]      // Raw CSS from <style> blocks
+    script: string | null         // Raw script content for bundling
+    scriptAttributes: Record<string, string> | null  // Script attributes (setup, lang)
     hasScript: boolean
     hasStyles: boolean
 }
@@ -112,6 +114,8 @@ function parseComponentFile(filePath: string): ComponentMetadata | null {
         slots,
         props,
         styles,
+        script: ir.script?.raw || null,                    // Store raw script content
+        scriptAttributes: ir.script?.attributes || null,   // Store script attributes
         hasScript: ir.script !== null,
         hasStyles: ir.styles.length > 0
     }

package/compiler/discovery/layouts.ts

@@ -41,8 +41,17 @@ export function discoverLayouts(layoutsDir: string): Map<string, LayoutMetadata>
                 if (match[1]) styles.push(match[1].trim())
             }
 
-            // Extract HTML (everything except script/style)
-            let html = source.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+            // Extract HTML (everything except inline scripts/style)
+            // Preserve external script tags (<script src="...">) but remove inline <script setup> blocks
+            // Use a function-based replace to check for src attribute
+            let html = source.replace(/<script([^>]*)>([\s\S]*?)<\/script>/gi, (match, attrs, content) => {
+                // Keep script tags with src attribute (external scripts)
+                if (attrs.includes('src=')) {
+                    return match;
+                }
+                // Remove inline scripts (those without src)
+                return '';
+            })
             html = html.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '').trim()
 
             layouts.set(name, {

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) {
@@ -53,6 +53,7 @@ export function compileZenSource(
     filePath,
     template,
     script,
+    // componentScripts: [],
     styles
   }
 
@@ -73,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,11 +6,35 @@
  * 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
+ */
+export type ComponentScriptIR = {
+  name: string                           // Component name (e.g., 'HeroSection')
+  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 = {
   filePath: string
   template: TemplateIR
   script: ScriptIR | null
   styles: StyleIR[]
+  componentScripts?: ComponentScriptIR[]  // Scripts from used components
 }
 
 export type TemplateIR = {

package/compiler/parse/parseTemplate.ts

@@ -22,10 +22,18 @@ function generateExpressionId(): string {
 
 /**
  * Strip script and style blocks from HTML before parsing
+ * Preserves external script tags (<script src="...">) but removes inline scripts
  */
 function stripBlocks(html: string): string {
-  // Remove script blocks
-  let stripped = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
+  // Remove only inline script blocks (those WITHOUT src attribute), preserve external scripts
+  let stripped = html.replace(/<script([^>]*)>([\s\S]*?)<\/script>/gi, (match, attrs, content) => {
+    // Keep script tags with src attribute (external scripts)
+    if (attrs.includes('src=')) {
+      return match;
+    }
+    // Remove inline scripts (those without src)
+    return '';
+  })
   // Remove style blocks
   stripped = stripped.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
   return stripped

package/compiler/parse/scriptAnalysis.ts

@@ -45,6 +45,7 @@ export function extractProps(script: string): string[] {
 
 /**
  * Transform script by removing state and prop declarations
+ * Also strips .zen imports (resolved at compile time) and other compile-time-only imports
  */
 export function transformStateDeclarations(script: string): string {
     let transformed = script
@@ -62,6 +63,13 @@ export function transformStateDeclarations(script: string): string {
     // Remove zenith/runtime imports
     transformed = transformed.replace(/import\s+{[^}]+}\s+from\s+['"]zenith\/runtime['"]\s*;?[ \t]*/g, '')
 
+    // Remove .zen file imports (resolved at compile time)
+    // Matches: import Name from '.../file.zen'; or import Name from '.../file.zen'
+    transformed = transformed.replace(/import\s+\w+\s+from\s+['"][^'"]*\.zen['"];?\s*/g, '')
+
+    // Remove relative imports with destructuring (components are inlined)
+    transformed = transformed.replace(/import\s+{[^}]*}\s+from\s+['"][^'"]+\.zen['"];?\s*/g, '')
+
     // Transform zenith:content imports to global lookups
     transformed = transformed.replace(
         /import\s*{\s*([^}]+)\s*}\s*from\s*['"]zenith:content['"]\s*;?/g,

package/compiler/runtime/transformIR.ts

@@ -4,13 +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, emitImports } from '../transform/componentScriptTransformer'
 
 export interface RuntimeCode {
   expressions: string  // Expression wrapper functions
@@ -25,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,
@@ -70,6 +71,9 @@ 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 (async)
+  const componentScriptResult = await transformAllComponentScripts(ir.componentScripts || [])
+
   // Generate complete runtime bundle
   const bundle = generateRuntimeBundle({
     expressions,
@@ -78,7 +82,9 @@ export function transformIR(ir: ZenIR): RuntimeCode {
     navigationRuntime,
     stylesCode,
     scriptCode,
-    stateInitCode
+    stateInitCode,
+    componentScriptCode: componentScriptResult.code,
+    npmImports: componentScriptResult.imports
   })
 
   return {
@@ -103,14 +109,21 @@ function generateRuntimeBundle(parts: {
   stylesCode: string
   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}
 
@@ -129,6 +142,9 @@ ${functionRegistrations}
 ${parts.stateInitCode ? `// State initialization
 ${parts.stateInitCode}` : ''}
 
+${parts.componentScriptCode ? `// Component factories (instance-scoped)
+${parts.componentScriptCode}` : ''}
+
 // Export hydration functions
 if (typeof window !== 'undefined') {
   window.zenithHydrate = window.__zenith_hydrate || function(state, container) {
@@ -187,10 +203,21 @@ if (typeof window !== 'undefined') {
     // Get the router outlet or body
     const container = document.querySelector('#app') || document.body;
     
-    // Hydrate with state
+    // Hydrate with state (expressions, bindings)
     if (window.__zenith_hydrate) {
       window.__zenith_hydrate(state, {}, {}, {}, container);
     }
+    
+    // Hydrate components by discovering data-zen-component markers
+    // This is the ONLY place component instantiation happens - driven by DOM markers
+    if (window.__zenith && window.__zenith.hydrateComponents) {
+      window.__zenith.hydrateComponents(container);
+    }
+    
+    // Trigger page-level mount lifecycle
+    if (window.__zenith && window.__zenith.triggerMount) {
+      window.__zenith.triggerMount();
+    }
   }
   
   // Run on DOM ready

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/componentResolver.ts

@@ -5,19 +5,19 @@
  * Uses compound component pattern for named slots (Card.Header, Card.Footer).
  */
 
-import type { TemplateNode, ComponentNode, ElementNode, ZenIR, LoopContext } from '../ir/types'
+import type { TemplateNode, ComponentNode, ElementNode, ZenIR, LoopContext, ComponentScriptIR } from '../ir/types'
 import type { ComponentMetadata } from '../discovery/componentDiscovery'
 import { extractSlotsFromChildren, resolveSlots } from './slotResolver'
 import { throwOrphanCompoundError, throwUnresolvedComponentError } from '../validate/invariants'
 
-// Track which components have been used (for style collection)
+// Track which components have been used (for style and script collection)
 const usedComponents = new Set<string>()
 
 /**
  * Resolve all component nodes in a template IR
  * 
  * Recursively replaces ComponentNode instances with their resolved templates
- * Also collects styles from used components and adds them to the IR
+ * Also collects styles AND scripts from used components and adds them to the IR
  */
 export function resolveComponentsInIR(
     ir: ZenIR,
@@ -35,6 +35,17 @@ export function resolveComponentsInIR(
         .filter((meta): meta is ComponentMetadata => meta !== undefined && meta.styles.length > 0)
         .flatMap(meta => meta.styles.map(raw => ({ raw })))
 
+    // Collect scripts from all used components (for bundling)
+    const componentScripts: ComponentScriptIR[] = Array.from(usedComponents)
+        .map(name => components.get(name))
+        .filter((meta): meta is ComponentMetadata => meta !== undefined && meta.script !== null)
+        .map(meta => ({
+            name: meta.name,
+            script: meta.script!,
+            props: meta.props,
+            scriptAttributes: meta.scriptAttributes || {}
+        }))
+
     return {
         ...ir,
         template: {
@@ -42,7 +53,9 @@ export function resolveComponentsInIR(
             nodes: resolvedNodes
         },
         // Merge component styles with existing page styles
-        styles: [...ir.styles, ...componentStyles]
+        styles: [...ir.styles, ...componentStyles],
+        // Add component scripts for bundling
+        componentScripts: [...(ir.componentScripts || []), ...componentScripts]
     }
 }
 
@@ -192,11 +205,12 @@ function resolveComponent(
     const resolvedTemplate = resolveSlots(templateNodes, resolvedSlots)
 
     // Forward attributes from component usage to the root element
-    // This ensures onclick, class, and other attributes are preserved
+    // Also adds data-zen-component marker for hydration-driven instantiation
     const forwardedTemplate = forwardAttributesToRoot(
         resolvedTemplate,
         componentNode.attributes,
-        componentNode.loopContext
+        componentNode.loopContext,
+        componentMeta.hasScript ? componentName : undefined  // Only mark if component has script
     )
 
     // Recursively resolve any nested components in the resolved template
@@ -210,16 +224,16 @@ function resolveComponent(
  * 
  * When using <Button onclick="increment">Text</Button>,
  * the onclick should be applied to the <button> element in Button.zen template.
+ * 
+ * Also adds data-zen-component marker if componentName is provided,
+ * enabling hydration-driven instantiation.
  */
 function forwardAttributesToRoot(
     nodes: TemplateNode[],
     attributes: ComponentNode['attributes'],
-    loopContext?: LoopContext
+    loopContext?: LoopContext,
+    componentName?: string  // If provided, adds hydration marker
 ): TemplateNode[] {
-    if (attributes.length === 0) {
-        return nodes
-    }
-
     // Find the first non-text element (the root element)
     const rootIndex = nodes.findIndex(n => n.type === 'element')
     if (rootIndex === -1) {
@@ -228,10 +242,19 @@ function forwardAttributesToRoot(
 
     const root = nodes[rootIndex] as ElementNode
 
-    // Merge attributes: component usage attributes override template defaults
-    // Also preserve the parent's loopContext on forwarded attributes
+    // Start with existing attributes
     const mergedAttributes = [...root.attributes]
 
+    // Add component hydration marker if this component has a script
+    if (componentName) {
+        mergedAttributes.push({
+            name: 'data-zen-component',
+            value: componentName,
+            location: { line: 0, column: 0 }
+        })
+    }
+
+    // Forward attributes from component usage
     for (const attr of attributes) {
         const existingIndex = mergedAttributes.findIndex(a => a.name === attr.name)