@zenithbuild/cli 0.7.3 → 0.7.5

package/dist/dev-server.js

@@ -15,11 +15,18 @@ import { existsSync, watch } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
 import { performance } from 'node:perf_hooks';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { appLocalRedirectLocation, imageEndpointPath, normalizeBasePath, routeCheckPath, stripBasePath } from './base-path.js';
+import { resolveBuildAdapter } from './adapters/resolve-adapter.js';
 import { createDevBuildSession } from './dev-build-session.js';
 import { createStartupProfiler } from './startup-profile.js';
 import { createSilentLogger } from './ui/logger.js';
 import { readChangeFingerprint } from './dev-watch.js';
-import { defaultRouteDenyMessage, executeServerRoute, injectSsrPayload, loadRouteManifest, resolveWithinDist, toStaticFilePath } from './preview.js';
+import { createTrustedOriginResolver, publicHost } from './request-origin.js';
+import { readRequestBodyBuffer } from './request-body.js';
+import { buildResourceResponseDescriptor } from './resource-response.js';
+import { supportsTargetRouteCheck } from './route-check-support.js';
+import { clientFacingRouteMessage, defaultRouteDenyMessage, logServerException, sanitizeRouteResult } from './server-error.js';
+import { executeServerRoute, injectSsrPayload, loadRouteSurfaceState, resolveWithinDist, toStaticFilePath } from './preview.js';
 import { materializeImageMarkup } from './images/materialize.js';
 import { injectImageRuntimePayload } from './images/payload.js';
 import { handleImageRequest } from './images/service.js';
@@ -37,6 +44,15 @@ const MIME_TYPES = {
     '.avif': 'image/avif',
     '.gif': 'image/gif'
 };
