nukejs 0.0.1 → 0.0.2

package/dist/middleware-loader.js

@@ -0,0 +1,50 @@
+import path from "path";
+import fs from "fs";
+import { pathToFileURL, fileURLToPath } from "url";
+import { log } from "./logger.js";
+const middlewares = [];
+async function loadMiddlewareFromPath(middlewarePath) {
+  if (!fs.existsSync(middlewarePath)) {
+    log.verbose(`No middleware found at ${middlewarePath}, skipping`);
+    return;
+  }
+  try {
+    const mod = await import(pathToFileURL(middlewarePath).href);
+    if (typeof mod.default === "function") {
+      middlewares.push(mod.default);
+      log.info(`Middleware loaded from ${middlewarePath}`);
+    } else {
+      log.warn(`${middlewarePath} does not export a default function`);
+    }
+  } catch (error) {
+    log.error(`Error loading middleware from ${middlewarePath}:`, error);
+  }
+}
+async function loadMiddleware() {
+  const appDir = path.dirname(fileURLToPath(import.meta.url));
+  const builtinPath = path.join(
+    appDir,
+    `middleware.${appDir.endsWith("dist") ? "js" : "ts"}`
+  );
+  const userPath = path.join(process.cwd(), "middleware.ts");
+  const paths = [.../* @__PURE__ */ new Set([builtinPath, userPath])];
+  for (const middlewarePath of paths) {
+    await loadMiddlewareFromPath(middlewarePath);
+  }
+}
+async function runMiddleware(req, res) {
+  if (middlewares.length === 0) return false;
+  for (const middleware of middlewares) {
+    await middleware(req, res);
+    if (res.writableEnded || res.headersSent) {
+      log.verbose("Middleware handled request, skipping further processing");
+      return true;
+    }
+  }
+  return false;
+}
+export {
+  loadMiddleware,
+  runMiddleware
+};
+//# sourceMappingURL=middleware-loader.js.map

package/dist/middleware-loader.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/middleware-loader.ts"],
+  "sourcesContent": ["/**\r\n * middleware-loader.ts \u2014 Middleware Chain Manager\r\n *\r\n * Loads and runs the NukeJS middleware stack.  Two layers are supported:\r\n *\r\n *   1. Built-in middleware   \u2014 shipped with the nukejs package.\r\n *                              Currently handles the /__hmr and /__hmr.js\r\n *                              routes required by the HMR client.\r\n *                              Located next to this file as `middleware.ts`\r\n *                              (or `middleware.js` in the compiled dist/).\r\n *\r\n *   2. User middleware       \u2014 `middleware.ts` in the project root (cwd).\r\n *                              Runs after the built-in layer so it can inspect\r\n *                              or short-circuit every incoming request, including\r\n *                              API and page routes.\r\n *\r\n * Each middleware function receives (req, res) and may either:\r\n *   - End the response (res.end / res.json) to short-circuit further handling.\r\n *   - Return without touching res to pass control to the next layer.\r\n *\r\n * runMiddleware() returns `true` if any middleware ended the response,\r\n * allowing app.ts to skip its own routing logic.\r\n *\r\n * Restart behaviour:\r\n *   When nuke.config.ts or middleware.ts change in dev, app.ts restarts the\r\n *   process.  The new process calls loadMiddleware() fresh so stale module\r\n *   caches are not an issue.\r\n */\r\n\r\nimport path from 'path';\r\nimport fs from 'fs';\r\nimport { pathToFileURL, fileURLToPath } from 'url';\r\nimport type { IncomingMessage, ServerResponse } from 'http';\r\nimport { log } from './logger';\r\n\r\n// \u2500\u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\nexport type MiddlewareFunction = (\r\n  req: IncomingMessage,\r\n  res: ServerResponse,\r\n) => Promise<void> | void;\r\n\r\n// \u2500\u2500\u2500 Internal state \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** Ordered list of loaded middleware functions.  Populated by loadMiddleware(). */\r\nconst middlewares: MiddlewareFunction[] = [];\r\n\r\n// \u2500\u2500\u2500 Loader helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Attempts to import a middleware file and push its default export onto the\r\n * stack.  Skips silently if the file doesn't exist.  Logs a warning if the\r\n * file exists but doesn't export a default function.\r\n */\r\nasync function loadMiddlewareFromPath(middlewarePath: string): Promise<void> {\r\n  if (!fs.existsSync(middlewarePath)) {\r\n    log.verbose(`No middleware found at ${middlewarePath}, skipping`);\r\n    return;\r\n  }\r\n\r\n  try {\r\n    const mod = await import(pathToFileURL(middlewarePath).href);\r\n    if (typeof mod.default === 'function') {\r\n      middlewares.push(mod.default);\r\n      log.info(`Middleware loaded from ${middlewarePath}`);\r\n    } else {\r\n      log.warn(`${middlewarePath} does not export a default function`);\r\n    }\r\n  } catch (error) {\r\n    log.error(`Error loading middleware from ${middlewarePath}:`, error);\r\n  }\r\n}\r\n\r\n// \u2500\u2500\u2500 Public API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Discovers and loads all middleware in priority order:\r\n *   1. Built-in (this package's own middleware.ts / middleware.js)\r\n *   2. User-supplied (cwd/middleware.ts)\r\n *\r\n * Duplicate paths (e.g. if cwd === package dir in a monorepo) are deduplicated\r\n * via a Set so the same file is never loaded twice.\r\n *\r\n * Should be called once at startup after the config is loaded.\r\n */\r\nexport async function loadMiddleware(): Promise<void> {\r\n  // __dirname equivalent in ESM.\r\n  const appDir = path.dirname(fileURLToPath(import.meta.url));\r\n\r\n  // The built-in middleware handles /__hmr and /__hmr.js for the HMR client.\r\n  const builtinPath = path.join(\r\n    appDir,\r\n    `middleware.${appDir.endsWith('dist') ? 'js' : 'ts'}`,\r\n  );\r\n\r\n  const userPath = path.join(process.cwd(), 'middleware.ts');\r\n\r\n  // Deduplicate in case the two paths resolve to the same file.\r\n  const paths = [...new Set([builtinPath, userPath])];\r\n\r\n  for (const middlewarePath of paths) {\r\n    await loadMiddlewareFromPath(middlewarePath);\r\n  }\r\n}\r\n\r\n/**\r\n * Runs all loaded middleware in registration order.\r\n *\r\n * Stops and returns `true` as soon as any middleware ends or sends a response\r\n * (res.writableEnded or res.headersSent), allowing app.ts to skip routing.\r\n *\r\n * Returns `false` if no middleware handled the request.\r\n */\r\nexport async function runMiddleware(\r\n  req: IncomingMessage,\r\n  res: ServerResponse,\r\n): Promise<boolean> {\r\n  if (middlewares.length === 0) return false;\r\n\r\n  for (const middleware of middlewares) {\r\n    await middleware(req, res);\r\n\r\n    if (res.writableEnded || res.headersSent) {\r\n      log.verbose('Middleware handled request, skipping further processing');\r\n      return true;\r\n    }\r\n  }\r\n\r\n  return false;\r\n}\r\n"],
+  "mappings": "AA6BA,OAAO,UAAU;AACjB,OAAO,QAAQ;AACf,SAAS,eAAe,qBAAqB;AAE7C,SAAS,WAAW;AAYpB,MAAM,cAAoC,CAAC;AAS3C,eAAe,uBAAuB,gBAAuC;AAC3E,MAAI,CAAC,GAAG,WAAW,cAAc,GAAG;AAClC,QAAI,QAAQ,0BAA0B,cAAc,YAAY;AAChE;AAAA,EACF;AAEA,MAAI;AACF,UAAM,MAAM,MAAM,OAAO,cAAc,cAAc,EAAE;AACvD,QAAI,OAAO,IAAI,YAAY,YAAY;AACrC,kBAAY,KAAK,IAAI,OAAO;AAC5B,UAAI,KAAK,0BAA0B,cAAc,EAAE;AAAA,IACrD,OAAO;AACL,UAAI,KAAK,GAAG,cAAc,qCAAqC;AAAA,IACjE;AAAA,EACF,SAAS,OAAO;AACd,QAAI,MAAM,iCAAiC,cAAc,KAAK,KAAK;AAAA,EACrE;AACF;AAcA,eAAsB,iBAAgC;AAEpD,QAAM,SAAS,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AAG1D,QAAM,cAAc,KAAK;AAAA,IACvB;AAAA,IACA,cAAc,OAAO,SAAS,MAAM,IAAI,OAAO,IAAI;AAAA,EACrD;AAEA,QAAM,WAAW,KAAK,KAAK,QAAQ,IAAI,GAAG,eAAe;AAGzD,QAAM,QAAQ,CAAC,GAAG,oBAAI,IAAI,CAAC,aAAa,QAAQ,CAAC,CAAC;AAElD,aAAW,kBAAkB,OAAO;AAClC,UAAM,uBAAuB,cAAc;AAAA,EAC7C;AACF;AAUA,eAAsB,cACpB,KACA,KACkB;AAClB,MAAI,YAAY,WAAW,EAAG,QAAO;AAErC,aAAW,cAAc,aAAa;AACpC,UAAM,WAAW,KAAK,GAAG;AAEzB,QAAI,IAAI,iBAAiB,IAAI,aAAa;AACxC,UAAI,QAAQ,yDAAyD;AACrE,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;",
+  "names": []
+}

