@zenithbuild/cli 0.6.13 → 0.7.0

package/dist/images/shared.js

@@ -0,0 +1,306 @@
+const DEFAULT_DEVICE_SIZES = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const DEFAULT_IMAGE_SIZES = [16, 32, 48, 64, 96, 128, 256, 384];
+const DEFAULT_FORMATS = ['webp', 'avif'];
+const DEFAULT_REMOTE_PATTERNS = [];
+const DEFAULT_MAX_REMOTE_BYTES = 10 * 1024 * 1024;
+const DEFAULT_MAX_PIXELS = 40_000_000;
+const DEFAULT_MINIMUM_CACHE_TTL = 60;
+const DEFAULT_QUALITY = 75;
+const IMAGE_RUNTIME_GLOBAL = '__zenith_image_runtime';
+export const DEFAULT_IMAGE_CONFIG = {
+    formats: DEFAULT_FORMATS,
+    quality: DEFAULT_QUALITY,
+    deviceSizes: DEFAULT_DEVICE_SIZES,
+    imageSizes: DEFAULT_IMAGE_SIZES,
+    remotePatterns: DEFAULT_REMOTE_PATTERNS,
+    allowSvg: false,
+    maxRemoteBytes: DEFAULT_MAX_REMOTE_BYTES,
+    maxPixels: DEFAULT_MAX_PIXELS,
+    minimumCacheTTL: DEFAULT_MINIMUM_CACHE_TTL,
+    dangerouslyAllowLocalNetwork: false
+};
+const TOP_LEVEL_KEYS = new Set([
+    'formats',
+    'quality',
+    'deviceSizes',
+    'imageSizes',
+    'remotePatterns',
+    'allowSvg',
+    'maxRemoteBytes',
+    'maxPixels',
+    'minimumCacheTTL',
+    'dangerouslyAllowLocalNetwork'
+]);
+function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function asPositiveInt(value, key) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`[Zenith:Config] images.${key} must be a positive integer`);
+    }
+    return value;
+}
+function normalizeStringArray(value, key) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`[Zenith:Config] images.${key} must be a non-empty array`);
+    }
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            throw new Error(`[Zenith:Config] images.${key} must contain non-empty strings`);
+        }
+        out.push(entry.trim().toLowerCase());
+    }
+    return [...new Set(out)];
+}
+function normalizePositiveIntArray(value, key) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`[Zenith:Config] images.${key} must be a non-empty array`);
+    }
+    const out = [];
+    for (const entry of value) {
+        out.push(asPositiveInt(entry, key));
+    }
+    return [...new Set(out)].sort((left, right) => left - right);
+}
+function normalizeRemotePattern(pattern) {
+    if (!isPlainObject(pattern)) {
+        throw new Error('[Zenith:Config] images.remotePatterns must contain plain objects');
+    }
+    const protocol = typeof pattern.protocol === 'string' && pattern.protocol.trim().length > 0
+        ? pattern.protocol.trim().replace(/:$/, '').toLowerCase()
+        : 'https';
+    const hostname = typeof pattern.hostname === 'string' ? pattern.hostname.trim().toLowerCase() : '';
+    if (!hostname) {
+        throw new Error('[Zenith:Config] images.remotePatterns[].hostname is required');
+    }
+    const port = typeof pattern.port === 'string' ? pattern.port.trim() : '';
+    const pathname = typeof pattern.pathname === 'string' && pattern.pathname.trim().length > 0
+        ? pattern.pathname.trim()
+        : '/**';
+    const search = typeof pattern.search === 'string' && pattern.search.length > 0
+        ? pattern.search
+        : '';
+    return {
+        protocol,
+        hostname,
+        port,
+        pathname,
+        search
+    };
+}
+function cloneImageConfig(config = DEFAULT_IMAGE_CONFIG) {
+    return {
+        ...config,
+        formats: [...(config.formats || [])],
+        deviceSizes: [...(config.deviceSizes || [])],
+        imageSizes: [...(config.imageSizes || [])],
+        remotePatterns: Array.isArray(config.remotePatterns)
+            ? config.remotePatterns.map((pattern) => ({ ...pattern }))
+            : []
+    };
+}
+export function normalizeImageConfig(input) {
+    if (input === undefined || input === null) {
+        return cloneImageConfig(DEFAULT_IMAGE_CONFIG);
+    }
+    if (!isPlainObject(input)) {
+        throw new Error('[Zenith:Config] images must be a plain object');
+    }
+    for (const key of Object.keys(input)) {
+        if (!TOP_LEVEL_KEYS.has(key)) {
+            throw new Error(`[Zenith:Config] Unknown key: "images.${key}"`);
+        }
+    }
+    const config = cloneImageConfig(DEFAULT_IMAGE_CONFIG);
+    if ('formats' in input) {
+        config.formats = normalizeStringArray(input.formats, 'formats');
+    }
+    if ('quality' in input) {
+        config.quality = asPositiveInt(input.quality, 'quality');
+    }
+    if ('deviceSizes' in input) {
+        config.deviceSizes = normalizePositiveIntArray(input.deviceSizes, 'deviceSizes');
+    }
+    if ('imageSizes' in input) {
+        config.imageSizes = normalizePositiveIntArray(input.imageSizes, 'imageSizes');
+    }
+    if ('remotePatterns' in input) {
+        if (!Array.isArray(input.remotePatterns)) {
+            throw new Error('[Zenith:Config] images.remotePatterns must be an array');
+        }
+        config.remotePatterns = input.remotePatterns.map(normalizeRemotePattern);
+    }
+    if ('allowSvg' in input) {
+        if (typeof input.allowSvg !== 'boolean') {
+            throw new Error('[Zenith:Config] images.allowSvg must be boolean');
+        }
+        config.allowSvg = input.allowSvg;
+    }
+    if ('maxRemoteBytes' in input) {
+        config.maxRemoteBytes = asPositiveInt(input.maxRemoteBytes, 'maxRemoteBytes');
+    }
+    if ('maxPixels' in input) {
+        config.maxPixels = asPositiveInt(input.maxPixels, 'maxPixels');
+    }
+    if ('minimumCacheTTL' in input) {
+        config.minimumCacheTTL = asPositiveInt(input.minimumCacheTTL, 'minimumCacheTTL');
+    }
+    if ('dangerouslyAllowLocalNetwork' in input) {
+        if (typeof input.dangerouslyAllowLocalNetwork !== 'boolean') {
+            throw new Error('[Zenith:Config] images.dangerouslyAllowLocalNetwork must be boolean');
+        }
+        config.dangerouslyAllowLocalNetwork = input.dangerouslyAllowLocalNetwork;
+    }
+    return config;
+}
+function escapeRegex(value) {
+    return String(value).replace(/[|\\{}()[\]^$+?.*]/g, '\\$&');
+}
+function globToRegExp(glob, isHostname = false) {
+    let pattern = escapeRegex(glob);
+    pattern = pattern.replaceAll('\\*\\*', '__DOUBLE_STAR__');
+    pattern = pattern.replaceAll('\\*', isHostname ? '[^.]*' : '[^/]*');
+    pattern = pattern.replaceAll('__DOUBLE_STAR__', '.*');
+    return new RegExp(`^${pattern}$`, 'i');
+}
+function hostnameMatches(hostname, pattern) {
+    if (pattern.startsWith('*.')) {
+        const suffix = pattern.slice(1);
+        return hostname.endsWith(suffix) && hostname.length > suffix.length;
+    }
+    return globToRegExp(pattern, true).test(hostname);
+}
+export function matchRemotePattern(inputUrl, patterns) {
+    if (!inputUrl || !Array.isArray(patterns) || patterns.length === 0) {
+        return false;
+    }
+    const url = inputUrl instanceof URL ? inputUrl : new URL(String(inputUrl));
+    const protocol = url.protocol.replace(/:$/, '').toLowerCase();
+    const hostname = url.hostname.toLowerCase();
+    const port = url.port || '';
+    const pathname = url.pathname || '/';
+    const search = url.search || '';
+    return patterns.some((pattern) => {
+        if (pattern.protocol && pattern.protocol !== protocol) {
+            return false;
+        }
+        if (!hostnameMatches(hostname, pattern.hostname || '')) {
+            return false;
+        }
+        if (pattern.port && pattern.port !== port) {
+            return false;
+        }
+        if (pattern.search && pattern.search !== search) {
+            return false;
+        }
+        return globToRegExp(pattern.pathname || '/**').test(pathname);
+    });
+}
+export function isRemoteImageUrl(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    return /^https?:\/\//i.test(value.trim());
+}
+export function normalizeImageSource(input) {
+    if (typeof input === 'string') {
+        const trimmed = input.trim();
+        if (!trimmed) {
+            return null;
+        }
+        if (isRemoteImageUrl(trimmed)) {
+            return { kind: 'remote', url: trimmed, width: null, height: null, alt: '' };
+        }
+        if (trimmed.startsWith('/')) {
+            return { kind: 'local', path: trimmed, width: null, height: null, alt: '' };
+        }
+        return null;
+    }
+    if (!isPlainObject(input)) {
+        return null;
+    }
+    const rawUrl = typeof input.url === 'string'
+        ? input.url
+        : typeof input.src === 'string'
+            ? input.src
+            : typeof input.path === 'string'
+                ? input.path
+                : '';
+    const normalized = normalizeImageSource(rawUrl);
+    if (!normalized) {
+        return null;
+    }
+    const width = Number.isInteger(input.width) && input.width > 0 ? input.width : null;
+    const height = Number.isInteger(input.height) && input.height > 0 ? input.height : null;
+    const alt = typeof input.alt === 'string' ? input.alt : '';
+    return {
+        ...normalized,
+        width,
+        height,
+        alt
+    };
+}
+export function normalizeImageFormat(value) {
+    return String(value || '').trim().toLowerCase().replace(/^\./, '');
+}
+export function buildLocalImageKey(publicPath) {
+    const input = String(publicPath || '');
+    let hash = 2166136261;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+export function buildLocalVariantPath(publicPath, width, quality, format) {
+    const key = buildLocalImageKey(publicPath);
+    return `/_zenith/image/local/${key}/w${width}-q${quality}.${normalizeImageFormat(format)}`;
+}
+export function buildRemoteVariantPath(remoteUrl, width, quality, format) {
+    const query = new URLSearchParams();
+    query.set('url', String(remoteUrl || ''));
+    query.set('w', String(width));
+    query.set('q', String(quality));
+    if (format) {
+        query.set('f', normalizeImageFormat(format));
+    }
+    return `/_zenith/image?${query.toString()}`;
+}
+export function resolveWidthCandidates(width, sizes, config, manifestEntry) {
+    const base = new Set([
+        ...(config?.deviceSizes || DEFAULT_DEVICE_SIZES),
+        ...(config?.imageSizes || DEFAULT_IMAGE_SIZES)
+    ]);
+    if (Number.isInteger(width) && width > 0) {
+        base.add(width);
+        base.add(width * 2);
+    }
+    if (!width && typeof sizes === 'string' && sizes.trim().length > 0) {
+        for (const candidate of config?.deviceSizes || DEFAULT_DEVICE_SIZES) {
+            base.add(candidate);
+        }
+    }
+    let widths = [...base].filter((entry) => Number.isInteger(entry) && entry > 0).sort((left, right) => left - right);
+    const available = Array.isArray(manifestEntry?.availableWidths) ? manifestEntry.availableWidths : null;
+    if (available && available.length > 0) {
+        widths = widths.filter((entry) => available.includes(entry));
+        if (widths.length === 0) {
+            widths = [...available];
+        }
+    }
+    return widths;
+}
+export function imageRuntimeGlobalName() {
+    return IMAGE_RUNTIME_GLOBAL;
+}
+export function normalizeImageRuntimePayload(payload) {
+    if (!isPlainObject(payload)) {
+        return null;
+    }
+    return {
+        mode: payload.mode === 'endpoint' ? 'endpoint' : 'passthrough',
+        config: normalizeImageConfig(payload.config || {}),
+        localImages: isPlainObject(payload.localImages) ? payload.localImages : {}
+    };
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { resolve, join, dirname } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { createZenithLogger } from './ui/logger.js';
+import { loadConfig } from './config.js';
 const COMMANDS = ['dev', 'build', 'preview'];
 const DEFAULT_VERSION = '0.0.0';
 const __filename = fileURLToPath(import.meta.url);
@@ -59,22 +60,6 @@ function resolvePort(args, fallback) {
     }
     return fallback;
 }
-/**
- * Load zenith.config.js from project root.
- *
- * @param {string} projectRoot
- * @returns {Promise<object>}
- */
-async function loadConfig(projectRoot) {
-    const configPath = join(projectRoot, 'zenith.config.js');
-    try {
-        const mod = await import(configPath);
-        return mod.default || {};
-    }
-    catch {
-        return {};
-    }
-}
 /**
  * CLI entry point.
  *
@@ -142,7 +127,7 @@ export async function cli(args, cwd) {
         const port = resolvePort(args.slice(1), 4000);
         const host = process.env.ZENITH_PREVIEW_HOST || '127.0.0.1';
         logger.dev('Starting preview server…');
-        const preview = await createPreviewServer({ distDir: outDir, port, host, logger });
+        const preview = await createPreviewServer({ distDir: outDir, port, host, logger, config, projectRoot });
         logger.ok(`http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${preview.port}`);
         process.on('SIGINT', () => {
             preview.close();

package/dist/manifest.js

@@ -32,6 +32,7 @@ export async function generateManifest(pagesDir, extension = '.zen') {
     for (const entry of entries) {
         _validateParams(entry.path);
     }
+    _validateManifestConflicts(entries);
     // Sort: static first, dynamic after, alpha within each category
     return _sortEntries(entries);
 }
@@ -142,6 +143,32 @@ function _validateParams(routePath) {
         }
     }
 }
+/**
+ * Reject duplicate or structurally ambiguous routes across different files.
+ *
+ * @param {ManifestEntry[]} entries
+ */
+function _validateManifestConflicts(entries) {
+    /** @type {Map<string, ManifestEntry>} */
+    const exactPaths = new Map();
+    /** @type {Map<string, ManifestEntry>} */
+    const structural = new Map();
+    for (const entry of entries) {
+        const existingExact = exactPaths.get(entry.path);
+        if (existingExact) {
+            throw new Error(`[Zenith CLI] Duplicate route path '${entry.path}' generated by '${existingExact.file}' and '${entry.file}'`);
+        }
+        exactPaths.set(entry.path, entry);
+        const signature = _routeConflictSignature(entry.path);
+        const existingStructural = structural.get(signature);
+        if (existingStructural && existingStructural.path !== entry.path) {
+            throw new Error(`[Zenith CLI] Ambiguous route patterns '${existingStructural.path}' (${existingStructural.file}) and '${entry.path}' (${entry.file}) match the same URL shape`);
+        }
+        if (!existingStructural) {
+            structural.set(signature, entry);
+        }
+    }
+}
 /**
  * Check if a route contains any dynamic segments.
  *
@@ -160,6 +187,24 @@ function _isDynamic(routePath) {
 function _sortEntries(entries) {
     return [...entries].sort((a, b) => compareRouteSpecificity(a.path, b.path));
 }
+/**
+ * Normalize a route path so structurally equivalent param names conflict.
+ *
+ * @param {string} routePath
+ * @returns {string}
+ */
+function _routeConflictSignature(routePath) {
+    const segments = routePath.split('/').filter(Boolean).map((segment) => {
+        if (segment.startsWith('*')) {
+            return segment.endsWith('?') ? '*?' : '*';
+        }
+        if (segment.startsWith(':')) {
+            return ':';
+        }
+        return segment;
+    });
+    return '/' + segments.join('/');
+}
 /**
  * Deterministic route precedence:
  *   static segment > param segment > catch-all segment.

package/dist/preview.d.ts

@@ -1,7 +1,7 @@
 /**
  * Create and start a preview server.
  *
- * @param {{ distDir: string, port?: number, host?: string, logger?: object | null }} options
+ * @param {{ distDir: string, port?: number, host?: string, logger?: object | null, config?: object, projectRoot?: string }} options
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export function createPreviewServer(options: {
@@ -9,6 +9,8 @@ export function createPreviewServer(options: {
     port?: number;
     host?: string;
     logger?: object | null;
+    config?: object;
+    projectRoot?: string;
 }): Promise<{
     server: import("http").Server;
     port: number;
@@ -59,6 +61,7 @@ export function executeServerRoute({ source, sourcePath, params, requestUrl, req
         load: string;
     };
 }>;
+export function defaultRouteDenyMessage(status: any): "Unauthorized" | "Forbidden" | "Not Found" | "Internal Server Error";
 /**
  * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
  * @returns {Promise<Record<string, unknown> | null>}

package/dist/preview.js

@@ -13,6 +13,10 @@ import { createServer } from 'node:http';
 import { access, readFile } from 'node:fs/promises';
 import { extname, join, normalize, resolve, sep, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadConfig } from './config.js';
+import { materializeImageMarkup } from './images/materialize.js';
+import { createImageRuntimePayload, injectImageRuntimePayload } from './images/payload.js';
+import { handleImageRequest } from './images/service.js';
 import { createSilentLogger } from './ui/logger.js';
 import { compareRouteSpecificity, matchRoute as matchManifestRoute, resolveRequestRoute } from './server/resolve-request-route.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -22,8 +26,12 @@ const MIME_TYPES = {
     '.css': 'text/css',
     '.json': 'application/json',
     '.png': 'image/png',
+    '.jpeg': 'image/jpeg',
     '.jpg': 'image/jpeg',
-    '.svg': 'image/svg+xml'
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.gif': 'image/gif'
 };
 const SERVER_SCRIPT_RUNNER = String.raw `
 import vm from 'node:vm';
@@ -378,14 +386,30 @@ try {
 /**
  * Create and start a preview server.
  *
- * @param {{ distDir: string, port?: number, host?: string, logger?: object | null }} options
+ * @param {{ distDir: string, port?: number, host?: string, logger?: object | null, config?: object, projectRoot?: string }} options
  * @returns {Promise<{ server: import('http').Server, port: number, close: () => void }>}
  */
 export async function createPreviewServer(options) {
+    const resolvedProjectRoot = options?.projectRoot ? resolve(options.projectRoot) : resolve(options.distDir, '..');
+    const resolvedConfig = options?.config && typeof options.config === 'object'
+        ? options.config
+        : await loadConfig(resolvedProjectRoot);
     const { distDir, port = 4000, host = '127.0.0.1', logger: providedLogger = null } = options;
+    const projectRoot = resolvedProjectRoot;
+    const config = resolvedConfig;
     const logger = providedLogger || createSilentLogger();
     const verboseLogging = logger.mode?.logLevel === 'verbose';
     let actualPort = port;
+    async function loadImageManifest() {
+        try {
+            const manifestRaw = await readFile(join(distDir, '_zenith', 'image', 'manifest.json'), 'utf8');
+            const parsed = JSON.parse(manifestRaw);
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
     function publicHost() {
         if (host === '0.0.0.0' || host === '::') {
             return '127.0.0.1';
@@ -469,6 +493,14 @@ export async function createPreviewServer(options) {
                 }));
                 return;
             }
+            if (url.pathname === '/_zenith/image') {
+                await handleImageRequest(req, res, {
+                    requestUrl: url,
+                    projectRoot,
+                    config: config.images
+                });
+                return;
+            }
             if (extname(url.pathname) && extname(url.pathname) !== '.html') {
                 const staticPath = resolveWithinDist(distDir, url.pathname);
                 if (!staticPath || !(await fileExists(staticPath))) {
@@ -540,7 +572,7 @@ export async function createPreviewServer(options) {
                 if (result && result.kind === 'deny') {
                     const status = Number.isInteger(result.status) ? result.status : 403;
                     res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
-                    res.end(result.message || (status === 401 ? 'Unauthorized' : 'Forbidden'));
+                    res.end(result.message || defaultRouteDenyMessage(status));
                     return;
                 }
                 if (result && result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
@@ -548,9 +580,20 @@ export async function createPreviewServer(options) {
                 }
             }
             let html = await readFile(htmlPath, 'utf8');
+            if (resolved.matched && resolved.route?.page_asset) {
+                const pageAssetPath = resolveWithinDist(distDir, resolved.route.page_asset);
+                html = await materializeImageMarkup({
+                    html,
+                    pageAssetPath,
+                    payload: createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint'),
+                    ssrData: ssrPayload,
+                    routePathname: resolved.route.path || url.pathname
+                });
+            }
             if (ssrPayload) {
                 html = injectSsrPayload(html, ssrPayload);
             }
+            html = injectImageRuntimePayload(html, createImageRuntimePayload(config.images, await loadImageManifest(), 'endpoint'));
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(html);
         }
@@ -674,6 +717,15 @@ export async function executeServerRoute({ source, sourcePath, params, requestUr
         trace: { guard: 'none', load: 'data' }
     };
 }
+export function defaultRouteDenyMessage(status) {
+    if (status === 401)
+        return 'Unauthorized';
+    if (status === 403)
+        return 'Forbidden';
+    if (status === 404)
+        return 'Not Found';
+    return 'Internal Server Error';
+}
 /**
  * @param {{ source: string, sourcePath: string, params: Record<string, string>, requestUrl?: string, requestMethod?: string, requestHeaders?: Record<string, string | string[] | undefined>, routePattern?: string, routeFile?: string, routeId?: string }} input
  * @returns {Promise<Record<string, unknown> | null>}
@@ -697,11 +749,12 @@ export async function executeServerScript(input) {
         };
     }
     if (result.kind === 'deny') {
+        const status = Number.isInteger(result.status) ? result.status : 403;
         return {
             __zenith_error: {
-                status: Number.isInteger(result.status) ? result.status : 403,
-                code: 'ACCESS_DENIED',
-                message: String(result.message || 'Access denied')
+                status,
+                code: status >= 500 ? 'LOAD_FAILED' : (status === 404 ? 'NOT_FOUND' : 'ACCESS_DENIED'),
+                message: String(result.message || defaultRouteDenyMessage(status))
             }
         };
     }

package/dist/resolve-components.js

@@ -8,9 +8,15 @@
 // Pipeline:
 //   buildComponentRegistry() → expandComponents() → expanded source string
 // ---------------------------------------------------------------------------
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, extname, join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { findMatchingComponentClose, findNextKnownComponentTag } from './component-tag-parser.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const FRAMEWORK_COMPONENTS = [
+    ['Image', join(__dirname, 'framework-components', 'Image.zen')]
+];
 // ---------------------------------------------------------------------------
 // Registry: Map<PascalCaseName, absolutePath>
 // ---------------------------------------------------------------------------
@@ -37,6 +43,18 @@ export function buildComponentRegistry(srcDir) {
         }
         walkDir(dir, registry);
     }
+    for (const [componentName, componentPath] of FRAMEWORK_COMPONENTS) {
+        if (!existsSync(componentPath)) {
+            continue;
+        }
+        if (registry.has(componentName)) {
+            throw new Error(`Duplicate component name "${componentName}":\n` +
+                `  1) ${registry.get(componentName)}\n` +
+                `  2) ${componentPath}\n` +
+                'Rename the local component to avoid shadowing the Zenith framework component.');
+        }
+        registry.set(componentName, componentPath);
+    }
     return registry;
 }
 /**
@@ -207,7 +225,6 @@ function expandTag(name, children, registry, sourceFile, chain, usedComponents)
     }
     const compSource = readFileSync(compPath, 'utf8');
     let template = extractTemplate(compSource);
-    // Check Document Mode
     const docMode = isDocumentMode(template);
     if (docMode) {
         // Document Mode: must contain exactly one <slot />

package/dist/server-contract.js

@@ -49,8 +49,9 @@ function assertValidRouteResultShape(value, where, allowedKinds) {
         }
     }
     if (kind === 'deny') {
-        if (!Number.isInteger(value.status) || (value.status !== 401 && value.status !== 403)) {
-            throw new Error(`[Zenith] ${where}: deny status must be 401 or 403.`);
+        if (!Number.isInteger(value.status) ||
+            (value.status !== 401 && value.status !== 403 && value.status !== 404)) {
+            throw new Error(`[Zenith] ${where}: deny status must be 401, 403, or 404.`);
         }
         if (value.message !== undefined && typeof value.message !== 'string') {
             throw new Error(`[Zenith] ${where}: deny message must be a string when provided.`);

package/dist/server-script-composition.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @param {{
+ *   sourceFile: string,
+ *   inlineServerScript?: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, source_path: string } | null,
+ *   adjacentGuardPath?: string | null,
+ *   adjacentLoadPath?: string | null
+ * }} input
+ * @returns {{ serverScript: { source: string, prerender: boolean, has_guard: boolean, has_load: boolean, source_path: string } | null, guardPath: string | null, loadPath: string | null }}
+ */
+export function composeServerScriptEnvelope({ sourceFile, inlineServerScript, adjacentGuardPath, adjacentLoadPath }: {
+    sourceFile: string;
+    inlineServerScript?: {
+        source: string;
+        prerender: boolean;
+        has_guard: boolean;
+        has_load: boolean;
+        source_path: string;
+    } | null;
+    adjacentGuardPath?: string | null;
+    adjacentLoadPath?: string | null;
+}): {
+    serverScript: {
+        source: string;
+        prerender: boolean;
+        has_guard: boolean;
+        has_load: boolean;
+        source_path: string;
+    } | null;
+    guardPath: string | null;
+    loadPath: string | null;
+};
+/**
+ * @param {string} sourceFile
+ * @returns {{ guardPath: string | null, loadPath: string | null }}
+ */
+export function resolveAdjacentServerModules(sourceFile: string): {
+    guardPath: string | null;
+    loadPath: string | null;
+};