+const IMAGE_RUNTIME_TAG_RE = new RegExp('<' + 'script\\b[^>]*\\bid=(["\'])zenith-image-runtime\\1[^>]*>[\\s\\S]*?<\\/' + 'script>', 'i');
+const EVENT_STREAM_MIME = ['text', 'event-stream'].join('/');
+const LEGACY_DEV_STREAM_PATH = ['/__zenith', '_hmr'].join('');
+function appendSetCookieHeaders(headers, setCookies = []) {
+    if (Array.isArray(setCookies) && setCookies.length > 0) {
+        headers['Set-Cookie'] = setCookies.slice();
+    }
+    return headers;
+}
 // Note: V0 HMR script injection has been moved to the runtime client.
 // This server purely hosts the V1 HMR contract endpoints.
 /**
@@ -50,6 +66,10 @@ export async function createDevServer(options) {
     const { pagesDir, outDir, port = 3000, host = '127.0.0.1', config = {}, logger: providedLogger = null } = options;
     const logger = providedLogger || createSilentLogger();
     const buildSession = createDevBuildSession({ pagesDir, outDir, config, logger });
+    const configuredBasePath = normalizeBasePath(config.basePath || '/');
+    const resolvedTarget = resolveBuildAdapter(config).target;
+    const routeCheckEnabled = supportsTargetRouteCheck(resolvedTarget);
+    const isStaticExportTarget = resolvedTarget === 'static-export';
     const resolvedPagesDir = resolve(pagesDir);
     const resolvedOutDir = resolve(outDir);
     const resolvedOutDirTmp = resolve(dirname(resolvedOutDir), `${basename(resolvedOutDir)}.tmp`);
@@ -86,17 +106,19 @@ export async function createDevServer(options) {
     let currentCssHref = '';
     let currentCssContent = '';
     let actualPort = port;
-    let currentRoutes = [];
+    const resolveServerOrigin = createTrustedOriginResolver({
+        host,
+        getPort: () => actualPort,
+        label: 'dev server'
+    });
+    let currentRouteState = { pageRoutes: [], resourceRoutes: [] };
     const rebuildDebounceMs = 5;
     const queuedRebuildDebounceMs = 5;
     function _publicHost() {
-        if (host === '0.0.0.0' || host === '::') {
-            return '127.0.0.1';
-        }
-        return host;
+        return publicHost(host);
     }
     function _serverOrigin() {
-        return `http://${_publicHost()}:${actualPort}`;
+        return resolveServerOrigin();
     }
     function _trace(event, payload = {}) {
         if (!traceEnabled)
@@ -208,6 +230,9 @@ export async function createDevServer(options) {
         throw lastError;
     }
     function _buildNotFoundPayload(pathname, category, cause) {
+        const hintedPath = category === 'page'
+            ? (stripBasePath(pathname, configuredBasePath) || pathname)
+            : pathname;
         const payload = {
             kind: 'zenith_dev_not_found',
             category,
@@ -235,7 +260,7 @@ export async function createDevServer(options) {
             payload.docsLink = '/docs/documentation/contracts/hmr-v1-contract.md';
             return payload;
         }
-        const routeFile = _routeFileHint(pathname);
+        const routeFile = _routeFileHint(hintedPath);
         payload.routeFile = routeFile;
         payload.cause = `no route file found at ${routeFile}`;
         payload.hint = `Create ${routeFile} or verify router manifest output.`;
@@ -355,22 +380,26 @@ export async function createDevServer(options) {
         return true;
     }
     async function _loadRoutesForRequests() {
-        if (buildStatus === 'building' && Array.isArray(currentRoutes) && currentRoutes.length > 0) {
-            return currentRoutes;
+        if (buildStatus === 'building' &&
+            ((Array.isArray(currentRouteState.pageRoutes) && currentRouteState.pageRoutes.length > 0) ||
+                (Array.isArray(currentRouteState.resourceRoutes) && currentRouteState.resourceRoutes.length > 0))) {
+            return currentRouteState;
         }
         try {
-            const routes = await loadRouteManifest(outDir);
-            if (Array.isArray(routes) && routes.length > 0) {
-                currentRoutes = routes;
-                return routes;
+            const routeState = await loadRouteSurfaceState(outDir, configuredBasePath);
+            if ((Array.isArray(routeState.pageRoutes) && routeState.pageRoutes.length > 0) ||
+                (Array.isArray(routeState.resourceRoutes) && routeState.resourceRoutes.length > 0)) {
+                currentRouteState = routeState;
+                return routeState;
             }
         }
         catch (error) {
-            if (!(Array.isArray(currentRoutes) && currentRoutes.length > 0)) {
+            if (!(Array.isArray(currentRouteState.pageRoutes) && currentRouteState.pageRoutes.length > 0) &&
+                !(Array.isArray(currentRouteState.resourceRoutes) && currentRouteState.resourceRoutes.length > 0)) {
                 throw error;
             }
         }
-        return currentRoutes;
+        return currentRouteState;
     }
     function _broadcastEvent(type, payload = {}) {
         const eventBuildId = Number.isInteger(payload.buildId) ? payload.buildId : buildId;
@@ -403,7 +432,7 @@ export async function createDevServer(options) {
             logger.build('Initial build (id=0)', { onceKey: 'dev-initial-build' });
             const initialBuild = await buildSession.build();
             const cssReady = await _syncCssStateFromBuild(initialBuild, buildId);
-            currentRoutes = await loadRouteManifest(outDir);
+            currentRouteState = await loadRouteSurfaceState(outDir, configuredBasePath);
             buildStatus = 'ok';
             buildError = null;
             lastBuildMs = Date.now();
@@ -422,7 +451,8 @@ export async function createDevServer(options) {
                 status: buildStatus,
                 durationMs,
                 cssReady,
-                routes: Array.isArray(currentRoutes) ? currentRoutes.length : 0
+                routes: (Array.isArray(currentRouteState.pageRoutes) ? currentRouteState.pageRoutes.length : 0) +
+                    (Array.isArray(currentRouteState.resourceRoutes) ? currentRouteState.resourceRoutes.length : 0)
             });
         }
         catch (err) {
@@ -452,15 +482,12 @@ export async function createDevServer(options) {
         }
     }
     const server = createServer(async (req, res) => {
-        const requestBase = typeof req.headers.host === 'string' && req.headers.host.length > 0
-            ? `http://${req.headers.host}`
-            : _serverOrigin();
-        const url = new URL(req.url, requestBase);
+        const url = new URL(req.url, _serverOrigin());
         let pathname = url.pathname;
         // Legacy HMR endpoint (deprecated but kept alive to avoid breaking old caches instantly)
-        if (pathname === '/__zenith_hmr') {
+        if (pathname === LEGACY_DEV_STREAM_PATH) {
             res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
+                'Content-Type': EVENT_STREAM_MIME,
                 'Cache-Control': 'no-store',
                 'Connection': 'keep-alive',
                 'X-Zenith-Deprecated': 'true'
@@ -498,7 +525,7 @@ export async function createDevServer(options) {
         // V1 Dev Events Endpoint (SSE)
         if (pathname === '/__zenith_dev/events') {
             res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
+                'Content-Type': EVENT_STREAM_MIME,
                 'Cache-Control': 'no-store',
                 'Connection': 'keep-alive',
                 'X-Accel-Buffering': 'no'
@@ -565,7 +592,10 @@ export async function createDevServer(options) {
             res.end(currentCssContent);
             return;
         }
-        if (pathname === '/_zenith/image') {
+        if (pathname === imageEndpointPath(configuredBasePath)) {
+            if (isStaticExportTarget) {
+                throw new Error('not found');
+            }
             await handleImageRequest(req, res, {
                 requestUrl: url,
                 projectRoot,
@@ -573,8 +603,13 @@ export async function createDevServer(options) {
             });
             return;
         }
-        if (pathname === '/__zenith/route-check') {
+        if (pathname === routeCheckPath(configuredBasePath)) {
             try {
+                if (!routeCheckEnabled) {
+                    res.writeHead(501, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                    res.end(JSON.stringify({ error: 'route_check_unsupported' }));
+                    return;
+                }
                 if (!initialBuildSettled && buildStatus === 'building') {
                     res.writeHead(503, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
                     res.end(JSON.stringify({
@@ -602,8 +637,16 @@ export async function createDevServer(options) {
                     res.end(JSON.stringify({ error: 'external_route_evaluation_forbidden' }));
                     return;
                 }
+                const canonicalTargetPath = stripBasePath(targetUrl.pathname, configuredBasePath);
+                if (canonicalTargetPath === null) {
+                    res.writeHead(404, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'route_not_found' }));
+                    return;
+                }
+                const canonicalTargetUrl = new URL(targetUrl.toString());
+                canonicalTargetUrl.pathname = canonicalTargetPath;
                 const routes = await _loadRoutesForRequests();
-                const resolvedCheck = resolveRequestRoute(targetUrl, routes);
+                const resolvedCheck = resolveRequestRoute(canonicalTargetUrl, routes.pageRoutes || []);
                 if (!resolvedCheck.matched || !resolvedCheck.route) {
                     res.writeHead(404, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: 'route_not_found' }));
@@ -623,16 +666,17 @@ export async function createDevServer(options) {
                 });
                 // Security: Enforce relative or same-origin redirects
                 if (checkResult && checkResult.result && checkResult.result.kind === 'redirect') {
-                    const loc = String(checkResult.result.location || '/');
+                    const loc = appLocalRedirectLocation(checkResult.result.location || '/', configuredBasePath);
+                    checkResult.result.location = loc;
                     if (loc.includes('://') || loc.startsWith('//')) {
                         try {
                             const parsedLoc = new URL(loc);
                             if (parsedLoc.origin !== targetUrl.origin) {
-                                checkResult.result.location = '/'; // Fallback to root for open redirect attempt
+                                checkResult.result.location = appLocalRedirectLocation('/', configuredBasePath);
                             }
                         }
                         catch {
-                            checkResult.result.location = '/';
+                            checkResult.result.location = appLocalRedirectLocation('/', configuredBasePath);
                         }
                     }
                 }
@@ -644,7 +688,7 @@ export async function createDevServer(options) {
                     'Vary': 'Cookie'
                 });
                 res.end(JSON.stringify({
-                    result: checkResult?.result || checkResult,
+                    result: sanitizeRouteResult(checkResult?.result || checkResult),
                     routeId: resolvedCheck.route.route_id || '',
                     to: targetUrl.toString()
                 }));
@@ -659,6 +703,7 @@ export async function createDevServer(options) {
         let resolvedPathFor404 = null;
         let staticRootFor404 = null;
         try {
+            const canonicalPath = stripBasePath(pathname, configuredBasePath);
             if (!initialBuildSettled && buildStatus === 'building') {
                 const pendingPayload = {
                     kind: 'zenith_dev_build_pending',
@@ -689,11 +734,19 @@ export async function createDevServer(options) {
                 ].join(''));
                 return;
             }
-            const requestExt = extname(pathname);
+            if (canonicalPath === null) {
+                throw new Error('not found');
+            }
+            const requestExt = extname(canonicalPath);
             if (requestExt && requestExt !== '.html') {
-                const assetPath = join(outDir, pathname);
+                const assetPath = isStaticExportTarget
+                    ? resolveWithinDist(outDir, pathname)
+                    : join(outDir, canonicalPath);
                 resolvedPathFor404 = assetPath;
                 staticRootFor404 = outDir;
+                if (!assetPath) {
+                    throw new Error('not found');
+                }
                 const asset = await _readFileForRequest(assetPath);
                 const mime = MIME_TYPES[requestExt] || 'application/octet-stream';
                 res.writeHead(200, { 'Content-Type': mime });
@@ -701,9 +754,42 @@ export async function createDevServer(options) {
                 return;
             }
             const routes = await _loadRoutesForRequests();
-            const resolved = resolveRequestRoute(url, routes);
+            const canonicalUrl = new URL(url.toString());
+            canonicalUrl.pathname = canonicalPath;
+            const resolvedResource = resolveRequestRoute(canonicalUrl, routes.resourceRoutes || []);
+            if (resolvedResource.matched && resolvedResource.route) {
+                const requestMethod = req.method || 'GET';
+                const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
+                    ? null
+                    : await readRequestBodyBuffer(req);
+                const execution = await executeServerRoute({
+                    source: resolvedResource.route.server_script || '',
+                    sourcePath: resolvedResource.route.server_script_path || '',
+                    params: resolvedResource.params,
+                    requestUrl: url.toString(),
+                    requestMethod,
+                    requestHeaders: req.headers,
+                    requestBodyBuffer,
+                    routePattern: resolvedResource.route.path,
+                    routeFile: resolvedResource.route.server_script_path || '',
+                    routeId: resolvedResource.route.route_id || '',
+                    routeKind: 'resource'
+                });
+                const descriptor = buildResourceResponseDescriptor(execution?.result, configuredBasePath, Array.isArray(execution?.setCookies) ? execution.setCookies : []);
+                res.writeHead(descriptor.status, appendSetCookieHeaders(descriptor.headers, descriptor.setCookies));
+                if ((req.method || 'GET').toUpperCase() === 'HEAD') {
+                    res.end();
+                    return;
+                }
+                res.end(descriptor.body);
+                return;
+            }
+            const resolved = resolveRequestRoute(canonicalUrl, routes.pageRoutes || []);
             let filePath = null;
-            if (resolved.matched && resolved.route) {
+            if (isStaticExportTarget) {
+                filePath = toStaticFilePath(outDir, pathname);
+            }
+            else if (resolved.matched && resolved.route) {
                 if (verboseLogging) {
                     logger.router(`${req.method || 'GET'} ${pathname} -> ${resolved.route.path} params=${JSON.stringify(resolved.params)}`);
                 }
@@ -713,7 +799,7 @@ export async function createDevServer(options) {
                 filePath = resolveWithinDist(outDir, output);
             }
             else {
-                filePath = toStaticFilePath(outDir, pathname);
+                filePath = toStaticFilePath(outDir, canonicalPath);
             }
             resolvedPathFor404 = filePath;
             staticRootFor404 = outDir;
@@ -721,48 +807,56 @@ export async function createDevServer(options) {
                 throw new Error('not found');
             }
             let ssrPayload = null;
+            let routeExecution = null;
             if (resolved.matched && resolved.route?.server_script && resolved.route.prerender !== true) {
-                let routeExecution = null;
                 try {
+                    const requestMethod = req.method || 'GET';
+                    const requestBodyBuffer = requestMethod === 'GET' || requestMethod === 'HEAD'
+                        ? null
+                        : await readRequestBodyBuffer(req);
                     routeExecution = await executeServerRoute({
                         source: resolved.route.server_script,
                         sourcePath: resolved.route.server_script_path || '',
                         params: resolved.params,
                         requestUrl: url.toString(),
-                        requestMethod: req.method || 'GET',
+                        requestMethod,
                         requestHeaders: req.headers,
+                        requestBodyBuffer,
                         routePattern: resolved.route.path,
                         routeFile: resolved.route.server_script_path || '',
                         routeId: resolved.route.route_id || ''
                     });
                 }
                 catch (error) {
+                    logServerException('dev server route execution failed', error);
                     ssrPayload = {
                         __zenith_error: {
+                            status: 500,
                             code: 'LOAD_FAILED',
-                            message: error instanceof Error ? error.message : String(error)
+                            message: error instanceof Error ? error.message : String(error || '')
                         }
                     };
                 }
-                const trace = routeExecution?.trace || { guard: 'none', load: 'none' };
+                const trace = routeExecution?.trace || { guard: 'none', action: 'none', load: 'none' };
                 const routeId = resolved.route.route_id || '';
+                const setCookies = Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : [];
                 if (verboseLogging) {
-                    logger.router(`${routeId || resolved.route.path} guard=${trace.guard} load=${trace.load}`);
+                    logger.router(`${routeId || resolved.route.path} guard=${trace.guard} action=${trace.action} load=${trace.load}`);
                 }
                 const result = routeExecution?.result;
                 if (result && result.kind === 'redirect') {
                     const status = Number.isInteger(result.status) ? result.status : 302;
-                    res.writeHead(status, {
-                        Location: result.location,
+                    res.writeHead(status, appendSetCookieHeaders({
+                        Location: appLocalRedirectLocation(result.location, configuredBasePath),
                         'Cache-Control': 'no-store'
-                    });
+                    }, setCookies));
                     res.end('');
                     return;
                 }
                 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 || defaultRouteDenyMessage(status));
+                    res.writeHead(status, appendSetCookieHeaders({ 'Content-Type': 'text/plain; charset=utf-8' }, setCookies));
+                    res.end(clientFacingRouteMessage(status, result.message));
                     return;
                 }
                 if (result && result.kind === 'data' && result.data && typeof result.data === 'object' && !Array.isArray(result.data)) {
@@ -770,21 +864,24 @@ export async function createDevServer(options) {
                 }
             }
             let content = await _readFileForRequest(filePath, 'utf8');
-            if (resolved.matched && resolved.route?.page_asset) {
-                const pageAssetPath = resolveWithinDist(outDir, resolved.route.page_asset);
+            if (resolved.matched) {
                 content = await materializeImageMarkup({
                     html: content,
-                    pageAssetPath,
                     payload: buildSession.getImageRuntimePayload(),
-                    ssrData: ssrPayload,
-                    routePathname: resolved.route.path || pathname
+                    imageMaterialization: Array.isArray(resolved.route?.image_materialization)
+                        ? resolved.route.image_materialization
+                        : []
                 });
             }
             if (ssrPayload) {
                 content = injectSsrPayload(content, ssrPayload);
             }
-            content = injectImageRuntimePayload(content, buildSession.getImageRuntimePayload());
-            res.writeHead(200, { 'Content-Type': 'text/html' });
+            if (!IMAGE_RUNTIME_TAG_RE.test(content)) {
+                content = injectImageRuntimePayload(content, buildSession.getImageRuntimePayload());
+            }
+            res.writeHead(Number.isInteger(routeExecution?.status) ? routeExecution.status : 200, appendSetCookieHeaders({
+                'Content-Type': 'text/html'
+            }, Array.isArray(routeExecution?.setCookies) ? routeExecution.setCookies : []));
             res.end(content);
         }
         catch (error) {
@@ -907,7 +1004,7 @@ export async function createDevServer(options) {
                 const buildResult = await buildSession.build({ changedFiles, logger });
                 const cssReady = await _syncCssStateFromBuild(buildResult, cycleBuildId);
                 if (!onlyCss) {
-                    currentRoutes = await loadRouteManifest(outDir);
+                    currentRouteState = await loadRouteSurfaceState(outDir, configuredBasePath);
                 }
                 const cssChanged = cssReady && (currentCssAssetPath !== previousCssAssetPath ||
                     currentCssContent !== previousCssContent);

package/dist/download-result.d.ts

@@ -0,0 +1,14 @@
+export function buildAttachmentContentDisposition(filename: any): string;
+export function createDownloadResult(body: any, options?: {}): {
+    kind: string;
+    body: any;
+    bodyEncoding: string;
+    bodySize: number;
+    filename: string;
+    contentType: string;
+    status: number;
+};
+export function assertValidDownloadResult(value: any, where?: string): void;
+export function decodeDownloadResultBody(result: any, where?: string): Buffer<ArrayBuffer>;
+export const DOWNLOAD_PAYLOAD_LIMIT_BYTES: number;
+export const DOWNLOAD_DEFAULT_CONTENT_TYPE: "application/octet-stream";

package/dist/download-result.js

@@ -0,0 +1,148 @@
+export const DOWNLOAD_PAYLOAD_LIMIT_BYTES = 5 * 1024 * 1024;
+export const DOWNLOAD_DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+const CONTROL_CHAR_RE = /[\0-\x1F\x7F]/;
+const PATH_SEPARATOR_RE = /[\\/]/;
+function formatWhere(where = 'download(...)') {
+    return String(where || 'download(...)');
+}
+function normalizeFilename(filename, where = 'download(...)') {
+    const label = formatWhere(where);
+    const value = String(filename ?? '').trim();
+    if (!value) {
+        throw new Error(`[Zenith] ${label}: download filename is required.`);
+    }
+    if (CONTROL_CHAR_RE.test(value) || PATH_SEPARATOR_RE.test(value)) {
+        throw new Error(`[Zenith] ${label}: download filename must not contain path separators or control characters.`);
+    }
+    return value;
+}
+function normalizeContentType(contentType, where = 'download(...)') {
+    const label = formatWhere(where);
+    if (contentType === undefined || contentType === null) {
+        return DOWNLOAD_DEFAULT_CONTENT_TYPE;
+    }
+    const value = String(contentType).trim();
+    if (!value) {
+        throw new Error(`[Zenith] ${label}: download contentType must be a non-empty string when provided.`);
+    }
+    if (CONTROL_CHAR_RE.test(value)) {
+        throw new Error(`[Zenith] ${label}: download contentType must not contain control characters.`);
+    }
+    return value;
+}
+function isBlobLike(value) {
+    return (typeof Blob !== 'undefined' && value instanceof Blob)
+        || (typeof File !== 'undefined' && value instanceof File);
+}
+function encodeBuffer(buffer, encoding) {
+    return encoding === 'utf8'
+        ? buffer.toString('utf8')
+        : buffer.toString('base64');
+}
+function decodeBody(body, bodyEncoding, where = 'download(...)') {
+    const label = formatWhere(where);
+    if (typeof body !== 'string') {
+        throw new Error(`[Zenith] ${label}: download body must be a string after normalization.`);
+    }
+    if (bodyEncoding === 'utf8') {
+        return Buffer.from(body, 'utf8');
+    }
+    if (bodyEncoding === 'base64') {
+        return Buffer.from(body, 'base64');
+    }
+    throw new Error(`[Zenith] ${label}: download bodyEncoding must be "utf8" or "base64".`);
+}
+function normalizeBody(body, where = 'download(...)') {
+    const label = formatWhere(where);
+    if (isBlobLike(body)) {
+        throw new Error(`[Zenith] ${label}: download body must be string, Uint8Array, ArrayBuffer, or Buffer-compatible bytes.`);
+    }
+    if (typeof body === 'string') {
+        const size = Buffer.byteLength(body, 'utf8');
+        if (size > DOWNLOAD_PAYLOAD_LIMIT_BYTES) {
+            throw new Error(`[Zenith] ${label}: download payload exceeds ${DOWNLOAD_PAYLOAD_LIMIT_BYTES} bytes.`);
+        }
+        return {
+            body: body,
+            bodyEncoding: 'utf8',
+            bodySize: size
+        };
+    }
+    if (body instanceof ArrayBuffer) {
+        const buffer = Buffer.from(body);
+        if (buffer.byteLength > DOWNLOAD_PAYLOAD_LIMIT_BYTES) {
+            throw new Error(`[Zenith] ${label}: download payload exceeds ${DOWNLOAD_PAYLOAD_LIMIT_BYTES} bytes.`);
+        }
+        return {
+            body: encodeBuffer(buffer, 'base64'),
+            bodyEncoding: 'base64',
+            bodySize: buffer.byteLength
+        };
+    }
+    if (ArrayBuffer.isView(body)) {
+        const buffer = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+        if (buffer.byteLength > DOWNLOAD_PAYLOAD_LIMIT_BYTES) {
+            throw new Error(`[Zenith] ${label}: download payload exceeds ${DOWNLOAD_PAYLOAD_LIMIT_BYTES} bytes.`);
+        }
+        return {
+            body: encodeBuffer(buffer, 'base64'),
+            bodyEncoding: 'base64',
+            bodySize: buffer.byteLength
+        };
+    }
+    throw new Error(`[Zenith] ${label}: download body must be string, Uint8Array, ArrayBuffer, or Buffer-compatible bytes.`);
+}
+function buildAsciiFilename(filename) {
+    const replaced = Array.from(String(filename || '')).map((char) => {
+        const code = char.charCodeAt(0);
+        if (code < 0x20 || code > 0x7E || char === '"' || char === '\\') {
+            return '_';
+        }
+        return char;
+    }).join('');
+    return replaced || 'download';
+}
+export function buildAttachmentContentDisposition(filename) {
+    const safeFilename = normalizeFilename(filename, 'download result');
+    const asciiFilename = buildAsciiFilename(safeFilename);
+    const encodedFilename = encodeURIComponent(safeFilename)
+        .replace(/['()]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(/\*/g, '%2A');
+    return `attachment; filename="${asciiFilename}"; filename*=UTF-8''${encodedFilename}`;
+}
+export function createDownloadResult(body, options = {}) {
+    const filename = normalizeFilename(options?.filename, 'download(...)');
+    const contentType = normalizeContentType(options?.contentType, 'download(...)');
+    const normalized = normalizeBody(body, 'download(...)');
+    return {
+        kind: 'download',
+        body: normalized.body,
+        bodyEncoding: normalized.bodyEncoding,
+        bodySize: normalized.bodySize,
+        filename,
+        contentType,
+        status: 200
+    };
+}
+export function assertValidDownloadResult(value, where = 'download result') {
+    const label = formatWhere(where);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`[Zenith] ${label}: download result must be an object.`);
+    }
+    normalizeFilename(value.filename, label);
+    normalizeContentType(value.contentType, label);
+    if (value.status !== 200) {
+        throw new Error(`[Zenith] ${label}: download status is fixed to 200 in this milestone.`);
+    }
+    if (!Number.isInteger(value.bodySize) || value.bodySize < 0 || value.bodySize > DOWNLOAD_PAYLOAD_LIMIT_BYTES) {
+        throw new Error(`[Zenith] ${label}: download bodySize must be an integer between 0 and ${DOWNLOAD_PAYLOAD_LIMIT_BYTES}.`);
+    }
+    const buffer = decodeBody(value.body, value.bodyEncoding, label);
+    if (buffer.byteLength !== value.bodySize) {
+        throw new Error(`[Zenith] ${label}: download bodySize does not match the normalized body.`);
+    }
+}
+export function decodeDownloadResultBody(result, where = 'download result') {
+    assertValidDownloadResult(result, where);
+    return decodeBody(result.body, result.bodyEncoding, where);
+}