package/dist/middleware.d.ts

@@ -0,0 +1,22 @@
+/**
+ * middleware.ts — Built-In NukeJS Middleware
+ *
+ * This is the internal middleware loaded before any user-defined middleware.
+ * It handles three responsibilities:
+ *
+ *   1. Static public files  (app/public/**)
+ *      Any file placed in app/public/ is served at its path relative to
+ *      that directory.  E.g. app/public/favicon.ico → GET /favicon.ico.
+ *      The correct Content-Type is set automatically.  Path traversal attempts
+ *      are rejected with 400.
+ *
+ *   2. HMR client script    (/__hmr.js)
+ *      Builds and serves hmr-bundle.ts on demand.  Injected into every dev
+ *      page as <script type="module" src="/__hmr.js">.
+ *
+ *   3. HMR SSE stream       (/__hmr)
+ *      Long-lived Server-Sent Events connection used by the browser to receive
+ *      reload/replace/restart events when source files change.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+export default function middleware(req: IncomingMessage, res: ServerResponse): Promise<void>;

package/dist/middleware.example.d.ts

@@ -0,0 +1,8 @@
+/**
+ * middleware.ts (place in project root)
+ *
+ * Runs before every request. Inspect/modify req, add headers, or send early
+ * responses to halt further processing.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+export default function middleware(req: IncomingMessage, res: ServerResponse): Promise<void>;

package/dist/middleware.example.js

@@ -0,0 +1,58 @@
+async function middleware(req, res) {
+  console.log(`[${(/* @__PURE__ */ new Date()).toISOString()}] ${req.method} ${req.url}`);
+  if (req.url?.startsWith("/admin") && !isAuthenticated(req)) {
+    res.statusCode = 401;
+    res.setHeader("Content-Type", "text/html");
+    res.end("<h1>401 Unauthorized</h1><p>Please log in to access this page.</p>");
+    return;
+  }
+  if (req.url === "/old-page") {
+    req.url = "/new-page";
+  }
+  res.setHeader("X-Powered-By", "nukejs-framework");
+  res.setHeader("X-Request-Id", generateRequestId());
+  if (req.url?.startsWith("/api/")) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    if (req.method === "OPTIONS") {
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
+  }
+  const clientIp = req.socket.remoteAddress || "unknown";
+  if (isRateLimited(clientIp)) {
+    res.statusCode = 429;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ error: "Too many requests" }));
+    return;
+  }
+  if (process.env.MAINTENANCE_MODE === "true" && !req.url?.startsWith("/__")) {
+    res.statusCode = 503;
+    res.setHeader("Content-Type", "text/html");
+    res.end("<h1>503 Service Unavailable</h1><p>We are currently down for maintenance.</p>");
+    return;
+  }
+}
+function isAuthenticated(req) {
+  return req.headers.authorization === "Bearer valid-token";
+}
+function generateRequestId() {
+  return Math.random().toString(36).substring(2, 15);
+}
+const rateLimitMap = /* @__PURE__ */ new Map();
+function isRateLimited(ip) {
+  const now = Date.now();
+  const limit = rateLimitMap.get(ip);
+  if (!limit || now > limit.resetAt) {
+    rateLimitMap.set(ip, { count: 1, resetAt: now + 6e4 });
+    return false;
+  }
+  limit.count++;
+  return limit.count > 100;
+}
+export {
+  middleware as default
+};
+//# sourceMappingURL=middleware.example.js.map

package/dist/middleware.example.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/middleware.example.ts"],
+  "sourcesContent": ["/**\r\n * middleware.ts (place in project root)\r\n *\r\n * Runs before every request. Inspect/modify req, add headers, or send early\r\n * responses to halt further processing.\r\n */\r\n\r\nimport type { IncomingMessage, ServerResponse } from 'http';\r\n\r\nexport default async function middleware(req: IncomingMessage, res: ServerResponse): Promise<void> {\r\n  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);\r\n\r\n  if (req.url?.startsWith('/admin') && !isAuthenticated(req)) {\r\n    res.statusCode = 401;\r\n    res.setHeader('Content-Type', 'text/html');\r\n    res.end('<h1>401 Unauthorized</h1><p>Please log in to access this page.</p>');\r\n    return;\r\n  }\r\n\r\n  if (req.url === '/old-page') {\r\n    req.url = '/new-page';\r\n  }\r\n\r\n  res.setHeader('X-Powered-By', 'nukejs-framework');\r\n  res.setHeader('X-Request-Id', generateRequestId());\r\n\r\n  if (req.url?.startsWith('/api/')) {\r\n    res.setHeader('Access-Control-Allow-Origin', '*');\r\n    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');\r\n    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');\r\n\r\n    if (req.method === 'OPTIONS') {\r\n      res.statusCode = 204;\r\n      res.end();\r\n      return;\r\n    }\r\n  }\r\n\r\n  const clientIp = req.socket.remoteAddress || 'unknown';\r\n  if (isRateLimited(clientIp)) {\r\n    res.statusCode = 429;\r\n    res.setHeader('Content-Type', 'application/json');\r\n    res.end(JSON.stringify({ error: 'Too many requests' }));\r\n    return;\r\n  }\r\n\r\n  if (process.env.MAINTENANCE_MODE === 'true' && !req.url?.startsWith('/__')) {\r\n    res.statusCode = 503;\r\n    res.setHeader('Content-Type', 'text/html');\r\n    res.end('<h1>503 Service Unavailable</h1><p>We are currently down for maintenance.</p>');\r\n    return;\r\n  }\r\n}\r\n\r\nfunction isAuthenticated(req: IncomingMessage): boolean {\r\n  return req.headers.authorization === 'Bearer valid-token';\r\n}\r\n\r\nfunction generateRequestId(): string {\r\n  return Math.random().toString(36).substring(2, 15);\r\n}\r\n\r\nconst rateLimitMap = new Map<string, { count: number; resetAt: number }>();\r\n\r\nfunction isRateLimited(ip: string): boolean {\r\n  const now = Date.now();\r\n  const limit = rateLimitMap.get(ip);\r\n\r\n  if (!limit || now > limit.resetAt) {\r\n    rateLimitMap.set(ip, { count: 1, resetAt: now + 60000 });\r\n    return false;\r\n  }\r\n\r\n  limit.count++;\r\n  return limit.count > 100;\r\n}\r\n"],
+  "mappings": "AASA,eAAO,WAAkC,KAAsB,KAAoC;AACjG,UAAQ,IAAI,KAAI,oBAAI,KAAK,GAAE,YAAY,CAAC,KAAK,IAAI,MAAM,IAAI,IAAI,GAAG,EAAE;AAEpE,MAAI,IAAI,KAAK,WAAW,QAAQ,KAAK,CAAC,gBAAgB,GAAG,GAAG;AAC1D,QAAI,aAAa;AACjB,QAAI,UAAU,gBAAgB,WAAW;AACzC,QAAI,IAAI,oEAAoE;AAC5E;AAAA,EACF;AAEA,MAAI,IAAI,QAAQ,aAAa;AAC3B,QAAI,MAAM;AAAA,EACZ;AAEA,MAAI,UAAU,gBAAgB,kBAAkB;AAChD,MAAI,UAAU,gBAAgB,kBAAkB,CAAC;AAEjD,MAAI,IAAI,KAAK,WAAW,OAAO,GAAG;AAChC,QAAI,UAAU,+BAA+B,GAAG;AAChD,QAAI,UAAU,gCAAgC,iCAAiC;AAC/E,QAAI,UAAU,gCAAgC,6BAA6B;AAE3E,QAAI,IAAI,WAAW,WAAW;AAC5B,UAAI,aAAa;AACjB,UAAI,IAAI;AACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,WAAW,IAAI,OAAO,iBAAiB;AAC7C,MAAI,cAAc,QAAQ,GAAG;AAC3B,QAAI,aAAa;AACjB,QAAI,UAAU,gBAAgB,kBAAkB;AAChD,QAAI,IAAI,KAAK,UAAU,EAAE,OAAO,oBAAoB,CAAC,CAAC;AACtD;AAAA,EACF;AAEA,MAAI,QAAQ,IAAI,qBAAqB,UAAU,CAAC,IAAI,KAAK,WAAW,KAAK,GAAG;AAC1E,QAAI,aAAa;AACjB,QAAI,UAAU,gBAAgB,WAAW;AACzC,QAAI,IAAI,+EAA+E;AACvF;AAAA,EACF;AACF;AAEA,SAAS,gBAAgB,KAA+B;AACtD,SAAO,IAAI,QAAQ,kBAAkB;AACvC;AAEA,SAAS,oBAA4B;AACnC,SAAO,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,UAAU,GAAG,EAAE;AACnD;AAEA,MAAM,eAAe,oBAAI,IAAgD;AAEzE,SAAS,cAAc,IAAqB;AAC1C,QAAM,MAAM,KAAK,IAAI;AACrB,QAAM,QAAQ,aAAa,IAAI,EAAE;AAEjC,MAAI,CAAC,SAAS,MAAM,MAAM,SAAS;AACjC,iBAAa,IAAI,IAAI,EAAE,OAAO,GAAG,SAAS,MAAM,IAAM,CAAC;AACvD,WAAO;AAAA,EACT;AAEA,QAAM;AACN,SAAO,MAAM,QAAQ;AACvB;",
+  "names": []
+}

package/dist/middleware.js

@@ -0,0 +1,59 @@
+import { build } from "esbuild";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { hmrClients } from "./hmr.js";
+import { getMimeType } from "./utils.js";
+const PUBLIC_DIR = path.resolve("./app/public");
+async function middleware(req, res) {
+  const rawUrl = req.url ?? "/";
+  const pathname = rawUrl.split("?")[0];
+  if (fs.existsSync(PUBLIC_DIR)) {
+    const candidate = path.join(PUBLIC_DIR, pathname);
+    const publicBase = PUBLIC_DIR.endsWith(path.sep) ? PUBLIC_DIR : PUBLIC_DIR + path.sep;
+    const safe = candidate.startsWith(publicBase) || candidate === PUBLIC_DIR;
+    if (!safe) {
+      res.statusCode = 400;
+      res.end("Bad request");
+      return;
+    }
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      const ext = path.extname(candidate);
+      res.setHeader("Content-Type", getMimeType(ext));
+      res.end(fs.readFileSync(candidate));
+      return;
+    }
+  }
+  if (rawUrl === "/__hmr.js") {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    const entry = path.join(dir, `hmr-bundle.${dir.endsWith("dist") ? "js" : "ts"}`);
+    const result = await build({
+      entryPoints: [entry],
+      write: false,
+      format: "esm",
+      minify: true,
+      bundle: true,
+      // React is not used in the HMR client, but excluding it prevents esbuild
+      // from inlining it if any transitive import references react.
+      external: ["react", "react-dom/client", "react/jsx-runtime"]
+    });
+    res.setHeader("Content-Type", "application/javascript");
+    res.end(result.outputFiles[0].text);
+    return;
+  }
+  if (rawUrl === "/__hmr") {
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.flushHeaders();
+    res.write('data: {"type":"connected"}\n\n');
+    hmrClients.add(res);
+    req.on("close", () => hmrClients.delete(res));
+    return;
+  }
+}
+export {
+  middleware as default
+};
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/middleware.ts"],
+  "sourcesContent": ["/**\r\n * middleware.ts \u2014 Built-In NukeJS Middleware\r\n *\r\n * This is the internal middleware loaded before any user-defined middleware.\r\n * It handles three responsibilities:\r\n *\r\n *   1. Static public files  (app/public/**)\r\n *      Any file placed in app/public/ is served at its path relative to\r\n *      that directory.  E.g. app/public/favicon.ico \u2192 GET /favicon.ico.\r\n *      The correct Content-Type is set automatically.  Path traversal attempts\r\n *      are rejected with 400.\r\n *\r\n *   2. HMR client script    (/__hmr.js)\r\n *      Builds and serves hmr-bundle.ts on demand.  Injected into every dev\r\n *      page as <script type=\"module\" src=\"/__hmr.js\">.\r\n *\r\n *   3. HMR SSE stream       (/__hmr)\r\n *      Long-lived Server-Sent Events connection used by the browser to receive\r\n *      reload/replace/restart events when source files change.\r\n */\r\n\r\nimport { build } from 'esbuild';\r\nimport type { IncomingMessage, ServerResponse } from 'http';\r\nimport path from 'path';\r\nimport fs from 'fs';\r\nimport { fileURLToPath } from 'url';\r\nimport { hmrClients } from './hmr';\r\nimport { getMimeType } from './utils';\r\n\r\n// Absolute path to the static public directory.\r\n// Files here are served at their path relative to this directory.\r\nconst PUBLIC_DIR = path.resolve('./app/public');\r\n\r\nexport default async function middleware(\r\n  req: IncomingMessage,\r\n  res: ServerResponse,\r\n): Promise<void> {\r\n\r\n  // \u2500\u2500 Static public files \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n  // Checked first so /favicon.ico, /main.css, etc. are never accidentally\r\n  // routed to the SSR or API layers.\r\n  const rawUrl = req.url ?? '/';\r\n  const pathname = rawUrl.split('?')[0]; // strip query string\r\n\r\n  if (fs.existsSync(PUBLIC_DIR)) {\r\n    // path.join handles the leading '/' in pathname naturally and normalises\r\n    // any '..' segments, making it safe to use directly with a startsWith guard.\r\n    // Using path.join (not path.resolve) ensures an absolute second argument\r\n    // cannot silently escape PUBLIC_DIR the way path.resolve would allow.\r\n    const candidate = path.join(PUBLIC_DIR, pathname);\r\n\r\n    // Path traversal guard: the resolved path must be inside PUBLIC_DIR.\r\n    // We normalise PUBLIC_DIR with a trailing separator so that a directory\r\n    // whose name is a prefix of another cannot pass (e.g. /public2 vs /public).\r\n    const publicBase = PUBLIC_DIR.endsWith(path.sep) ? PUBLIC_DIR : PUBLIC_DIR + path.sep;\r\n    const safe = candidate.startsWith(publicBase) || candidate === PUBLIC_DIR;\r\n\r\n    if (!safe) {\r\n      res.statusCode = 400;\r\n      res.end('Bad request');\r\n      return;\r\n    }\r\n\r\n    // Serve the file if it exists at any depth inside PUBLIC_DIR.\r\n    // Directories are intentionally skipped (no directory listings).\r\n    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {\r\n      const ext = path.extname(candidate);\r\n      res.setHeader('Content-Type', getMimeType(ext));\r\n      res.end(fs.readFileSync(candidate));\r\n      return;\r\n    }\r\n  }\r\n\r\n  // \u2500\u2500 HMR client script \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n  // Builds hmr-bundle.ts on demand so the browser always gets the latest version.\r\n  if (rawUrl === '/__hmr.js') {\r\n    const dir   = path.dirname(fileURLToPath(import.meta.url));\r\n    // Resolve to .js in dist/ or .ts when running from source.\r\n    const entry = path.join(dir, `hmr-bundle.${dir.endsWith('dist') ? 'js' : 'ts'}`);\r\n\r\n    const result = await build({\r\n      entryPoints: [entry],\r\n      write:       false,\r\n      format:      'esm',\r\n      minify:      true,\r\n      bundle:      true,\r\n      // React is not used in the HMR client, but excluding it prevents esbuild\r\n      // from inlining it if any transitive import references react.\r\n      external:    ['react', 'react-dom/client', 'react/jsx-runtime'],\r\n    });\r\n\r\n    res.setHeader('Content-Type', 'application/javascript');\r\n    res.end(result.outputFiles[0].text);\r\n    return; // Prevent fall-through to the SSE block below.\r\n  }\r\n\r\n  // \u2500\u2500 HMR SSE stream \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n  // Long-lived connection tracked in hmrClients so hmr.ts can broadcast events\r\n  // to all connected browsers when a file changes.\r\n  if (rawUrl === '/__hmr') {\r\n    res.setHeader('Content-Type', 'text/event-stream');\r\n    res.setHeader('Cache-Control', 'no-cache');\r\n    res.setHeader('Connection', 'keep-alive');\r\n    res.setHeader('Access-Control-Allow-Origin', '*');\r\n    res.flushHeaders();\r\n\r\n    // Send an immediate 'connected' event so the client knows the stream is live.\r\n    res.write('data: {\"type\":\"connected\"}\\n\\n');\r\n\r\n    hmrClients.add(res);\r\n    req.on('close', () => hmrClients.delete(res));\r\n    return;\r\n  }\r\n}"],
+  "mappings": "AAqBA,SAAS,aAAa;AAEtB,OAAO,UAAU;AACjB,OAAO,QAAQ;AACf,SAAS,qBAAqB;AAC9B,SAAS,kBAAkB;AAC3B,SAAS,mBAAmB;AAI5B,MAAM,aAAa,KAAK,QAAQ,cAAc;AAE9C,eAAO,WACL,KACA,KACe;AAKf,QAAM,SAAS,IAAI,OAAO;AAC1B,QAAM,WAAW,OAAO,MAAM,GAAG,EAAE,CAAC;AAEpC,MAAI,GAAG,WAAW,UAAU,GAAG;AAK7B,UAAM,YAAY,KAAK,KAAK,YAAY,QAAQ;AAKhD,UAAM,aAAa,WAAW,SAAS,KAAK,GAAG,IAAI,aAAa,aAAa,KAAK;AAClF,UAAM,OAAO,UAAU,WAAW,UAAU,KAAK,cAAc;AAE/D,QAAI,CAAC,MAAM;AACT,UAAI,aAAa;AACjB,UAAI,IAAI,aAAa;AACrB;AAAA,IACF;AAIA,QAAI,GAAG,WAAW,SAAS,KAAK,GAAG,SAAS,SAAS,EAAE,OAAO,GAAG;AAC/D,YAAM,MAAM,KAAK,QAAQ,SAAS;AAClC,UAAI,UAAU,gBAAgB,YAAY,GAAG,CAAC;AAC9C,UAAI,IAAI,GAAG,aAAa,SAAS,CAAC;AAClC;AAAA,IACF;AAAA,EACF;AAIA,MAAI,WAAW,aAAa;AAC1B,UAAM,MAAQ,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AAEzD,UAAM,QAAQ,KAAK,KAAK,KAAK,cAAc,IAAI,SAAS,MAAM,IAAI,OAAO,IAAI,EAAE;AAE/E,UAAM,SAAS,MAAM,MAAM;AAAA,MACzB,aAAa,CAAC,KAAK;AAAA,MACnB,OAAa;AAAA,MACb,QAAa;AAAA,MACb,QAAa;AAAA,MACb,QAAa;AAAA;AAAA;AAAA,MAGb,UAAa,CAAC,SAAS,oBAAoB,mBAAmB;AAAA,IAChE,CAAC;AAED,QAAI,UAAU,gBAAgB,wBAAwB;AACtD,QAAI,IAAI,OAAO,YAAY,CAAC,EAAE,IAAI;AAClC;AAAA,EACF;AAKA,MAAI,WAAW,UAAU;AACvB,QAAI,UAAU,gBAAgB,mBAAmB;AACjD,QAAI,UAAU,iBAAiB,UAAU;AACzC,QAAI,UAAU,cAAc,YAAY;AACxC,QAAI,UAAU,+BAA+B,GAAG;AAChD,QAAI,aAAa;AAGjB,QAAI,MAAM,gCAAgC;AAE1C,eAAW,IAAI,GAAG;AAClB,QAAI,GAAG,SAAS,MAAM,WAAW,OAAO,GAAG,CAAC;AAC5C;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/renderer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * renderer.ts — Dev-Mode Async SSR Renderer
+ *
+ * Implements a recursive async renderer used in `nuke dev` to convert a React
+ * element tree into an HTML string.  It is a lighter alternative to
+ * react-dom/server.renderToString that:
+ *
+ *   - Supports async server components (components that return Promises).
+ *   - Emits <span data-hydrate-id="…"> markers for "use client" boundaries
+ *     instead of trying to render them server-side without their browser APIs.
+ *   - Serializes props passed to client components into the marker's
+ *     data-hydrate-props attribute so the browser can reconstruct them.
+ *
+ * In production (nuke build), the equivalent renderer is inlined into each
+ * page's standalone bundle by build-common.ts (makePageAdapterSource).
+ *
+ * RenderContext:
+ *   registry    — Map<id, filePath> of all client components for this page.
+ *                 Populated by component-analyzer.ts before rendering.
+ *   hydrated    — Set<id> populated during render; used to tell the browser
+ *                 which components to hydrate on this specific request.
+ *   skipClientSSR — When true (HMR request), client components emit an empty
+ *                 marker instead of running renderToString (faster dev reload).
+ */
+export interface RenderContext {
+    /** id → absolute file path for every client component reachable from this page. */
+    registry: Map<string, string>;
+    /** Populated during render: IDs of client components actually encountered. */
+    hydrated: Set<string>;
+    /** When true, skip renderToString for client components (faster HMR). */
+    skipClientSSR?: boolean;
+}
+/**
+ * Recursively renders a React element (or primitive) to an HTML string.
+ *
+ * Handles:
+ *   null / undefined / boolean  → ''
+ *   string / number             → HTML-escaped text
+ *   array                       → rendered in parallel, joined
+ *   Fragment                    → renders children directly
+ *   HTML element string         → renderHtmlElement()
+ *   function component          → renderFunctionComponent()
+ */
+export declare function renderElementToHtml(element: any, ctx: RenderContext): Promise<string>;

package/dist/renderer.js

@@ -0,0 +1,130 @@
+import path from "path";
+import fs from "fs";
+import { createElement, Fragment } from "react";
+import { renderToString } from "react-dom/server";
+import { log } from "./logger.js";
+import { getComponentCache } from "./component-analyzer.js";
+import { escapeHtml } from "./utils.js";
+async function renderElementToHtml(element, ctx) {
+  if (element === null || element === void 0 || typeof element === "boolean") return "";
+  if (typeof element === "string" || typeof element === "number")
+    return escapeHtml(String(element));
+  if (Array.isArray(element)) {
+    const parts = await Promise.all(element.map((e) => renderElementToHtml(e, ctx)));
+    return parts.join("");
+  }
+  if (!element.type) return "";
+  const { type, props } = element;
+  if (type === Fragment) return renderElementToHtml(props.children, ctx);
+  if (typeof type === "string") return renderHtmlElement(type, props, ctx);
+  if (typeof type === "function") return renderFunctionComponent(type, props, ctx);
+  return "";
+}
+async function renderHtmlElement(type, props, ctx) {
+  const { children, ...attributes } = props || {};
+  const attrs = Object.entries(attributes).map(([key, value]) => {
+    if (key === "className") key = "class";
+    if (key === "htmlFor") key = "for";
+    if (key === "dangerouslySetInnerHTML") return "";
+    if (typeof value === "boolean") return value ? key : "";
+    if (key === "style" && typeof value === "object") {
+      const styleStr = Object.entries(value).map(([k, v]) => {
+        const prop = k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+        const safeVal = String(v).replace(/[<>"'`\\]/g, "");
+        return `${prop}:${safeVal}`;
+      }).join(";");
+      return `style="${styleStr}"`;
+    }
+    return `${key}="${escapeHtml(String(value))}"`;
+  }).filter(Boolean).join(" ");
+  const attrStr = attrs ? ` ${attrs}` : "";
+  if (props?.dangerouslySetInnerHTML) {
+    return `<${type}${attrStr}>${props.dangerouslySetInnerHTML.__html}</${type}>`;
+  }
+  if (["img", "br", "hr", "input", "meta", "link"].includes(type)) {
+    return `<${type}${attrStr} />`;
+  }
+  const childrenHtml = children ? await renderElementToHtml(children, ctx) : "";
+  return `<${type}${attrStr}>${childrenHtml}</${type}>`;
+}
+async function renderFunctionComponent(type, props, ctx) {
+  const componentCache = getComponentCache();
+  for (const [id, filePath] of ctx.registry.entries()) {
+    const info = componentCache.get(filePath);
+    if (!info?.isClientComponent) continue;
+    const content = fs.readFileSync(filePath, "utf-8");
+    const match = content.match(/export\s+default\s+(?:function\s+)?(\w+)/);
+    if (!match?.[1] || type.name !== match[1]) continue;
+    try {
+      ctx.hydrated.add(id);
+      const serializedProps = serializePropsForHydration(props, ctx.registry);
+      log.verbose(`Client component rendered for hydration: ${id} (${path.basename(filePath)})`);
+      const html = ctx.skipClientSSR ? "" : renderToString(createElement(type, props));
+      return `<span data-hydrate-id="${id}" data-hydrate-props="${escapeHtml(
+        JSON.stringify(serializedProps)
+      )}">${html}</span>`;
+    } catch (err) {
+      log.error("Error rendering client component:", err);
+      return `<div style="color:red">Error rendering client component: ${escapeHtml(String(err))}</div>`;
+    }
+  }
+  try {
+    const result = type(props);
+    const resolved = result?.then ? await result : result;
+    return renderElementToHtml(resolved, ctx);
+  } catch (err) {
+    log.error("Error rendering component:", err);
+    return `<div style="color:red">Error rendering component: ${escapeHtml(String(err))}</div>`;
+  }
+}
+function serializePropsForHydration(props, registry) {
+  if (!props || typeof props !== "object") return props;
+  const out = {};
+  for (const [key, value] of Object.entries(props)) {
+    const s = serializeValue(value, registry);
+    if (s !== void 0) out[key] = s;
+  }
+  return out;
+}
+function serializeValue(value, registry) {
+  if (value === null || value === void 0) return value;
+  if (typeof value === "function") return void 0;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value))
+    return value.map((v) => serializeValue(v, registry)).filter((v) => v !== void 0);
+  if (value.$$typeof)
+    return serializeReactElement(value, registry);
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    const s = serializeValue(v, registry);
+    if (s !== void 0) out[k] = s;
+  }
+  return out;
+}
+function serializeReactElement(element, registry) {
+  const { type, props } = element;
+  if (typeof type === "string") {
+    return { __re: "html", tag: type, props: serializePropsForHydration(props, registry) };
+  }
+  if (typeof type === "function") {
+    const componentCache = getComponentCache();
+    for (const [id, filePath] of registry.entries()) {
+      const info = componentCache.get(filePath);
+      if (!info?.isClientComponent) continue;
+      const content = fs.readFileSync(filePath, "utf-8");
+      const match = content.match(/export\s+default\s+(?:function\s+)?(\w+)/);
+      if (match?.[1] && type.name === match[1]) {
+        return {
+          __re: "client",
+          componentId: id,
+          props: serializePropsForHydration(props, registry)
+        };
+      }
+    }
+  }
+  return void 0;
+}
+export {
+  renderElementToHtml
+};
+//# sourceMappingURL=renderer.js.map

