@fiyuu/runtime 0.1.0

package/src/server-renderer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * HTML document rendering, status pages, and response helpers
+ * for the Fiyuu runtime server.
+ */
+import type { ServerResponse } from "node:http";
+import type { MetaDefinition, RenderMode } from "@fiyuu/core";
+import type { StatusPageInput } from "./server-types.js";
+export declare function renderDocument(input: {
+    body: string;
+    data: unknown;
+    route: string;
+    intent: string;
+    render: RenderMode;
+    clientPath: string | null;
+    liveReload: boolean;
+    warnings: string[];
+    renderTimeMs: number;
+    developerTools: boolean;
+    requestId: string;
+    meta: MetaDefinition;
+    websocketPath: string;
+}): string;
+export declare function getStatusTone(statusCode: number): {
+    background: string;
+    border: string;
+    accent: string;
+    accentSoft: string;
+};
+export declare function renderStatusPage(input: StatusPageInput): string;
+export declare function sendDocumentStatusPage(response: ServerResponse, input: StatusPageInput): void;
+export declare function renderStartupMessage(mode: "dev" | "start", url: string, actualPort: number, preferredPort: number, websocketUrl?: string): string;
+export declare function serveClientAsset(response: ServerResponse, assetPath: string): Promise<void>;
+export declare function serveClientRuntime(response: ServerResponse, websocketPath: string): void;
+export declare function attachLiveReload(response: ServerResponse, liveClients: Set<ServerResponse>): void;

package/src/server-renderer.js