package/dist/framework-components/Image.zen

@@ -335,4 +335,4 @@ const imageHtml = renderImage();
 const imagePayload = serializeImageProps();
 </script>
 
-<span class="contents" data-zenith-image={imagePayload} innerHTML={imageHtml}></span>
+<span class="contents" data-zenith-image={imagePayload} unsafeHTML={imageHtml}></span>

package/dist/images/materialization-plan.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/images/materialization-plan.js

@@ -0,0 +1,6 @@
+/**
+ * Static Image props are evaluated in the Rust compiler (`zenith-compiler --merge-image-materialization`).
+ * See `mergePageImageMaterialization` in `build/compiler-runtime.js` and `packages/compiler/zenith_compiler/src/image_materialization.rs`.
+ * Legacy CLI-side TypeScript reconstruction was removed in Phase 2 Track B Sub-step 2.
+ */
+export {};

package/dist/images/materialize.d.ts

@@ -3,12 +3,14 @@ type ImagePayload = {
     config: Record<string, unknown>;
     localImages: Record<string, unknown>;
 };
+type ImageMaterializationEntry = {
+    selector?: string;
+    props?: Record<string, unknown> | null;
+};
 export declare function materializeImageMarkup(options: {
     html: string;
-    pageAssetPath?: string | null;
     payload: ImagePayload;
-    ssrData?: Record<string, unknown> | null;
-    routePathname?: string;
+    imageMaterialization?: ImageMaterializationEntry[] | null;
 }): Promise<string>;
 export declare function materializeImageMarkupInHtmlFiles(options: {
     distDir: string;