@zenithbuild/cli 0.5.0-beta.2.6 → 0.6.2

package/README.md

@@ -5,6 +5,11 @@
 
 The command-line interface for developing and building Zenith applications.
 
+## Canonical Docs
+
+- CLI contract: `../zenith-docs/documentation/cli-contract.md`
+- Script server/data contract: `../zenith-docs/documentation/contracts/server-data.md`
+
 ## Overview
 
 `@zenithbuild/cli` provides the toolchain needed to manage Zenith projects. While `create-zenith` is for scaffolding, this CLI is for the daily development loop: serving apps, building for production, and managing plugins.

package/dist/build.js

@@ -15,7 +15,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { generateManifest } from './manifest.js';
 import { buildComponentRegistry, expandComponents, extractTemplate, isDocumentMode } from './resolve-components.js';
@@ -63,10 +63,63 @@ const COMPILER_BIN = resolveBinary([
     resolve(CLI_ROOT, '../zenith-compiler/target/release/zenith-compiler')
 ]);
 
-const BUNDLER_BIN = resolveBinary([
-    resolve(CLI_ROOT, '../bundler/target/release/zenith-bundler'),
-    resolve(CLI_ROOT, '../zenith-bundler/target/release/zenith-bundler')
-]);
+function getBundlerBin() {
+    const envBin = process.env.ZENITH_BUNDLER_BIN;
+    if (envBin && typeof envBin === 'string' && existsSync(envBin)) {
+        return envBin;
+    }
+    return resolveBinary([
+        resolve(CLI_ROOT, '../bundler/target/release/zenith-bundler'),
+        resolve(CLI_ROOT, '../zenith-bundler/target/release/zenith-bundler')
+    ]);
+}
+
+/**
+ * Build a per-build warning emitter that deduplicates repeated compiler lines.
+ *
+ * @param {(line: string) => void} sink
+ * @returns {(line: string) => void}
+ */
+export function createCompilerWarningEmitter(sink = (line) => console.warn(line)) {
+    const emitted = new Set();
+    return (line) => {
+        const text = String(line || '').trim();
+        if (!text || emitted.has(text)) {
+            return;
+        }
+        emitted.add(text);
+        sink(text);
+    };
+}
+
+/**
+ * Forward child-process output line-by-line through the structured logger.
+ *
+ * @param {import('node:stream').Readable | null | undefined} stream
+ * @param {(line: string) => void} onLine
+ */
+function forwardStreamLines(stream, onLine) {
+    if (!stream || typeof stream.on !== 'function') {
+        return;
+    }
+    let pending = '';
+    stream.setEncoding?.('utf8');
+    stream.on('data', (chunk) => {
+        pending += String(chunk || '');
+        const lines = pending.split(/\r?\n/);
+        pending = lines.pop() || '';
+        for (const line of lines) {
+            if (line.trim().length > 0) {
+                onLine(line);
+            }
+        }
+    });
+    stream.on('end', () => {
+        if (pending.trim().length > 0) {
+            onLine(pending);
+        }
+    });
+}
 
 /**
  * Run the compiler process and parse its JSON stdout.
@@ -77,15 +130,21 @@ const BUNDLER_BIN = resolveBinary([
  *
  * @param {string} filePath — path for diagnostics (and file reading when no stdinSource)
  * @param {string} [stdinSource] — if provided, piped to compiler via stdin
+ * @param {object} compilerRunOptions
+ * @param {(warning: string) => void} [compilerRunOptions.onWarning]
+ * @param {boolean} [compilerRunOptions.suppressWarnings]
  * @returns {object}
  */
