ruvyxa 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thirawat Sinlapasomsak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# ruvyxa
+
+Rust-powered full-stack TypeScript framework CLI and runtime.
+
+## Install
+
+```bash
+npm install ruvyxa
+```
+
+The `ruvyxa` npm package includes the TypeScript runtime files and a native CLI binary for the current release platform. Users do not need Rust or Cargo to run the CLI after installing from npm.
+
+## Usage
+
+```bash
+npx ruvyxa dev --root .
+npx ruvyxa build --root .
+npx ruvyxa start --root .
+```
+
+Framework APIs are re-exported from `@ruvyxa/core`:
+
+```ts
+import { defineConfig, action, loader } from "ruvyxa"
+```
+
+## Publish Notes
+
+This package runs `prepack` before publishing. The script builds `dist/` and copies the release binary into `native-bin/` so the published CLI can run outside the monorepo. Platform-specific packages such as `@ruvyxa/cli-win32-x64` can also provide the binary as optional dependencies.

package/bin/ruvyxa.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import { chmodSync, existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(here, "..")
+const monorepoRoot = resolve(here, "../../..")
+const executable = process.platform === "win32" ? "ruvyxa.exe" : "ruvyxa"
+const platformKey = `${process.platform}-${process.arch}`
+
+const binary = findBinary()
+
+if (!binary) {
+  console.error(`Ruvyxa native CLI binary was not found for ${platformKey}.`)
+  console.error("Reinstall ruvyxa, or install the matching @ruvyxa/cli-* optional package.")
+  console.error("When working from source, run `cargo build -p ruvyxa_cli` first.")
+  process.exit(1)
+}
+
+const result = spawnSync(binary, process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdio: "inherit",
+  shell: process.platform === "win32",
+})
+
+if (result.error) {
+  console.error(`Failed to run Ruvyxa native CLI at ${binary}: ${result.error.message}`)
+  process.exit(1)
+}
+
+process.exit(result.status ?? 1)
+
+function findBinary() {
+  const bundled = resolve(packageRoot, "native-bin", platformKey, executable)
+  if (existsSync(bundled)) return prepareExecutable(bundled)
+
+  const optionalPackage = optionalBinaryPackageName()
+  if (optionalPackage) {
+    try {
+      const packageJson = import.meta.resolve(`${optionalPackage}/package.json`)
+      const packageRoot = dirname(fileURLToPath(packageJson))
+      const optionalBinary = join(packageRoot, "bin", executable)
+      if (existsSync(optionalBinary)) return prepareExecutable(optionalBinary)
+    } catch {
+      // Optional platform package is absent on unsupported platforms.
+    }
+  }
+
+  for (const profile of ["debug", "release"]) {
+    const sourceBinary = resolve(monorepoRoot, "target", profile, executable)
+    if (existsSync(sourceBinary)) return prepareExecutable(sourceBinary)
+  }
+
+  return null
+}
+
+function prepareExecutable(binary) {
+  if (process.platform !== "win32") {
+    chmodSync(binary, 0o755)
+  }
+
+  return binary
+}
+
+function optionalBinaryPackageName() {
+  switch (platformKey) {
+    case "darwin-arm64":
+      return "@ruvyxa/cli-darwin-arm64"
+    case "darwin-x64":
+      return "@ruvyxa/cli-darwin-x64"
+    case "linux-arm64":
+      return "@ruvyxa/cli-linux-arm64"
+    case "linux-x64":
+      return "@ruvyxa/cli-linux-x64"
+    case "win32-x64":
+      return "@ruvyxa/cli-win32-x64"
+    default:
+      return null
+  }
+}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export * from "@ruvyxa/core/config";
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA"}

package/dist/config.js

@@ -0,0 +1,2 @@
+export * from "@ruvyxa/core/config";
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "@ruvyxa/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "@ruvyxa/core";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export * from "@ruvyxa/core/server";
+//# 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,cAAc,qBAAqB,CAAA"}

package/dist/server.js