package/dist/renderer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/renderer.ts"],
+  "sourcesContent": ["/**\r\n * renderer.ts \u2014 Dev-Mode Async SSR Renderer\r\n *\r\n * Implements a recursive async renderer used in `nuke dev` to convert a React\r\n * element tree into an HTML string.  It is a lighter alternative to\r\n * react-dom/server.renderToString that:\r\n *\r\n *   - Supports async server components (components that return Promises).\r\n *   - Emits <span data-hydrate-id=\"\u2026\"> markers for \"use client\" boundaries\r\n *     instead of trying to render them server-side without their browser APIs.\r\n *   - Serializes props passed to client components into the marker's\r\n *     data-hydrate-props attribute so the browser can reconstruct them.\r\n *\r\n * In production (nuke build), the equivalent renderer is inlined into each\r\n * page's standalone bundle by build-common.ts (makePageAdapterSource).\r\n *\r\n * RenderContext:\r\n *   registry    \u2014 Map<id, filePath> of all client components for this page.\r\n *                 Populated by component-analyzer.ts before rendering.\r\n *   hydrated    \u2014 Set<id> populated during render; used to tell the browser\r\n *                 which components to hydrate on this specific request.\r\n *   skipClientSSR \u2014 When true (HMR request), client components emit an empty\r\n *                 marker instead of running renderToString (faster dev reload).\r\n */\r\n\r\nimport path from 'path';\r\nimport fs from 'fs';\r\nimport { createElement, Fragment } from 'react';\r\nimport { renderToString } from 'react-dom/server';\r\nimport { log } from './logger';\r\nimport { getComponentCache } from './component-analyzer';\r\nimport { escapeHtml } from './utils';\r\n\r\n// \u2500\u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\nexport interface RenderContext {\r\n  /** id \u2192 absolute file path for every client component reachable from this page. */\r\n  registry:       Map<string, string>;\r\n  /** Populated during render: IDs of client components actually encountered. */\r\n  hydrated:       Set<string>;\r\n  /** When true, skip renderToString for client components (faster HMR). */\r\n  skipClientSSR?: boolean;\r\n}\r\n\r\n// \u2500\u2500\u2500 Top-level renderer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Recursively renders a React element (or primitive) to an HTML string.\r\n *\r\n * Handles:\r\n *   null / undefined / boolean  \u2192 ''\r\n *   string / number             \u2192 HTML-escaped text\r\n *   array                       \u2192 rendered in parallel, joined\r\n *   Fragment                    \u2192 renders children directly\r\n *   HTML element string         \u2192 renderHtmlElement()\r\n *   function component          \u2192 renderFunctionComponent()\r\n */\r\nexport async function renderElementToHtml(\r\n  element: any,\r\n  ctx: RenderContext,\r\n): Promise<string> {\r\n  if (element === null || element === undefined || typeof element === 'boolean') return '';\r\n  if (typeof element === 'string' || typeof element === 'number')\r\n    return escapeHtml(String(element));\r\n\r\n  if (Array.isArray(element)) {\r\n    const parts = await Promise.all(element.map(e => renderElementToHtml(e, ctx)));\r\n    return parts.join('');\r\n  }\r\n\r\n  if (!element.type) return '';\r\n\r\n  const { type, props } = element;\r\n\r\n  if (type === Fragment)              return renderElementToHtml(props.children, ctx);\r\n  if (typeof type === 'string')       return renderHtmlElement(type, props, ctx);\r\n  if (typeof type === 'function')     return renderFunctionComponent(type, props, ctx);\r\n\r\n  return '';\r\n}\r\n\r\n// \u2500\u2500\u2500 HTML element renderer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Renders a native HTML element (e.g. `<div className=\"foo\">`).\r\n *\r\n * Attribute conversion:\r\n *   className \u2192 class\r\n *   htmlFor   \u2192 for\r\n *   style     \u2192 converted from camelCase object to CSS string\r\n *   boolean   \u2192 omitted when false, rendered as name-only attribute when true\r\n *   dangerouslySetInnerHTML \u2192 inner HTML set verbatim (no escaping)\r\n *\r\n * Void elements (img, br, input, etc.) are self-closed.\r\n */\r\nasync function renderHtmlElement(\r\n  type: string,\r\n  props: any,\r\n  ctx: RenderContext,\r\n): Promise<string> {\r\n  const { children, ...attributes } = (props || {}) as Record<string, any>;\r\n\r\n  const attrs = Object.entries(attributes as Record<string, any>)\r\n    .map(([key, value]) => {\r\n      // React prop name \u2192 HTML attribute name.\r\n      if (key === 'className')              key = 'class';\r\n      if (key === 'htmlFor')                key = 'for';\r\n      if (key === 'dangerouslySetInnerHTML') return ''; // handled separately below\r\n\r\n      if (typeof value === 'boolean') return value ? key : '';\r\n\r\n      // camelCase style object \u2192 \"prop:value;\u2026\" CSS string.\r\n      if (key === 'style' && typeof value === 'object') {\r\n        const styleStr = Object.entries(value)\r\n          .map(([k, v]) => {\r\n            const prop    = k.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);\r\n            // Strip characters that could break out of the attribute value.\r\n            const safeVal = String(v).replace(/[<>\"'`\\\\]/g, '');\r\n            return `${prop}:${safeVal}`;\r\n          })\r\n          .join(';');\r\n        return `style=\"${styleStr}\"`;\r\n      }\r\n\r\n      return `${key}=\"${escapeHtml(String(value))}\"`;\r\n    })\r\n    .filter(Boolean)\r\n    .join(' ');\r\n\r\n  const attrStr = attrs ? ` ${attrs}` : '';\r\n\r\n  if (props?.dangerouslySetInnerHTML) {\r\n    return `<${type}${attrStr}>${props.dangerouslySetInnerHTML.__html}</${type}>`;\r\n  }\r\n\r\n  // Void elements cannot have children.\r\n  if (['img', 'br', 'hr', 'input', 'meta', 'link'].includes(type)) {\r\n    return `<${type}${attrStr} />`;\r\n  }\r\n\r\n  const childrenHtml = children ? await renderElementToHtml(children, ctx) : '';\r\n  return `<${type}${attrStr}>${childrenHtml}</${type}>`;\r\n}\r\n\r\n// \u2500\u2500\u2500 Function component renderer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Renders a function (or class) component.\r\n *\r\n * Client boundary detection:\r\n *   The component cache maps file paths to ComponentInfo.  We match the\r\n *   component's function name against the default export of each registered\r\n *   client file to determine whether this component is a client boundary.\r\n *\r\n *   If it is, we emit a hydration marker and optionally run renderToString\r\n *   to produce the initial HTML inside the marker (skipped when skipClientSSR\r\n *   is set, e.g. during HMR navigation).\r\n *\r\n * Class components:\r\n *   Instantiated via `new type(props)` and their render() method called.\r\n *\r\n * Async components:\r\n *   Awaited if the return value is a Promise (standard server component pattern).\r\n */\r\nasync function renderFunctionComponent(\r\n  type: Function,\r\n  props: any,\r\n  ctx: RenderContext,\r\n): Promise<string> {\r\n  const componentCache = getComponentCache();\r\n\r\n  // Check whether this component function is a registered client component.\r\n  for (const [id, filePath] of ctx.registry.entries()) {\r\n    const info = componentCache.get(filePath);\r\n    if (!info?.isClientComponent) continue;\r\n\r\n    // Match by default export function name.\r\n    const content = fs.readFileSync(filePath, 'utf-8');\r\n    const match   = content.match(/export\\s+default\\s+(?:function\\s+)?(\\w+)/);\r\n    if (!match?.[1] || type.name !== match[1]) continue;\r\n\r\n    // This is a client boundary.\r\n    try {\r\n      ctx.hydrated.add(id);\r\n      const serializedProps = serializePropsForHydration(props, ctx.registry);\r\n      log.verbose(`Client component rendered for hydration: ${id} (${path.basename(filePath)})`);\r\n\r\n      // Optionally SSR the component so the initial HTML is meaningful\r\n      // (improves perceived performance and avoids layout shift).\r\n      const html = ctx.skipClientSSR\r\n        ? ''\r\n        : renderToString(createElement(type as React.ComponentType<any>, props));\r\n\r\n      return `<span data-hydrate-id=\"${id}\" data-hydrate-props=\"${escapeHtml(\r\n        JSON.stringify(serializedProps),\r\n      )}\">${html}</span>`;\r\n    } catch (err) {\r\n      log.error('Error rendering client component:', err);\r\n      return `<div style=\"color:red\">Error rendering client component: ${escapeHtml(String(err))}</div>`;\r\n    }\r\n  }\r\n\r\n  // Server component \u2014 call it and recurse into the result.\r\n  try {\r\n    const result   = type(props);\r\n    const resolved = result?.then ? await result : result;\r\n    return renderElementToHtml(resolved, ctx);\r\n  } catch (err) {\r\n    log.error('Error rendering component:', err);\r\n    return `<div style=\"color:red\">Error rendering component: ${escapeHtml(String(err))}</div>`;\r\n  }\r\n}\r\n\r\n// \u2500\u2500\u2500 Prop serialization \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Converts props into a JSON-serializable form for the data-hydrate-props\r\n * attribute.  React elements inside props are serialized to a tagged object\r\n * format ({ __re: 'html'|'client', \u2026 }) that the browser's reconstructElement\r\n * function (in bundle.ts) can turn back into real React elements.\r\n *\r\n * Functions are dropped (cannot be serialized).\r\n */\r\nfunction serializePropsForHydration(\r\n  props: any,\r\n  registry: Map<string, string>,\r\n): any {\r\n  if (!props || typeof props !== 'object') return props;\r\n  const out: any = {};\r\n  for (const [key, value] of Object.entries(props as Record<string, any>)) {\r\n    const s = serializeValue(value, registry);\r\n    if (s !== undefined) out[key] = s;\r\n  }\r\n  return out;\r\n}\r\n\r\nfunction serializeValue(value: any, registry: Map<string, string>): any {\r\n  if (value === null || value === undefined)  return value;\r\n  if (typeof value === 'function')            return undefined; // not serializable\r\n  if (typeof value !== 'object')              return value;\r\n  if (Array.isArray(value))\r\n    return value.map(v => serializeValue(v, registry)).filter(v => v !== undefined);\r\n  if ((value as any).$$typeof)\r\n    return serializeReactElement(value, registry);\r\n\r\n  const out: any = {};\r\n  for (const [k, v] of Object.entries(value as Record<string, any>)) {\r\n    const s = serializeValue(v, registry);\r\n    if (s !== undefined) out[k] = s;\r\n  }\r\n  return out;\r\n}\r\n\r\n/**\r\n * Serializes a React element to its wire format:\r\n *   Native element  \u2192 { __re: 'html',   tag, props }\r\n *   Client component \u2192 { __re: 'client', componentId, props }\r\n *   Server component \u2192 undefined (cannot be serialized)\r\n */\r\nfunction serializeReactElement(element: any, registry: Map<string, string>): any {\r\n  const { type, props } = element;\r\n\r\n  if (typeof type === 'string') {\r\n    return { __re: 'html', tag: type, props: serializePropsForHydration(props, registry) };\r\n  }\r\n\r\n  if (typeof type === 'function') {\r\n    const componentCache = getComponentCache();\r\n    for (const [id, filePath] of registry.entries()) {\r\n      const info = componentCache.get(filePath);\r\n      if (!info?.isClientComponent) continue;\r\n      const content = fs.readFileSync(filePath, 'utf-8');\r\n      const match   = content.match(/export\\s+default\\s+(?:function\\s+)?(\\w+)/);\r\n      if (match?.[1] && type.name === match[1]) {\r\n        return {\r\n          __re:        'client',\r\n          componentId: id,\r\n          props:       serializePropsForHydration(props, registry),\r\n        };\r\n      }\r\n    }\r\n  }\r\n\r\n  return undefined; // Server component \u2014 not serializable\r\n}\r\n"],
+  "mappings": "AAyBA,OAAO,UAAU;AACjB,OAAO,QAAQ;AACf,SAAS,eAAe,gBAAgB;AACxC,SAAS,sBAAsB;AAC/B,SAAS,WAAW;AACpB,SAAS,yBAAyB;AAClC,SAAS,kBAAkB;AA0B3B,eAAsB,oBACpB,SACA,KACiB;AACjB,MAAI,YAAY,QAAQ,YAAY,UAAa,OAAO,YAAY,UAAW,QAAO;AACtF,MAAI,OAAO,YAAY,YAAY,OAAO,YAAY;AACpD,WAAO,WAAW,OAAO,OAAO,CAAC;AAEnC,MAAI,MAAM,QAAQ,OAAO,GAAG;AAC1B,UAAM,QAAQ,MAAM,QAAQ,IAAI,QAAQ,IAAI,OAAK,oBAAoB,GAAG,GAAG,CAAC,CAAC;AAC7E,WAAO,MAAM,KAAK,EAAE;AAAA,EACtB;AAEA,MAAI,CAAC,QAAQ,KAAM,QAAO;AAE1B,QAAM,EAAE,MAAM,MAAM,IAAI;AAExB,MAAI,SAAS,SAAuB,QAAO,oBAAoB,MAAM,UAAU,GAAG;AAClF,MAAI,OAAO,SAAS,SAAgB,QAAO,kBAAkB,MAAM,OAAO,GAAG;AAC7E,MAAI,OAAO,SAAS,WAAgB,QAAO,wBAAwB,MAAM,OAAO,GAAG;AAEnF,SAAO;AACT;AAgBA,eAAe,kBACb,MACA,OACA,KACiB;AACjB,QAAM,EAAE,UAAU,GAAG,WAAW,IAAK,SAAS,CAAC;AAE/C,QAAM,QAAQ,OAAO,QAAQ,UAAiC,EAC3D,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM;AAErB,QAAI,QAAQ,YAA0B,OAAM;AAC5C,QAAI,QAAQ,UAA0B,OAAM;AAC5C,QAAI,QAAQ,0BAA2B,QAAO;AAE9C,QAAI,OAAO,UAAU,UAAW,QAAO,QAAQ,MAAM;AAGrD,QAAI,QAAQ,WAAW,OAAO,UAAU,UAAU;AAChD,YAAM,WAAW,OAAO,QAAQ,KAAK,EAClC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM;AACf,cAAM,OAAU,EAAE,QAAQ,UAAU,OAAK,IAAI,EAAE,YAAY,CAAC,EAAE;AAE9D,cAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,cAAc,EAAE;AAClD,eAAO,GAAG,IAAI,IAAI,OAAO;AAAA,MAC3B,CAAC,EACA,KAAK,GAAG;AACX,aAAO,UAAU,QAAQ;AAAA,IAC3B;AAEA,WAAO,GAAG,GAAG,KAAK,WAAW,OAAO,KAAK,CAAC,CAAC;AAAA,EAC7C,CAAC,EACA,OAAO,OAAO,EACd,KAAK,GAAG;AAEX,QAAM,UAAU,QAAQ,IAAI,KAAK,KAAK;AAEtC,MAAI,OAAO,yBAAyB;AAClC,WAAO,IAAI,IAAI,GAAG,OAAO,IAAI,MAAM,wBAAwB,MAAM,KAAK,IAAI;AAAA,EAC5E;AAGA,MAAI,CAAC,OAAO,MAAM,MAAM,SAAS,QAAQ,MAAM,EAAE,SAAS,IAAI,GAAG;AAC/D,WAAO,IAAI,IAAI,GAAG,OAAO;AAAA,EAC3B;AAEA,QAAM,eAAe,WAAW,MAAM,oBAAoB,UAAU,GAAG,IAAI;AAC3E,SAAO,IAAI,IAAI,GAAG,OAAO,IAAI,YAAY,KAAK,IAAI;AACpD;AAsBA,eAAe,wBACb,MACA,OACA,KACiB;AACjB,QAAM,iBAAiB,kBAAkB;AAGzC,aAAW,CAAC,IAAI,QAAQ,KAAK,IAAI,SAAS,QAAQ,GAAG;AACnD,UAAM,OAAO,eAAe,IAAI,QAAQ;AACxC,QAAI,CAAC,MAAM,kBAAmB;AAG9B,UAAM,UAAU,GAAG,aAAa,UAAU,OAAO;AACjD,UAAM,QAAU,QAAQ,MAAM,0CAA0C;AACxE,QAAI,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,MAAM,CAAC,EAAG;AAG3C,QAAI;AACF,UAAI,SAAS,IAAI,EAAE;AACnB,YAAM,kBAAkB,2BAA2B,OAAO,IAAI,QAAQ;AACtE,UAAI,QAAQ,4CAA4C,EAAE,KAAK,KAAK,SAAS,QAAQ,CAAC,GAAG;AAIzF,YAAM,OAAO,IAAI,gBACb,KACA,eAAe,cAAc,MAAkC,KAAK,CAAC;AAEzE,aAAO,0BAA0B,EAAE,yBAAyB;AAAA,QAC1D,KAAK,UAAU,eAAe;AAAA,MAChC,CAAC,KAAK,IAAI;AAAA,IACZ,SAAS,KAAK;AACZ,UAAI,MAAM,qCAAqC,GAAG;AAClD,aAAO,4DAA4D,WAAW,OAAO,GAAG,CAAC,CAAC;AAAA,IAC5F;AAAA,EACF;AAGA,MAAI;AACF,UAAM,SAAW,KAAK,KAAK;AAC3B,UAAM,WAAW,QAAQ,OAAO,MAAM,SAAS;AAC/C,WAAO,oBAAoB,UAAU,GAAG;AAAA,EAC1C,SAAS,KAAK;AACZ,QAAI,MAAM,8BAA8B,GAAG;AAC3C,WAAO,qDAAqD,WAAW,OAAO,GAAG,CAAC,CAAC;AAAA,EACrF;AACF;AAYA,SAAS,2BACP,OACA,UACK;AACL,MAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;AAChD,QAAM,MAAW,CAAC;AAClB,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAA4B,GAAG;AACvE,UAAM,IAAI,eAAe,OAAO,QAAQ;AACxC,QAAI,MAAM,OAAW,KAAI,GAAG,IAAI;AAAA,EAClC;AACA,SAAO;AACT;AAEA,SAAS,eAAe,OAAY,UAAoC;AACtE,MAAI,UAAU,QAAQ,UAAU,OAAY,QAAO;AACnD,MAAI,OAAO,UAAU,WAAuB,QAAO;AACnD,MAAI,OAAO,UAAU,SAAuB,QAAO;AACnD,MAAI,MAAM,QAAQ,KAAK;AACrB,WAAO,MAAM,IAAI,OAAK,eAAe,GAAG,QAAQ,CAAC,EAAE,OAAO,OAAK,MAAM,MAAS;AAChF,MAAK,MAAc;AACjB,WAAO,sBAAsB,OAAO,QAAQ;AAE9C,QAAM,MAAW,CAAC;AAClB,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,KAA4B,GAAG;AACjE,UAAM,IAAI,eAAe,GAAG,QAAQ;AACpC,QAAI,MAAM,OAAW,KAAI,CAAC,IAAI;AAAA,EAChC;AACA,SAAO;AACT;AAQA,SAAS,sBAAsB,SAAc,UAAoC;AAC/E,QAAM,EAAE,MAAM,MAAM,IAAI;AAExB,MAAI,OAAO,SAAS,UAAU;AAC5B,WAAO,EAAE,MAAM,QAAQ,KAAK,MAAM,OAAO,2BAA2B,OAAO,QAAQ,EAAE;AAAA,EACvF;AAEA,MAAI,OAAO,SAAS,YAAY;AAC9B,UAAM,iBAAiB,kBAAkB;AACzC,eAAW,CAAC,IAAI,QAAQ,KAAK,SAAS,QAAQ,GAAG;AAC/C,YAAM,OAAO,eAAe,IAAI,QAAQ;AACxC,UAAI,CAAC,MAAM,kBAAmB;AAC9B,YAAM,UAAU,GAAG,aAAa,UAAU,OAAO;AACjD,YAAM,QAAU,QAAQ,MAAM,0CAA0C;AACxE,UAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,MAAM,CAAC,GAAG;AACxC,eAAO;AAAA,UACL,MAAa;AAAA,UACb,aAAa;AAAA,UACb,OAAa,2BAA2B,OAAO,QAAQ;AAAA,QACzD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO;AACT;",
+  "names": []
+}

