@zenithbuild/cli 0.7.9 → 0.7.11

package/README.md

@@ -83,7 +83,8 @@ Current limitations:
 
 - There is no separate `assetPrefix` knob. Assets intentionally follow `basePath`.
 - `static-export` does not expose deployed `/_zenith/image` or `/__zenith/route-check` endpoints. A plain static file server is the contract.
-- `vercel` and `netlify` do not yet emit a deployed `/_zenith/image` endpoint. The `node` target does.
+- `node`, `vercel`, and `netlify` expose deployed `/_zenith/image` endpoints on the packaged image contract.
+- Hosted `vercel` and `netlify` targets skip advisory `/__zenith/route-check`; direct HTML requests remain the server-side route boundary.
 - Image materialization is route-artifact-driven. Bundler owns final build/static HTML image materialization, while preview and server render still materialize at runtime from structured `image_materialization` metadata. No path executes page assets, and dynamic image props are currently unsupported until the compiler emits a dedicated image-props artifact.
 - There is no shipped plugin install/remove command surface in this CLI.
 
@@ -92,6 +93,8 @@ Current limitations:
 ### `zenith dev`
 Starts the development server on `localhost:3000`.
 
+Changes to `zenith.config.js` or `zenith.config.ts` require restarting `zenith dev`. If the dev watcher observes a config-file edit, it reports the restart policy instead of rebuilding with stale config.
+
 ### `zenith build`
 Compiles and bundles your application for production.
 

package/dist/build/compiler-runtime.js