@@ -0,0 +1,2 @@
+export * from "@ruvyxa/core/server";
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "ruvyxa",
+  "version": "1.0.0",
+  "description": "The Ruvyxa CLI and runtime: Rust-powered full-stack TypeScript with SSR, actions, HMR, and production-accurate builds.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ruvyxa": "./bin/ruvyxa.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "native-bin",
+    "runtime/action-renderer.mjs",
+    "runtime/api-renderer.mjs",
+    "runtime/client-renderer.mjs",
+    "runtime/ssr-renderer.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "framework",
+    "typescript",
+    "react",
+    "rust",
+    "ssr",
+    "fullstack"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thirawat27/ruvyxa.git",
+    "directory": "packages/ruvyxa"
+  },
+  "bugs": {
+    "url": "https://github.com/thirawat27/ruvyxa/issues"
+  },
+  "homepage": "https://github.com/thirawat27/ruvyxa#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    }
+  },
+  "dependencies": {
+    "esbuild": "^0.27.2",
+    "@ruvyxa/core": "^1.0.0"
+  },
+  "optionalDependencies": {
+    "@ruvyxa/cli-darwin-arm64": "^1.0.0",
+    "@ruvyxa/cli-darwin-x64": "^1.0.0",
+    "@ruvyxa/cli-linux-arm64": "^1.0.0",
+    "@ruvyxa/cli-linux-x64": "^1.0.0",
+    "@ruvyxa/cli-win32-x64": "^1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "format": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/runtime/action-renderer.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto"
+import { mkdir } from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { build } from "esbuild"
+
+const [
+  projectRootArg,
+  actionFileArg,
+  actionName = "",
+  payloadJson = "{}",
+  requestPath = "/",
+] = process.argv.slice(2)
+
+if (!projectRootArg || !actionFileArg || !actionName) {
+  fail("RUV1503", "Action renderer requires projectRoot, actionFile, and actionName arguments.")
+}
+
+const projectRoot = path.resolve(projectRootArg)
+const actionFile = path.resolve(actionFileArg)
+
+try {
+  const bundleFile = await bundleActionModule(projectRoot, actionFile)
+  const mod = await import(pathToFileURL(bundleFile).href + `?t=${Date.now()}`)
+  const action = mod[actionName]
+
+  if (typeof action !== "function" || action.ruvyxa?.kind !== "action") {
+    process.stdout.write(
+      JSON.stringify({
+        ok: true,
+        status: 404,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body: JSON.stringify({
+          error: `Action ${actionName} was not found in ${path.basename(actionFile)}`,
+        }),
+      }),
+    )
+    process.exit(0)
+  }
+
+  const input = parsePayload(payloadJson)
+  const invalidated = []
+  const request = new Request(`http://localhost${requestPath}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(input),
+  })
+  const result = await action(input, {
+    request,
+    invalidate(key) {
+      invalidated.push(key)
+    },
+  })
+  const response = normalizeActionResult(result, invalidated)
+  const body = await response.text()
+  const headers = Object.fromEntries(response.headers.entries())
+
+  process.stdout.write(
+    JSON.stringify({
+      ok: true,
+      status: response.status,
+      headers,
+      body,
+    }),
+  )
+} catch (error) {
+  fail("RUV1500", error instanceof Error ? error.message : String(error), error?.stack)
+}
+
+async function bundleActionModule(projectRoot, actionFile) {
+  const cacheDir = path.join(projectRoot, ".ruvyxa", "cache", "actions")
+  await mkdir(cacheDir, { recursive: true })
+
+  const moduleCode = `export * from ${JSON.stringify(toImportPath(actionFile))}`
+  const hash = createHash("sha256")
+    .update(moduleCode)
+    .update(actionFile)
+    .digest("hex")
+    .slice(0, 16)
+  const outfile = path.join(cacheDir, `${hash}.mjs`)
+
+  await build({
+    stdin: {
+      contents: moduleCode,
+      resolveDir: projectRoot,
+      sourcefile: "ruvyxa:action-entry.ts",
+      loader: "ts",
+    },
+    outfile,
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    absWorkingDir: projectRoot,
+  })
+
+  return outfile
+}
+
+function parsePayload(payloadJson) {
+  let parsed
+  try {
+    parsed = JSON.parse(payloadJson || "{}")
+  } catch {
+    parsed = Object.fromEntries(new URLSearchParams(payloadJson))
+  }
+
+  if (parsed && typeof parsed === "object" && "input" in parsed) {
+    return parsed.input
+  }
+  return parsed
+}
+
+function normalizeActionResult(result, invalidated) {
+  if (result instanceof Response) {
+    return result
+  }
+
+  return Response.json({ data: result, invalidated })
+}
+
+function toImportPath(file) {
+  return path.resolve(file).replaceAll("\\", "/")
+}
+
+function fail(code, message, stack) {
+  process.stdout.write(JSON.stringify({ ok: false, code, message, stack }))
+  process.exit(1)
+}

package/runtime/api-renderer.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto"
+import { mkdir } from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { build } from "esbuild"
+
+const [
+  projectRootArg,
+  routeFileArg,
+  method = "GET",
+  requestPath = "/",
+  paramsJson = "{}",
+] = process.argv.slice(2)
+
+if (!projectRootArg || !routeFileArg) {
+  fail("RUV1201", "API renderer requires projectRoot and routeFile arguments.")
+}
+
+const projectRoot = path.resolve(projectRootArg)
+const routeFile = path.resolve(routeFileArg)
+
+try {
+  const bundleFile = await bundleApiModule(projectRoot, routeFile)
+  const mod = await import(pathToFileURL(bundleFile).href + `?t=${Date.now()}`)
+  const handler = mod[method.toUpperCase()]
+
+  if (typeof handler !== "function") {
+    process.stdout.write(
+      JSON.stringify({
+        ok: true,
+        status: 405,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+        body: `Method ${method.toUpperCase()} is not allowed`,
+      }),
+    )
+    process.exit(0)
+  }
+
+  const request = new Request(`http://localhost${requestPath}`, { method: method.toUpperCase() })
+  const result = await handler({
+    request,
+    params: JSON.parse(paramsJson),
+  })
+  const response = normalizeResponse(result)
+  const body = await response.text()
+  const headers = Object.fromEntries(response.headers.entries())
+
+  process.stdout.write(
+    JSON.stringify({
+      ok: true,
+      status: response.status,
+      headers,
+      body,
+    }),
+  )
+} catch (error) {
+  fail("RUV1200", error instanceof Error ? error.message : String(error), error?.stack)
+}
+
+async function bundleApiModule(projectRoot, routeFile) {
+  const cacheDir = path.join(projectRoot, ".ruvyxa", "cache", "api")
+  await mkdir(cacheDir, { recursive: true })
+
+  const moduleCode = `export * from ${JSON.stringify(toImportPath(routeFile))}`
+  const hash = createHash("sha256")
+    .update(moduleCode)
+    .update(routeFile)
+    .digest("hex")
+    .slice(0, 16)
+  const outfile = path.join(cacheDir, `${hash}.mjs`)
+
+  await build({
+    stdin: {
+      contents: moduleCode,
+      resolveDir: projectRoot,
+      sourcefile: "ruvyxa:api-entry.ts",
+      loader: "ts",
+    },
+    outfile,
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    absWorkingDir: projectRoot,
+  })
+
+  return outfile
+}
+
+function normalizeResponse(result) {
+  if (result instanceof Response) {
+    return result
+  }
+
+  return Response.json(result)
+}
+
+function toImportPath(file) {
+  return path.resolve(file).replaceAll("\\", "/")
+}
+
+function fail(code, message, stack) {
+  process.stdout.write(JSON.stringify({ ok: false, code, message, stack }))
+  process.exit(1)
+}

package/runtime/client-renderer.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto"
+import { existsSync } from "node:fs"
+import { mkdir, readFile } from "node:fs/promises"
+import path from "node:path"
+
+import { build } from "esbuild"
+
+const [projectRootArg, appDirArg, pageFileArg, requestPath = "/", paramsJson = "{}"] =
+  process.argv.slice(2)
+
+if (!projectRootArg || !appDirArg || !pageFileArg) {
+  fail("RUV1301", "Client renderer requires projectRoot, appDir, and pageFile arguments.")
+}
+
+const projectRoot = path.resolve(projectRootArg)
+const appDir = path.resolve(appDirArg)
+const pageFile = path.resolve(pageFileArg)
+
+try {
+  const layouts = collectLayouts(appDir, path.dirname(pageFile))
+  const bundleFile = await bundleClientModule(projectRoot, pageFile, layouts, requestPath, paramsJson)
+  const script = await readFile(bundleFile, "utf8")
+  process.stdout.write(JSON.stringify({ ok: true, script }))
+} catch (error) {
+  fail("RUV1300", error instanceof Error ? error.message : String(error), error?.stack)
+}
+
+function collectLayouts(appDir, routeDir) {
+  const layouts = []
+  let current = appDir
+
+  pushIfExists(layouts, path.join(current, "layout.tsx"))
+
+  const relative = path.relative(appDir, routeDir)
+  if (relative && !relative.startsWith("..")) {
+    for (const segment of relative.split(path.sep)) {
+      if (!segment) continue
+      current = path.join(current, segment)
+      pushIfExists(layouts, path.join(current, "layout.tsx"))
+    }
+  }
+
+  return layouts
+}
+
+function pushIfExists(collection, file) {
+  if (existsSync(file)) {
+    collection.push(file)
+  }
+}
+
+async function bundleClientModule(projectRoot, pageFile, layouts, requestPath, paramsJson) {
+  const cacheDir = path.join(projectRoot, ".ruvyxa", "cache", "client")
+  await mkdir(cacheDir, { recursive: true })
+
+  const imports = [`import Page from ${JSON.stringify(toImportPath(pageFile))}`]
+  const wrappers = []
+
+  layouts.forEach((layoutFile, index) => {
+    imports.push(`import Layout${index} from ${JSON.stringify(toImportPath(layoutFile))}`)
+    wrappers.push(`Layout${index}`)
+  })
+
+  const moduleCode = `
+import React from "react"
+import { hydrateRoot } from "react-dom/client"
+${imports.join("\n")}
+
+const params = globalThis.__RUVYXA_ROUTE_PARAMS__ ?? ${paramsJson}
+const currentRequestPath = globalThis.__RUVYXA_REQUEST_PATH__ ?? ${JSON.stringify(requestPath)}
+let tree = React.createElement(Page, { params, requestPath: currentRequestPath })
+for (const Layout of [${wrappers.join(", ")}].reverse()) {
+  tree = React.createElement(Layout, null, tree)
+}
+
+if (globalThis.__RUVYXA_ROOT__) {
+  globalThis.__RUVYXA_ROOT__.render(tree)
+} else {
+  globalThis.__RUVYXA_ROOT__ = hydrateRoot(document, tree)
+}
+window.__RUVYXA_HYDRATED = true
+`
+
+  const hash = createHash("sha256")
+    .update(moduleCode)
+    .update(pageFile)
+    .digest("hex")
+    .slice(0, 16)
+  const outfile = path.join(cacheDir, `${hash}.js`)
+
+  await build({
+    stdin: {
+      contents: moduleCode,
+      resolveDir: projectRoot,
+      sourcefile: "ruvyxa:client-entry.tsx",
+      loader: "tsx",
+    },
+    outfile,
+    bundle: true,
+    format: "iife",
+    platform: "browser",
+    jsx: "automatic",
+    minify: process.env.RUVYXA_CLIENT_MINIFY === "1",
+    treeShaking: true,
+    absWorkingDir: projectRoot,
+    plugins: [
+      clientBoundaryPlugin(projectRoot),
+      {
+        name: "ruvyxa-css-empty-module",
+        setup(build) {
+          build.onLoad({ filter: /\.css$/ }, () => ({ contents: "", loader: "js" }))
+        },
+      },
+    ],
+  })
+
+  return outfile
+}
+
+function clientBoundaryPlugin(projectRoot) {
+  return {
+    name: "ruvyxa-client-boundary",
+    setup(build) {
+      build.onResolve({ filter: /^server-only$/ }, (args) => {
+        throw boundaryError(
+          "RUV1007",
+          "Server-only module imported into client bundle",
+          args.importer,
+          'Remove `import "server-only"` from code that is reachable by the browser bundle.',
+        )
+      })
+
+      build.onResolve({ filter: /^client-only$/ }, () => ({
+        path: "ruvyxa:client-only",
+        namespace: "ruvyxa-virtual",
+      }))
+
+      build.onLoad({ filter: /^ruvyxa:client-only$/, namespace: "ruvyxa-virtual" }, () => ({
+        contents: "",
+        loader: "js",
+      }))
+
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+        if (!isProjectSource(projectRoot, args.path)) {
+          return null
+        }
+
+        const normalized = args.path.replaceAll("\\", "/")
+        const contents = await readFile(args.path, "utf8")
+
+        if (isServerOnlyPath(projectRoot, args.path)) {
+          throw boundaryError(
+            "RUV1007",
+            "Server-only file imported into client bundle",
+            args.path,
+            "Move this import behind a server loader/API route, or pass serialized data into the page.",
+          )
+        }
+
+        if (contents.includes('import "server-only"') || contents.includes("import 'server-only'")) {
+          throw boundaryError(
+            "RUV1007",
+            "Server-only module imported into client bundle",
+            args.path,
+            'Move server-only code out of the browser graph or remove `import "server-only"`.',
+          )
+        }
+
+        const privateEnv = findPrivateEnvAccess(contents)
+        if (privateEnv) {
+          throw boundaryError(
+            "RUV1008",
+            "Private environment variable used in client bundle",
+            args.path,
+            `Rename ${privateEnv} to RUVYXA_PUBLIC_* if it is safe for browsers, or move the code to server-only logic.`,
+          )
+        }
+
+        return {
+          contents,
+          loader: loaderFor(normalized),
+        }
+      })
+    },
+  }
+}
+
+function isProjectSource(projectRoot, file) {
+  const relative = path.relative(projectRoot, file)
+  return relative && !relative.startsWith("..") && !path.isAbsolute(relative) && !relative.includes("node_modules")
+}
+
+function isServerOnlyPath(projectRoot, file) {
+  const normalized = path.relative(projectRoot, file).replaceAll("\\", "/")
+  return (
+    normalized === "server.ts" ||
+    normalized === "server.js" ||
+    normalized.startsWith("server/") ||
+    normalized.endsWith("/server.ts") ||
+    normalized.endsWith("/server.js")
+  )
+}
+
+function findPrivateEnvAccess(contents) {
+  const matches = contents.matchAll(/\bprocess\.env\.([A-Z_][A-Z0-9_]*)/g)
+
+  for (const match of matches) {
+    const name = match[1]
+    if (name !== "NODE_ENV" && !name.startsWith("RUVYXA_PUBLIC_")) {
+      return name
+    }
+  }
+
+  return null
+}
+
+function loaderFor(file) {
+  if (file.endsWith(".tsx")) return "tsx"
+  if (file.endsWith(".jsx")) return "jsx"
+  if (file.endsWith(".ts") || file.endsWith(".mts") || file.endsWith(".cts")) return "ts"
+  return "js"
+}
+
+function boundaryError(code, title, file, fix) {
+  return new Error(`${code}: ${title}
+
+File:
+  ${file || "(entrypoint)"}
+
+Why this is a problem:
+  This module is reachable from the browser hydration bundle.
+
+Fix:
+  ${fix}`)
+}
+
+function toImportPath(file) {
+  return path.resolve(file).replaceAll("\\", "/")
+}
+
+function fail(code, message, stack) {
+  process.stdout.write(JSON.stringify({ ok: false, code, message, stack }))
+  process.exit(1)
+}