package/dist/router.d.ts

@@ -0,0 +1,84 @@
+/**
+ * router.ts — File-System Based URL Router
+ *
+ * Maps incoming URL paths to handler files using Next.js-compatible conventions:
+ *
+ *   server/users/index.ts          → /users
+ *   server/users/[id].ts           → /users/:id         (dynamic segment)
+ *   server/blog/[...slug].ts       → /blog/*            (catch-all)
+ *   server/files/[[...path]].ts    → /files or /files/* (optional catch-all)
+ *
+ * Route specificity (higher = wins over lower):
+ *   static segment     +4   (e.g. 'about')
+ *   dynamic segment    +3   (e.g. '[id]')
+ *   catch-all          +2   (e.g. '[...slug]')
+ *   optional catch-all +1   (e.g. '[[...path]]')
+ *
+ * Path traversal protection:
+ *   matchRoute() rejects URL segments that contain '..' or '.' and verifies
+ *   that the resolved file path stays inside the base directory before
+ *   checking whether the file exists.
+ */
+/**
+ * Recursively collects all .ts/.tsx files in `dir`, returning paths relative to
+ * `baseDir` without the file extension.
+ *
+ * Example output: ['index', 'users/index', 'users/[id]', 'blog/[...slug]']
+ */
+export declare function findAllRoutes(dir: string, baseDir?: string): string[];
+/**
+ * Attempts to match `urlSegments` against a route that may contain dynamic
+ * segments ([param]), catch-alls ([...slug]), and optional catch-alls ([[...path]]).
+ *
+ * Returns the captured params on success, or null if the route does not match.
+ *
+ * Param value types:
+ *   [param]         → string
+ *   [...slug]       → string[]  (at least one segment required)
+ *   [[...path]]     → string[]  (zero or more segments)
+ */
+export declare function matchDynamicRoute(urlSegments: string[], routePath: string): {
+    params: Record<string, string | string[]>;
+} | null;
+/**
+ * Computes a specificity score for a route path.
+ * Used to sort candidate routes so more specific routes shadow catch-alls.
+ *
+ * Higher score = more specific:
+ *   static segment      4
+ *   [dynamic]           3
+ *   [...catchAll]       2
+ *   [[...optCatchAll]]  1
+ */
+export declare function getRouteSpecificity(routePath: string): number;
+export interface RouteMatch {
+    filePath: string;
+    params: Record<string, string | string[]>;
+    routePattern: string;
+}
+/**
+ * Resolves a URL path to a route file inside `baseDir`.
+ *
+ * Steps:
+ *   1. Reject '..' or '.' path segments (path traversal guard).
+ *   2. Try an exact file match (e.g. /about → baseDir/about.tsx).
+ *   3. Sort all discovered routes by specificity (most specific first).
+ *   4. Return the first dynamic route that matches.
+ *
+ * @param urlPath   The URL path to match (e.g. '/users/42').
+ * @param baseDir   Absolute path to the directory containing route files.
+ * @param extension File extension to look for ('.tsx' or '.ts').
+ */
+export declare function matchRoute(urlPath: string, baseDir: string, extension?: string): RouteMatch | null;
+/**
+ * Returns every layout.tsx file that wraps a given route file, in
+ * outermost-first order (root layout first, nearest layout last).
+ *
+ * Layout chain example for app/pages/blog/[slug]/page.tsx:
+ *   app/pages/layout.tsx          ← root layout
+ *   app/pages/blog/layout.tsx     ← blog section layout
+ *
+ * The outermost-first order matches how wrapWithLayouts() nests them:
+ * the last layout in the array is the innermost wrapper.
+ */
+export declare function findLayoutsForRoute(routeFilePath: string, pagesDir: string): string[];