@@ -91,6 +91,9 @@ export function runCompiler(filePath, stdinSource, compilerOpts = {}, compilerRu
     if (compilerOpts?.strictDomLints) {
         args.push('--strict-dom-lints');
     }
+    if (compilerOpts?.internalAllowUnboundMarkup) {
+        args.push('--internal-allow-unbound-markup');
+    }
     const opts = {
         encoding: 'utf8',
         maxBuffer: COMPILER_SPAWN_MAX_BUFFER

package/dist/build/page-loop-state.d.ts

@@ -169,12 +169,9 @@ export function createPageLoopExecutionState(): {
     envelopes: never[];
 };
 export function preparePageIrForMerge(pageIr: any): void;
-export function applyServerEnvelopeToPageIr({ pageIr, composedServer, hasGuard, hasLoad, hasAction, entry, srcDir, sourceFile }: {
+export function applyServerEnvelopeToPageIr({ pageIr, composedServer, entry, srcDir, sourceFile }: {
     pageIr: any;
     composedServer: any;
-    hasGuard: any;
-    hasLoad: any;
-    hasAction: any;
     entry: any;
     srcDir: any;
     sourceFile: any;

package/dist/build/page-loop-state.js

@@ -1,4 +1,5 @@
 import { relative } from 'node:path';
+import { classifyPageRoute } from '../route-classification.js';
 import { createBindingResolutionTotals, createComponentLoopPhaseTotals, createMergePhaseTotals, createOccurrenceApplyPhaseTotals, createPagePhaseTotals, createScopedRewritePhaseTotals } from './page-loop-metrics.js';
 export function createPageLoopState() {
     return {
@@ -46,22 +47,22 @@ export function preparePageIrForMerge(pageIr) {
     pageIr.hoisted.state = pageIr.hoisted.state || [];
     pageIr.hoisted.code = pageIr.hoisted.code || [];
 }
-export function applyServerEnvelopeToPageIr({ pageIr, composedServer, hasGuard, hasLoad, hasAction, entry, srcDir, sourceFile }) {
+export function applyServerEnvelopeToPageIr({ pageIr, composedServer, entry, srcDir, sourceFile }) {
+    const classification = classifyPageRoute({
+        file: entry.file,
+        serverScript: composedServer.serverScript
+    });
     if (composedServer.serverScript) {
         const { has_action: _unusedHasAction, export_paths: _unusedExportPaths, ...serverScript } = composedServer.serverScript;
         pageIr.server_script = serverScript;
-        pageIr.prerender = composedServer.serverScript.prerender === true;
+        pageIr.prerender = classification.prerender;
         if (pageIr.ssr_data === undefined) {
             pageIr.ssr_data = null;
         }
     }
-    if (pageIr.prerender === true && (hasGuard || hasLoad || hasAction)) {
-        throw new Error(`[zenith] Build failed for ${entry.file}: protected routes require SSR/runtime. ` +
-            'Cannot prerender a static route with a `guard`, `load`, or `action` function.');
-    }
-    pageIr.has_guard = hasGuard;
-    pageIr.has_load = hasLoad;
-    pageIr.has_action = hasAction;
+    pageIr.has_guard = classification.hasGuard;
+    pageIr.has_load = classification.hasLoad;
+    pageIr.has_action = classification.hasAction;
     pageIr.guard_module_ref = composedServer.guardPath ? relative(srcDir, composedServer.guardPath).replaceAll('\\', '/') : null;
     pageIr.load_module_ref = composedServer.loadPath ? relative(srcDir, composedServer.loadPath).replaceAll('\\', '/') : null;
     pageIr.action_module_ref = composedServer.actionPath ? relative(srcDir, composedServer.actionPath).replaceAll('\\', '/') : null;

package/dist/build/page-loop.js

@@ -56,13 +56,20 @@ export async function buildPageEnvelopes(input) {
         const expandedStartedAt = performance.now();
         const { expandedSource } = expandComponents(rawSource, registry, sourceFile);
         pageExpandMs = startupProfile.roundMs(performance.now() - expandedStartedAt);
+        const usesInternalExpandedSource = expandedSource !== rawSource;
+        if (usesInternalExpandedSource) {
+            const rawServerExtracted = extractServerScript(rawSource, sourceFile, compilerOpts);
+            timedRunCompiler('page', sourceFile, rawServerExtracted.source, compilerOpts, { compilerToolchain: compilerBin, onWarning: emitCompilerWarning });
+        }
         const expandedServerExtractStartedAt = performance.now();
         const extractedServer = extractServerScript(expandedSource, sourceFile, compilerOpts);
         pagePhase.serverExtractMs += startupProfile.roundMs(performance.now() - expandedServerExtractStartedAt);
         const compileSource = extractedServer.source;
         await cooperativeYield();
         const pageCompileStartedAt = performance.now();
-        let pageIr = timedRunCompiler('page', sourceFile, compileSource, compilerOpts, { compilerToolchain: compilerBin, onWarning: emitCompilerWarning });
+        let pageIr = timedRunCompiler('page', sourceFile, compileSource, usesInternalExpandedSource
+            ? { ...compilerOpts, internalAllowUnboundMarkup: true }
+            : compilerOpts, { compilerToolchain: compilerBin, onWarning: emitCompilerWarning });
         pageCompileMs = startupProfile.roundMs(performance.now() - pageCompileStartedAt);
         const composedServer = composeServerScriptEnvelope({
             sourceFile,
@@ -71,15 +78,9 @@ export async function buildPageEnvelopes(input) {
             adjacentLoadPath: adjacentLoad,
             adjacentActionPath: adjacentAction
         });
-        const hasGuard = composedServer.serverScript?.has_guard === true;
-        const hasLoad = composedServer.serverScript?.has_load === true;
-        const hasAction = composedServer.serverScript?.has_action === true;
         applyServerEnvelopeToPageIr({
             pageIr,
             composedServer,
-            hasGuard,
-            hasLoad,
-            hasAction,
             entry,
             srcDir,
             sourceFile

package/dist/build/server-script.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { findNextKnownComponentTag } from '../component-tag-parser.js';
+import { readRouteHandlerExport } from '../route-handler-export-analysis.js';
 import { extractStaticExportPaths } from '../static-export-paths.js';
 /**
  * @param {string} source
@@ -56,40 +57,25 @@ export function extractServerScript(source, sourceFile, compilerOpts = {}) {
             `  Reason: <script server> block is empty\n` +
             `  Example: export const data = { ... }`);
     }
-    const loadFnMatch = serverSource.match(/\bexport\s+(?:async\s+)?function\s+load\s*\(([^)]*)\)/);
-    const loadConstParenMatch = serverSource.match(/\bexport\s+const\s+load\s*=\s*(?:async\s*)?\(([^)]*)\)\s*=>/);
-    const loadConstSingleArgMatch = serverSource.match(/\bexport\s+const\s+load\s*=\s*(?:async\s*)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/);
-    const hasLoad = Boolean(loadFnMatch || loadConstParenMatch || loadConstSingleArgMatch);
-    const loadMatchCount = Number(Boolean(loadFnMatch)) +
-        Number(Boolean(loadConstParenMatch)) +
-        Number(Boolean(loadConstSingleArgMatch));
-    if (loadMatchCount > 1) {
+    const loadExport = readRouteHandlerExport(serverSource, 'load');
+    const hasLoad = loadExport.hasExport;
+    if (loadExport.matchCount > 1) {
         throw new Error(`Zenith server script contract violation:\n` +
             `  File: ${sourceFile}\n` +
             `  Reason: multiple load exports detected\n` +
             `  Example: keep exactly one export const load = async (ctx) => ({ ... })`);
     }
-    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) {
+    const guardExport = readRouteHandlerExport(serverSource, 'guard');
+    const hasGuard = guardExport.hasExport;
+    if (guardExport.matchCount > 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 actionFnMatch = serverSource.match(/\bexport\s+(?:async\s+)?function\s+action\s*\(([^)]*)\)/);
-    const actionConstParenMatch = serverSource.match(/\bexport\s+const\s+action\s*=\s*(?:async\s*)?\(([^)]*)\)\s*=>/);
-    const actionConstSingleArgMatch = serverSource.match(/\bexport\s+const\s+action\s*=\s*(?:async\s*)?([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/);
-    const hasAction = Boolean(actionFnMatch || actionConstParenMatch || actionConstSingleArgMatch);
-    const actionMatchCount = Number(Boolean(actionFnMatch)) +
-        Number(Boolean(actionConstParenMatch)) +
-        Number(Boolean(actionConstSingleArgMatch));
-    if (actionMatchCount > 1) {
+    const actionExport = readRouteHandlerExport(serverSource, 'action');
+    const hasAction = actionExport.hasExport;
+    if (actionExport.matchCount > 1) {
         throw new Error(`Zenith server script contract violation:\n` +
             `  File: ${sourceFile}\n` +
             `  Reason: multiple action exports detected\n` +
@@ -112,10 +98,7 @@ export function extractServerScript(source, sourceFile, compilerOpts = {}) {
             `  Example: use only export const data or export const load`);
     }
     if (hasLoad) {
-        const singleArg = String(loadConstSingleArgMatch?.[1] || '').trim();
-        const paramsText = String((loadFnMatch || loadConstParenMatch)?.[1] || '').trim();
-        const arity = singleArg ? 1 : paramsText.length === 0 ? 0 : paramsText.split(',').length;
-        if (arity !== 1) {
+        if (loadExport.arity !== null && loadExport.arity !== 1) {
             throw new Error(`Zenith server script contract violation:\n` +
                 `  File: ${sourceFile}\n` +
                 `  Reason: load(ctx) must accept exactly one argument\n` +
@@ -123,10 +106,7 @@ export 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) {
+        if (guardExport.arity !== null && guardExport.arity !== 1) {
             throw new Error(`Zenith server script contract violation:\n` +
                 `  File: ${sourceFile}\n` +
                 `  Reason: guard(ctx) must accept exactly one argument\n` +
@@ -134,10 +114,7 @@ export function extractServerScript(source, sourceFile, compilerOpts = {}) {
         }
     }
     if (hasAction) {
-        const singleArg = String(actionConstSingleArgMatch?.[1] || '').trim();
-        const paramsText = String((actionFnMatch || actionConstParenMatch)?.[1] || '').trim();
-        const arity = singleArg ? 1 : paramsText.length === 0 ? 0 : paramsText.split(',').length;
-        if (arity !== 1) {
+        if (actionExport.arity !== null && actionExport.arity !== 1) {
             throw new Error(`Zenith server script contract violation:\n` +
                 `  File: ${sourceFile}\n` +
                 `  Reason: action(ctx) must accept exactly one argument\n` +

package/dist/build/type-declarations.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
+import { renderZenithEnvDts } from '../types/zenith-env-dts.js';
 /**
  * @param {string} targetPath
  * @param {string} next
@@ -60,60 +61,6 @@ function renderZenithRouteDts(manifest) {
     lines.push('');
     return `${lines.join('\n')}\n`;
 }
-/**
- * @returns {string}
- */
-function renderZenithEnvDts() {
-    return [
-        '// Auto-generated by Zenith CLI. Do not edit manually.',
-        'export {};',
-        '',
-        'declare global {',
-        '  namespace Zenith {',
-        '    type Params = Record<string, string>;',
-        '',
-        '    interface ErrorState {',
-        '      status?: number;',
-        '      code?: string;',
-        '      message: string;',
-        '    }',
-        '',
-        '    type PageData = Record<string, unknown> & { __zenith_error?: ErrorState };',
-        '',
-        '    interface RouteMeta {',
-        '      id: string;',
-        '      file: string;',
-        '      pattern: string;',
-        '    }',
-        '',
-        '    interface LoadContext {',
-        '      params: Params;',
-        '      url: URL;',
-        '      request: Request;',
-        '      route: RouteMeta;',
-        '    }',
-        '',
-        '    type Load<T extends PageData = PageData> = (ctx: LoadContext) => Promise<T> | T;',
-        '',
-        '    interface Fragment {',
-        '      __zenith_fragment: true;',
-        '      mount: (anchor: Node | null) => void;',
-        '      unmount: () => void;',
-        '    }',
-        '',
-        '    type Renderable =',
-        '      | string',
-        '      | number',
-        '      | boolean',
-        '      | null',
-        '      | undefined',
-        '      | Renderable[]',
-        '      | Fragment;',
-        '  }',
-        '}',
-        ''
-    ].join('\n');
-}
 /**
  * @param {string} pagesDir
  * @returns {string}

package/dist/dev-build-session/helpers.js

@@ -143,18 +143,38 @@ function collectTemplateClassSignature(envelope) {
     return [...classes].sort();
 }
 export function buildPageOnlyFastPathSignature(envelope) {
+    const ir = envelope.ir || {};
     return stableJson({
         route: envelope.route,
         router: envelope.router === true,
+        interactivityShape: {
+            requiresJs: envelope.requires_js === true,
+            signals: Array.isArray(ir.signals) ? ir.signals.length : 0,
+            refs: Array.isArray(ir.ref_bindings) ? ir.ref_bindings.length : 0,
+            events: Array.isArray(ir.event_bindings)
+                ? ir.event_bindings.map((entry) => [entry.index, entry.event]).sort()
+                : [],
+            markers: Array.isArray(ir.marker_bindings)
+                ? ir.marker_bindings.map((entry) => [entry.index, entry.kind]).sort()
+                : [],
+            componentInstances: Array.isArray(ir.component_instances) ? ir.component_instances.length : 0,
+            hoistedCode: Array.isArray(ir.hoisted?.code)
+                ? ir.hoisted.code.filter((entry) => String(entry || '').trim().length > 0).length
+                : 0,
+            hoistedState: Array.isArray(ir.hoisted?.state) ? ir.hoisted.state.length : 0,
+            hoistedSignals: Array.isArray(ir.hoisted?.signals) ? ir.hoisted.signals.length : 0
+        },
         assetContract: collectEnvelopeAssetContract(envelope),
         templateClassSignature: collectTemplateClassSignature(envelope),
-        styleBlocks: envelope.ir.style_blocks || [],
-        serverScript: envelope.ir.server_script || null,
-        prerender: envelope.ir.prerender === true,
-        hasGuard: envelope.ir.has_guard === true,
-        hasLoad: envelope.ir.has_load === true,
-        guardModuleRef: envelope.ir.guard_module_ref || null,
-        loadModuleRef: envelope.ir.load_module_ref || null
+        styleBlocks: ir.style_blocks || [],
+        serverScript: ir.server_script || null,
+        prerender: ir.prerender === true,
+        hasGuard: ir.has_guard === true,
+        hasLoad: ir.has_load === true,
+        hasAction: ir.has_action === true,
+        guardModuleRef: ir.guard_module_ref || null,
+        loadModuleRef: ir.load_module_ref || null,
+        actionModuleRef: ir.action_module_ref || null
     });
 }
 export function buildGlobalGraphHash(envelopes) {

package/dist/dev-build-session/session.js

@@ -5,10 +5,12 @@ import { collectAssets, runBundler } from '../build/compiler-runtime.js';
 import { buildPageEnvelopes } from '../build/page-loop.js';
 import { createPageLoopCaches } from '../build/page-loop-state.js';
 import { deriveProjectRootFromPagesDir, ensureZenithTypeDeclarations } from '../build/type-declarations.js';
+import { rewriteSoftNavigationHrefBasePathInHtmlFiles } from '../base-path-html.js';
 import { injectImageMaterializationIntoRouterManifest } from '../images/router-manifest.js';
 import { buildImageArtifacts } from '../images/service.js';
 import { materializeImageMarkupInHtmlFiles } from '../images/materialize.js';
 import { createImageRuntimePayload, injectImageRuntimePayloadIntoHtmlFiles } from '../images/payload.js';
+import { writeResourceRouteManifest } from '../resource-manifest.js';
 import { createStartupProfiler } from '../startup-profile.js';
 import { resolveBuildAdapter } from '../adapters/resolve-adapter.js';
 import { supportsTargetRouteCheck } from '../route-check-support.js';
@@ -34,6 +36,9 @@ export function createDevBuildSession(options) {
     };
     ensureToolchainCompatibility(bundlerBin);
     const state = createDevBuildState(config, basePath);
+    function pageManifestEntries() {
+        return state.manifest.filter((entry) => entry?.route_kind !== 'resource');
+    }
     async function syncImageState(startupProfile) {
         const { manifest } = await startupProfile.measureAsync('build_image_artifacts', () => buildImageArtifacts({
             projectRoot,
@@ -50,12 +55,13 @@ export function createDevBuildSession(options) {
     }
     async function runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo, bundlerOptions = {}) {
         const orderedEnvelopes = bundlerOptions.envelopesOverride
-            || orderEnvelopes(state.manifest, resolvedPagesDir, state.envelopeByFile);
+            || orderEnvelopes(pageManifestEntries(), resolvedPagesDir, state.envelopeByFile);
         if (!orderedEnvelopes || orderedEnvelopes.length === 0) {
             throw new Error('Dev rebuild cache is incomplete; full rebuild required.');
         }
         await startupProfile.measureAsync('run_bundler', () => runBundler(orderedEnvelopes, outDir, projectRoot, activeLogger, showBundlerInfo, bundlerBin, {
             routeCheck: routeCheckEnabled,
+            basePath,
             devStableAssets: true,
             rebuildStrategy: bundlerOptions.rebuildStrategy || 'full',
             changedRoutes: bundlerOptions.changedRoutes || [],
@@ -63,6 +69,7 @@ export function createDevBuildSession(options) {
             globalGraphHash: bundlerOptions.globalGraphHash || ''
         }), { envelopes: orderedEnvelopes.length });
         await startupProfile.measureAsync('inject_image_materialization_manifest', () => injectImageMaterializationIntoRouterManifest(outDir, orderedEnvelopes), { envelopes: orderedEnvelopes.length });
+        await startupProfile.measureAsync('rewrite_soft_navigation_base_path', () => rewriteSoftNavigationHrefBasePathInHtmlFiles(outDir, basePath));
         const assets = await startupProfile.measureAsync('collect_assets', () => collectAssets(outDir));
         return { assets, envelopeCount: orderedEnvelopes.length };
     }
@@ -78,14 +85,15 @@ export function createDevBuildSession(options) {
         });
         state.registry = startupProfile.measureSync('build_component_registry', () => buildComponentRegistry(srcDir));
         state.manifest = await startupProfile.measureAsync('generate_manifest', () => generateManifest(resolvedPagesDir));
+        const pageManifest = pageManifestEntries();
         await startupProfile.measureAsync('ensure_zenith_type_declarations', () => ensureZenithTypeDeclarations({
-            manifest: state.manifest,
+            manifest: pageManifest,
             pagesDir: resolvedPagesDir
         }));
         state.pageLoopCaches = createPageLoopCaches();
         const emitCompilerWarning = buildCompilerWarningEmitter(activeLogger);
         const { envelopes, expressionRewriteMetrics } = await buildPageEnvelopes({
-            manifest: state.manifest,
+            manifest: pageManifest,
             pagesDir: resolvedPagesDir,
             srcDir,
             registry: state.registry,
@@ -98,20 +106,21 @@ export function createDevBuildSession(options) {
             pageLoopCaches: state.pageLoopCaches
         });
         state.envelopeByFile = new Map(envelopes.map((entry) => [entry.file, entry]));
-        state.manifestEntryByPath = toManifestEntryMap(state.manifest, resolvedPagesDir);
+        state.manifestEntryByPath = toManifestEntryMap(pageManifest, resolvedPagesDir);
         state.pageOnlyFastPathSignatureByFile = new Map(envelopes.map((entry) => [entry.file, buildPageOnlyFastPathSignature(entry)]));
         state.globalGraphHash = buildGlobalGraphHash(envelopes);
         const { assets } = await runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo);
+        await startupProfile.measureAsync('write_resource_manifest', () => writeResourceRouteManifest(outDir, state.manifest, basePath));
         await syncImageState(startupProfile);
         startupProfile.emit('build_complete', {
-            pages: state.manifest.length,
+            pages: pageManifest.length,
             assets: assets.length,
             compilerTotals,
             expressionRewriteMetrics,
             strategy: 'full'
         });
         state.hasSuccessfulBuild = true;
-        return { pages: state.manifest.length, assets, strategy: 'full' };
+        return { pages: pageManifest.length, assets, strategy: 'full' };
     }
     async function runBundleOnlyBuild(activeLogger, showBundlerInfo) {
         const startupProfile = createStartupProfiler('cli-build');
@@ -120,7 +129,7 @@ export function createDevBuildSession(options) {
         const { assets } = await runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo, { rebuildStrategy: 'bundle-only' });
         await syncImageState(startupProfile);
         startupProfile.emit('build_complete', {
-            pages: state.manifest.length,
+            pages: pageManifestEntries().length,
             assets: assets.length,
             compilerTotals,
             expressionRewriteMetrics,
@@ -155,7 +164,7 @@ export function createDevBuildSession(options) {
             state.envelopeByFile.set(envelope.file, envelope);
             state.pageOnlyFastPathSignatureByFile.set(envelope.file, buildPageOnlyFastPathSignature(envelope));
         }
-        const orderedEnvelopes = orderEnvelopes(state.manifest, resolvedPagesDir, state.envelopeByFile);
+        const orderedEnvelopes = orderEnvelopes(pageManifestEntries(), resolvedPagesDir, state.envelopeByFile);
         if (!orderedEnvelopes || orderedEnvelopes.length === 0) {
             throw new Error('Dev rebuild cache is incomplete; full rebuild required.');
         }
@@ -169,14 +178,14 @@ export function createDevBuildSession(options) {
         });
         await syncImageState(startupProfile);
         startupProfile.emit('build_complete', {
-            pages: state.manifest.length,
+            pages: pageManifestEntries().length,
             assets: assets.length,
             compilerTotals,
             expressionRewriteMetrics,
             strategy: 'page-only',
             rebuiltPages: entries.length
         });
-        return { pages: state.manifest.length, assets, strategy: 'page-only', rebuiltPages: entries.length };
+        return { pages: pageManifestEntries().length, assets, strategy: 'page-only', rebuiltPages: entries.length };
     }
     return {
         async build(buildOptions = {}) {

package/dist/dev-server/build-error-response.d.ts

@@ -0,0 +1,21 @@
+export function buildDevErrorPayload({ pathname, state }: {
+    pathname: any;
+    state: any;
+}): {
+    kind: string;
+    requestedPath: any;
+    buildId: any;
+    pendingBuildId: any;
+    buildStatus: any;
+    error: {
+        message: string;
+    };
+    hint: string;
+};
+export function respondWithDevBuildError({ req, res, pathname, state, looksLikeJsonRequest }: {
+    req: any;
+    res: any;
+    pathname: any;
+    state: any;
+    looksLikeJsonRequest: any;
+}): void;

package/dist/dev-server/build-error-response.js

@@ -0,0 +1,48 @@
+function truncateMessage(message, limit = 1000) {
+    const value = String(message || 'Dev build failed.');
+    return value.length > limit ? `${value.slice(0, limit - 3)}...` : value;
+}
+function escapeHtml(value) {
+    return String(value)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+export function buildDevErrorPayload({ pathname, state }) {
+    const message = truncateMessage(state.buildError?.message || 'Dev build failed.');
+    return {
+        kind: 'zenith_dev_build_failed',
+        requestedPath: pathname,
+        buildId: state.buildId,
+        pendingBuildId: state.pendingBuildId,
+        buildStatus: state.buildStatus,
+        error: { message },
+        hint: 'Fix the build error and save again.'
+    };
+}
+export function respondWithDevBuildError({ req, res, pathname, state, looksLikeJsonRequest }) {
+    const payload = buildDevErrorPayload({ pathname, state });
+    if (looksLikeJsonRequest(req, pathname)) {
+        res.writeHead(503, {
+            'Content-Type': 'application/json',
+            'Cache-Control': 'no-store',
+            'X-Zenith-Dev-Error': 'build-failed'
+        });
+        res.end(JSON.stringify(payload));
+        return;
+    }
+    res.writeHead(503, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Cache-Control': 'no-store',
+        'X-Zenith-Dev-Error': 'build-failed'
+    });
+    res.end([
+        '<!DOCTYPE html>',
+        '<html><head><meta charset="utf-8"><title>Zenith Dev Build Failed</title></head>',
+        '<body style="font-family: ui-monospace, SFMono-Regular, Menlo, monospace; padding: 20px; background: #101216; color: #e6edf3;">',
+        '<h1 style="margin-top:0;">Zenith Dev Build Failed</h1>',
+        `<pre style="white-space: pre-wrap; line-height: 1.5;">Requested: ${escapeHtml(pathname)}\nStatus: build failed\nError: ${escapeHtml(payload.error.message)}\nHint: ${escapeHtml(payload.hint)}</pre>`,
+        '</body></html>'
+    ].join(''));
+}

package/dist/dev-server/port-fallback.d.ts

@@ -0,0 +1,15 @@
+export function isPortConflict(error: any): any;
+export function listenWithPortFallback({ server, port, host, maxAttempts }: {
+    server: any;
+    port: any;
+    host: any;
+    maxAttempts?: number | undefined;
+}): Promise<{
+    port: any;
+    requestedPort: any;
+    portFallback: {
+        requestedPort: any;
+        occupiedPorts: any[];
+        finalPort: any;
+    } | null;
+}>;

package/dist/dev-server/port-fallback.js

@@ -0,0 +1,61 @@
+const MAX_PORT = 65535;
+const DEFAULT_MAX_ATTEMPTS = 20;
+export function isPortConflict(error) {
+    return error && error.code === 'EADDRINUSE';
+}
+function normalizeRequestedPort(port) {
+    return Number.isInteger(port) && port >= 0 ? port : 3000;
+}
+function waitForListen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            server.off('error', onError);
+            server.off('listening', onListening);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onListening = () => {
+            cleanup();
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, host);
+    });
+}
+export async function listenWithPortFallback({ server, port, host, maxAttempts = DEFAULT_MAX_ATTEMPTS }) {
+    const requestedPort = normalizeRequestedPort(port);
+    let candidatePort = requestedPort;
+    const occupiedPorts = [];
+    for (let attempt = 0; attempt <= maxAttempts; attempt += 1) {
+        try {
+            await waitForListen(server, candidatePort, host);
+            const address = server.address();
+            const actualPort = address && typeof address === 'object' ? address.port : candidatePort;
+            return {
+                port: actualPort,
+                requestedPort,
+                portFallback: occupiedPorts.length > 0
+                    ? {
+                        requestedPort,
+                        occupiedPorts: occupiedPorts.slice(),
+                        finalPort: actualPort
+                    }
+                    : null
+            };
+        }
+        catch (error) {
+            if (requestedPort === 0 ||
+                !isPortConflict(error) ||
+                candidatePort >= MAX_PORT ||
+                attempt >= maxAttempts) {
+                throw error;
+            }
+            occupiedPorts.push(candidatePort);
+            candidatePort += 1;
+        }
+    }
+    throw new Error(`Unable to bind dev server after ${maxAttempts + 1} attempts`);
+}

package/dist/dev-server/request-handler.js

@@ -9,6 +9,7 @@ import { materializeImageMarkup } from '../images/materialize.js';
 import { injectImageRuntimePayload } from '../images/payload.js';
 import { handleImageRequest } from '../images/service.js';
 import { resolveRequestRoute } from '../server/resolve-request-route.js';
+import { respondWithDevBuildError } from './build-error-response.js';
 import { handleRouteCheckRequest } from './route-check.js';
 export function createDevRequestHandler(options) {
     const { outDir, projectRoot, imageConfig, configuredBasePath, routeCheckEnabled, isStaticExportTarget, logger, verboseLogging, buildSession, state, serverOrigin, loadRoutesForRequests, readFileForRequest, trace404, looksLikeJsonRequest, classifyNotFound, infer404Cause, buildNotFoundPayload, renderNotFoundHtml, appendSetCookieHeaders, MIME_TYPES, EVENT_STREAM_MIME, LEGACY_DEV_STREAM_PATH, IMAGE_RUNTIME_TAG_RE } = options;
@@ -230,6 +231,16 @@ export function createDevRequestHandler(options) {
                 res.end(descriptor.body);
                 return;
             }
+            if (state.buildStatus === 'error' && (!requestExt || requestExt === '.html')) {
+                respondWithDevBuildError({
+                    req,
+                    res,
+                    pathname,
+                    state,
+                    looksLikeJsonRequest
+                });
+                return;
+            }
             const resolved = resolveRequestRoute(canonicalUrl, routes.pageRoutes || []);
             let filePath = null;
             if (isStaticExportTarget) {
@@ -245,7 +256,7 @@ export function createDevRequestHandler(options) {
                 filePath = resolveWithinDist(outDir, output);
             }
             else {
-                filePath = toStaticFilePath(outDir, canonicalPath);
+                filePath = null;
             }
             resolvedPathFor404 = filePath;
             staticRootFor404 = outDir;