package/runtime/ssr-renderer.mjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto"
+import { existsSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { createRequire } from "node:module"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { build } from "esbuild"
+
+const [projectRootArg, appDirArg, pageFileArg, requestPath = "/", paramsJson = "{}"] =
+  process.argv.slice(2)
+
+if (!projectRootArg || !appDirArg || !pageFileArg) {
+  fail("RUV1101", "SSR renderer requires projectRoot, appDir, and pageFile arguments.")
+}
+
+const projectRoot = path.resolve(projectRootArg)
+const appDir = path.resolve(appDirArg)
+const pageFile = path.resolve(pageFileArg)
+
+try {
+  const requireFromProject = createRequire(path.join(projectRoot, "package.json"))
+  requireFromProject.resolve("react")
+  requireFromProject.resolve("react-dom/server")
+
+  const layouts = collectLayouts(appDir, path.dirname(pageFile))
+  const bundleFile = await bundleSsrModule(projectRoot, pageFile, layouts)
+  const mod = await import(pathToFileURL(bundleFile).href + `?t=${Date.now()}`)
+  const html = await mod.render({ path: requestPath, params: JSON.parse(paramsJson) })
+
+  process.stdout.write(JSON.stringify({ ok: true, html }))
+} catch (error) {
+  fail("RUV1100", error instanceof Error ? error.message : String(error), error?.stack)
+}
+
+function collectLayouts(appDir, routeDir) {
+  const layouts = []
+  let current = appDir
+
+  pushIfExists(layouts, path.join(current, "layout.tsx"))
+
+  const relative = path.relative(appDir, routeDir)
+  if (relative && !relative.startsWith("..")) {
+    for (const segment of relative.split(path.sep)) {
+      if (!segment) continue
+      current = path.join(current, segment)
+      pushIfExists(layouts, path.join(current, "layout.tsx"))
+    }
+  }
+
+  return layouts
+}
+
+function pushIfExists(collection, file) {
+  if (existsSync(file)) {
+    collection.push(file)
+  }
+}
+
+async function bundleSsrModule(projectRoot, pageFile, layouts) {
+  const cacheDir = path.join(projectRoot, ".ruvyxa", "cache", "ssr")
+  await mkdir(cacheDir, { recursive: true })
+
+  const imports = [`import Page from ${JSON.stringify(toImportPath(pageFile))}`]
+  const wrappers = []
+
+  layouts.forEach((layoutFile, index) => {
+    imports.push(`import Layout${index} from ${JSON.stringify(toImportPath(layoutFile))}`)
+    wrappers.push(`Layout${index}`)
+  })
+
+  const moduleCode = `
+import React from "react"
+import { renderToString } from "react-dom/server"
+${imports.join("\n")}
+
+export async function render(ctx) {
+  let tree = React.createElement(Page, { params: ctx.params ?? {}, requestPath: ctx.path })
+  for (const Layout of [${wrappers.join(", ")}].reverse()) {
+    tree = React.createElement(Layout, null, tree)
+  }
+  return "<!doctype html>" + renderToString(tree)
+}
+`
+
+  const hash = createHash("sha256")
+    .update(moduleCode)
+    .update(pageFile)
+    .digest("hex")
+    .slice(0, 16)
+  const outfile = path.join(cacheDir, `${hash}.mjs`)
+
+  await build({
+    stdin: {
+      contents: moduleCode,
+      resolveDir: projectRoot,
+      sourcefile: "ruvyxa:ssr-entry.tsx",
+      loader: "tsx",
+    },
+    outfile,
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    jsx: "automatic",
+    absWorkingDir: projectRoot,
+    external: ["react", "react-dom/server"],
+    plugins: [
+      {
+        name: "ruvyxa-css-empty-module",
+        setup(build) {
+          build.onLoad({ filter: /\.css$/ }, () => ({ contents: "", loader: "js" }))
+        },
+      },
+    ],
+  })
+
+  return outfile
+}
+
+function toImportPath(file) {
+  return path.resolve(file).replaceAll("\\", "/")
+}
+
+function fail(code, message, stack) {
+  process.stdout.write(JSON.stringify({ ok: false, code, message, stack }))
+  process.exit(1)
+}