mates-fullstack 1.0.0-beta.1

package/dist/server-fn.js

@@ -0,0 +1,373 @@
+/**
+ * mates-ssr — server-fn.ts
+ *
+ * `serverFn` is the only API surface a developer touches to define a server
+ * function.  It is a near-identity wrapper on the server and is NEVER executed
+ * in the browser — the Bun build plugin (`serverFnPlugin` in cli.ts) intercepts
+ * every import of a file inside `src/api/` during `Bun.build()` and replaces
+ * the entire module with lightweight RPC stubs before Bun ever tries to resolve
+ * the file's own imports (db, secrets, fs, etc.).
+ *
+ * ─── Server behaviour ────────────────────────────────────────────────────────
+ *
+ *   import { serverFn } from "mates-ssr";
+ *   export const getUsers = serverFn(async (filter?: string) => {
+ *     return db.query("SELECT * FROM users WHERE name LIKE ?").all(filter);
+ *   });
+ *
+ *   On the server:
+ *     - serverFn() is called once at module-load time.
+ *     - It marks the function with metadata (__isMatesServerFn__, __fnName__)
+ *       so the fn-registry can index it during startup scanning.
+ *     - It returns the original async function unchanged.
+ *     - When called during an SSR render pass (isSSR() === true) the function
+ *       executes directly, in-process, with zero network overhead.
+ *     - When called from a server-side API handler context the function also
+ *       executes directly.
+ *
+ * ─── Client behaviour ────────────────────────────────────────────────────────
+ *
+ *   The Bun plugin rewrites the entire src/api/*.ts module before bundling.
+ *   What the browser receives is:
+ *
+ *     import { __callServerFn } from "mates-ssr/client";
+ *     export const getUsers   = (...args) => __callServerFn("users", "getUsers",   args);
+ *     export const createUser = (...args) => __callServerFn("users", "createUser", args);
+ *
+ *   `serverFn()` itself is never present in client.js.
+ *   The original function body (db queries, secrets, file I/O) is never present
+ *   in client.js.
+ *   The imports of the api file (db, auth, etc.) are never resolved by Bun for
+ *   the browser target — the plugin replaces the file before resolution.
+ *
+ * ─── Type safety ─────────────────────────────────────────────────────────────
+ *
+ *   serverFn() is generic and preserves the full signature of the wrapped
+ *   function:
+ *
+ *     export const getUser = serverFn(async (id: number): Promise<User> => { … });
+ *     //           ^─────── type: (id: number) => Promise<User>
+ *
+ *   The client stub generated by the plugin also accepts the same argument
+ *   types because TypeScript resolves the import from the original .ts source
+ *   file (which has the real types) — only the runtime implementation is
+ *   replaced in the browser bundle.  Types are never stripped by the plugin.
+ *
+ * ─── Error handling ──────────────────────────────────────────────────────────
+ *
+ *   Errors thrown inside a serverFn are:
+ *
+ *   On the server (direct call):
+ *     - Propagated as normal JS exceptions.
+ *     - The caller (asyncAction, onMount, etc.) handles them via try/catch
+ *       or the error atom of asyncAction.
+ *
+ *   On the client (RPC call via __callServerFn):
+ *     - The RPC endpoint catches the error and returns:
+ *         HTTP 500  { "error": "message", "code": "SERVER_FN_ERROR" }
+ *     - __callServerFn re-throws as a plain Error with the server's message.
+ *     - The caller handles it identically to a direct error.
+ *
+ * ─── Constraints ─────────────────────────────────────────────────────────────
+ *
+ *   1. serverFn MUST be used at the top level of a src/api/ file — not inside
+ *      another function, class, or conditional.  The plugin uses a static regex
+ *      scan to extract export names; dynamic usage is not detected.
+ *
+ *   2. Arguments MUST be JSON-serialisable.  The RPC layer uses JSON.stringify
+ *      on the client and JSON.parse on the server.  Dates, Sets, Maps, and class
+ *      instances are not supported without a custom serialiser.
+ *
+ *   3. Return values MUST be JSON-serialisable for the same reason.
+ *
+ *   4. serverFn files must live under the configured apiDir (default: src/api/).
+ *      Files outside that directory are not intercepted by the plugin and will
+ *      not have their server-only imports stripped.
+ *
+ *   5. Do NOT import serverFn files from client-only code that is NOT also
+ *      imported through a src/api/ path.  If you import a serverFn file
+ *      directly in src/client.ts (bypassing the api/ directory convention)
+ *      the plugin will still intercept it by path, but this is a footgun —
+ *      keep all server function definitions inside src/api/.
+ */
+// ─── Marker symbol ────────────────────────────────────────────────────────────
+// Attached to every wrapped function so the fn-registry scanner can identify
+// server functions at startup without re-parsing source files at runtime.
+export const SERVER_FN_MARKER = Symbol("mates.serverFn");
+// ─── Implicit server context ──────────────────────────────────────────────────
+// Uses AsyncLocalStorage backed by a globalThis-shared instance (via
+// Symbol.for) so that both the framework source and the node_modules copy
+// share the same ALS — even though they are separate module evaluations.
+// This is async-safe: concurrent requests each get their own ALS scope.
+import { AsyncLocalStorage } from "node:async_hooks";
+const _SERVER_CTX_KEY = Symbol.for("mates-ssr.serverCtxStorage");
+function _getContextStorage() {
+    const g = globalThis;
+    if (!g[_SERVER_CTX_KEY]) {
+        g[_SERVER_CTX_KEY] = new AsyncLocalStorage();
+    }
+    return g[_SERVER_CTX_KEY];
+}
+/**
+ * Run a function with the given ServerContext available via getContext().
+ * Uses AsyncLocalStorage so concurrent requests are properly isolated.
+ * @internal — called by fn-registry's callServerFn
+ */
+export function runWithServerContext(ctx, fn) {
+    return _getContextStorage().run({ ctx }, fn);
+}
+/**
+ * Set the server context for the current function call.
+ * @internal — called by fn-registry's callServerFn
+ * @deprecated Use runWithServerContext() instead for async safety.
+ *             Kept for backward compatibility.
+ */
+export function setCurrentServerContext(_ctx) {
+    // No-op — context is now managed via runWithServerContext + ALS.
+    // This function is retained so existing imports don't break.
+}
+/**
+ * Get the current server context.
+ * Used inside server functions to access auth, roles, and the raw request.
+ *
+ * The framework wraps each server function call in `runWithServerContext()`,
+ * which sets up an AsyncLocalStorage scope. `getContext()` reads from
+ * that scope — fully isolated per request even under high concurrency.
+ *
+ * @example
+ * export async function getUsers(filter: string) {
+ *   const { auth } = getContext();
+ *   checkAuth(auth);
+ *   return UsersDAL.getAll(filter);
+ * }
+ */
+export function getContext() {
+    const store = _getContextStorage().getStore();
+    if (store)
+        return store.ctx;
+    // Fallback for when called outside a server context (e.g. in tests)
+    return {
+        auth: null,
+        roles: {
+            has: () => false,
+            hasAll: () => false,
+            list: () => [],
+        },
+        req: null,
+        custom: {},
+    };
+}
+// ─── ServerError ──────────────────────────────────────────────────────────────
+/**
+ * Throw this from any server function to send a specific HTTP status,
+ * error message, and optional structured data to the client.
+ *
+ * The client receives an Error with .status, .code, and .data properties.
+ *
+ * @example
+ * // 404 — not found
+ * throw new ServerError(404, "Post not found");
+ *
+ * @example
+ * // 403 — forbidden with extra context
+ * throw new ServerError(403, "Access denied", {
+ *   code: "POST_PRIVATE",
+ *   postId: id,
+ * });
+ *
+ * @example
+ * // 400 — validation / business rule
+ * throw new ServerError(400, "Title too long", {
+ *   code: "TITLE_TOO_LONG",
+ *   max: 200,
+ *   actual: body.title.length,
+ * });
+ *
+ * @example
+ * // 409 — conflict
+ * throw new ServerError(409, "Email already registered", {
+ *   code: "EMAIL_TAKEN",
+ * });
+ */
+export class ServerError extends Error {
+    /** HTTP status code sent to the client */
+    status;
+    /** Machine-readable error code. Defaults to HTTP status name if not provided. */
+    code;
+    /** Extra structured data sent alongside the error. Never throws — always JSON-serializable. */
+    data;
+    constructor(status, message, data) {
+        super(message);
+        this.name = "ServerError";
+        this.status = status;
+        this.data = data
+            ? Object.fromEntries(Object.entries(data).filter(([k]) => k !== "code"))
+            : {};
+        this.code = data?.code ?? httpStatusCode(status);
+    }
+}
+/**
+ * Convert HTTP status number to a readable code string.
+ */
+function httpStatusCode(status) {
+    const codes = {
+        400: "BAD_REQUEST",
+        401: "UNAUTHORIZED",
+        403: "FORBIDDEN",
+        404: "NOT_FOUND",
+        405: "METHOD_NOT_ALLOWED",
+        408: "REQUEST_TIMEOUT",
+        409: "CONFLICT",
+        410: "GONE",
+        413: "PAYLOAD_TOO_LARGE",
+        422: "UNPROCESSABLE_ENTITY",
+        429: "TOO_MANY_REQUESTS",
+        500: "INTERNAL_SERVER_ERROR",
+        501: "NOT_IMPLEMENTED",
+        502: "BAD_GATEWAY",
+        503: "SERVICE_UNAVAILABLE",
+        504: "GATEWAY_TIMEOUT",
+    };
+    return codes[status] ?? "ERROR";
+}
+// ─── Core ─────────────────────────────────────────────────────────────────────
+/**
+ * Wrap an async function as a server function.
+ *
+ * On the server the original function is returned as-is (with metadata).
+ * In the client bundle the entire module is replaced by the build plugin —
+ * this wrapper is never present in browser code.
+ *
+ * @param fn   The async function to mark as server-only.
+ * @param name Optional explicit name.  When omitted the function's `.name`
+ *             property is used.  Explicit names are useful for minified builds
+ *             or when the inferred name would be ambiguous.
+ *
+ * @example
+ * export const getUsers = serverFn(async (filter?: string) => {
+ *   return db.query("SELECT * FROM users WHERE name LIKE ?").all(filter);
+ * });
+ *
+ * @example
+ * export const createUser = serverFn(
+ *   async (data: { name: string; email: string }) => {
+ *     if (!data.email) throw new Error("email is required");
+ *     return db.query("INSERT INTO users (name,email) VALUES (?,?) RETURNING *")
+ *              .get(data.name, data.email);
+ *   }
+ * );
+ */
+export function serverFn(fn, name) {
+    // Resolve the name used for registry lookup and RPC routing.
+    // Priority: explicit name arg → fn.name → throw (name is required for routing).
+    const resolvedName = name ?? fn.name;
+    if (!resolvedName) {
+        throw new Error("[mates-ssr] serverFn(): could not determine function name.\n" +
+            "Pass an explicit name: serverFn(async () => { … }, 'myFnName')\n" +
+            "or use a named function expression: serverFn(async function myFn() { … })");
+    }
+    // Attach metadata as non-enumerable properties so they are invisible to
+    // spread operators, JSON.stringify, and iteration — but readable by the
+    // registry scanner and the RPC handler.
+    Object.defineProperties(fn, {
+        [SERVER_FN_MARKER]: {
+            value: true,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        __fnName__: {
+            value: resolvedName,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+        __isMatesServerFn__: {
+            // String marker for fast duck-typing checks without importing the symbol
+            value: true,
+            writable: false,
+            enumerable: false,
+            configurable: false,
+        },
+    });
+    return fn;
+}
+// ─── Guard ────────────────────────────────────────────────────────────────────
+/**
+ * Returns true when `value` is a function wrapped with serverFn().
+ *
+ * Useful for the fn-registry scanner and for defensive checks inside the
+ * RPC endpoint handler.
+ */
+export function isServerFn(value) {
+    return (typeof value === "function" && value.__isMatesServerFn__ === true);
+}
+// ─── Context helpers ──────────────────────────────────────────────────────────
+//
+// During a request (SSR render pass, API route, or serverFn RPC call) the
+// original HTTP Request is stored in an AsyncLocalStorage context managed by
+// ssr-context.ts.  server.ts wraps every incoming fetch() in runWithContext()
+// so the ALS slot is populated for the entire async call-chain — fully isolated
+// per request even under high concurrency.
+//
+// serverFn implementations call getServerContext() to read cookies, auth
+// headers, and other request-level data without needing the Request threaded
+// explicitly through every call site.
+import { getSSRRequest } from "./ssr-context.js";
+/**
+ * Retrieve the original HTTP Request for the current request context.
+ *
+ * Returns null when called outside a request context (e.g. from a client-side
+ * asyncAction call via the RPC stub).
+ *
+ * @example
+ * export const getProfile = serverFn(async () => {
+ *   const req = getServerContext();
+ *   const token = req?.headers.get("authorization");
+ *   if (!token) throw new Error("Unauthorized");
+ *   return verifyToken(token);
+ * });
+ */
+export function getServerContext() {
+    return getSSRRequest();
+}
+/**
+ * Convenience helper — read a cookie from the current request context.
+ *
+ * Returns null when called on the client or when the cookie is absent.
+ *
+ * @example
+ * export const getSession = serverFn(async () => {
+ *   const sessionId = getCookie("session_id");
+ *   if (!sessionId) throw new Error("Not authenticated");
+ *   return sessionStore.get(sessionId);
+ * });
+ */
+export function getCookie(name) {
+    const req = getSSRRequest();
+    if (!req)
+        return null;
+    const cookieHeader = req.headers.get("cookie");
+    if (!cookieHeader)
+        return null;
+    for (const part of cookieHeader.split(";")) {
+        const [key, ...rest] = part.trim().split("=");
+        if (key.trim() === name) {
+            return decodeURIComponent(rest.join("="));
+        }
+    }
+    return null;
+}
+/**
+ * Convenience helper — read a request header from the current request context.
+ *
+ * @example
+ * export const getUser = serverFn(async () => {
+ *   const auth = getHeader("authorization");
+ *   return verifyJWT(auth);
+ * });
+ */
+export function getHeader(name) {
+    return getSSRRequest()?.headers.get(name) ?? null;
+}
+//# sourceMappingURL=server-fn.js.map

package/dist/server-fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-fn.js","sourceRoot":"","sources":["../src/server-fn.ts"],"names":[],"mappings":"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"}

package/dist/server-public.d.ts

@@ -0,0 +1,13 @@
+/**
+ * mates-fullstack/server — server-safe public exports.
+ *
+ * This entry is intended for server/api, server/main, server/socket, and addons.
+ * Build/scanner/runtime internals are exported from mates-fullstack/internal.
+ */
+export * from "./index.js";
+export { createContext, createContextFromHeaders, applyResHeaders, } from "./ctx.js";
+export { writeStream } from "./stream.js";
+export { writeDownload } from "./download.js";
+export { runRequestHooks, runResponseHooks, clearMiddleware, middlewareStats, type RequestHookResult, } from "./middleware.js";
+export { type SocketCtx, type SocketHandlers, type SocketLifecycleFn, type SocketRpcFn, } from "./socket-router.js";
+//# sourceMappingURL=server-public.d.ts.map

package/dist/server-public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-public.d.ts","sourceRoot":"","sources":["../src/server-public.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAE3B,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC"}

package/dist/server-public.js

@@ -0,0 +1,12 @@
+/**
+ * mates-fullstack/server — server-safe public exports.
+ *
+ * This entry is intended for server/api, server/main, server/socket, and addons.
+ * Build/scanner/runtime internals are exported from mates-fullstack/internal.
+ */
+export * from "./index.js";
+export { createContext, createContextFromHeaders, applyResHeaders, } from "./ctx.js";
+export { writeStream } from "./stream.js";
+export { writeDownload } from "./download.js";
+export { runRequestHooks, runResponseHooks, clearMiddleware, middlewareStats, } from "./middleware.js";
+//# sourceMappingURL=server-public.js.map

package/dist/server-public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-public.js","sourceRoot":"","sources":["../src/server-public.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAC;AAE3B,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,eAAe,GAChB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,GAEhB,MAAM,iBAAiB,CAAC"}

package/dist/server-timeout.d.ts

@@ -0,0 +1,38 @@
+/**
+ * mates-fullstack — server-timeout.ts
+ *
+ * Override the server-side request timeout.
+ * Must be called at module level in server/main.ts before the server starts.
+ *
+ * The timeout governs:
+ *   - RPC calls (POST /api/**)  — how long the function is allowed to run
+ *   - SSR rendering               — how long the renderer will wait
+ *   - Graceful shutdown drain     — 2× the request timeout
+ *
+ * @default 10 seconds
+ */
+/**
+ * Override the server request timeout.
+ *
+ * Call once at module level in server/main.ts.
+ * Must be called before the server starts.
+ *
+ * @param seconds Timeout in seconds. Must be >= 1.
+ *
+ * @example
+ * // All requests get 30 seconds to complete
+ * setServerTimeout(30);
+ *
+ * // Real-time app — fail fast
+ * setServerTimeout(5);
+ *
+ * // Long-running exports
+ * setServerTimeout(60);
+ */
+export declare function setServerTimeout(seconds: number): void;
+/**
+ * @internal — read by server.ts
+ * Returns the resolved timeout in milliseconds.
+ */
+export declare function _getServerTimeoutMs(): number;
+//# sourceMappingURL=server-timeout.d.ts.map

package/dist/server-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-timeout.d.ts","sourceRoot":"","sources":["../src/server-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAOtD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/server-timeout.js

@@ -0,0 +1,46 @@
+/**
+ * mates-fullstack — server-timeout.ts
+ *
+ * Override the server-side request timeout.
+ * Must be called at module level in server/main.ts before the server starts.
+ *
+ * The timeout governs:
+ *   - RPC calls (POST /api/**)  — how long the function is allowed to run
+ *   - SSR rendering               — how long the renderer will wait
+ *   - Graceful shutdown drain     — 2× the request timeout
+ *
+ * @default 10 seconds
+ */
+let _timeoutMs = null;
+/**
+ * Override the server request timeout.
+ *
+ * Call once at module level in server/main.ts.
+ * Must be called before the server starts.
+ *
+ * @param seconds Timeout in seconds. Must be >= 1.
+ *
+ * @example
+ * // All requests get 30 seconds to complete
+ * setServerTimeout(30);
+ *
+ * // Real-time app — fail fast
+ * setServerTimeout(5);
+ *
+ * // Long-running exports
+ * setServerTimeout(60);
+ */
+export function setServerTimeout(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 1) {
+        throw new Error(`[mates-fullstack] setServerTimeout: timeout must be >= 1 second, got ${seconds}.`);
+    }
+    _timeoutMs = Math.floor(seconds * 1000);
+}
+/**
+ * @internal — read by server.ts
+ * Returns the resolved timeout in milliseconds.
+ */
+export function _getServerTimeoutMs() {
+    return _timeoutMs ?? 10000;
+}
+//# sourceMappingURL=server-timeout.js.map

package/dist/server-timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-timeout.js","sourceRoot":"","sources":["../src/server-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,IAAI,UAAU,GAAkB,IAAI,CAAC;AAErC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CACb,wEAAwE,OAAO,GAAG,CACnF,CAAC;IACJ,CAAC;IACD,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,IAAI,KAAM,CAAC;AAC9B,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,100 @@
+/**
+ * mates-fullstack — server.ts
+ *
+ * Pure Node.js (node:http) HTTP server.
+ * No express, no hono, no fastify, no Bun APIs.
+ *
+ * Request routing order:
+ *  1.  GET  /health, /healthz              → 200 JSON { status: "ok", timestamp }
+ *  2.  GET  /__mates_reload  (dev only)    → SSE live-reload stream
+ *  3.  POST /__mates_log     (dev only)    → console.log browser messages
+ *  4.  GET  /_mates/*                      → virtual files (rpc-client.js, errors.js, etc.)
+ *  5.  Upgrade: websocket                  → emit "upgrade" (caller handles WS)
+ *  6.  onRequest hooks                 → raw HTTP escape hatch
+ *  7.  GET  /api/docs                      → docs page (dev or API_DOCS=true)
+ *  8.  POST /api/**                        → RPC runner
+ *  9.       /api/**  (non-POST)            → 405
+ * 10.  Static assets: /assets/** or public/→ serveStatic()
+ * 11.  GET  /**                            → renderPage() (SSR)
+ * 12.  (other methods) /**                 → 405
+ * 13.  fallthrough                         → 404
+ */
+/// <reference types="node" />
+import http from "node:http";
+import type { ResolvedPaths } from "./project-resolver.js";
+/** Module-level server configuration for limits that aren't per-request */
+interface ServerConfig {
+    staticStreamTimeout: number;
+    maxSseClients: number;
+}
+/**
+ * Configure server-level limits. Call before startServer().
+ */
+export declare function configureServer(options: Partial<ServerConfig>): void;
+export interface ServerOptions {
+    paths: ResolvedPaths;
+    dev: boolean;
+    /** Project root — used to locate client/index.html */
+    projectRoot: string;
+    /** Absolute path to built client JS file. Optional in dev no-bundle mode. */
+    clientBundlePath?: string | null;
+    /** Serve client modules directly from source in dev. */
+    noBundle?: boolean;
+    /** Root used by /_src and /_asset routes. Defaults to projectRoot. */
+    sourceRoot?: string;
+    /** Absolute browser entry source file for no-bundle dev. */
+    sourceClientEntry?: string | null;
+    /** Source server/api directory for no-bundle RPC stub generation. */
+    sourceApiDir?: string | null;
+    /** CSS bundle filename in dist/assets/ */
+    cssFilename?: string | null;
+    /** For SSR shortcut wiring */
+    matesPath: string;
+    /** Default 10_000 (10 seconds) */
+    timeoutMs?: number;
+    /** Default false */
+    trustProxy?: boolean;
+    /** Maximum concurrent connections. Default: 1000 */
+    maxConnections?: number;
+    /** Static file streaming timeout in ms. Default: 60000 */
+    staticStreamTimeout?: number;
+    /** Maximum SSE reload clients. Default: 500 */
+    maxSseClients?: number;
+}
+/** Shape of an HMR update broadcast over the SSE channel. */
+export type HmrUpdate = {
+    kind: "reload";
+} | {
+    kind: "css";
+    css?: string;
+    path?: string;
+} | {
+    kind: "js";
+    path: string;
+};
+/**
+ * Trigger an HMR event for all connected dev clients.
+ * Called by the CLI (via the runtime-reload endpoint) when a file change
+ * triggers a rebuild.
+ *
+ * `update.kind === "css"` swaps the stylesheet in place (no page reload,
+ * preserving application state); anything else falls back to a full reload.
+ */
+export declare function notifyReload(generation: string, update?: HmrUpdate): void;
+/**
+ * Returns the current number of in-flight requests.
+ */
+export declare function getActiveRequests(): number;
+/**
+ * Returns the client IP address from the request.
+ * When trustProxy=true, reads X-Forwarded-For / X-Real-IP first.
+ */
+export declare function getClientIp(req: http.IncomingMessage, trustProxy: boolean): string;
+export declare function buildDevImportMap(projectRoot: string): Record<string, string>;
+/**
+ * Create and start the Node.js HTTP server.
+ * Returns a cleanup/shutdown function.
+ */
+export declare function startServer(options: ServerOptions): Promise<() => void>;
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAW7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAoB3D,2EAA2E;AAC3E,UAAU,YAAY;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;CACvB;AAOD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAKpE;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAiFD,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAajC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,SAA8B,GACrC,IAAI,CAcN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,UAAU,EAAE,OAAO,GAClB,MAAM,CAeR;AA0WD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmC7E;AA2sBD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAmJ7E"}