@vmz/core 0.0.4 → 0.1.0

package/dist/serve-host.d.ts

@@ -1 +1,14 @@
+/**
+ * Generic VMZ Node host — SSR file-route pages + dist static + RPC/REST.
+ *
+ * Invoked by `vmz serve` / `vmz dev` (or: node dist/vmz-serve-host.mjs).
+ *
+ * Pathname → `pages/**` (PascalCase stem → lowercase URL; `index` → parent;
+ * `[Param]` / `[...rest]` dynamic). Not an SPA shell.
+ *
+ * `VMZ_DEV=1`: POST `/__vmz/reload` soft-reloads modules (cache-bust import);
+ * GET `/__vmz/events` SSE notifies the browser:
+ * - island HMR → re-import `entry-client.js` (no full document reload)
+ * - otherwise → `location.reload`
+ */
 export {};

package/dist/serve-host.mjs

@@ -12,13 +12,13 @@
  * - island HMR → re-import `entry-client.js` (no full document reload)
  * - otherwise → `location.reload`
  */
+import { existsSync } from 'node:fs';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
 import http from 'node:http';
 import path from 'node:path';
-import { readdir, writeFile, readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { setServerModuleResolver, setRoutes, handleNodeRequest } from './vmz-runtime.js';
 import { registerComponents, renderToStream, renderToString } from './vmz-dom.js';
+import { handleNodeRequest, setRoutes, setServerModuleResolver } from './vmz-runtime.js';
 const distDir = process.env.VMZ_DIST ? path.resolve(process.env.VMZ_DIST) : path.dirname(fileURLToPath(import.meta.url));
 const host = process.env.VMZ_HOST || '127.0.0.1';
 const port = Number(process.env.VMZ_PORT || process.env.PORT || 5173);
@@ -33,6 +33,8 @@ const pageCtors = new Map();
 let cssEntry = null;
 /** @type {{ defaultThemeId: string, themeIds: string[], activationAttr: string, contentHash: string|null } | null} */
 let styleTheme = null;
+/** Locale route realization artifact from `_vmz/locale-route-realization.json` (optional). */
+let localeArtifact = null;
 /** @type {Set<import('node:http').ServerResponse>} */
 const sseClients = new Set();
 /** In-flight HTTP requests (graceful shutdown drain). */
@@ -94,9 +96,14 @@ async function renderPageStream(pathname, opts = {}) {
     if (isDev && lastDevError && pageCtors.size === 0) {
         return { status: 500, stream: emitDevErrorHtml(lastDevError) };
     }
-    let match = matchFileRoute(pathname, pageCatalog);
+    const localePlan = resolveLocalePath(pathname);
+    if (localePlan.redirectTo) {
+        return { status: 302, redirect: localePlan.redirectTo, headers: { Location: localePlan.redirectTo } };
+    }
+    const routePath = localePlan.restPath || pathname;
+    let match = matchFileRoute(routePath, pageCatalog);
     let status = 200;
-    const gated = await runRouteGate(pathname, match?.chunkId);
+    const gated = await runRouteGate(routePath, match?.chunkId);
     if (gated === 'not_found') {
         match = findRootCatchAll(pageCatalog);
         status = 404;
@@ -121,16 +128,24 @@ async function renderPageStream(pathname, opts = {}) {
         }
         return null;
     }
-    const params = extractRouteParams(match.segs, pathname);
+    const params = extractRouteParams(match.segs, routePath);
     const method = String(opts.method || 'GET').toUpperCase();
+    const localeCtx = {
+        localeId: localePlan.localeId,
+        dir: localePlan.dir,
+        pathname,
+        routePath,
+        alternates: pageMetaAlternates(match.chunkId, localePlan.localeId),
+    };
     if (typeof Page.access === 'function') {
         const access = await Page.access({
             params,
-            pathname,
+            pathname: routePath,
             chunkId: match.chunkId,
             signal: opts.signal,
             searchParams: opts.searchParams,
             method,
+            localeId: localeCtx.localeId,
         });
         const closed = normalizeAccessResult(access);
         if (closed.kind === 'redirect') {
@@ -148,7 +163,7 @@ async function renderPageStream(pathname, opts = {}) {
                     const eventOnlyShell = isEventOnlyShell(resumeEntries.map((e) => e.strategy));
                     return {
                         status: 404,
-                        stream: emitPageHtml(NotFound, catchAll.chunkId, eventOnlyShell, { ...params }, opts),
+                        stream: emitPageHtml(NotFound, catchAll.chunkId, eventOnlyShell, { ...params }, opts, [], localeCtx),
                     };
                 }
             }
@@ -159,12 +174,13 @@ async function renderPageStream(pathname, opts = {}) {
     if (method === 'POST' && typeof Page.action === 'function') {
         const acted = await Page.action({
             params,
-            pathname,
+            pathname: routePath,
             chunkId: match.chunkId,
             signal: opts.signal,
             searchParams: opts.searchParams,
             body: opts.body,
             method,
+            localeId: localeCtx.localeId,
         });
         const actionClosed = normalizeActionResult(acted);
         if (actionClosed.kind === 'redirect') {
@@ -183,10 +199,11 @@ async function renderPageStream(pathname, opts = {}) {
     if (typeof Page.load === 'function') {
         const loaded = await Page.load({
             params,
-            pathname,
+            pathname: routePath,
             chunkId: match.chunkId,
             signal: opts.signal,
             searchParams: opts.searchParams,
+            localeId: localeCtx.localeId,
         });
         if (opts.signal?.aborted) {
             return { status: 499, stream: emitAccessShell('route-nav-cancelled') };
@@ -204,7 +221,7 @@ async function renderPageStream(pathname, opts = {}) {
     const layoutChain = resolveLayoutChain(match.chunkId);
     return {
         status,
-        stream: emitPageHtml(Page, match.chunkId, eventOnlyShell, props, opts, layoutChain),
+        stream: emitPageHtml(Page, match.chunkId, eventOnlyShell, props, opts, layoutChain, localeCtx),
     };
 }
 /**
@@ -274,7 +291,7 @@ async function* emitAccessShell(marker) {
  * @param {{ signal?: AbortSignal, searchParams?: URLSearchParams, cookieHeader?: string }} [opts]
  * @param {string[]} [layoutChain] layout chunk ids outer→inner
  */
-async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {}, layoutChain = []) {
+async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {}, layoutChain = [], localeCtx = {}) {
     const signal = opts.signal;
     const live = isDev
         ? `\n  <script>
@@ -381,15 +398,31 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
     const cssLink = cssEntry ? `  <link rel="stylesheet" href="/${String(cssEntry).replace(/^\/+/, '')}?t=${reloadToken}" />\n` : '';
     const propsJson = JSON.stringify(props ?? {});
     const layoutAttr = layoutChain.length ? ` data-vmz-layout="${escapeAttr(layoutChain.join(','))}"` : '';
+    const localeId = localeCtx.localeId || localeArtifact?.defaultLocale || 'en';
+    const dir = localeCtx.dir || 'ltr';
+    const localeAttr = ` data-vmz-locale="${escapeAttr(localeId)}" data-vmz-dir="${escapeAttr(dir)}"`;
+    const routingJson = localeArtifact?.routing
+        ? escapeAttr(JSON.stringify({
+            strategy: localeArtifact.routing.strategy || 'prefix',
+            defaultPrefix: localeArtifact.routing.defaultPrefix || 'include',
+            defaultLocale: localeArtifact.defaultLocale,
+            locales: (localeArtifact.locales || []).map((l) => l.id),
+        }))
+        : '';
+    const routingAttr = routingJson ? ` data-vmz-locale-routing="${routingJson}"` : '';
+    const hreflangLinks = (localeCtx.alternates || [])
+        .map((a) => `  <link rel="alternate" hreflang="${escapeAttr(a.hreflang)}" href="${escapeAttr(a.href)}" />`)
+        .join('\n');
+    const hreflangBlock = hreflangLinks ? `${hreflangLinks}\n` : '';
     yield `<!DOCTYPE html>
-<html lang="en"${htmlTheme}>
+<html lang="${escapeAttr(localeId)}" data-locale="${escapeAttr(localeId)}" dir="${escapeAttr(dir)}"${routingAttr}${htmlTheme}>
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>VMZ</title>
-${themeBoot}${cssLink}</head>
+${hreflangBlock}${themeBoot}${cssLink}</head>
 <body>
-  <div id="app" data-vmz-page="${escapeAttr(chunkId)}"${layoutAttr} data-vmz-props="${escapeAttr(propsJson)}">`;
+  <div id="app" data-vmz-page="${escapeAttr(chunkId)}"${layoutAttr}${localeAttr} data-vmz-props="${escapeAttr(propsJson)}">`;
     let bodyHtml = '';
     for await (const chunk of renderToStream(Page, props, { signal })) {
         if (signal?.aborted)
@@ -407,6 +440,10 @@ ${themeBoot}${cssLink}</head>
         if (signal?.aborted)
             return;
     }
+    // Locale discipline: same-app Links retain current LocaleId (realization authority).
+    if (localeArtifact && localeId) {
+        bodyHtml = localizeBodyLinksInHost(bodyHtml, localeId, localeArtifact);
+    }
     yield bodyHtml;
     if (signal?.aborted)
         return;
@@ -547,6 +584,12 @@ async function softReload(opts = {}) {
         catch {
             setRoutes([]);
         }
+        try {
+            localeArtifact = JSON.parse(await readFile(path.join(distDir, '_vmz', 'locale-route-realization.json'), 'utf8'));
+        }
+        catch {
+            localeArtifact = null;
+        }
         const componentEntries = await listClientComponents(distDir);
         const nextCatalog = await listPageClientFiles(distDir);
         if (!nextCatalog.length) {
@@ -697,6 +740,130 @@ async function* emitDevErrorHtml(err) {
 function escapeHtml(s) {
     return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
+/**
+ * Resolve LocaleId from pathname using `_vmz/locale-route-realization.json`.
+ * LocaleId is a realization dimension — matching still uses stable route path.
+ * @param {string} pathname
+ */
+function resolveLocalePath(pathname) {
+    const raw = String(pathname || '/');
+    const normalized = raw.length > 1 && raw.endsWith('/') ? raw.slice(0, -1) : raw || '/';
+    if (!localeArtifact) {
+        return { localeId: 'en', dir: 'ltr', restPath: normalized, redirectTo: null };
+    }
+    const supported = (localeArtifact.locales || []).map((l) => l.id);
+    const defaultLocale = localeArtifact.defaultLocale || supported[0] || 'en';
+    const directions = Object.fromEntries((localeArtifact.locales || []).map((l) => [l.id, l.direction || 'ltr']));
+    const routing = localeArtifact.routing || {};
+    const parts = normalized.split('/').filter(Boolean);
+    let localeId = null;
+    let restPath = normalized;
+    if (parts.length && supported.includes(parts[0])) {
+        localeId = parts[0];
+        const rest = parts.slice(1);
+        restPath = rest.length ? `/${rest.join('/')}` : '/';
+    }
+    // omit defaultPrefix: prefixed defaultLocale URL redirects to unprefixed canonical.
+    if (routing.defaultPrefix === 'omit' && localeId === defaultLocale) {
+        return {
+            localeId: defaultLocale,
+            dir: directions[defaultLocale] || 'ltr',
+            restPath,
+            redirectTo: restPath,
+        };
+    }
+    const contentLocale = localeId || defaultLocale;
+    return {
+        localeId: contentLocale,
+        dir: directions[contentLocale] || 'ltr',
+        restPath,
+        redirectTo: null,
+    };
+}
+/**
+ * Realize href for current LocaleId (prefix strategy). Kept local so serve-host
+ * stays free of CLI package imports.
+ * @param {string} href
+ * @param {string} localeId
+ * @param {any} artifact
+ */
+function localizeSameAppHrefHost(href, localeId, artifact) {
+    if (!href || !localeId || !artifact)
+        return href;
+    if (href.startsWith('#') || /^(mailto|tel|javascript):/i.test(href))
+        return href;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('/'))
+        return href;
+    let pathname = String(href);
+    let search = '';
+    let hash = '';
+    const hashIdx = pathname.indexOf('#');
+    if (hashIdx >= 0) {
+        hash = pathname.slice(hashIdx);
+        pathname = pathname.slice(0, hashIdx);
+    }
+    const qIdx = pathname.indexOf('?');
+    if (qIdx >= 0) {
+        search = pathname.slice(qIdx);
+        pathname = pathname.slice(0, qIdx);
+    }
+    if (!pathname)
+        pathname = '/';
+    const supported = (artifact.locales || []).map((l) => l.id).filter(Boolean);
+    const defaultLocale = artifact.defaultLocale || artifact.routing?.defaultLocale;
+    const routing = artifact.routing || {};
+    const strategy = routing.strategy || 'prefix';
+    const defaultPrefix = routing.defaultPrefix || 'include';
+    const parts = pathname.split('/').filter(Boolean);
+    let rest = pathname;
+    if (parts.length && supported.includes(parts[0])) {
+        const r = parts.slice(1);
+        rest = r.length ? `/${r.join('/')}` : '/';
+    }
+    if (rest.length > 1 && rest.endsWith('/'))
+        rest = rest.slice(0, -1);
+    if (!rest.startsWith('/'))
+        rest = `/${rest}`;
+    if (strategy === 'none' || strategy === 'domain')
+        return `${rest}${search}${hash}`;
+    const omitDefault = defaultPrefix === 'omit' && localeId === defaultLocale;
+    if (omitDefault)
+        return `${rest}${search}${hash}`;
+    const pathOut = rest === '/' ? `/${localeId}` : `/${localeId}${rest}`;
+    return `${pathOut}${search}${hash}`;
+}
+/**
+ * @param {string} html
+ * @param {string} localeId
+ * @param {any} artifact
+ */
+function localizeBodyLinksInHost(html, localeId, artifact) {
+    if (!html || !localeId || !artifact)
+        return html;
+    return String(html).replace(/<a\b([^>]*)>/gi, (full, attrs) => {
+        if (!/\bdata-vmz-route\s*=/.test(attrs))
+            return full;
+        const hm = attrs.match(/\bhref\s*=\s*"([^"]*)"/i);
+        if (!hm)
+            return full;
+        const next = localizeSameAppHrefHost(hm[1], localeId, artifact);
+        if (next === hm[1])
+            return full;
+        const newAttrs = attrs.replace(/\bhref\s*=\s*"[^"]*"/i, `href="${escapeAttr(next)}"`);
+        return `<a${newAttrs}>`;
+    });
+}
+/**
+ * @param {string} chunkId
+ * @param {string} localeId
+ */
+function pageMetaAlternates(chunkId, localeId) {
+    if (!localeArtifact?.pageMetas)
+        return [];
+    const meta = localeArtifact.pageMetas.find((m) => m.routeId === chunkId && m.locale === localeId) ||
+        localeArtifact.pageMetas.find((m) => m.routeId === chunkId && m.locale === localeArtifact.defaultLocale);
+    return Array.isArray(meta?.alternates) ? meta.alternates : [];
+}
 /** @param {string} href */
 function bustUrl(href) {
     const u = new URL(href);
@@ -977,7 +1144,7 @@ globalThis.__vmzLoadComponent = async (name) => {
     return `/**
  * Generated by vmz serve — hydrate matched file-route page (data-vmz-page) + layout chain + client Link takeover.
  */
-import { registerComponents, hydrate, hydrateRoute, destroy } from ${JSON.stringify(`./vmz-dom.js${q}`)};
+import { registerComponents, hydrate, hydrateRoute, hydrateRoutePage, destroy } from ${JSON.stringify(`./vmz-dom.js${q}`)};
 import { installClientNavigation } from ${JSON.stringify(`./vmz-client-nav.js${q}`)};
 ${imports}
 
@@ -1003,6 +1170,7 @@ await hydrateRoute(Page, root, props, layoutCtors);
 installClientNavigation({
   hydrate,
   hydrateRoute,
+  hydrateRoutePage,
   destroy,
   importPage: async (id) => (await import("./" + id + ".client.js${q}")).default,
 });

package/dist/server.d.ts

@@ -29,8 +29,16 @@ export declare function handleRpc(body: any): Promise<any>;
  * @returns {Route | null}
  */
 export declare function matchRoute(verb: any, pathname: any): any;
+/**
+ * Web Standards Fetch entry for ServerArtifact hosts (Node adapter, worker/edge parity).
+ * Handles RPC + public ServerRoute only; static/SSR stay on Node host options.
+ * @param {Request} request
+ * @returns {Promise<Response>}
+ */
+export declare function handleFetchRequest(request: any): Promise<Response>;
 /**
  * Node `http.createServer` listener: RPC + REST + optional static / SSR index.
+ * RPC/REST go through {@link handleFetchRequest} so Node and Fetch hosts share one core.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
  * @param {NodeRequestOptions} [opts]

package/dist/server.js

@@ -106,8 +106,95 @@ export function matchRoute(verb, pathname) {
     const v = verb.toUpperCase();
     return routes.find((r) => r.verb.toUpperCase() === v && r.path === pathname) ?? null;
 }
+/**
+ * Build `callServerLocal` args from a Fetch Request for REST routes.
+ * GET/HEAD → `[]`. JSON POST/PUT/PATCH → `[body]`. form-urlencoded → `[record]`.
+ * Multipart → `[record]` where File/Blob parts stay as File/Blob (tool-site binary upload).
+ * Octet-stream PUT also forwards Upload resumable chunk headers (upload-id / chunk-index / chunk-total).
+ * Extra args are ignored by zero-parameter server methods (JS).
+ * @param {Request} request
+ * @param {string} verb
+ * @returns {Promise<unknown[]>}
+ */
+async function routeArgsFromRequest(request, verb) {
+    const v = String(verb || 'GET').toUpperCase();
+    if (v === 'GET' || v === 'HEAD' || v === 'OPTIONS')
+        return [];
+    const ctype = String(request.headers.get('content-type') || '');
+    if (ctype.includes('application/json')) {
+        const text = await request.text();
+        if (!text || !String(text).trim())
+            return [{}];
+        try {
+            return [JSON.parse(text)];
+        }
+        catch (err) {
+            throw new Error(`invalid JSON body: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (ctype.includes('multipart/form-data')) {
+        // Parse from raw bytes — undici Request.formData() can UTF-8-mangle high bytes in file parts
+        // (0xFF/0xFE → U+FFFD), which breaks Upload binary / tool-site intakes.
+        const buf = Buffer.from(await request.arrayBuffer());
+        return [parseMultipartBuffer(buf, ctype)];
+    }
+    // Object-store PUT / resumable chunk PUT — keep bytes (never request.text()).
+    if (ctype.includes('application/octet-stream') ||
+        ((v === 'PUT' || v === 'PATCH') && !ctype.includes('json') && !ctype.includes('x-www-form-urlencoded'))) {
+        const buf = Buffer.from(await request.arrayBuffer());
+        const key = String(request.headers.get('x-vmz-object-key') || '');
+        const uploadId = String(request.headers.get('x-vmz-upload-id') || '');
+        const chunkIndexRaw = request.headers.get('x-vmz-chunk-index');
+        const chunkTotalRaw = request.headers.get('x-vmz-chunk-total');
+        const chunkIndex = chunkIndexRaw != null && String(chunkIndexRaw).trim() !== '' ? Number(chunkIndexRaw) : undefined;
+        const chunkTotal = chunkTotalRaw != null && String(chunkTotalRaw).trim() !== '' ? Number(chunkTotalRaw) : undefined;
+        return [
+            {
+                bytes: buf,
+                size: buf.byteLength,
+                key,
+                uploadId,
+                chunkIndex: Number.isFinite(chunkIndex) ? chunkIndex : undefined,
+                chunkTotal: Number.isFinite(chunkTotal) ? chunkTotal : undefined,
+                contentType: ctype || 'application/octet-stream',
+            },
+        ];
+    }
+    const raw = await request.text();
+    return [parseFormBody(raw, ctype)];
+}
+/**
+ * Web Standards Fetch entry for ServerArtifact hosts (Node adapter, worker/edge parity).
+ * Handles RPC + public ServerRoute only; static/SSR stay on Node host options.
+ * @param {Request} request
+ * @returns {Promise<Response>}
+ */
+export async function handleFetchRequest(request) {
+    const url = new URL(request.url);
+    const verb = (request.method || 'GET').toUpperCase();
+    try {
+        if (verb === 'POST' && url.pathname === DEFAULT_RPC_PATH) {
+            const body = await request.json();
+            const result = await handleRpc(body);
+            return Response.json(result);
+        }
+        const route = matchRoute(verb, url.pathname);
+        if (route) {
+            const args = await routeArgsFromRequest(request, verb);
+            const result = await callServerLocal(route.moduleId, route.method, args);
+            return Response.json(result);
+        }
+        return Response.json({ error: 'not found', path: url.pathname }, { status: 404 });
+    }
+    catch (err) {
+        return Response.json({
+            error: err instanceof Error ? err.message : String(err),
+        }, { status: 500 });
+    }
+}
 /**
  * Node `http.createServer` listener: RPC + REST + optional static / SSR index.
+ * RPC/REST go through {@link handleFetchRequest} so Node and Fetch hosts share one core.
  * @param {import('node:http').IncomingMessage} req
  * @param {import('node:http').ServerResponse} res
  * @param {NodeRequestOptions} [opts]
@@ -117,15 +204,12 @@ export async function handleNodeRequest(req, res, opts = {}) {
     const url = new URL(req.url || '/', `http://${host}`);
     const verb = (req.method || 'GET').toUpperCase();
     try {
-        if (verb === 'POST' && url.pathname === DEFAULT_RPC_PATH) {
-            const body = await readJson(req);
-            const result = await handleRpc(body);
-            return sendJson(res, 200, result);
-        }
+        const isRpc = verb === 'POST' && url.pathname === DEFAULT_RPC_PATH;
         const route = matchRoute(verb, url.pathname);
-        if (route) {
-            const result = await callServerLocal(route.moduleId, route.method, []);
-            return sendJson(res, 200, result);
+        if (isRpc || route) {
+            const request = await incomingToRequest(req, url);
+            const response = await handleFetchRequest(request);
+            return await writeFetchResponse(res, response);
         }
         // Static first for assets + DocumentMount (`/d/…`) so docs aren't swallowed by SSR 404 shells.
         // web-static route HTML (`index.html`, `about/index.html`, …) is a CDN/deploy projection only —
@@ -247,6 +331,43 @@ export async function handleNodeRequest(req, res, opts = {}) {
         });
     }
 }
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {URL} url
+ * @returns {Promise<Request>}
+ */
+async function incomingToRequest(req, url) {
+    const method = (req.method || 'GET').toUpperCase();
+    /** @type {HeadersInit} */
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v == null)
+            continue;
+        headers[k] = Array.isArray(v) ? v.join(', ') : String(v);
+    }
+    if (method === 'GET' || method === 'HEAD') {
+        return new Request(url, { method, headers });
+    }
+    const raw = await readRawBody(req);
+    // Node undici requires duplex when constructing Request with a body.
+    return new Request(url, { method, headers, body: raw, duplex: 'half' });
+}
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {Response} response
+ */
+async function writeFetchResponse(res, response) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    const buf = Buffer.from(await response.arrayBuffer());
+    if (!headers['content-length'] && !headers['Content-Length']) {
+        headers['content-length'] = String(buf.byteLength);
+    }
+    res.writeHead(response.status, headers);
+    res.end(buf);
+}
 /**
  * Resolve a path under distDir; reject `..` escapes.
  * @param {string} distDir
@@ -402,16 +523,103 @@ function readJson(req) {
 }
 /**
  * @param {import('node:http').IncomingMessage} req
- * @returns {Promise<string>}
+ * @returns {Promise<Buffer>}
  */
 function readRawBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
         req.on('data', (c) => chunks.push(c));
-        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        // Buffer — never utf8-string: multipart File bytes must survive (Upload binary gate).
+        req.on('end', () => resolve(Buffer.concat(chunks)));
         req.on('error', reject);
     });
 }
+/**
+ * Buffer-safe multipart/form-data parser (file parts stay binary).
+ * @param {Buffer} buf
+ * @param {string} contentType
+ * @returns {Record<string, unknown>}
+ */
+function parseMultipartBuffer(buf, contentType) {
+    const bm = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(String(contentType || ''));
+    const boundary = bm ? bm[1] || bm[2] : '';
+    if (!boundary) {
+        throw new Error('multipart: missing boundary');
+    }
+    const sep = Buffer.from(`--${boundary}`);
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    let start = indexOfBuffer(buf, sep, 0);
+    if (start < 0)
+        return out;
+    start += sep.length;
+    // Optional leading CRLF after first boundary is handled per-part.
+    while (start < buf.length) {
+        if (buf[start] === 0x2d && buf[start + 1] === 0x2d)
+            break; // trailing --
+        if (buf[start] === 0x0d && buf[start + 1] === 0x0a)
+            start += 2;
+        const next = indexOfBuffer(buf, sep, start);
+        const end = next < 0 ? buf.length : next;
+        let part = buf.subarray(start, end);
+        // Trim trailing CRLF before boundary.
+        if (part.length >= 2 && part[part.length - 2] === 0x0d && part[part.length - 1] === 0x0a) {
+            part = part.subarray(0, part.length - 2);
+        }
+        const splitAt = indexOfBuffer(part, Buffer.from('\r\n\r\n'), 0);
+        if (splitAt >= 0) {
+            const headerText = part.subarray(0, splitAt).toString('utf8');
+            let body = part.subarray(splitAt + 4);
+            const nameM = /content-disposition:[^\r\n]*;\s*name="([^"]*)"/i.exec(headerText);
+            const fileM = /content-disposition:[^\r\n]*;\s*filename="([^"]*)"/i.exec(headerText);
+            const typeM = /content-type:\s*([^\r\n]+)/i.exec(headerText);
+            const key = nameM ? nameM[1] : '';
+            if (key) {
+                if (fileM) {
+                    const filename = fileM[1] || 'upload.bin';
+                    const type = typeM ? String(typeM[1]).trim() : 'application/octet-stream';
+                    // Copy body — File may outlive the request buffer.
+                    const copy = Buffer.from(body);
+                    const file = new File([copy], filename, { type });
+                    const prev = out[key];
+                    if (prev == null) {
+                        out[key] = file;
+                    }
+                    else if (Array.isArray(prev)) {
+                        prev.push(file);
+                    }
+                    else {
+                        out[key] = [prev, file];
+                    }
+                }
+                else {
+                    out[key] = body.toString('utf8');
+                }
+            }
+        }
+        if (next < 0)
+            break;
+        start = next + sep.length;
+    }
+    return out;
+}
+/**
+ * @param {Buffer} hay
+ * @param {Buffer} needle
+ * @param {number} from
+ */
+function indexOfBuffer(hay, needle, from) {
+    if (!needle.length)
+        return from;
+    outer: for (let i = Math.max(0, from); i <= hay.length - needle.length; i++) {
+        for (let j = 0; j < needle.length; j++) {
+            if (hay[i + j] !== needle[j])
+                continue outer;
+        }
+        return i;
+    }
+    return -1;
+}
 /**
  * @param {string} raw
  * @param {string} contentType

package/dist/vmz-dom.d.ts

@@ -0,0 +1,5 @@
+/**
+ * App-dist alias: compiler copies dom.js → vmz-dom.js.
+ * Package-local serve-host imports this path during `@vmz/core` build.
+ */
+export * from './dom.js';

package/dist/vmz-dom.js

@@ -0,0 +1,6 @@
+// @ts-nocheck
+/**
+ * App-dist alias: compiler copies dom.js → vmz-dom.js.
+ * Package-local serve-host imports this path during `@vmz/core` build.
+ */
+export * from './dom.js';

package/dist/vmz-runtime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * App-dist alias: compiler copies server.js → vmz-runtime.js.
+ * Package-local serve-host imports this path during `@vmz/core` build.
+ */
+export * from './server.js';

package/dist/vmz-runtime.js

@@ -0,0 +1,6 @@
+// @ts-nocheck
+/**
+ * App-dist alias: compiler copies server.js → vmz-runtime.js.
+ * Package-local serve-host imports this path during `@vmz/core` build.
+ */
+export * from './server.js';