-function runCompiler(filePath, stdinSource, compilerOpts = {}) {
+function runCompiler(filePath, stdinSource, compilerOpts = {}, compilerRunOptions = {}) {
     const args = stdinSource !== undefined
         ? ['--stdin', filePath]
         : [filePath];
     if (compilerOpts?.experimentalEmbeddedMarkup) {
         args.push('--embedded-markup-expressions');
     }
+    if (compilerOpts?.strictDomLints) {
+        args.push('--strict-dom-lints');
+    }
     const opts = { encoding: 'utf8' };
     if (stdinSource !== undefined) {
         opts.input = stdinSource;
@@ -102,6 +161,20 @@ function runCompiler(filePath, stdinSource, compilerOpts = {}) {
         );
     }
 
+    if (result.stderr && result.stderr.trim().length > 0 && compilerRunOptions.suppressWarnings !== true) {
+        const lines = String(result.stderr)
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const line of lines) {
+            if (typeof compilerRunOptions.onWarning === 'function') {
+                compilerRunOptions.onWarning(line);
+            } else {
+                console.warn(line);
+            }
+        }
+    }
+
     try {
         return JSON.parse(result.stdout);
     } catch (err) {
@@ -143,7 +216,7 @@ function buildComponentExpressionRewrite(compPath, componentSource, compIr, comp
 
     let templateIr;
     try {
-        templateIr = runCompiler(compPath, templateOnly, compilerOpts);
+        templateIr = runCompiler(compPath, templateOnly, compilerOpts, { suppressWarnings: true });
     } catch {
         return out;
     }
@@ -200,6 +273,57 @@ function mergeExpressionRewriteMaps(pageMap, pageAmbiguous, componentRewrite) {
     }
 }
 
+function resolveStateKeyFromBindings(identifier, stateBindings, preferredKeys = null) {
+    const ident = String(identifier || '').trim();
+    if (!ident) {
+        return null;
+    }
+
+    const exact = stateBindings.find((entry) => String(entry?.key || '') === ident);
+    if (exact && typeof exact.key === 'string') {
+        return exact.key;
+    }
+
+    const suffix = `_${ident}`;
+    const matches = stateBindings
+        .map((entry) => String(entry?.key || ''))
+        .filter((key) => key.endsWith(suffix));
+
+    if (preferredKeys instanceof Set && preferredKeys.size > 0) {
+        const preferredMatches = matches.filter((key) => preferredKeys.has(key));
+        if (preferredMatches.length === 1) {
+            return preferredMatches[0];
+        }
+    }
+
+    if (matches.length === 1) {
+        return matches[0];
+    }
+
+    return null;
+}
+
+function rewriteRefBindingIdentifiers(pageIr, preferredKeys = null) {
+    if (!Array.isArray(pageIr?.ref_bindings) || pageIr.ref_bindings.length === 0) {
+        return;
+    }
+
+    const stateBindings = Array.isArray(pageIr?.hoisted?.state) ? pageIr.hoisted.state : [];
+    if (stateBindings.length === 0) {
+        return;
+    }
+
+    for (const binding of pageIr.ref_bindings) {
+        if (!binding || typeof binding !== 'object' || typeof binding.identifier !== 'string') {
+            continue;
+        }
+        const resolved = resolveStateKeyFromBindings(binding.identifier, stateBindings, preferredKeys);
+        if (resolved) {
+            binding.identifier = resolved;
+        }
+    }
+}
+
 /**
  * Rewrite unresolved page expressions using component script-aware mappings.
  *
@@ -232,6 +356,9 @@ function applyExpressionRewrites(pageIr, expressionMap, ambiguous) {
             bindings[index].literal === current
         ) {
             bindings[index].literal = rewritten;
+            if (bindings[index].compiled_expr === current) {
+                bindings[index].compiled_expr = rewritten;
+            }
         }
     }
 }
@@ -271,6 +398,15 @@ function rewriteLegacyMarkupIdentifiers(pageIr) {
             _LEGACY_MARKUP_RE.lastIndex = 0;
             bindings[i].literal = bindings[i].literal.replace(_LEGACY_MARKUP_RE, '__ZENITH_INTERNAL_ZENHTML');
         }
+        if (
+            bindings[i] &&
+            typeof bindings[i] === 'object' &&
+            typeof bindings[i].compiled_expr === 'string' &&
+            bindings[i].compiled_expr.includes(_LEGACY_MARKUP_IDENT)
+        ) {
+            _LEGACY_MARKUP_RE.lastIndex = 0;
+            bindings[i].compiled_expr = bindings[i].compiled_expr.replace(_LEGACY_MARKUP_RE, '__ZENITH_INTERNAL_ZENHTML');
+        }
     }
 }
 
@@ -452,7 +588,7 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
     const scriptRe = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
     const serverMatches = [];
     const reservedServerExportRe =
-        /\bexport\s+const\s+(?:data|prerender)\b|\bexport\s+(?:async\s+)?function\s+load\s*\(|\bexport\s+const\s+load\s*=/;
+        /\bexport\s+const\s+(?:data|prerender|guard|load)\b|\bexport\s+(?:async\s+)?function\s+(?:load|guard)\s*\(|\bexport\s+const\s+(?:load|guard)\s*=/;
 
     for (const match of source.matchAll(scriptRe)) {
         const attrs = String(match[1] || '');
@@ -463,8 +599,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
             throw new Error(
                 `Zenith server script contract violation:\n` +
                 `  File: ${sourceFile}\n` +
-                `  Reason: data/load/prerender exports are only allowed in <script server lang="ts">\n` +
-                `  Example: move export const data or export const load into <script server lang="ts">`
+                `  Reason: guard/load/data exports are only allowed in <script server lang="ts"> or adjacent .guard.ts / .load.ts files\n` +
+                `  Example: move the export into <script server lang="ts">`
             );
         }
 
@@ -535,6 +671,25 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         );
     }
 
+    const guardFnMatch = serverSource.match(/\bexport\s+(?:async\s+)?function\s+guard\s*\(([^)]*)\)/);
+    const guardConstParenMatch = serverSource.match(/\bexport\s+const\s+guard\s*=\s*(?:async\s*)?\(([^)]*)\)\s*=>/);
+    const guardConstSingleArgMatch = serverSource.match(
+        /\bexport\s+const\s+guard\s*=\s*(?:async\s*)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/
+    );
+    const hasGuard = Boolean(guardFnMatch || guardConstParenMatch || guardConstSingleArgMatch);
+    const guardMatchCount =
+        Number(Boolean(guardFnMatch)) +
+        Number(Boolean(guardConstParenMatch)) +
+        Number(Boolean(guardConstSingleArgMatch));
+    if (guardMatchCount > 1) {
+        throw new Error(
+            `Zenith server script contract violation:\n` +
+            `  File: ${sourceFile}\n` +
+            `  Reason: multiple guard exports detected\n` +
+            `  Example: keep exactly one export const guard = async (ctx) => ({ ... })`
+        );
+    }
+
     const hasData = /\bexport\s+const\s+data\b/.test(serverSource);
     const hasSsrData = /\bexport\s+const\s+ssr_data\b/.test(serverSource);
     const hasSsr = /\bexport\s+const\s+ssr\b/.test(serverSource);
@@ -575,6 +730,24 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         }
     }
 
+    if (hasGuard) {
+        const singleArg = String(guardConstSingleArgMatch?.[1] || '').trim();
+        const paramsText = String((guardFnMatch || guardConstParenMatch)?.[1] || '').trim();
+        const arity = singleArg
+            ? 1
+            : paramsText.length === 0
+                ? 0
+                : paramsText.split(',').length;
+        if (arity !== 1) {
+            throw new Error(
+                `Zenith server script contract violation:\n` +
+                `  File: ${sourceFile}\n` +
+                `  Reason: guard(ctx) must accept exactly one argument\n` +
+                `  Example: export const guard = async (ctx) => ({ ... })`
+            );
+        }
+    }
+
     const prerenderMatch = serverSource.match(/\bexport\s+const\s+prerender\s*=\s*([^\n;]+)/);
     let prerender = false;
     if (prerenderMatch) {
@@ -596,6 +769,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
             serverScript: {
                 source: serverSource,
                 prerender,
+                has_guard: hasGuard,
+                has_load: hasLoad,
                 source_path: sourceFile
             }
         };
@@ -609,6 +784,8 @@ function extractServerScript(source, sourceFile, compilerOpts = {}) {
         serverScript: {
             source: serverSource,
             prerender,
+            has_guard: hasGuard,
+            has_load: hasLoad,
             source_path: sourceFile
         }
     };
@@ -654,7 +831,7 @@ function collectComponentUsageAttrs(source, registry) {
  * @param {{ includeCode: boolean, cssImportsOnly: boolean, documentMode?: boolean, componentAttrs?: string }} options
  * @param {Set<string>} seenStaticImports
  */
-function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStaticImports) {
+function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStaticImports, knownRefKeys = null) {
     // Merge components_scripts
     if (compIr.components_scripts) {
         for (const [hoistId, script] of Object.entries(compIr.components_scripts)) {
@@ -669,6 +846,17 @@ function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStati
         pageIr.component_instances.push(...compIr.component_instances);
     }
 
+    if (knownRefKeys instanceof Set && Array.isArray(compIr.ref_bindings)) {
+        const componentStateBindings = Array.isArray(compIr?.hoisted?.state) ? compIr.hoisted.state : [];
+        for (const binding of compIr.ref_bindings) {
+            if (!binding || typeof binding.identifier !== 'string' || binding.identifier.length === 0) {
+                continue;
+            }
+            const resolved = resolveStateKeyFromBindings(binding.identifier, componentStateBindings);
+            knownRefKeys.add(resolved || binding.identifier);
+        }
+    }
+
     // Merge hoisted imports (deduplicated, rebased to the page file path)
     if (compIr.hoisted?.imports?.length) {
         for (const imp of compIr.hoisted.imports) {
@@ -741,11 +929,7 @@ function mergeComponentIr(pageIr, compIr, compPath, pageFile, options, seenStati
                 : rebased;
             const withPropsPrelude = injectPropsPrelude(filteredImports, options.componentAttrs || '');
             const transpiled = transpileTypeScriptToJs(withPropsPrelude, compPath);
-            const withRefFallbacks = injectRefFallbacksInZenMount(
-                transpiled,
-                options.refFallbacks || []
-            );
-            const deduped = dedupeStaticImportsInSource(withRefFallbacks, seenStaticImports);
+            const deduped = dedupeStaticImportsInSource(transpiled, seenStaticImports);
             const deferred = deferComponentRuntimeBlock(deduped);
             if (deferred.trim().length > 0 && !pageIr.hoisted.code.includes(deferred)) {
                 pageIr.hoisted.code.push(deferred);
@@ -868,7 +1052,7 @@ function transpileTypeScriptToJs(source, sourceFile) {
             fileName: sourceFile,
             compilerOptions: {
                 module: ts.ModuleKind.ESNext,
-                target: ts.ScriptTarget.ES2022,
+                target: ts.ScriptTarget.ES5,
                 importsNotUsedAsValues: ts.ImportsNotUsedAsValues.Preserve,
                 verbatimModuleSyntax: true,
                 newLine: ts.NewLineKind.LineFeed,
@@ -1103,7 +1287,7 @@ function injectPropsPrelude(source, attrs) {
     }
 
     const propsLiteral = renderPropsLiteralFromAttrs(attrs);
-    return `const props = ${propsLiteral};\n${source}`;
+    return `var props = ${propsLiteral};\n${source}`;
 }
 
 /**
@@ -1155,111 +1339,37 @@ function deferComponentRuntimeBlock(source) {
     return wrapped;
 }
 
-/**
- * @param {string} componentSource
- * @returns {Array<{ identifier: string, selector: string }>}
- */
-function extractRefFallbackAssignments(componentSource) {
-    const template = extractTemplate(componentSource);
-    const tagRe = /<[^>]*ref=\{([A-Za-z_$][A-Za-z0-9_$]*)\}[^>]*>/g;
-    const out = [];
-    const seen = new Set();
-
-    let match;
-    while ((match = tagRe.exec(template)) !== null) {
-        const tag = match[0];
-        const identifier = match[1];
-        const attrMatch = tag.match(/\b(data-[a-z0-9-]+-runtime)\b/i)
-            || tag.match(/\b(data-[a-z0-9-]+)\b/i);
-        if (!attrMatch) {
-            continue;
-        }
-
-        const selector = `[${attrMatch[1]}]`;
-        const key = `${identifier}:${selector}`;
-        if (seen.has(key)) {
-            continue;
-        }
-        seen.add(key);
-        out.push({ identifier, selector });
-    }
-
-    return out;
-}
-
-/**
- * @param {string} source
- * @param {string} originalIdentifier
- * @returns {string | null}
- */
-function resolveRenamedRefIdentifier(source, originalIdentifier) {
-    const re = /const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*ref\s*\(/g;
-    let match;
-    while ((match = re.exec(source)) !== null) {
-        const candidate = match[1];
-        if (candidate === originalIdentifier || candidate.endsWith(`_${originalIdentifier}`)) {
-            return candidate;
-        }
-    }
-    return null;
-}
-
-/**
- * @param {string} source
- * @param {Array<{ identifier: string, selector: string }>} refFallbacks
- * @returns {string}
- */
-function injectRefFallbacksInZenMount(source, refFallbacks) {
-    if (!Array.isArray(refFallbacks) || refFallbacks.length === 0) {
-        return source;
-    }
-
-    const lines = [];
-    for (let i = 0; i < refFallbacks.length; i++) {
-        const fallback = refFallbacks[i];
-        const refIdentifier = resolveRenamedRefIdentifier(source, fallback.identifier);
-        if (!refIdentifier) {
-            continue;
-        }
-        const selector = JSON.stringify(fallback.selector);
-        const nodeVar = `__zenith_ref_node_${i}`;
-        lines.push(
-            `    if (typeof document !== 'undefined' && ${refIdentifier} && !${refIdentifier}.current) {`,
-            `        const ${nodeVar} = document.querySelector(${selector});`,
-            `        if (${nodeVar}) {`,
-            `            ${refIdentifier}.current = ${nodeVar};`,
-            '        }',
-            '    }'
-        );
-    }
-
-    if (lines.length === 0) {
-        return source;
-    }
-
-    const mountRe = /zenMount\s*\(\s*\([^)]*\)\s*=>\s*\{/;
-    if (!mountRe.test(source)) {
-        return source;
-    }
-
-    return source.replace(mountRe, (match) => `${match}\n${lines.join('\n')}\n`);
-}
-
 /**
  * Run bundler process for one page envelope.
  *
  * @param {object|object[]} envelope
  * @param {string} outDir
+ * @param {string} projectRoot
+ * @param {object | null} [logger]
+ * @param {boolean} [showInfo]
  * @returns {Promise<void>}
  */
-function runBundler(envelope, outDir) {
+function runBundler(envelope, outDir, projectRoot, logger = null, showInfo = true) {
     return new Promise((resolvePromise, rejectPromise) => {
+        const useStructuredLogger = Boolean(logger && typeof logger.childLine === 'function');
         const child = spawn(
-            BUNDLER_BIN,
+            getBundlerBin(),
             ['--out-dir', outDir],
-            { stdio: ['pipe', 'inherit', 'inherit'] }
+            {
+                cwd: projectRoot,
+                stdio: useStructuredLogger ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'inherit']
+            }
         );
 
+        if (useStructuredLogger) {
+            forwardStreamLines(child.stdout, (line) => {
+                logger.childLine('bundler', line, { stream: 'stdout', showInfo });
+            });
+            forwardStreamLines(child.stderr, (line) => {
+                logger.childLine('bundler', line, { stream: 'stderr', showInfo: true });
+            });
+        }
+
         child.on('error', (err) => {
             rejectPromise(new Error(`Bundler spawn failed: ${err.message}`));
         });
@@ -1325,15 +1435,17 @@ async function collectAssets(rootDir) {
  *      d. Merge component IRs into page IR
  *   3. Send all envelopes to bundler
  *
- * @param {{ pagesDir: string, outDir: string, config?: object }} options
+ * @param {{ pagesDir: string, outDir: string, config?: object, logger?: object | null, showBundlerInfo?: boolean }} options
  * @returns {Promise<{ pages: number, assets: string[] }>}
  */
 export async function build(options) {
-    const { pagesDir, outDir, config = {} } = options;
+    const { pagesDir, outDir, config = {}, logger = null, showBundlerInfo = true } = options;
+    const projectRoot = deriveProjectRootFromPagesDir(pagesDir);
     const softNavigationEnabled = config.softNavigation === true || config.router === true;
     const compilerOpts = {
         typescriptDefault: config.typescriptDefault === true,
-        experimentalEmbeddedMarkup: config.embeddedMarkupExpressions === true || config.experimental?.embeddedMarkupExpressions === true
+        experimentalEmbeddedMarkup: config.embeddedMarkupExpressions === true || config.experimental?.embeddedMarkupExpressions === true,
+        strictDomLints: config.strictDomLints === true
     };
 
     await rm(outDir, { recursive: true, force: true });
@@ -1345,7 +1457,13 @@ export async function build(options) {
     // 1. Build component registry
     const registry = buildComponentRegistry(srcDir);
     if (registry.size > 0) {
-        console.log(`[zenith] Component registry: ${registry.size} components`);
+        if (logger && typeof logger.build === 'function') {
+            logger.build(`registry=${registry.size} components`, {
+                onceKey: `component-registry:${registry.size}`
+            });
+        } else {
+            console.log(`[zenith] Component registry: ${registry.size} components`);
+        }
     }
 
     const manifest = await generateManifest(pagesDir);
@@ -1356,10 +1474,15 @@ export async function build(options) {
     const componentIrCache = new Map();
     /** @type {Map<string, boolean>} */
     const componentDocumentModeCache = new Map();
-    /** @type {Map<string, Array<{ identifier: string, selector: string }>>} */
-    const componentRefFallbackCache = new Map();
     /** @type {Map<string, { map: Map<string, string>, ambiguous: Set<string> }>} */
     const componentExpressionRewriteCache = new Map();
+    const emitCompilerWarning = createCompilerWarningEmitter((line) => {
+        if (logger && typeof logger.warn === 'function') {
+            logger.warn(line, { onceKey: `compiler-warning:${line}` });
+            return;
+        }
+        console.warn(line);
+    });
 
     const envelopes = [];
     for (const entry of manifest) {
@@ -1367,6 +1490,14 @@ export async function build(options) {
         const rawSource = readFileSync(sourceFile, 'utf8');
         const componentUsageAttrs = collectComponentUsageAttrs(rawSource, registry);
 
+        const baseName = sourceFile.slice(0, -extname(sourceFile).length);
+        let adjacentGuard = null;
+        let adjacentLoad = null;
+        for (const ext of ['.ts', '.js']) {
+            if (!adjacentGuard && existsSync(`${baseName}.guard${ext}`)) adjacentGuard = `${baseName}.guard${ext}`;
+            if (!adjacentLoad && existsSync(`${baseName}.load${ext}`)) adjacentLoad = `${baseName}.load${ext}`;
+        }
+
         // 2a. Expand PascalCase component tags
         const { expandedSource, usedComponents } = expandComponents(
             rawSource, registry, sourceFile
@@ -1375,7 +1506,16 @@ export async function build(options) {
         const compileSource = extractedServer.source;
 
         // 2b. Compile expanded page source via --stdin
-        const pageIr = runCompiler(sourceFile, compileSource, compilerOpts);
+        const pageIr = runCompiler(
+            sourceFile,
+            compileSource,
+            compilerOpts,
+            { onWarning: emitCompilerWarning }
+        );
+
+        const hasGuard = (extractedServer.serverScript && extractedServer.serverScript.has_guard) || adjacentGuard !== null;
+        const hasLoad = (extractedServer.serverScript && extractedServer.serverScript.has_load) || adjacentLoad !== null;
+
         if (extractedServer.serverScript) {
             pageIr.server_script = extractedServer.serverScript;
             pageIr.prerender = extractedServer.serverScript.prerender === true;
@@ -1384,6 +1524,20 @@ export async function build(options) {
             }
         }
 
+        // Static Build Route Protection Policy
+        if (pageIr.prerender === true && (hasGuard || hasLoad)) {
+            throw new Error(
+                `[zenith] Build failed for ${entry.file}: protected routes require SSR/runtime. ` +
+                `Cannot prerender a static route with a \`guard\` or \`load\` function.`
+            );
+        }
+
+        // Apply metadata to IR
+        pageIr.has_guard = hasGuard;
+        pageIr.has_load = hasLoad;
+        pageIr.guard_module_ref = adjacentGuard ? relative(srcDir, adjacentGuard).replaceAll('\\', '/') : null;
+        pageIr.load_module_ref = adjacentLoad ? relative(srcDir, adjacentLoad).replaceAll('\\', '/') : null;
+
         // Ensure IR has required array fields for merging
         pageIr.components_scripts = pageIr.components_scripts || {};
         pageIr.component_instances = pageIr.component_instances || [];
@@ -1397,6 +1551,7 @@ export async function build(options) {
         const seenStaticImports = new Set();
         const pageExpressionRewriteMap = new Map();
         const pageAmbiguousExpressionMap = new Set();
+        const knownRefKeys = new Set();
 
         // 2c. Compile each used component separately for its script IR
         for (const compName of usedComponents) {
@@ -1409,17 +1564,19 @@ export async function build(options) {
                 compIr = componentIrCache.get(compPath);
             } else {
                 const componentCompileSource = stripStyleBlocks(componentSource);
-                compIr = runCompiler(compPath, componentCompileSource, compilerOpts);
+                compIr = runCompiler(
+                    compPath,
+                    componentCompileSource,
+                    compilerOpts,
+                    { onWarning: emitCompilerWarning }
+                );
                 componentIrCache.set(compPath, compIr);
             }
 
             let isDocMode = componentDocumentModeCache.get(compPath);
-            let refFallbacks = componentRefFallbackCache.get(compPath);
             if (isDocMode === undefined) {
                 isDocMode = isDocumentMode(extractTemplate(componentSource));
-                refFallbacks = extractRefFallbackAssignments(componentSource);
                 componentDocumentModeCache.set(compPath, isDocMode);
-                componentRefFallbackCache.set(compPath, refFallbacks);
             }
 
             let expressionRewrite = componentExpressionRewriteCache.get(compPath);
@@ -1443,10 +1600,10 @@ export async function build(options) {
                     includeCode: true,
                     cssImportsOnly: isDocMode,
                     documentMode: isDocMode,
-                    componentAttrs: (componentUsageAttrs.get(compName) || [])[0] || '',
-                    refFallbacks: refFallbacks || []
+                    componentAttrs: (componentUsageAttrs.get(compName) || [])[0] || ''
                 },
-                seenStaticImports
+                seenStaticImports,
+                knownRefKeys
             );
         }
 
@@ -1457,6 +1614,7 @@ export async function build(options) {
         );
 
         rewriteLegacyMarkupIdentifiers(pageIr);
+        rewriteRefBindingIdentifiers(pageIr, knownRefKeys);
 
         envelopes.push({
             route: entry.path,
@@ -1467,7 +1625,7 @@ export async function build(options) {
     }
 
     if (envelopes.length > 0) {
-        await runBundler(envelopes, outDir);
+    await runBundler(envelopes, outDir, projectRoot, logger, showBundlerInfo);
     }
 
     const assets = await collectAssets(outDir);