@tyndall/runtime 0.0.1

package/README.md

@@ -0,0 +1,32 @@
+# @tyndall/runtime
+
+## Overview
+Runtime HTTP serving package for static routes, SSR execution, and route payload responses.
+
+## Responsibilities
+- Start runtime server using generated artifacts
+- Serve static assets and route payload responses
+- Run SSR handlers when route metadata requires server rendering
+- Stream SSR responses when server entries provide `renderToStream`
+- Resolve client/server chunk files using manifest asset metadata (`assets.assetsDir`)
+- Emit module or classic script tags based on manifest `assets.scriptType`
+- Emit build version markers and append `?v=` to script URLs when manifest versioning is configured
+
+## Public API Highlights
+- createServer
+- createExpressHandler
+- createFastifyPlugin
+
+## Development
+- Build: bun run --filter @tyndall/runtime build
+- Test (from workspace root): bun test
+
+## Documentation
+- Package specification: [spec.md](./spec.md)
+- Package architecture: [architecture.md](./architecture.md)
+- Package changes: [CHANGELOG.md](./CHANGELOG.md)
+
+## Maintenance Rules
+- Keep this document aligned with implemented package behavior.
+- Update spec.md and architecture.md whenever package contracts or design boundaries change.
+- Record user-visible package changes in CHANGELOG.md.

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { type DynamicPageApiProvider, type Manifest, type ResolverFallbackPolicy, type UIAdapterFactory, type UIAdapterRegistry } from "@tyndall/core";
+export interface RuntimeHandlerOptions {
+    distDir?: string;
+    dynamicPageApi?: DynamicPageApiProvider;
+    adapterRegistry?: UIAdapterRegistry;
+    uiAdapter?: string | UIAdapterFactory;
+    uiOptions?: Record<string, unknown>;
+    fallbackPolicy?: ResolverFallbackPolicy;
+    appMode?: "ssg" | "ssr";
+}
+export interface RuntimeServerOptions extends RuntimeHandlerOptions {
+    port?: number;
+    host?: string;
+}
+export interface RuntimeServer {
+    host: string;
+    port: number;
+    url: string;
+    close: () => Promise<void>;
+}
+export declare const loadManifest: (distDir: string) => Promise<Manifest>;
+export declare const createServer: (options?: RuntimeServerOptions) => Promise<RuntimeServer>;
+export declare const createExpressHandler: (options?: RuntimeHandlerOptions) => (request: {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string | string[] | undefined>;
+}, response: {
+    statusCode: number;
+    setHeader: (key: string, value: string) => void;
+    end: (body?: string | Uint8Array) => void;
+    write?: (chunk: string | Uint8Array) => void;
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+    once?: (event: string, listener: (...args: unknown[]) => void) => void;
+    removeListener?: (event: string, listener: (...args: unknown[]) => void) => void;
+    flushHeaders?: () => void;
+}, next?: (error?: unknown) => void) => void;
+export declare const createFastifyPlugin: (options?: RuntimeHandlerOptions) => (fastify: {
+    all: (path: string, routeHandler: (req: any, reply: any) => Promise<void>) => void;
+}) => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAQL,KAAK,sBAAsB,EAE3B,KAAK,QAAQ,EAMb,KAAK,sBAAsB,EAG3B,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAGvB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,OAAO,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;CACzB;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AA4fD,eAAO,MAAM,YAAY,GAAU,SAAS,MAAM,KAAG,OAAO,CAAC,QAAQ,CAyBpE,CAAC;AAgeF,eAAO,MAAM,YAAY,GACvB,UAAS,oBAAyB,KACjC,OAAO,CAAC,aAAa,CAkCvB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,UAAS,qBAA0B,MAGpE,SAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;CAAE,EACnG,UAAU;IACR,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,KAAK,IAAI,CAAC;IAC1C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,KAAK,IAAI,CAAC;IAC7C,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IACrE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;IACjF,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,EACD,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,SAYnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,UAAS,qBAA0B,MAEvD,SAAS;IAAE,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;CAAE,kBAa9G,CAAC"}

package/dist/index.js