@@ -0,0 +1,213 @@
+/**
+ * HTML document rendering, status pages, and response helpers
+ * for the Fiyuu runtime server.
+ */
+import { createReadStream, existsSync } from "node:fs";
+import { buildClientRuntime } from "./client-runtime.js";
+import { escapeHtml, sendText, serialize } from "./server-utils.js";
+import { renderUnifiedToolsScript } from "./server-devtools.js";
+// ── Document rendering ────────────────────────────────────────────────────────
+export function renderDocument(input) {
+    const liveReloadScript = input.liveReload
+        ? `<script type="module">const events=new EventSource('/__fiyuu/live');events.onmessage=(event)=>{if(event.data==='reload'){location.reload();}};</script>`
+        : "";
+    const liveErrorDebuggerScript = input.liveReload
+        ? `<script type="module">(function(){const host=document.createElement('aside');host.style.cssText='position:fixed;left:12px;top:12px;z-index:10000;max-width:min(560px,calc(100vw - 24px));background:#2a1717;color:#ffe9e9;border:1px solid #7f3e3e;border-radius:12px;padding:10px 12px;font:12px/1.45 ui-monospace,monospace;white-space:pre-wrap;display:none';const title=document.createElement('div');title.style.cssText='font-weight:700;margin-bottom:6px';title.textContent='Fiyuu Live Error';const body=document.createElement('div');const close=document.createElement('button');close.textContent='dismiss';close.style.cssText='margin-top:8px;border:1px solid #9f5b5b;background:transparent;color:#ffe9e9;border-radius:999px;padding:2px 8px;cursor:pointer';close.addEventListener('click',()=>{host.style.display='none';});host.append(title,body,close);function show(message){body.textContent=message;host.style.display='block';if(!host.isConnected)document.body.appendChild(host);}window.addEventListener('error',(event)=>{const stack=event.error&&event.error.stack?event.error.stack:'';show(String(event.message||'Unknown runtime error')+(stack?'\n\n'+stack:''));});window.addEventListener('unhandledrejection',(event)=>{const reason=event.reason instanceof Error?(event.reason.stack||event.reason.message):String(event.reason||'Unhandled promise rejection');show(reason);});})();</script>`
+        : "";
+    const runtimeScript = `<script defer src="/__fiyuu/runtime.js"></script>`;
+    const clientScript = input.clientPath ? `<script type="module" src="${input.clientPath}"></script>` : "";
+    const unifiedToolsScript = input.liveReload && input.developerTools ? renderUnifiedToolsScript(input) : "";
+    return `<!doctype html>
+<html lang="en" data-render-mode="${input.render}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(input.meta.seo?.title ?? input.meta.title ?? "Fiyuu")}</title>
+    <meta name="description" content="${escapeHtml(input.meta.seo?.description ?? (input.intent || "Fiyuu application"))}" />
+    <script>
+      // Theme detection runs before anything else to prevent flash of wrong theme.
+      (function(){
+        try {
+          var saved = localStorage.getItem('fiyuu-theme');
+          var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+          var isDark = saved === 'dark' || (!saved && prefersDark);
+          document.documentElement.classList.toggle('dark', isDark);
+          document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
+        } catch(e) {}
+      })();
+    </script>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script>
+      // Tailwind CDN config must be set after the script loads.
+      if (typeof tailwind !== 'undefined') {
+        tailwind.config = { darkMode: 'class' };
+      }
+    </script>
+    <style>
+      *, *::before, *::after { box-sizing: border-box; }
+      :root { color-scheme: light; }
+      html.dark { color-scheme: dark; }
+      body { margin: 0; font-family: ui-sans-serif, system-ui, sans-serif; background: #f7f8f5; color: #172018; }
+      html.dark body { background: #111513; color: #f0f5ee; }
+      #app { min-height: 100vh; }
+    </style>
+  </head>
+  <body>
+    <div id="app">${input.body}</div>
+    <script>window.__FIYUU_DATA__=${serialize(input.data)};window.__FIYUU_ROUTE__=${JSON.stringify(input.route)};window.__FIYUU_INTENT__=${JSON.stringify(input.intent)};window.__FIYUU_RENDER__=${JSON.stringify(input.render)};window.__FIYUU_WS_PATH__=${JSON.stringify(input.websocketPath)};</script>
+    ${runtimeScript}
+    ${clientScript}
+    ${unifiedToolsScript}
+    ${liveErrorDebuggerScript}
+    ${liveReloadScript}
+  </body>
+</html>`;
+}
+// ── Status page rendering ─────────────────────────────────────────────────────
+export function getStatusTone(statusCode) {
+    if (statusCode >= 500) {
+        return {
+            background: "#f2dfd5",
+            border: "rgba(151, 73, 45, .22)",
+            accent: "#97492d",
+            accentSoft: "rgba(151, 73, 45, .20)",
+        };
+    }
+    if (statusCode === 404) {
+        return {
+            background: "#e4ebdf",
+            border: "rgba(58, 98, 75, .22)",
+            accent: "#3a624b",
+            accentSoft: "rgba(58, 98, 75, .18)",
+        };
+    }
+    return {
+        background: "#e8e2d4",
+        border: "rgba(105, 88, 52, .22)",
+        accent: "#695834",
+        accentSoft: "rgba(105, 88, 52, .18)",
+    };
+}
+export function renderStatusPage(input) {
+    const tone = getStatusTone(input.statusCode);
+    const badges = [
+        `HTTP ${input.statusCode}`,
+        input.method ? `Method ${input.method}` : "",
+        input.route ? `Route ${input.route}` : "",
+    ]
+        .filter(Boolean)
+        .map((item) => `<span class="badge">${escapeHtml(item)}</span>`)
+        .join("");
+    const hints = (input.hints ?? []).map((item) => `<li>${escapeHtml(item)}</li>`).join("");
+    const diagnostics = (input.diagnostics ?? [])
+        .map((item) => `<li><code>${escapeHtml(item)}</code></li>`)
+        .join("");
+    const requestMeta = input.requestId
+        ? `<p class="meta">Request ID: <code>${escapeHtml(input.requestId)}</code></p>`
+        : "";
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(`${input.statusCode} ${input.title} - Fiyuu`)}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        --bg: ${tone.background};
+        --panel: rgba(255,255,255,.76);
+        --border: ${tone.border};
+        --text: #18211d;
+        --muted: rgba(24,33,29,.62);
+        --accent: ${tone.accent};
+        --accent-soft: ${tone.accentSoft};
+        --code-bg: rgba(24,33,29,.06);
+      }
+      *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+      body { background: var(--bg); color: var(--text); font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; min-height: 100dvh; display: flex; align-items: center; justify-content: center; padding: 24px; }
+      .card { background: var(--panel); border: 1px solid var(--border); border-radius: 20px; padding: 32px 36px; max-width: 600px; width: 100%; backdrop-filter: blur(12px); box-shadow: 0 8px 32px rgba(0,0,0,.06); }
+      .badge { display: inline-flex; padding: 3px 10px; border-radius: 999px; background: var(--accent-soft); color: var(--accent); font: 600 11px/1.5 ui-monospace, monospace; margin-right: 6px; }
+      h1 { font-size: 22px; font-weight: 700; margin: 14px 0 8px; }
+      .summary { color: var(--muted); margin-bottom: 16px; }
+      .detail { background: var(--code-bg); border-radius: 10px; padding: 12px 14px; font: 13px/1.5 ui-monospace, monospace; margin-bottom: 18px; white-space: pre-wrap; word-break: break-word; }
+      h2 { font-size: 12px; font-weight: 600; text-transform: uppercase; letter-spacing: .06em; color: var(--muted); margin: 18px 0 8px; }
+      ul { padding-left: 18px; }
+      li { margin-top: 6px; }
+      code { background: var(--code-bg); border-radius: 4px; padding: 1px 5px; font-family: ui-monospace, monospace; font-size: .9em; }
+      .meta { font-size: 12px; color: var(--muted); margin-top: 20px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <div>${badges}</div>
+      <h1>${escapeHtml(input.title)}</h1>
+      <p class="summary">${escapeHtml(input.summary)}</p>
+      ${input.detail ? `<pre class="detail">${escapeHtml(input.detail)}</pre>` : ""}
+      ${hints ? `<h2>Suggestions</h2><ul>${hints}</ul>` : ""}
+      ${diagnostics ? `<h2>Diagnostics</h2><ul>${diagnostics}</ul>` : ""}
+      ${requestMeta}
+    </div>
+  </body>
+</html>`;
+}
+export function sendDocumentStatusPage(response, input) {
+    response.statusCode = input.statusCode;
+    response.setHeader("content-type", "text/html; charset=utf-8");
+    if (input.requestId) {
+        response.setHeader("x-fiyuu-request-id", input.requestId);
+    }
+    response.end(renderStatusPage(input));
+}
+// ── Startup message ───────────────────────────────────────────────────────────
+export function renderStartupMessage(mode, url, actualPort, preferredPort, websocketUrl) {
+    const lines = [
+        "",
+        `Fiyuu ${mode === "dev" ? "Development Server" : "Production Server"}`,
+        `- URL: ${url}`,
+        `- Mode: ${mode.toUpperCase()}`,
+    ];
+    if (actualPort !== preferredPort) {
+        lines.push(`- Port: ${preferredPort} was busy, using ${actualPort}`);
+    }
+    else {
+        lines.push(`- Port: ${actualPort}`);
+    }
+    if (mode === "dev") {
+        lines.push("- Live Reload: enabled");
+        lines.push("- Rendering: per-route SSR/CSR");
+    }
+    if (websocketUrl) {
+        lines.push(`- WebSocket: ${websocketUrl.replace(`:${preferredPort}`, `:${actualPort}`)}`);
+    }
+    return lines.join("\n");
+}
+// ── Static asset serving ──────────────────────────────────────────────────────
+export async function serveClientAsset(response, assetPath) {
+    if (!existsSync(assetPath)) {
+        sendText(response, 404, `Missing client asset ${assetPath}`);
+        return;
+    }
+    response.statusCode = 200;
+    response.setHeader("content-type", "text/javascript; charset=utf-8");
+    response.setHeader("cache-control", "public, max-age=31536000, immutable");
+    createReadStream(assetPath).pipe(response);
+}
+export function serveClientRuntime(response, websocketPath) {
+    response.statusCode = 200;
+    response.setHeader("content-type", "text/javascript; charset=utf-8");
+    response.setHeader("cache-control", "public, max-age=300");
+    response.end(buildClientRuntime(websocketPath));
+}
+// ── Live reload SSE ───────────────────────────────────────────────────────────
+export function attachLiveReload(response, liveClients) {
+    response.writeHead(200, {
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+        "content-type": "text/event-stream",
+    });
+    response.write(`data: ready\n\n`);
+    liveClients.add(response);
+    response.on("close", () => {
+        liveClients.delete(response);
+    });
+}

package/src/server-router.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Dynamic route matching for the Fiyuu runtime server.
+ * Builds a RouteIndex from FeatureRecords and matches incoming pathnames.
+ */
+import type { FeatureRecord } from "@fiyuu/core";
+import type { RouteIndex, RouteMatch } from "./server-types.js";
+export declare const QUERY_CACHE_SWEEP_INTERVAL_MS = 15000;
+export declare const QUERY_CACHE_MAX_ENTRIES = 2000;
+export declare function buildRouteRegex(route: string): {
+    regex: RegExp;
+    paramNames: string[];
+};
+export declare function buildRouteIndex(features: FeatureRecord[]): RouteIndex;
+export declare function matchRoute(routeIndex: RouteIndex, pathname: string): RouteMatch | null;

package/src/server-router.js

@@ -0,0 +1,67 @@
+/**
+ * Dynamic route matching for the Fiyuu runtime server.
+ * Builds a RouteIndex from FeatureRecords and matches incoming pathnames.
+ */
+export const QUERY_CACHE_SWEEP_INTERVAL_MS = 15_000;
+export const QUERY_CACHE_MAX_ENTRIES = 2_000;
+export function buildRouteRegex(route) {
+    const paramNames = [];
+    const parts = route.split("/").filter(Boolean);
+    const regexParts = parts.map((segment) => {
+        const optionalCatchAll = segment.match(/^\[\[\.\.\.(\w+)\]\]$/);
+        if (optionalCatchAll) {
+            paramNames.push(optionalCatchAll[1]);
+            return `(?:/(.*))?`;
+        }
+        const catchAll = segment.match(/^\[\.\.\.(\w+)\]$/);
+        if (catchAll) {
+            paramNames.push(catchAll[1]);
+            return `(.+)`;
+        }
+        const dynamic = segment.match(/^\[(\w+)\]$/);
+        if (dynamic) {
+            paramNames.push(dynamic[1]);
+            return `([^/]+)`;
+        }
+        return segment.replace(/[$()*+.[\]?\\^{}|]/g, "\\$&");
+    });
+    return { regex: new RegExp(`^/${regexParts.join("/")}$`), paramNames };
+}
+export function buildRouteIndex(features) {
+    const exact = new Map();
+    const dynamic = features
+        .filter((feature) => feature.isDynamic)
+        .sort((left, right) => {
+        if (left.params.length !== right.params.length) {
+            return left.params.length - right.params.length;
+        }
+        return right.route.length - left.route.length;
+    })
+        .map((feature) => {
+        const { regex, paramNames } = buildRouteRegex(feature.route);
+        return { feature, regex, paramNames };
+    });
+    for (const feature of features) {
+        if (!feature.isDynamic) {
+            exact.set(feature.route, feature);
+        }
+    }
+    return { exact, dynamic };
+}
+export function matchRoute(routeIndex, pathname) {
+    const exact = routeIndex.exact.get(pathname);
+    if (exact) {
+        return { feature: exact, params: {} };
+    }
+    for (const matcher of routeIndex.dynamic) {
+        const match = pathname.match(matcher.regex);
+        if (!match)
+            continue;
+        const params = {};
+        for (let i = 0; i < matcher.paramNames.length; i++) {
+            params[matcher.paramNames[i]] = match[i + 1] ?? "";
+        }
+        return { feature: matcher.feature, params };
+    }
+    return null;
+}

package/src/server-types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Shared types and interfaces for the Fiyuu runtime server.
+ * All other server modules import from here — no implementation code.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { WebSocket } from "ws";
+import type { createProjectGraph, FeatureRecord, FiyuuConfig, MetaDefinition, RenderMode } from "@fiyuu/core";
+import type { FiyuuDB } from "@fiyuu/db";
+import type { FiyuuRealtime } from "@fiyuu/realtime";
+import type { ClientAsset } from "./bundler.js";
+import type { InsightsReport } from "./inspector.js";
+export type { IncomingMessage, ServerResponse };
+export type { FeatureRecord, FiyuuConfig, MetaDefinition, RenderMode };
+export interface ModuleShape {
+    default?: unknown;
+    execute?: (context: any) => Promise<unknown> | unknown;
+    page?: {
+        intent: string;
+    };
+    cache?: {
+        ttl?: number;
+        vary?: string[];
+    };
+}
+export interface LayoutModule {
+    default?: unknown;
+}
+export interface GeaRenderable {
+    props?: Record<string, unknown>;
+    template?: (props?: Record<string, unknown>) => string;
+    toString: () => string;
+}
+export interface ApiRouteModule {
+    GET?: (context: RequestContext) => Promise<unknown> | unknown;
+    POST?: (context: RequestContext) => Promise<unknown> | unknown;
+    PUT?: (context: RequestContext) => Promise<unknown> | unknown;
+    PATCH?: (context: RequestContext) => Promise<unknown> | unknown;
+    DELETE?: (context: RequestContext) => Promise<unknown> | unknown;
+}
+export interface SocketModule {
+    registerSocketServer?: () => {
+        namespace?: string;
+        events?: string[];
+        onConnect?: (socket: WebSocket) => void;
+        onMessage?: (socket: WebSocket, message: string) => void;
+    };
+}
+export interface MiddlewareModule {
+    middleware?: MiddlewareHandler | MiddlewareHandler[];
+}
+export interface MiddlewareContext {
+    request: IncomingMessage;
+    url: URL;
+    responseHeaders: Record<string, string>;
+    requestId: string;
+    warnings: string[];
+}
+export interface MiddlewareResult {
+    headers?: Record<string, string>;
+    response?: {
+        status?: number;
+        json?: unknown;
+        body?: string;
+    };
+}
+export type MiddlewareNext = () => Promise<void>;
+export type MiddlewareHandler = (context: MiddlewareContext, next: MiddlewareNext) => Promise<MiddlewareResult | void> | MiddlewareResult | void;
+export interface RequestContext {
+    request: IncomingMessage;
+    route: string;
+    feature: FeatureRecord | null;
+    input?: Record<string, unknown>;
+}
+export interface StartServerOptions {
+    mode: "dev" | "start";
+    rootDirectory: string;
+    appDirectory: string;
+    config?: FiyuuConfig;
+    port?: number;
+    maxPort?: number;
+    clientOutputDirectory: string;
+    staticClientRoot: string;
+}
+export interface StartedServer {
+    port: number;
+    url: string;
+    websocketUrl?: string;
+    close: () => Promise<void>;
+}
+export interface QueryCacheEntry {
+    data: unknown;
+    expiresAt: number;
+}
+export interface SsgCacheEntry {
+    html: string;
+    etag: string;
+    expiresAt: number | null;
+    revalidateSeconds: number | null;
+}
+export interface RuntimeState {
+    graph: Awaited<ReturnType<typeof createProjectGraph>>;
+    features: FeatureRecord[];
+    routeIndex: RouteIndex;
+    assets: ClientAsset[];
+    assetsByRoute: Map<string, ClientAsset>;
+    insights: InsightsReport;
+    ssgCache: Map<string, SsgCacheEntry>;
+    queryCache: Map<string, QueryCacheEntry>;
+    queryInflight: Map<string, Promise<unknown>>;
+    queryCacheLastPruneAt: number;
+    layoutStackCache: Map<string, Array<{
+        component: unknown;
+        meta: MetaDefinition;
+    }>>;
+    featureMetaCache: Map<string, MetaDefinition>;
+    mergedMetaCache: Map<string, MetaDefinition>;
+    serverEvents: Array<{
+        at: string;
+        level: "info" | "warn" | "error";
+        event: string;
+        details?: string;
+    }>;
+    version: number;
+    warnings: string[];
+    db: FiyuuDB;
+    realtime: FiyuuRealtime;
+    serviceNames: string[];
+}
+export interface TinyRouteContext {
+    request: IncomingMessage;
+    response: ServerResponse;
+    url: URL;
+    state: RuntimeState;
+    options: StartServerOptions;
+    liveClients: Set<ServerResponse>;
+}
+export interface TinyRoute {
+    method: "GET" | "POST";
+    path: string;
+    type: "exact" | "prefix";
+    devOnly?: boolean;
+    handler: (context: TinyRouteContext) => Promise<void> | void;
+}
+export interface StatusPageInput {
+    statusCode: number;
+    title: string;
+    summary: string;
+    detail?: string;
+    route?: string;
+    method?: string;
+    requestId?: string;
+    hints?: string[];
+    diagnostics?: string[];
+}
+export interface RouteMatch {
+    feature: FeatureRecord;
+    params: Record<string, string>;
+}
+export interface DynamicRouteMatcher {
+    feature: FeatureRecord;
+    regex: RegExp;
+    paramNames: string[];
+}
+export interface RouteIndex {
+    exact: Map<string, FeatureRecord>;
+    dynamic: DynamicRouteMatcher[];
+}

package/src/server-types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types and interfaces for the Fiyuu runtime server.
+ * All other server modules import from here — no implementation code.
+ */
+export {};

package/src/server-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pure utility functions for the Fiyuu runtime server.
+ * No dependencies on other server modules — safe to import anywhere.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RuntimeState } from "./server-types.js";
+export declare function escapeHtml(value: unknown): string;
+export declare function serialize(value: unknown): string;
+export declare function createRequestId(): string;
+export declare function prefersHtmlResponse(request: IncomingMessage): boolean;
+export declare function sendJson(response: ServerResponse, statusCode: number, value: unknown): void;
+export declare function sendText(response: ServerResponse, statusCode: number, message: string): void;
+export declare function createWeakEtag(value: string): string;
+export declare function parseRequestBody(request: IncomingMessage): Promise<Record<string, unknown>>;
+export declare function pushServerEvent(state: RuntimeState, level: "info" | "warn" | "error", event: string, details?: string): void;

package/src/server-utils.js

@@ -0,0 +1,97 @@
+/**
+ * Pure utility functions for the Fiyuu runtime server.
+ * No dependencies on other server modules — safe to import anywhere.
+ */
+import { createHash } from "node:crypto";
+// ── HTML escaping ─────────────────────────────────────────────────────────────
+export function escapeHtml(value) {
+    const text = value == null ? "" : String(value);
+    return text
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+// ── Serialisation ─────────────────────────────────────────────────────────────
+export function serialize(value) {
+    return JSON.stringify(value ?? null).replaceAll("<", "\\u003c");
+}
+// ── Request ID ────────────────────────────────────────────────────────────────
+export function createRequestId() {
+    return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+// ── Content negotiation ───────────────────────────────────────────────────────
+export function prefersHtmlResponse(request) {
+    if ((request.url ?? "").startsWith("/api")) {
+        return false;
+    }
+    const accept = request.headers.accept ?? "";
+    if (accept.includes("application/json") && !accept.includes("text/html")) {
+        return false;
+    }
+    return true;
+}
+// ── Response helpers ──────────────────────────────────────────────────────────
+export function sendJson(response, statusCode, value) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "application/json; charset=utf-8");
+    response.end(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function sendText(response, statusCode, message) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "text/plain; charset=utf-8");
+    response.end(message);
+}
+export function createWeakEtag(value) {
+    const digest = createHash("sha1").update(value).digest("base64url");
+    return `W/\"${digest}\"`;
+}
+const MAX_BODY_BYTES = 1_048_576; // 1 MB
+export async function parseRequestBody(request) {
+    const chunks = [];
+    let totalBytes = 0;
+    for await (const chunk of request) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        totalBytes += buffer.byteLength;
+        if (totalBytes > MAX_BODY_BYTES) {
+            throw Object.assign(new Error("Request body too large (limit: 1 MB)."), { statusCode: 413 });
+        }
+        chunks.push(buffer);
+    }
+    const rawBody = Buffer.concat(chunks).toString("utf8").trim();
+    if (!rawBody) {
+        return {};
+    }
+    const contentType = request.headers["content-type"] ?? "";
+    if (contentType.includes("application/json")) {
+        const parsed = JSON.parse(rawBody);
+        // Reject prototype pollution attempts.
+        if (parsed !== null && typeof parsed === "object") {
+            const hasOwn = Object.prototype.hasOwnProperty;
+            if (hasOwn.call(parsed, "__proto__") ||
+                hasOwn.call(parsed, "constructor") ||
+                hasOwn.call(parsed, "prototype")) {
+                throw Object.assign(new Error("Request body contains forbidden keys."), { statusCode: 400 });
+            }
+        }
+        return parsed;
+    }
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+        const entries = [...new URLSearchParams(rawBody).entries()].filter(([key]) => key !== "__proto__" && key !== "constructor" && key !== "prototype");
+        return Object.fromEntries(entries);
+    }
+    return { raw: rawBody };
+}
+// ── Server event log ──────────────────────────────────────────────────────────
+export function pushServerEvent(state, level, event, details) {
+    state.serverEvents.unshift({
+        at: new Date().toISOString(),
+        level,
+        event,
+        details,
+    });
+    if (state.serverEvents.length > 120) {
+        state.serverEvents.length = 120;
+    }
+}

package/src/server-websocket.d.ts

@@ -0,0 +1,7 @@
+/**
+ * WebSocket server attachment for the Fiyuu runtime.
+ * Wires up a ws.WebSocketServer on the HTTP server's upgrade event.
+ */
+import { createServer } from "node:http";
+import type { StartServerOptions } from "./server-types.js";
+export declare function attachWebsocketServer(server: ReturnType<typeof createServer>, options: StartServerOptions, websocketPath: string): Promise<string | undefined>;