@zenithbuild/cli 0.7.4 → 0.7.7

package/dist/dev-build-session.js

@@ -1,434 +1 @@
-import { existsSync } from 'node:fs';
-import { createHash } from 'node:crypto';
-import { resolve } from 'node:path';
-import { buildComponentRegistry } from './resolve-components.js';
-import { normalizeBasePath } from './base-path.js';
-import { collectAssets, createCompilerWarningEmitter, 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 { 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 { createStartupProfiler } from './startup-profile.js';
-import { resolveBundlerBin } from './toolchain-paths.js';
-import { resolveBuildAdapter } from './adapters/resolve-adapter.js';
-import { supportsTargetRouteCheck } from './route-check-support.js';
-import { createBundlerToolchain, createCompilerToolchain, ensureToolchainCompatibility, getActiveToolchainCandidate } from './toolchain-runner.js';
-import { maybeWarnAboutZenithVersionMismatch } from './version-check.js';
-import { generateManifest } from './manifest.js';
-function createCompilerTotals() {
-    return {
-        pageMs: 0,
-        ownerMs: 0,
-        componentMs: 0,
-        pageCalls: 0,
-        ownerCalls: 0,
-        componentCalls: 0,
-        componentCacheHits: 0,
-        componentCacheMisses: 0
-    };
-}
-function createExpressionRewriteMetrics() {
-    return {
-        calls: 0,
-        compilerOwnedBindings: 0,
-        ambiguousBindings: 0
-    };
-}
-function toManifestEntryMap(manifest, pagesDir) {
-    const map = new Map();
-    for (const entry of manifest) {
-        map.set(resolve(pagesDir, entry.file), entry);
-    }
-    return map;
-}
-function orderEnvelopes(manifest, pagesDir, envelopeByFile) {
-    const ordered = [];
-    for (const entry of manifest) {
-        const envelope = envelopeByFile.get(resolve(pagesDir, entry.file));
-        if (!envelope) {
-            return null;
-        }
-        ordered.push(envelope);
-    }
-    return ordered;
-}
-function isCssOnlyChange(changedFiles) {
-    return changedFiles.length > 0 && changedFiles.every((filePath) => filePath.endsWith('.css'));
-}
-function stableJson(value) {
-    if (value === null || value === undefined) {
-        return 'null';
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map((entry) => stableJson(entry)).join(',')}]`;
-    }
-    if (typeof value === 'object') {
-        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
-    }
-    return JSON.stringify(value);
-}
-function collectJsImportSpecifiers(source) {
-    const values = [];
-    const patterns = [
-        /\bimport\s+(?:[^'"\n;]*?\s+from\s+)?['"]([^'"]+)['"]/g,
-        /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
-        /\bexport\s+[^'"\n;]*?\s+from\s+['"]([^'"]+)['"]/g
-    ];
-    for (const pattern of patterns) {
-        pattern.lastIndex = 0;
-        for (const match of source.matchAll(pattern)) {
-            const value = String(match[1] || '').trim();
-            if (value.length > 0 && !values.includes(value)) {
-                values.push(value);
-            }
-        }
-    }
-    return values.sort();
-}
-function isExternalRuntimeSpecifier(specifier) {
-    return !specifier.startsWith('.')
-        && !specifier.startsWith('/')
-        && !specifier.startsWith('@/')
-        && !specifier.startsWith('\0zenith:')
-        && !specifier.includes('zenith:');
-}
-function collectEnvelopeAssetContract(envelope) {
-    const cssImportSpecifiers = new Set();
-    const externalImportSpecifiers = new Set();
-    for (const entry of envelope.ir.hoisted?.imports || []) {
-        for (const specifier of collectJsImportSpecifiers(String(entry || ''))) {
-            if (specifier.endsWith('.css')) {
-                cssImportSpecifiers.add(specifier);
-            }
-            if (isExternalRuntimeSpecifier(specifier)) {
-                externalImportSpecifiers.add(specifier);
-            }
-        }
-    }
-    for (const moduleEntry of envelope.ir.modules || []) {
-        for (const specifier of collectJsImportSpecifiers(String(moduleEntry?.source || ''))) {
-            if (specifier.endsWith('.css')) {
-                cssImportSpecifiers.add(specifier);
-            }
-            if (isExternalRuntimeSpecifier(specifier)) {
-                externalImportSpecifiers.add(specifier);
-            }
-        }
-    }
-    for (const importEntry of envelope.ir.imports || []) {
-        const specifier = String(importEntry?.spec || '').trim();
-        if (!specifier) {
-            continue;
-        }
-        if (specifier.endsWith('.css')) {
-            cssImportSpecifiers.add(specifier);
-        }
-        if (isExternalRuntimeSpecifier(specifier)) {
-            externalImportSpecifiers.add(specifier);
-        }
-    }
-    return {
-        componentHoistIds: Object.keys(envelope.ir.components_scripts || {}).sort(),
-        cssImportSpecifiers: [...cssImportSpecifiers].sort(),
-        externalImportSpecifiers: [...externalImportSpecifiers].sort()
-    };
-}
-function collectTemplateClassSignature(envelope) {
-    const html = typeof envelope?.ir?.html === 'string' ? envelope.ir.html : '';
-    if (!html) {
-        return [];
-    }
-    const classes = new Set();
-    const classAttrRe = /\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
-    let match;
-    while ((match = classAttrRe.exec(html)) !== null) {
-        const rawValue = String(match[1] || match[2] || '');
-        for (const token of rawValue.split(/\s+/)) {
-            const value = token.trim();
-            if (value.length > 0) {
-                classes.add(value);
-            }
-        }
-    }
-    return [...classes].sort();
-}
-function buildPageOnlyFastPathSignature(envelope) {
-    return stableJson({
-        route: envelope.route,
-        router: envelope.router === true,
-        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
-    });
-}
-function buildGlobalGraphHash(envelopes) {
-    const nodesByHoistId = new Map();
-    const edgeSet = new Set();
-    for (const envelope of envelopes) {
-        for (const node of envelope.ir.graph_nodes || []) {
-            if (node && typeof node.hoist_id === 'string' && node.hoist_id.length > 0) {
-                nodesByHoistId.set(node.hoist_id, true);
-            }
-        }
-        for (const edge of envelope.ir.graph_edges || []) {
-            if (typeof edge === 'string' && edge.length > 0) {
-                edgeSet.add(edge);
-            }
-        }
-    }
-    let seed = '';
-    for (const hoistId of [...nodesByHoistId.keys()].sort()) {
-        seed += `node:${hoistId}\n`;
-    }
-    for (const edge of [...edgeSet].sort()) {
-        seed += `edge:${edge}\n`;
-    }
-    return createHash('sha256').update(seed).digest('hex');
-}
-function selectPageOnlyEntries(changedFiles, pagesDir, manifestEntryByPath) {
-    if (changedFiles.length === 0) {
-        return [];
-    }
-    const selected = new Map();
-    for (const filePath of changedFiles) {
-        const resolvedPath = resolve(filePath);
-        if (!resolvedPath.startsWith(pagesDir) || !resolvedPath.endsWith('.zen') || !existsSync(resolvedPath)) {
-            return [];
-        }
-        const entry = manifestEntryByPath.get(resolvedPath);
-        if (!entry) {
-            return [];
-        }
-        selected.set(entry.file, entry);
-    }
-    return [...selected.values()];
-}
-async function maybeRunVersionCheck({ state, startupProfile, projectRoot, logger, bundlerBin }) {
-    if (state.versionChecked) {
-        return;
-    }
-    const resolvedBundlerCandidate = getActiveToolchainCandidate(bundlerBin);
-    await startupProfile.measureAsync('version_mismatch_check', () => maybeWarnAboutZenithVersionMismatch({
-        projectRoot,
-        logger,
-        command: 'dev',
-        bundlerBinPath: resolvedBundlerCandidate?.path || resolveBundlerBin(projectRoot)
-    }));
-    state.versionChecked = true;
-}
-function buildCompilerWarningEmitter(logger) {
-    return createCompilerWarningEmitter((line) => {
-        if (logger && typeof logger.warn === 'function') {
-            logger.warn(line, { onceKey: `compiler-warning:${line}` });
-            return;
-        }
-        console.warn(line);
-    });
-}
-export function createDevBuildSession(options) {
-    const { pagesDir, outDir, config = {}, logger = null } = options;
-    const resolvedPagesDir = resolve(pagesDir);
-    const projectRoot = deriveProjectRootFromPagesDir(resolvedPagesDir);
-    const srcDir = resolve(resolvedPagesDir, '..');
-    const compilerBin = createCompilerToolchain({ projectRoot, logger });
-    const bundlerBin = createBundlerToolchain({ projectRoot, logger });
-    const routerEnabled = config.router === true;
-    const { target } = resolveBuildAdapter(config);
-    const basePath = normalizeBasePath(config.basePath || '/');
-    const routeCheckEnabled = supportsTargetRouteCheck(target);
-    const compilerOpts = {
-        typescriptDefault: config.typescriptDefault === true,
-        experimentalEmbeddedMarkup: config.embeddedMarkupExpressions === true,
-        strictDomLints: config.strictDomLints === true
-    };
-    ensureToolchainCompatibility(bundlerBin);
-    const state = {
-        versionChecked: false,
-        registry: new Map(),
-        manifest: [],
-        manifestEntryByPath: new Map(),
-        envelopeByFile: new Map(),
-        pageOnlyFastPathSignatureByFile: new Map(),
-        globalGraphHash: '',
-        pageLoopCaches: createPageLoopCaches(),
-        hasSuccessfulBuild: false,
-        imageManifest: {},
-        imageRuntimePayload: createImageRuntimePayload(config.images, {}, 'passthrough', basePath)
-    };
-    async function syncImageState(startupProfile) {
-        const { manifest } = await startupProfile.measureAsync('build_image_artifacts', () => buildImageArtifacts({
-            projectRoot,
-            outDir,
-            config: config.images
-        }));
-        state.imageManifest = manifest;
-        state.imageRuntimePayload = createImageRuntimePayload(config.images, manifest, 'passthrough', basePath);
-        await startupProfile.measureAsync('materialize_image_markup', () => materializeImageMarkupInHtmlFiles({
-            distDir: outDir,
-            payload: state.imageRuntimePayload
-        }));
-        await startupProfile.measureAsync('inject_image_runtime_payload', () => injectImageRuntimePayloadIntoHtmlFiles(outDir, state.imageRuntimePayload));
-    }
-    async function runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo, bundlerOptions = {}) {
-        const orderedEnvelopes = bundlerOptions.envelopesOverride
-            || orderEnvelopes(state.manifest, 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,
-            devStableAssets: true,
-            rebuildStrategy: bundlerOptions.rebuildStrategy || 'full',
-            changedRoutes: bundlerOptions.changedRoutes || [],
-            fastPath: bundlerOptions.fastPath === true,
-            globalGraphHash: bundlerOptions.globalGraphHash || ''
-        }), { envelopes: orderedEnvelopes.length });
-        await startupProfile.measureAsync('inject_image_materialization_manifest', () => injectImageMaterializationIntoRouterManifest(outDir, orderedEnvelopes), { envelopes: orderedEnvelopes.length });
-        const assets = await startupProfile.measureAsync('collect_assets', () => collectAssets(outDir));
-        return { assets, envelopeCount: orderedEnvelopes.length };
-    }
-    async function runFullBuild(activeLogger, showBundlerInfo) {
-        const startupProfile = createStartupProfiler('cli-build');
-        const compilerTotals = createCompilerTotals();
-        await maybeRunVersionCheck({
-            state,
-            startupProfile,
-            projectRoot,
-            logger: activeLogger,
-            bundlerBin
-        });
-        state.registry = startupProfile.measureSync('build_component_registry', () => buildComponentRegistry(srcDir));
-        state.manifest = await startupProfile.measureAsync('generate_manifest', () => generateManifest(resolvedPagesDir));
-        await startupProfile.measureAsync('ensure_zenith_type_declarations', () => ensureZenithTypeDeclarations({
-            manifest: state.manifest,
-            pagesDir: resolvedPagesDir
-        }));
-        state.pageLoopCaches = createPageLoopCaches();
-        const emitCompilerWarning = buildCompilerWarningEmitter(activeLogger);
-        const { envelopes, expressionRewriteMetrics } = await buildPageEnvelopes({
-            manifest: state.manifest,
-            pagesDir: resolvedPagesDir,
-            srcDir,
-            registry: state.registry,
-            compilerOpts,
-            compilerBin,
-            routerEnabled,
-            startupProfile,
-            compilerTotals,
-            emitCompilerWarning,
-            pageLoopCaches: state.pageLoopCaches
-        });
-        state.envelopeByFile = new Map(envelopes.map((entry) => [entry.file, entry]));
-        state.manifestEntryByPath = toManifestEntryMap(state.manifest, resolvedPagesDir);
-        state.pageOnlyFastPathSignatureByFile = new Map(envelopes.map((entry) => [entry.file, buildPageOnlyFastPathSignature(entry)]));
-        state.globalGraphHash = buildGlobalGraphHash(envelopes);
-        const { assets } = await runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo);
-        await syncImageState(startupProfile);
-        startupProfile.emit('build_complete', {
-            pages: state.manifest.length,
-            assets: assets.length,
-            compilerTotals,
-            expressionRewriteMetrics,
-            strategy: 'full'
-        });
-        state.hasSuccessfulBuild = true;
-        return { pages: state.manifest.length, assets, strategy: 'full' };
-    }
-    async function runBundleOnlyBuild(activeLogger, showBundlerInfo) {
-        const startupProfile = createStartupProfiler('cli-build');
-        const compilerTotals = createCompilerTotals();
-        const expressionRewriteMetrics = createExpressionRewriteMetrics();
-        const { assets } = await runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo, { rebuildStrategy: 'bundle-only' });
-        await syncImageState(startupProfile);
-        startupProfile.emit('build_complete', {
-            pages: state.manifest.length,
-            assets: assets.length,
-            compilerTotals,
-            expressionRewriteMetrics,
-            strategy: 'bundle-only'
-        });
-        return { pages: state.manifest.length, assets, strategy: 'bundle-only' };
-    }
-    async function runPageOnlyBuild(entries, activeLogger, showBundlerInfo) {
-        const startupProfile = createStartupProfiler('cli-build');
-        const compilerTotals = createCompilerTotals();
-        const emitCompilerWarning = buildCompilerWarningEmitter(activeLogger);
-        const { envelopes, expressionRewriteMetrics } = await buildPageEnvelopes({
-            manifest: entries,
-            pagesDir: resolvedPagesDir,
-            srcDir,
-            registry: state.registry,
-            compilerOpts,
-            compilerBin,
-            routerEnabled,
-            startupProfile,
-            compilerTotals,
-            emitCompilerWarning,
-            pageLoopCaches: state.pageLoopCaches
-        });
-        const previousFastPathSignatures = new Map(state.pageOnlyFastPathSignatureByFile);
-        const canUseFastPath = entries.every((entry, index) => {
-            const previous = previousFastPathSignatures.get(resolve(resolvedPagesDir, entry.file));
-            const next = buildPageOnlyFastPathSignature(envelopes[index]);
-            return typeof previous === 'string' && previous === next;
-        });
-        for (const envelope of envelopes) {
-            state.envelopeByFile.set(envelope.file, envelope);
-            state.pageOnlyFastPathSignatureByFile.set(envelope.file, buildPageOnlyFastPathSignature(envelope));
-        }
-        const orderedEnvelopes = orderEnvelopes(state.manifest, resolvedPagesDir, state.envelopeByFile);
-        if (!orderedEnvelopes || orderedEnvelopes.length === 0) {
-            throw new Error('Dev rebuild cache is incomplete; full rebuild required.');
-        }
-        state.globalGraphHash = buildGlobalGraphHash(orderedEnvelopes);
-        const { assets } = await runBundlerWithCachedEnvelopes(startupProfile, activeLogger, showBundlerInfo, {
-            rebuildStrategy: 'page-only',
-            changedRoutes: entries.map((entry) => entry.path),
-            fastPath: canUseFastPath,
-            envelopesOverride: canUseFastPath ? envelopes : orderedEnvelopes,
-            globalGraphHash: canUseFastPath ? state.globalGraphHash : ''
-        });
-        await syncImageState(startupProfile);
-        startupProfile.emit('build_complete', {
-            pages: state.manifest.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 {
-        async build(buildOptions = {}) {
-            const activeLogger = buildOptions.logger || logger;
-            const showBundlerInfo = buildOptions.showBundlerInfo !== false;
-            const changedFiles = Array.isArray(buildOptions.changedFiles)
-                ? [...new Set(buildOptions.changedFiles.map((entry) => resolve(String(entry))))]
-                : [];
-            if (!state.hasSuccessfulBuild || changedFiles.length === 0) {
-                return runFullBuild(activeLogger, showBundlerInfo);
-            }
-            if (isCssOnlyChange(changedFiles)) {
-                return runBundleOnlyBuild(activeLogger, showBundlerInfo);
-            }
-            const pageOnlyEntries = selectPageOnlyEntries(changedFiles, resolvedPagesDir, state.manifestEntryByPath);
-            if (pageOnlyEntries.length > 0) {
-                return runPageOnlyBuild(pageOnlyEntries, activeLogger, showBundlerInfo);
-            }
-            return runFullBuild(activeLogger, showBundlerInfo);
-        },
-        getImageRuntimePayload() {
-            return state.imageRuntimePayload;
-        }
-    };
-}
+export { createDevBuildSession } from './dev-build-session/session.js';

package/dist/dev-server/css-state.d.ts

@@ -0,0 +1,7 @@
+export function syncCssStateFromBuild({ buildResult, nextBuildId, outDir, state, trace }: {
+    buildResult: any;
+    nextBuildId: any;
+    outDir: any;
+    state: any;
+    trace: any;
+}): Promise<boolean>;

package/dist/dev-server/css-state.js

@@ -0,0 +1,92 @@
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+function delay(ms) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+function pickCssAsset(assets) {
+    if (!Array.isArray(assets) || assets.length === 0) {
+        return '';
+    }
+    const cssAssets = assets
+        .filter((entry) => typeof entry === 'string' && entry.endsWith('.css'))
+        .map((entry) => entry.startsWith('/') ? entry : `/${entry}`);
+    if (cssAssets.length === 0) {
+        return '';
+    }
+    const devStable = cssAssets.find((entry) => entry.endsWith('/styles.dev.css'));
+    if (devStable) {
+        return devStable;
+    }
+    const preferred = cssAssets.find((entry) => /\/styles(\.|\/|$)/.test(entry));
+    return preferred || cssAssets[0];
+}
+async function waitForCssFile(absolutePath, retries = 16, delayMs = 40) {
+    for (let i = 0; i <= retries; i++) {
+        try {
+            const info = await stat(absolutePath);
+            if (info.isFile()) {
+                return true;
+            }
+        }
+        catch {
+            // keep retrying
+        }
+        if (i < retries) {
+            await delay(delayMs);
+        }
+    }
+    return false;
+}
+export async function syncCssStateFromBuild({ buildResult, nextBuildId, outDir, state, trace }) {
+    state.currentCssHref = `/__zenith_dev/styles.css?buildId=${nextBuildId}`;
+    const candidate = pickCssAsset(buildResult?.assets);
+    if (!candidate) {
+        trace('css_sync_skipped', { reason: 'no_css_asset', buildId: nextBuildId });
+        return false;
+    }
+    const absoluteCssPath = join(outDir, candidate);
+    const ready = await waitForCssFile(absoluteCssPath);
+    if (!ready) {
+        trace('css_sync_skipped', {
+            reason: 'css_not_ready',
+            buildId: nextBuildId,
+            cssAsset: candidate,
+            resolvedPath: absoluteCssPath
+        });
+        return false;
+    }
+    let cssContent = '';
+    try {
+        cssContent = await readFile(absoluteCssPath, 'utf8');
+    }
+    catch {
+        trace('css_sync_skipped', {
+            reason: 'css_read_failed',
+            buildId: nextBuildId,
+            cssAsset: candidate,
+            resolvedPath: absoluteCssPath
+        });
+        return false;
+    }
+    if (typeof cssContent !== 'string') {
+        trace('css_sync_skipped', {
+            reason: 'css_invalid_type',
+            buildId: nextBuildId,
+            cssAsset: candidate,
+            resolvedPath: absoluteCssPath
+        });
+        return false;
+    }
+    if (cssContent.length === 0) {
+        trace('css_sync_skipped', {
+            reason: 'css_empty',
+            buildId: nextBuildId,
+            cssAsset: candidate,
+            resolvedPath: absoluteCssPath
+        });
+        cssContent = '/* zenith-dev: empty css */';
+    }
+    state.currentCssAssetPath = candidate;
+    state.currentCssContent = cssContent;
+    return true;
+}

package/dist/dev-server/not-found.d.ts

@@ -0,0 +1,23 @@
+export function classifyDevPath(pathname: any): "dev_events" | "dev_state" | "dev_styles" | "asset" | "other";
+export function traceNotFound(trace: any, req: any, url: any, details?: {}): void;
+export function classifyNotFound(pathname: any): "page" | "asset" | "dev_internal" | "zenith_internal";
+export function routeFileHint(pathname: any): string;
+export function infer404Cause(category: any, buildStatus: any): "initial build failed" | "unknown Zenith dev endpoint" | "asset not emitted by latest build" | null;
+export function looksLikeJsonRequest(req: any, pathname: any): boolean;
+export function buildNotFoundPayload({ pathname, category, cause, buildId, buildStatus, configuredBasePath, currentCssHref }: {
+    pathname: any;
+    category: any;
+    cause: any;
+    buildId: any;
+    buildStatus: any;
+    configuredBasePath: any;
+    currentCssHref: any;
+}): {
+    kind: string;
+    category: any;
+    requestedPath: any;
+    buildId: any;
+    buildStatus: any;
+    cause: any;
+};
+export function renderNotFoundHtml(payload: any): string;

package/dist/dev-server/not-found.js

@@ -0,0 +1,129 @@
+import { stripBasePath } from '../base-path.js';
+export function classifyDevPath(pathname) {
+    if (pathname.startsWith('/__zenith_dev/events'))
+        return 'dev_events';
+    if (pathname.startsWith('/__zenith_dev/state'))
+        return 'dev_state';
+    if (pathname.startsWith('/__zenith_dev/styles.css'))
+        return 'dev_styles';
+    if (pathname.startsWith('/assets/'))
+        return 'asset';
+    return 'other';
+}
+export function traceNotFound(trace, req, url, details = {}) {
+    trace('http_404', {
+        method: req.method || 'GET',
+        url: `${url.pathname}${url.search}`,
+        classify: classifyDevPath(url.pathname),
+        ...details
+    });
+}
+export function classifyNotFound(pathname) {
+    const lower = String(pathname || '').toLowerCase();
+    if (lower.startsWith('/__zenith_dev/'))
+        return 'dev_internal';
+    if (lower.startsWith('/__zenith/'))
+        return 'zenith_internal';
+    if (lower.startsWith('/_assets/')
+        || lower.startsWith('/assets/')
+        || lower.endsWith('.css')
+        || lower.endsWith('.js')
+        || lower.endsWith('.map')
+        || lower.endsWith('.json')) {
+        return 'asset';
+    }
+    return 'page';
+}
+export function routeFileHint(pathname) {
+    const normalized = String(pathname || '/').replace(/\/+$/, '');
+    if (normalized === '' || normalized === '/') {
+        return 'src/pages/index.zen';
+    }
+    return `src/pages${normalized}.zen`;
+}
+export function infer404Cause(category, buildStatus) {
+    if (category === 'dev_internal' || category === 'zenith_internal') {
+        if (buildStatus === 'error') {
+            return 'initial build failed';
+        }
+        return 'unknown Zenith dev endpoint';
+    }
+    if (category === 'asset') {
+        if (buildStatus === 'error') {
+            return 'initial build failed';
+        }
+        return 'asset not emitted by latest build';
+    }
+    return null;
+}
+export function looksLikeJsonRequest(req, pathname) {
+    const accept = String(req.headers.accept || '').toLowerCase();
+    const secFetchDest = String(req.headers['sec-fetch-dest'] || '').toLowerCase();
+    if (accept.includes('application/json') || accept.includes('application/problem+json')) {
+        return true;
+    }
+    if (pathname.endsWith('.json')) {
+        return true;
+    }
+    return secFetchDest === 'empty';
+}
+export function buildNotFoundPayload({ pathname, category, cause, buildId, buildStatus, configuredBasePath, currentCssHref }) {
+    const hintedPath = category === 'page'
+        ? (stripBasePath(pathname, configuredBasePath) || pathname)
+        : pathname;
+    const payload = {
+        kind: 'zenith_dev_not_found',
+        category,
+        requestedPath: pathname,
+        buildId,
+        buildStatus,
+        cause: cause || ''
+    };
+    if (category === 'asset') {
+        payload.hint = buildStatus === 'error'
+            ? 'Dev server is running but initial build failed; fix compile errors and refresh.'
+            : 'Check emitted assets in dist and verify the requested path.';
+        if (pathname.endsWith('.css')) {
+            payload.expectedCssHref = currentCssHref || null;
+            payload.hint = buildStatus === 'error'
+                ? `Dev server is running but initial build failed; expected CSS at ${currentCssHref || '<none>'}.`
+                : `Requested CSS is missing; expected current href ${currentCssHref || '<none>'}.`;
+        }
+        return payload;
+    }
+    if (category === 'dev_internal' || category === 'zenith_internal') {
+        payload.hint = buildStatus === 'error'
+            ? 'Dev server is running but initial build failed; restart after fixing compile errors.'
+            : 'Check Zenith dev endpoint path and dev client version.';
+        payload.docsLink = '/docs/documentation/contracts/hmr-v1-contract.md';
+        return payload;
+    }
+    const routeFile = routeFileHint(hintedPath);
+    payload.routeFile = routeFile;
+    payload.cause = `no route file found at ${routeFile}`;
+    payload.hint = `Create ${routeFile} or verify router manifest output.`;
+    return payload;
+}
+export function renderNotFoundHtml(payload) {
+    const escaped = (value) => String(value || '')
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+    const details = [
+        `Requested: ${payload.requestedPath}`,
+        `Category: ${payload.category}`,
+        `Build: ${payload.buildStatus} (id=${payload.buildId})`,
+        `Cause: ${payload.cause}`,
+        payload.expectedCssHref ? `Expected CSS href: ${payload.expectedCssHref}` : '',
+        `Hint: ${payload.hint || 'Inspect dev server output.'}`,
+        payload.docsLink ? `Docs: ${payload.docsLink}` : ''
+    ].filter(Boolean).join('\n');
+    return [
+        '<!DOCTYPE html>',
+        '<html><head><meta charset="utf-8"><title>Zenith Dev 404</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 404</h1>',
+        `<pre style="white-space: pre-wrap; line-height: 1.5;">${escaped(details)}</pre>`,
+        '</body></html>'
+    ].join('');
+}