@@ -0,0 +1,815 @@
+import { createServer as createHttpServer } from "node:http";
+import { createRequire } from "node:module";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { handleDynamicPageApiRequest, HyperError, resolveRouteWithPolicyFallback, resolveUIAdapter, runGetServerProps, serializeProps, validateManifest, } from "@tyndall/core";
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+};
+const MANIFEST_FILE = "manifest.json";
+const NAVIGATION_HEADER = "x-hyper-navigation";
+const NAVIGATION_MODE = "csr";
+const DYNAMIC_FALLBACK_HEADER = "x-hyper-dynamic-fallback";
+const RENDER_WARNINGS_HEADER = "x-hyper-render-warnings";
+const resolveFilePath = (distDir, urlPath) => {
+    const sanitized = urlPath.split("?")[0].split("#")[0];
+    const withIndex = sanitized.endsWith("/") || sanitized === "" ? `${sanitized}index.html` : sanitized;
+    const fullPath = resolve(distDir, `.${withIndex}`);
+    // Important: block path traversal outside the dist directory.
+    if (!fullPath.startsWith(resolve(distDir))) {
+        return null;
+    }
+    return fullPath;
+};
+const normalizeAssetsDir = (value) => value.replace(/^\/+|\/+$/g, "");
+const resolveAssetPath = (distDir, urlPath, assetsDir) => {
+    const normalizedAssetsDir = normalizeAssetsDir(assetsDir);
+    const prefix = `/${normalizedAssetsDir}/`;
+    if (!urlPath.startsWith(prefix)) {
+        return null;
+    }
+    const fullPath = resolve(distDir, `.${urlPath}`);
+    if (!fullPath.startsWith(resolve(distDir))) {
+        return null;
+    }
+    return fullPath;
+};
+const computeEtag = (stats) => `W/\"${stats.size}-${Math.trunc(stats.mtimeMs)}\"`;
+const readStaticFile = async (filePath) => {
+    const data = await readFile(filePath);
+    const ext = extname(filePath);
+    return {
+        body: data,
+        contentType: CONTENT_TYPES[ext] ?? "application/octet-stream",
+    };
+};
+const buildRuntimeRouteGraph = (manifest) => {
+    const routes = [];
+    const orderedIds = Object.keys(manifest.routes).sort((a, b) => a.localeCompare(b));
+    for (const routeId of orderedIds) {
+        const segments = [];
+        const trimmed = routeId.replace(/^\/+/, "");
+        const parts = trimmed ? trimmed.split("/") : [];
+        for (const part of parts) {
+            if (part.startsWith(":")) {
+                const name = part.slice(1);
+                if (!name) {
+                    throw new HyperError("ROUTE_INVALID", `Invalid dynamic segment in route: ${routeId}`, {
+                        routeId,
+                    });
+                }
+                segments.push({ type: "dynamic", name });
+                continue;
+            }
+            if (part.startsWith("*")) {
+                const name = part.slice(1);
+                if (!name) {
+                    throw new HyperError("ROUTE_INVALID", `Invalid catch-all segment in route: ${routeId}`, {
+                        routeId,
+                    });
+                }
+                segments.push({ type: "catchAll", name });
+                continue;
+            }
+            segments.push({ type: "static", value: part });
+        }
+        routes.push({ id: routeId, filePath: routeId, segments });
+    }
+    return { routes };
+};
+const resolveManifestFile = (distDir, entryPath) => {
+    const fullPath = resolve(distDir, entryPath);
+    const base = resolve(distDir);
+    if (!fullPath.startsWith(base)) {
+        return null;
+    }
+    return fullPath;
+};
+const stripBasePath = (pathname, basePath) => {
+    if (!basePath || basePath === "/") {
+        return pathname;
+    }
+    if (pathname.startsWith(basePath)) {
+        const next = pathname.slice(basePath.length);
+        return next.startsWith("/") ? next : `/${next}`;
+    }
+    return pathname;
+};
+const isNavigationRequest = (request) => {
+    const raw = request.headers?.[NAVIGATION_HEADER];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return typeof value === "string" && value.toLowerCase() === NAVIGATION_MODE;
+};
+const setRenderWarningsHeader = (response, warnings) => {
+    if (!warnings || warnings.length === 0) {
+        return;
+    }
+    response.setHeader(RENDER_WARNINGS_HEADER, warnings.join(" | "));
+};
+const resolveRuntimePropsSerializer = (options) => {
+    if (!options.uiAdapter) {
+        return serializeProps;
+    }
+    // Keep SSR payload serialization aligned with the active UI adapter when configured.
+    const adapter = resolveUIAdapter(options.uiAdapter, options.uiOptions ?? {}, options.adapterRegistry ?? {});
+    return adapter.serializeProps ?? serializeProps;
+};
+const parseAttributeMap = (value) => {
+    const attributes = {};
+    const attributePattern = /([a-zA-Z0-9:_-]+)\s*=\s*["']([^"']*)["']/g;
+    let match;
+    while ((match = attributePattern.exec(value)) !== null) {
+        attributes[match[1]] = match[2];
+    }
+    return attributes;
+};
+const extractAppFragment = (html) => {
+    const start = html.match(/<div[^>]*id=["']app["'][^>]*>/i);
+    if (!start || start.index === undefined) {
+        return null;
+    }
+    const openTag = start[0];
+    const bodyStart = start.index + openTag.length;
+    const openDivPattern = /<div\b[^>]*>/gi;
+    const closeDivPattern = /<\/div>/gi;
+    let depth = 1;
+    let cursor = bodyStart;
+    while (depth > 0) {
+        openDivPattern.lastIndex = cursor;
+        closeDivPattern.lastIndex = cursor;
+        const nextOpen = openDivPattern.exec(html);
+        const nextClose = closeDivPattern.exec(html);
+        if (!nextClose) {
+            return null;
+        }
+        if (nextOpen && nextOpen.index < nextClose.index) {
+            depth += 1;
+            cursor = nextOpen.index + nextOpen[0].length;
+            continue;
+        }
+        depth -= 1;
+        if (depth === 0) {
+            return {
+                startTag: openTag,
+                appHtml: html.slice(bodyStart, nextClose.index),
+            };
+        }
+        cursor = nextClose.index + nextClose[0].length;
+    }
+    return null;
+};
+const extractScriptPayload = (html) => {
+    const match = html.match(/<script[^>]*id=["']__HYPER_PROPS__["'][^>]*>([\s\S]*?)<\/script>/i);
+    return match?.[1] ?? "{}";
+};
+const extractHeadFromHtml = (html) => {
+    const head = {};
+    const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+    if (!headMatch) {
+        return head;
+    }
+    const body = headMatch[1];
+    const titleMatch = body.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    if (titleMatch) {
+        head.title = titleMatch[1];
+    }
+    const meta = [];
+    const link = [];
+    const script = [];
+    const metaPattern = /<meta\s+([^>]*?)>/gi;
+    const linkPattern = /<link\s+([^>]*?)>/gi;
+    const scriptPattern = /<script\s+([^>]*?)><\/script>/gi;
+    let match;
+    while ((match = metaPattern.exec(body)) !== null) {
+        meta.push(parseAttributeMap(match[1]));
+    }
+    while ((match = linkPattern.exec(body)) !== null) {
+        link.push(parseAttributeMap(match[1]));
+    }
+    while ((match = scriptPattern.exec(body)) !== null) {
+        script.push(parseAttributeMap(match[1]));
+    }
+    if (meta.length > 0) {
+        head.meta = meta;
+    }
+    if (link.length > 0) {
+        head.link = link;
+    }
+    if (script.length > 0) {
+        head.script = script;
+    }
+    return head;
+};
+const extractNavigationPayloadFromHtml = (html, fallbackRouteId) => {
+    const app = extractAppFragment(html);
+    if (!app) {
+        return null;
+    }
+    const attrs = parseAttributeMap(app.startTag);
+    return {
+        kind: "hyper-route-payload",
+        routeId: attrs["data-hyper-route"] ?? fallbackRouteId,
+        appHtml: app.appHtml,
+        propsPayload: extractScriptPayload(html),
+        head: extractHeadFromHtml(html),
+        hydration: attrs["data-hyper-hydration"] === "islands" ? "islands" : "full",
+    };
+};
+const renderRuntimePlaceholder = (routeId) => [
+    "<!doctype html>",
+    "<html data-hyper-ssr=\"true\">",
+    "<head>",
+    `<title>SSR ${routeId}</title>`,
+    "</head>",
+    "<body>",
+    `<main data-hyper-ssr=\"true\">SSR Route: ${routeId}</main>`,
+    "</body>",
+    "</html>",
+].join("");
+const renderRuntimeDynamicFallback = (pathname) => [
+    "<!doctype html>",
+    "<html>",
+    "<head>",
+    `<title>Dynamic ${pathname}</title>`,
+    "</head>",
+    "<body>",
+    `<main data-hyper-dynamic=\"true\">Dynamic Route: ${pathname}</main>`,
+    "</body>",
+    "</html>",
+].join("");
+const renderHeadDescriptor = (head) => {
+    const parts = [];
+    if (head.title) {
+        parts.push(`<title>${head.title}</title>`);
+    }
+    for (const meta of head.meta ?? []) {
+        const attrs = Object.entries(meta)
+            .map(([key, value]) => `${key}="${value}"`)
+            .join(" ");
+        parts.push(`<meta ${attrs}>`);
+    }
+    for (const link of head.link ?? []) {
+        const attrs = Object.entries(link)
+            .map(([key, value]) => `${key}="${value}"`)
+            .join(" ");
+        parts.push(`<link ${attrs}>`);
+    }
+    for (const script of head.script ?? []) {
+        const attrs = Object.entries(script)
+            .map(([key, value]) => `${key}="${value}"`)
+            .join(" ");
+        parts.push(`<script ${attrs}></script>`);
+    }
+    return parts.join("");
+};
+const escapeHtml = (value) => value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\"/g, "&quot;");
+const renderScriptTags = (scripts, scriptType) => scripts
+    .map((src) => scriptType === "classic"
+    ? `<script src=\"${src}\"></script>`
+    : `<script type=\"module\" src=\"${src}\"></script>`)
+    .join("");
+const renderSsrHtmlFragments = (routeId, head, propsPayload, scripts, hydration, scriptType, buildVersion) => {
+    const headHtml = renderHeadDescriptor(head);
+    const scriptsHtml = renderScriptTags(scripts, scriptType);
+    const islandAttr = hydration === "islands" ? " data-hyper-island-root=\"router\"" : "";
+    const buildVersionMeta = buildVersion
+        ? `<meta name=\"hyper-build-version\" content=\"${escapeHtml(buildVersion)}\">`
+        : "";
+    const buildVersionAttr = buildVersion
+        ? ` data-hyper-build-version=\"${escapeHtml(buildVersion)}\"`
+        : "";
+    const prefix = [
+        "<!doctype html>",
+        `<html${buildVersionAttr}>`,
+        "<head>",
+        headHtml,
+        buildVersionMeta,
+        "</head>",
+        "<body>",
+        `<div id=\"app\" data-hyper-route=\"${routeId}\" data-hyper-hydration=\"${hydration}\"${islandAttr}>`,
+    ].join("");
+    const suffix = [
+        "</div>",
+        `<script id=\"__HYPER_PROPS__\" type=\"application/json\">${propsPayload}</script>`,
+        `<script>window.__HYPER_ROUTE_ID__ = ${JSON.stringify(routeId)};</script>`,
+        scriptsHtml,
+        "</body>",
+        "</html>",
+    ].join("");
+    return { prefix, suffix };
+};
+const renderSsrHtml = (routeId, html, head, propsPayload, scripts, hydration, scriptType, buildVersion) => {
+    const { prefix, suffix } = renderSsrHtmlFragments(routeId, head, propsPayload, scripts, hydration, scriptType, buildVersion);
+    return `${prefix}${html}${suffix}`;
+};
+const resolveScriptUrl = (basePath, file) => {
+    const withSlash = file.startsWith("/") ? file : `/${file}`;
+    if (!basePath || basePath === "/") {
+        return withSlash;
+    }
+    return `${basePath}${withSlash}`;
+};
+const resolveChunkFilePath = (distDir, assetsDir, file) => {
+    const normalized = file.replace(/^\/+/, "");
+    const relativePath = normalized.includes("/") ? normalized : `${assetsDir}/${normalized}`;
+    return resolveManifestFile(distDir, relativePath);
+};
+const resolveChunkScripts = (manifest, entryKey, basePath, assetsDir, buildVersion) => {
+    const scripts = [];
+    const visited = new Set();
+    const walk = (key) => {
+        if (visited.has(key)) {
+            return;
+        }
+        visited.add(key);
+        const chunk = manifest.chunks[key];
+        if (!chunk) {
+            return;
+        }
+        for (const dep of chunk.imports ?? []) {
+            walk(dep);
+        }
+        const normalized = chunk.file.replace(/^\/+/, "");
+        const filePath = normalized.includes("/") ? normalized : `${assetsDir}/${normalized}`;
+        scripts.push(appendBuildVersion(resolveScriptUrl(basePath, filePath), buildVersion));
+    };
+    walk(entryKey);
+    return scripts;
+};
+const resolveScriptType = (manifest) => manifest.assets?.scriptType === "classic" ? "classic" : "module";
+const isExternalUrl = (value) => value.startsWith("http://") || value.startsWith("https://") || value.startsWith("//");
+const appendBuildVersion = (value, buildVersion) => {
+    if (!buildVersion) {
+        return value;
+    }
+    if (isExternalUrl(value)) {
+        return value;
+    }
+    const separator = value.includes("?") ? "&" : "?";
+    return `${value}${separator}v=${encodeURIComponent(buildVersion)}`;
+};
+const loadServerModule = async (filePath) => {
+    const moduleUrl = pathToFileURL(filePath).href;
+    try {
+        return await import(moduleUrl);
+    }
+    catch {
+        const require = createRequire(import.meta.url);
+        return require(filePath);
+    }
+};
+export const loadManifest = async (distDir) => {
+    const manifestPath = join(distDir, MANIFEST_FILE);
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf-8");
+    }
+    catch (error) {
+        throw new HyperError("MANIFEST_INVALID", `Manifest file not found: ${manifestPath}`, { path: manifestPath }, error);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new HyperError("MANIFEST_INVALID", `Manifest JSON is invalid: ${manifestPath}`, { path: manifestPath }, error);
+    }
+    return validateManifest(parsed);
+};
+const createRuntimeContext = async (options) => {
+    const distDir = resolve(options.distDir ?? join(process.cwd(), "dist"));
+    // Critical: validate manifest on startup to keep runtime/render expectations aligned.
+    const manifest = await loadManifest(distDir);
+    const routeGraph = buildRuntimeRouteGraph(manifest);
+    const basePath = manifest.basePath ?? "";
+    const assetsDir = typeof manifest.assets?.assetsDir === "string" && manifest.assets.assetsDir.length > 0
+        ? normalizeAssetsDir(manifest.assets.assetsDir)
+        : "assets";
+    const serializeRouteProps = resolveRuntimePropsSerializer(options);
+    const resolveServerEntryModule = async (entry) => {
+        if (!entry.serverEntry) {
+            throw new Error("Missing server entry for SSR route.");
+        }
+        const chunk = manifest.chunks[entry.serverEntry];
+        if (!chunk) {
+            throw new HyperError("MANIFEST_INVALID", "Missing server chunk for entry.", {
+                entry: entry.serverEntry,
+            });
+        }
+        const serverFile = resolveChunkFilePath(distDir, assetsDir, chunk.file);
+        if (!serverFile) {
+            throw new HyperError("MANIFEST_INVALID", "Invalid server entry file path.", {
+                entry: entry.serverEntry,
+                file: chunk.file,
+            });
+        }
+        return await loadServerModule(serverFile);
+    };
+    const renderSsrRoute = async (entry, routeId, params, request, response) => {
+        const serverModule = await resolveServerEntryModule(entry);
+        const renderToHtml = serverModule?.renderToHtml;
+        if (typeof renderToHtml !== "function") {
+            throw new HyperError("MANIFEST_INVALID", "Server entry missing renderToHtml export.", {
+                entry: entry.serverEntry,
+            });
+        }
+        const getServerProps = serverModule?.getServerProps ??
+            serverModule?.getServerSideProps;
+        // Important: resolve server props before render so SSR output matches data contracts.
+        const serverProps = getServerProps
+            ? await runGetServerProps(getServerProps, {
+                routeId,
+                params,
+                request,
+                response,
+            })
+            : null;
+        const props = serverProps?.props ?? {};
+        const renderResult = await renderToHtml({ routeId, params, props });
+        const scripts = resolveChunkScripts(manifest, entry.clientEntry, basePath, assetsDir, manifest.version);
+        const scriptType = resolveScriptType(manifest);
+        const propsPayload = serializeRouteProps(props);
+        const hydration = serverModule?.hydration === "full" || serverModule?.hydration === "islands"
+            ? serverModule.hydration
+            : "islands";
+        const payload = {
+            kind: "hyper-route-payload",
+            routeId,
+            appHtml: renderResult.html,
+            propsPayload,
+            head: renderResult.head ?? {},
+            hydration,
+        };
+        const finalHtml = renderSsrHtml(routeId, payload.appHtml, payload.head, payload.propsPayload, scripts, hydration, scriptType, manifest.version);
+        return {
+            payload,
+            html: finalHtml,
+            status: renderResult.status ?? serverProps?.status ?? 200,
+            headers: {
+                ...(serverProps?.headers ?? {}),
+                ...(renderResult.headers ?? {}),
+            },
+        };
+    };
+    const renderSsrStream = async (entry, routeId, params, request, response) => {
+        const serverModule = await resolveServerEntryModule(entry);
+        const renderToStream = serverModule?.renderToStream;
+        if (typeof renderToStream !== "function") {
+            return null;
+        }
+        const getServerProps = serverModule?.getServerProps ??
+            serverModule?.getServerSideProps;
+        const serverProps = getServerProps
+            ? await runGetServerProps(getServerProps, {
+                routeId,
+                params,
+                request,
+                response,
+            })
+            : null;
+        const props = serverProps?.props ?? {};
+        const renderResult = await renderToStream({ routeId, params, props });
+        if (!renderResult || !renderResult.stream || typeof renderResult.stream.pipe !== "function") {
+            return null;
+        }
+        const scripts = resolveChunkScripts(manifest, entry.clientEntry, basePath, assetsDir, manifest.version);
+        const scriptType = resolveScriptType(manifest);
+        const propsPayload = serializeRouteProps(props);
+        const hydration = serverModule?.hydration === "full" || serverModule?.hydration === "islands"
+            ? serverModule.hydration
+            : "islands";
+        return {
+            stream: renderResult.stream,
+            head: renderResult.head ?? {},
+            propsPayload,
+            scripts,
+            hydration,
+            scriptType,
+            status: renderResult.status ?? serverProps?.status ?? 200,
+            headers: {
+                ...(serverProps?.headers ?? {}),
+                ...(renderResult.headers ?? {}),
+            },
+            abort: renderResult.abort,
+        };
+    };
+    return {
+        distDir,
+        manifest,
+        routeGraph,
+        basePath,
+        assetsDir,
+        fallbackPolicy: options.fallbackPolicy,
+        appMode: options.appMode ?? "ssg",
+        dynamicPageApi: options.dynamicPageApi,
+        renderSsrRoute,
+        renderSsrStream,
+    };
+};
+const handleRuntimeRequest = async (context, request, response) => {
+    const requestUrl = new URL(request.url ?? "/", "http://localhost");
+    const urlPath = stripBasePath(requestUrl.pathname, context.basePath);
+    const navigationRequest = isNavigationRequest(request);
+    if (context.dynamicPageApi) {
+        const apiResult = await handleDynamicPageApiRequest({
+            method: request.method ?? "GET",
+            pathname: urlPath,
+            query: requestUrl.searchParams,
+            headers: request.headers ?? {},
+        }, context.dynamicPageApi);
+        if (apiResult) {
+            response.statusCode = apiResult.status;
+            for (const [key, value] of Object.entries(apiResult.headers)) {
+                response.setHeader(key, value);
+            }
+            response.end(apiResult.body ?? "");
+            return;
+        }
+    }
+    const assetPath = resolveAssetPath(context.distDir, urlPath, context.assetsDir);
+    if (assetPath) {
+        try {
+            const assetStat = await stat(assetPath);
+            if (assetStat.isFile()) {
+                const etag = computeEtag(assetStat);
+                if (request.headers?.["if-none-match"] === etag) {
+                    response.statusCode = 304;
+                    response.setHeader("etag", etag);
+                    response.end();
+                    return;
+                }
+                const file = await readStaticFile(assetPath);
+                response.statusCode = 200;
+                response.setHeader("content-type", file.contentType);
+                response.setHeader("cache-control", "public, max-age=31536000, immutable");
+                response.setHeader("etag", etag);
+                response.end(file.body);
+                return;
+            }
+        }
+        catch {
+            // Fall through to regular route handling.
+        }
+    }
+    const filePath = resolveFilePath(context.distDir, urlPath);
+    if (filePath && !navigationRequest) {
+        try {
+            const fileStat = await stat(filePath);
+            if (fileStat.isFile()) {
+                const file = await readStaticFile(filePath);
+                response.statusCode = 200;
+                response.setHeader("content-type", file.contentType);
+                response.end(file.body);
+                return;
+            }
+        }
+        catch {
+            // Fall through to route handling.
+        }
+    }
+    const resolvedRoute = await resolveRouteWithPolicyFallback({
+        pathname: urlPath,
+        routeGraph: context.routeGraph,
+        appMode: context.appMode,
+        policy: context.fallbackPolicy,
+        dynamicResolver: context.dynamicPageApi
+            ? (path) => context.dynamicPageApi?.resolveByPath({
+                path,
+                locale: requestUrl.searchParams.get("locale") ?? undefined,
+                variant: requestUrl.searchParams.get("variant") ?? undefined,
+                device: requestUrl.searchParams.get("device") ?? undefined,
+                ctxHash: requestUrl.searchParams.get("ctxHash") ?? undefined,
+            }) ?? Promise.resolve(null)
+            : undefined,
+    });
+    if (resolvedRoute.type === "redirect") {
+        response.statusCode = 307;
+        response.setHeader("location", resolvedRoute.location);
+        response.end();
+        return;
+    }
+    if (resolvedRoute.type === "dynamic") {
+        setRenderWarningsHeader(response, resolvedRoute.warnings);
+        if (resolvedRoute.mode === "ssr") {
+            response.statusCode = 501;
+            response.setHeader("content-type", "text/plain; charset=utf-8");
+            response.end("Dynamic SSR fallback is not implemented in runtime.");
+            return;
+        }
+        if (navigationRequest) {
+            response.statusCode = 204;
+            response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+            response.setHeader(DYNAMIC_FALLBACK_HEADER, "csr");
+            response.end();
+            return;
+        }
+        response.statusCode = 200;
+        response.setHeader("content-type", "text/html; charset=utf-8");
+        response.end(renderRuntimeDynamicFallback(urlPath));
+        return;
+    }
+    if (resolvedRoute.type === "file") {
+        const match = resolvedRoute.match;
+        const entry = context.manifest.routes[match.route.id];
+        if (entry?.serverEntry) {
+            try {
+                if (!navigationRequest && typeof response.write === "function") {
+                    const streamResult = await context.renderSsrStream(entry, match.route.id, match.params, request, response);
+                    if (streamResult) {
+                        response.statusCode = streamResult.status ?? 200;
+                        for (const [key, value] of Object.entries(streamResult.headers ?? {})) {
+                            response.setHeader(key, value);
+                        }
+                        response.setHeader("content-type", "text/html; charset=utf-8");
+                        const { prefix, suffix } = renderSsrHtmlFragments(match.route.id, streamResult.head, streamResult.propsPayload, streamResult.scripts, streamResult.hydration, streamResult.scriptType, context.manifest.version);
+                        response.write(prefix);
+                        response.flushHeaders?.();
+                        const stream = streamResult.stream;
+                        const finalize = () => {
+                            response.write?.(suffix);
+                            response.end();
+                        };
+                        const handleStreamError = () => {
+                            response.statusCode = 500;
+                            response.end("SSR render failed");
+                        };
+                        if (typeof stream.pipe === "function") {
+                            try {
+                                const streamTarget = response;
+                                stream.pipe(streamTarget, { end: false });
+                            }
+                            catch {
+                                handleStreamError();
+                                return;
+                            }
+                        }
+                        if (typeof stream.on === "function") {
+                            stream.on("end", finalize);
+                            stream.on("error", handleStreamError);
+                        }
+                        else {
+                            finalize();
+                        }
+                        if (streamResult.abort && typeof response.on === "function") {
+                            response.on("close", () => {
+                                streamResult.abort?.("client-disconnect");
+                            });
+                        }
+                        return;
+                    }
+                }
+                const ssrResult = await context.renderSsrRoute(entry, match.route.id, match.params, request, response);
+                if (navigationRequest) {
+                    response.statusCode = ssrResult.status ?? 200;
+                    for (const [key, value] of Object.entries(ssrResult.headers ?? {})) {
+                        response.setHeader(key, value);
+                    }
+                    response.setHeader("content-type", "application/json; charset=utf-8");
+                    response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+                    response.end(JSON.stringify(ssrResult.payload));
+                    return;
+                }
+                response.statusCode = ssrResult.status ?? 200;
+                for (const [key, value] of Object.entries(ssrResult.headers ?? {})) {
+                    response.setHeader(key, value);
+                }
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                response.end(ssrResult.html);
+                return;
+            }
+            catch {
+                response.statusCode = 500;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end("SSR render failed");
+                return;
+            }
+        }
+        if (entry?.type === "static" && entry.html) {
+            const htmlPath = resolveManifestFile(context.distDir, entry.html);
+            if (!htmlPath) {
+                response.statusCode = 500;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end("Invalid manifest html path");
+                return;
+            }
+            try {
+                const file = await readStaticFile(htmlPath);
+                if (navigationRequest) {
+                    const text = file.body.toString("utf-8");
+                    const payload = extractNavigationPayloadFromHtml(text, match.route.id);
+                    if (!payload) {
+                        response.statusCode = 500;
+                        response.setHeader("content-type", "application/json; charset=utf-8");
+                        response.end(JSON.stringify({ error: "Invalid static route payload" }));
+                        return;
+                    }
+                    response.statusCode = 200;
+                    response.setHeader("content-type", "application/json; charset=utf-8");
+                    response.setHeader("x-hyper-navigation", NAVIGATION_MODE);
+                    response.end(JSON.stringify(payload));
+                    return;
+                }
+                response.statusCode = 200;
+                response.setHeader("content-type", file.contentType);
+                response.end(file.body);
+                return;
+            }
+            catch {
+                response.statusCode = 500;
+                response.setHeader("content-type", "text/plain; charset=utf-8");
+                response.end("Missing HTML for static route");
+                return;
+            }
+        }
+        response.statusCode = 200;
+        response.setHeader("content-type", "text/html; charset=utf-8");
+        response.end(renderRuntimePlaceholder(match.route.id));
+        return;
+    }
+    response.statusCode = 404;
+    response.setHeader("content-type", "text/plain; charset=utf-8");
+    response.end("Not Found");
+};
+const createRuntimeHandler = (options = {}) => {
+    let contextPromise = null;
+    const getContext = () => {
+        if (!contextPromise) {
+            contextPromise = createRuntimeContext(options);
+        }
+        return contextPromise;
+    };
+    return async (request, response) => {
+        const context = await getContext();
+        await handleRuntimeRequest(context, request, response);
+    };
+};
+export const createServer = async (options = {}) => {
+    const host = options.host ?? "localhost";
+    const port = options.port ?? 3000;
+    const context = await createRuntimeContext(options);
+    const server = createHttpServer((request, response) => {
+        void handleRuntimeRequest(context, request, response);
+    });
+    await new Promise((resolvePromise, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => resolvePromise());
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        throw new Error("Runtime server did not return a TCP address.");
+    }
+    return {
+        host: address.address,
+        port: address.port,
+        url: `http://${address.address}:${address.port}`,
+        close: () => new Promise((resolvePromise, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolvePromise();
+            });
+        }),
+    };
+};
+export const createExpressHandler = (options = {}) => {
+    const handler = createRuntimeHandler(options);
+    return (request, response, next) => {
+        handler(request, response).catch((error) => {
+            if (next) {
+                next(error);
+                return;
+            }
+            response.statusCode = 500;
+            response.setHeader("content-type", "text/plain; charset=utf-8");
+            response.end("Runtime handler error");
+        });
+    };
+};
+export const createFastifyPlugin = (options = {}) => {
+    const handler = createRuntimeHandler(options);
+    return async (fastify) => {
+        fastify.all("*", async (request, reply) => {
+            const rawRequest = request?.raw ?? request;
+            const rawResponse = reply?.raw ?? reply;
+            try {
+                await handler(rawRequest, rawResponse);
+            }
+            catch {
+                rawResponse.statusCode = 500;
+                rawResponse.setHeader("content-type", "text/plain; charset=utf-8");
+                rawResponse.end("Runtime handler error");
+            }
+        });
+    };
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@tyndall/runtime",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@tyndall/core": "workspace:*",
+    "@tyndall/shared": "workspace:*"
+  }
+}