@praxisjs/ssg 0.1.0

package/dist/routes.d.ts

@@ -0,0 +1,32 @@
+import type { RouteComponent, RouteDefinition } from "@praxisjs/router";
+/** Expands the one dynamic route it's declared on into concrete paths — colocated alternative to the global `getStaticPaths` export on `root`. Takes precedence over it for that route. Receives the route's own full path, so helpers like `@praxisjs/content`'s `collectionStaticPaths()` don't need it repeated. */
+export type RouteStaticPaths = (fullPath: string) => Promise<string[]>;
+/** Same shape `@Router([...])` itself accepts — a plain RouteDefinition (optionally with its own `getStaticPaths`) or a bare @Route-decorated class. */
+export type RouteEntry = (RouteDefinition & {
+    getStaticPaths?: RouteStaticPaths;
+}) | RouteComponent;
+/** Normalizes top-level route entries the same way the `@Router` decorator does, before passing them to `createRouter`. */
+export declare function normalizeRoutes(routes: RouteEntry[]): RouteDefinition[];
+export interface FlattenedRoute {
+    route: RouteDefinition;
+    fullPath: string;
+}
+/** Mirrors RouterInstance's own path-prefixing in @praxisjs/router (router.ts's addRoute). */
+export declare function flattenRoutes(routes: RouteDefinition[], prefix?: string): FlattenedRoute[];
+export declare function isStaticPath(path: string): boolean;
+export type GetStaticPaths = (route: RouteDefinition, fullPath: string) => Promise<string[]>;
+export interface ResolvePathsConfig {
+    routes: RouteDefinition[];
+    getStaticPaths?: GetStaticPaths;
+}
+/**
+ * Resolves every concrete path to prerender: static routes are used as-is;
+ * dynamic routes (`:slug`, `**`) are expanded via the route's own
+ * `getStaticPaths` if it declared one, falling back to the global
+ * `getStaticPaths` — otherwise they're skipped (documented: nothing to
+ * enumerate without either).
+ */
+export declare function resolvePaths(config: ResolvePathsConfig): Promise<string[]>;
+/** `/` -> `index.html`; `/about` -> `about/index.html`; trailing-slash convention. */
+export declare function pathToOutputFile(path: string): string;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxE,uTAAuT;AACvT,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAEvE,wJAAwJ;AACxJ,MAAM,MAAM,UAAU,GAAG,CAAC,eAAe,GAAG;IAAE,cAAc,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAAG,cAAc,CAAC;AAEpG,2HAA2H;AAC3H,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,eAAe,EAAE,CAEvE;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,MAAM,SAAK,GAAG,cAAc,EAAE,CAUtF;AAMD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAE7F,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsBhF;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGrD"}

package/dist/routes.js

@@ -0,0 +1,59 @@
+import { normalizeRoute } from "@praxisjs/router/internal";
+/** Normalizes top-level route entries the same way the `@Router` decorator does, before passing them to `createRouter`. */
+export function normalizeRoutes(routes) {
+    return routes.map(normalizeRoute);
+}
+/** Mirrors RouterInstance's own path-prefixing in @praxisjs/router (router.ts's addRoute). */
+export function flattenRoutes(routes, prefix = "") {
+    const out = [];
+    for (const route of routes) {
+        const fullPath = prefix + route.path;
+        out.push({ route, fullPath });
+        if (route.children) {
+            out.push(...flattenRoutes(route.children, fullPath === "/" ? "" : fullPath));
+        }
+    }
+    return out;
+}
+// Matches the same segment shapes @praxisjs/router's compilePath() does (utils.ts):
+// ":name", ":name?" (optional param), "**" (catch-all).
+const DYNAMIC_SEGMENT = /:[^/?]+\??|\*\*/;
+export function isStaticPath(path) {
+    return !DYNAMIC_SEGMENT.test(path);
+}
+/**
+ * Resolves every concrete path to prerender: static routes are used as-is;
+ * dynamic routes (`:slug`, `**`) are expanded via the route's own
+ * `getStaticPaths` if it declared one, falling back to the global
+ * `getStaticPaths` — otherwise they're skipped (documented: nothing to
+ * enumerate without either).
+ */
+export async function resolvePaths(config) {
+    const flattened = flattenRoutes(config.routes);
+    const paths = new Set();
+    for (const { route, fullPath } of flattened) {
+        if (isStaticPath(fullPath)) {
+            paths.add(fullPath);
+            continue;
+        }
+        // normalizeRoute() passes plain route-literal objects through unchanged,
+        // so this survives even though RouteDefinition itself doesn't declare it.
+        const ownStaticPaths = route.getStaticPaths;
+        const expanded = ownStaticPaths
+            ? await ownStaticPaths(fullPath)
+            : config.getStaticPaths
+                ? await config.getStaticPaths(route, fullPath)
+                : undefined;
+        if (!expanded)
+            continue;
+        for (const p of expanded)
+            paths.add(p);
+    }
+    return Array.from(paths);
+}
+/** `/` -> `index.html`; `/about` -> `about/index.html`; trailing-slash convention. */
+export function pathToOutputFile(path) {
+    const trimmed = path.replace(/^\/+|\/+$/g, "");
+    return trimmed === "" ? "index.html" : `${trimmed}/index.html`;
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQ3D,2HAA2H;AAC3H,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,OAAO,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACpC,CAAC;AAOD,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,MAAyB,EAAE,MAAM,GAAG,EAAE;IAClE,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC;QACrC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,GAAG,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oFAAoF;AACpF,wDAAwD;AACxD,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAE1C,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AASD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAA0B;IAC3D,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,SAAS,EAAE,CAAC;QAC5C,IAAI,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3B,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,yEAAyE;QACzE,0EAA0E;QAC1E,MAAM,cAAc,GAAI,KAA+C,CAAC,cAAc,CAAC;QACvF,MAAM,QAAQ,GAAG,cAAc;YAC7B,CAAC,CAAC,MAAM,cAAc,CAAC,QAAQ,CAAC;YAChC,CAAC,CAAC,MAAM,CAAC,cAAc;gBACrB,CAAC,CAAC,MAAM,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC;gBAC9C,CAAC,CAAC,SAAS,CAAC;QAChB,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,KAAK,MAAM,CAAC,IAAI,QAAQ;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3B,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;IAC/C,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,aAAa,CAAC;AACjE,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@praxisjs/ssg",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./prerender": {
+      "import": "./dist/prerender.js",
+      "types": "./dist/prerender.d.ts"
+    }
+  },
+  "dependencies": {
+    "jsdom": "^29.0.1",
+    "@praxisjs/core": "2.1.0",
+    "@praxisjs/head": "0.3.0",
+    "@praxisjs/router": "2.2.0",
+    "@praxisjs/runtime": "0.6.0",
+    "@praxisjs/shared": "0.3.1"
+  },
+  "peerDependencies": {
+    "vite": ">=8.0.0"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.1.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}

package/src/__tests__/loader-hook.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from "vitest";
+
+import type { ResolveFnOutput, ResolveHookContext } from "node:module";
+
+import { resolve } from "../loader-hook";
+
+const CONTEXT = {} as ResolveHookContext;
+
+function notFound(): never {
+  const err = new Error("not found") as Error & { code?: string };
+  err.code = "ERR_MODULE_NOT_FOUND";
+  throw err;
+}
+
+function ok(url: string): ResolveFnOutput {
+  return { url, shortCircuit: true } as ResolveFnOutput;
+}
+
+describe("loader-hook resolve()", () => {
+  it("returns nextResolve's result directly when it succeeds", async () => {
+    const nextResolve = vi.fn(async () => ok("file:///real.js"));
+    const result = await resolve("./real", CONTEXT, nextResolve);
+    expect(result).toEqual(ok("file:///real.js"));
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("rethrows without retrying for a bare (non-relative) specifier", async () => {
+    const nextResolve = vi.fn(async () => notFound());
+    await expect(resolve("some-package", CONTEXT, nextResolve)).rejects.toThrow("not found");
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("rethrows without retrying when the error has no code", async () => {
+    const nextResolve = vi.fn(async () => {
+      throw new Error("weird failure");
+    });
+    await expect(resolve("./router", CONTEXT, nextResolve)).rejects.toThrow("weird failure");
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("rethrows without retrying for a non-retryable error code", async () => {
+    const nextResolve = vi.fn(async () => {
+      const err = new Error("permission denied") as Error & { code?: string };
+      err.code = "EACCES";
+      throw err;
+    });
+    await expect(resolve("./router", CONTEXT, nextResolve)).rejects.toThrow("permission denied");
+    expect(nextResolve).toHaveBeenCalledOnce();
+  });
+
+  it("retries with a .js suffix and returns it when that succeeds", async () => {
+    const nextResolve = vi.fn(async (specifier: string) => {
+      if (specifier === "./router.js") return ok("file:///router.js");
+      return notFound();
+    });
+    const result = await resolve("./router", CONTEXT, nextResolve);
+    expect(result).toEqual(ok("file:///router.js"));
+    expect(nextResolve).toHaveBeenCalledTimes(2);
+  });
+
+  it("falls back to /index.js when the .js candidate also fails", async () => {
+    const nextResolve = vi.fn(async (specifier: string) => {
+      if (specifier === "./router/index.js") return ok("file:///router/index.js");
+      return notFound();
+    });
+    const result = await resolve("./router", CONTEXT, nextResolve);
+    expect(result).toEqual(ok("file:///router/index.js"));
+    expect(nextResolve).toHaveBeenCalledTimes(3);
+  });
+
+  it("rethrows the original error when both retry candidates fail", async () => {
+    const nextResolve = vi.fn(async () => notFound());
+    await expect(resolve("../router", CONTEXT, nextResolve)).rejects.toThrow("not found");
+    expect(nextResolve).toHaveBeenCalledTimes(3);
+  });
+});

package/src/__tests__/plugin.test.ts

@@ -0,0 +1,161 @@
+import { mkdtemp, readFile, rm, writeFile, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+import type { ResolvedConfig } from "vite";
+
+import { prerender } from "../prerender";
+import { ssgPlugin } from "../index";
+
+vi.mock("../prerender", () => ({
+  prerender: vi.fn(),
+  // Pass-through stand-in — the real DOM-global install/restore mechanics
+  // are covered in prerender.test.ts; here we only need loadEntry() to call
+  // through to whatever function it wraps.
+  withDomGlobals: vi.fn((_html: string, _url: string, fn: () => unknown) => fn()),
+}));
+
+const ssrLoadModule = vi.fn();
+const close = vi.fn();
+const createServer = vi.fn(async (_options: unknown) => ({ ssrLoadModule, close }));
+
+vi.mock("vite", () => ({
+  createServer: (options: unknown) => createServer(options),
+}));
+
+// registerLoaderHook()'s fallback path (module.register with a file URL)
+// assumes a built dist/ layout — loader-hook.js physically next to index.js
+// — which doesn't exist under vitest's on-the-fly source transform. The
+// mechanism itself is covered separately by running the actual built dist/
+// output through Node directly (see the plan's manual verification step);
+// here we only need to confirm ssgPlugin() triggers registration.
+const { registerHooks, register } = vi.hoisted(() => ({
+  registerHooks: vi.fn(),
+  register: vi.fn(),
+}));
+vi.mock("node:module", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:module")>();
+  return { ...actual, registerHooks, register };
+});
+
+const RootComponent = class {} as never;
+const routes = [{ path: "/", component: RootComponent }];
+
+function fakeResolvedConfig(root: string, outDir = "dist"): ResolvedConfig {
+  return {
+    root,
+    build: { outDir },
+    configFile: `${root}/vite.config.ts`,
+  } as unknown as ResolvedConfig;
+}
+
+describe("ssgPlugin()", () => {
+  let dir: string;
+
+  afterEach(async () => {
+    vi.clearAllMocks();
+    if (dir) await rm(dir, { recursive: true, force: true });
+  });
+
+  it("loads the root component and routes from a single SSR module load, prerenders, and writes files", async () => {
+    dir = await mkdtemp(join(tmpdir(), "praxisjs-ssg-"));
+    await mkdir(join(dir, "dist"), { recursive: true });
+    await writeFile(join(dir, "dist", "index.html"), "<html><body><div id=\"app\"></div></body></html>");
+
+    ssrLoadModule.mockResolvedValue({ default: RootComponent, routes });
+    vi.mocked(prerender).mockResolvedValue([
+      { path: "/", file: "index.html", html: "<html>home</html>" },
+      { path: "/about", file: "about/index.html", html: "<html>about</html>" },
+    ]);
+
+    const plugin = ssgPlugin({ root: "./src/app.tsx" });
+
+    // ssgPlugin() must register the extensionless-import retry hook
+    // synchronously, before closeBundle ever dynamically imports
+    // ./prerender (which is what actually needs it) — see index.ts.
+    expect(registerHooks.mock.calls.length + register.mock.calls.length).toBeGreaterThan(0);
+
+    const configResolved = plugin.configResolved as (c: ResolvedConfig) => void | Promise<void>;
+    await configResolved(fakeResolvedConfig(dir));
+    const closeBundle = plugin.closeBundle as () => Promise<void>;
+    await closeBundle();
+
+    expect(createServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        root: dir,
+        configFile: `${dir}/vite.config.ts`,
+        server: { middlewareMode: true, watch: null },
+        appType: "custom",
+        ssr: { external: true },
+        optimizeDeps: { noDiscovery: true, include: [] },
+      }),
+    );
+    // A single ssrLoadModule call reads both the default export and the
+    // named `routes` export — vite.config.ts never imports app source itself.
+    expect(ssrLoadModule).toHaveBeenCalledOnce();
+    expect(ssrLoadModule).toHaveBeenCalledWith("./src/app.tsx");
+    expect(close).toHaveBeenCalledOnce();
+
+    expect(prerender).toHaveBeenCalledWith(
+      expect.objectContaining({
+        root: RootComponent,
+        routes,
+        template: "<html><body><div id=\"app\"></div></body></html>",
+      }),
+    );
+
+    expect(await readFile(join(dir, "dist", "index.html"), "utf-8")).toBe("<html>home</html>");
+    expect(await readFile(join(dir, "dist", "about", "index.html"), "utf-8")).toBe("<html>about</html>");
+  });
+
+  it("throws a clear error when the root module has no default export", async () => {
+    dir = await mkdtemp(join(tmpdir(), "praxisjs-ssg-"));
+    await mkdir(join(dir, "dist"), { recursive: true });
+    await writeFile(join(dir, "dist", "index.html"), "<html><body><div id=\"app\"></div></body></html>");
+
+    ssrLoadModule.mockResolvedValue({ routes });
+
+    const plugin = ssgPlugin({ root: "./src/app.tsx" });
+    const configResolved = plugin.configResolved as (c: ResolvedConfig) => void | Promise<void>;
+    await configResolved(fakeResolvedConfig(dir));
+    const closeBundle = plugin.closeBundle as () => Promise<void>;
+
+    await expect(closeBundle()).rejects.toThrow(/no default export/);
+    expect(close).toHaveBeenCalledOnce(); // server is closed even on failure
+  });
+
+  it("throws a clear error when the root module has no named routes export", async () => {
+    dir = await mkdtemp(join(tmpdir(), "praxisjs-ssg-"));
+    await mkdir(join(dir, "dist"), { recursive: true });
+    await writeFile(join(dir, "dist", "index.html"), "<html><body><div id=\"app\"></div></body></html>");
+
+    ssrLoadModule.mockResolvedValue({ default: RootComponent });
+
+    const plugin = ssgPlugin({ root: "./src/app.tsx" });
+    const configResolved = plugin.configResolved as (c: ResolvedConfig) => void | Promise<void>;
+    await configResolved(fakeResolvedConfig(dir));
+    const closeBundle = plugin.closeBundle as () => Promise<void>;
+
+    await expect(closeBundle()).rejects.toThrow(/no named "routes" export/);
+    expect(close).toHaveBeenCalledOnce();
+  });
+
+  it("passes hydrate: false through to prerender()", async () => {
+    dir = await mkdtemp(join(tmpdir(), "praxisjs-ssg-"));
+    await mkdir(join(dir, "dist"), { recursive: true });
+    await writeFile(join(dir, "dist", "index.html"), "<html><body><div id=\"app\"></div></body></html>");
+
+    ssrLoadModule.mockResolvedValue({ default: RootComponent, routes });
+    vi.mocked(prerender).mockResolvedValue([{ path: "/", file: "index.html", html: "<html></html>" }]);
+
+    const plugin = ssgPlugin({ root: "./src/app.tsx", hydrate: false });
+    const configResolved = plugin.configResolved as (c: ResolvedConfig) => void | Promise<void>;
+    await configResolved(fakeResolvedConfig(dir));
+    const closeBundle = plugin.closeBundle as () => Promise<void>;
+    await closeBundle();
+
+    expect(prerender).toHaveBeenCalledWith(expect.objectContaining({ hydrate: false }));
+  });
+});

package/src/__tests__/prerender.test.ts

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+
+import { StatefulComponent } from "@praxisjs/core";
+import { resource } from "@praxisjs/core/internal";
+import { Head } from "@praxisjs/head";
+import type { RouteDefinition, RouteLocation } from "@praxisjs/router";
+import { Location } from "@praxisjs/router";
+import { getCurrentScope, mountComponent, mountElement, render } from "@praxisjs/runtime";
+
+import { prerender, withDomGlobals } from "../prerender";
+
+const TEMPLATE =
+  '<!doctype html><html><head><title>App</title></head><body><div id="app"></div></body></html>';
+
+@Head((self) => ({ title: `Page: ${(self as Page).location().path}` }))
+class Page extends StatefulComponent {
+  static __isComponent = true as const;
+  static __isStateless = false;
+  @Location() location!: RouteLocation;
+
+  render() {
+    return mountElement("main", {
+      id: "root",
+      children: [
+        mountElement("h1", { children: `Path: ${this.location().path}` }, getCurrentScope()),
+        mountElement("button", { id: "btn", onClick: () => {}, children: "Click" }, getCurrentScope()),
+      ],
+    }, getCurrentScope());
+  }
+}
+
+class AsyncPage extends StatefulComponent {
+  static __isComponent = true as const;
+  static __isStateless = false;
+  data = resource(() => Promise.resolve("loaded content"));
+
+  render() {
+    return mountElement("p", { id: "data", children: () => this.data.data() ?? "pending" }, getCurrentScope());
+  }
+}
+
+describe("prerender()", () => {
+  it("renders each static route to its own page with the hydration marker", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/", component: Page as never },
+      { path: "/about", component: Page as never },
+    ];
+
+    const pages = await prerender({ root: Page as never, routes, template: TEMPLATE });
+
+    expect(pages.map((p) => p.path).sort()).toEqual(["/", "/about"]);
+    const home = pages.find((p) => p.path === "/")!;
+    expect(home.file).toBe("index.html");
+    expect(home.html).toContain("Path: /");
+    expect(home.html).toContain('data-praxis-ssg="1"');
+
+    const about = pages.find((p) => p.path === "/about")!;
+    expect(about.file).toBe("about/index.html");
+    expect(about.html).toContain("Path: /about");
+  });
+
+  it("omits the hydration marker when hydrate: false", async () => {
+    const routes: RouteDefinition[] = [{ path: "/", component: Page as never }];
+    const pages = await prerender({ root: Page as never, routes, template: TEMPLATE, hydrate: false });
+    expect(pages[0].html).not.toContain("data-praxis-ssg");
+  });
+
+  it("expands a dynamic route via getStaticPaths", async () => {
+    const routes: RouteDefinition[] = [{ path: "/blog/:slug", component: Page as never }];
+    const pages = await prerender({
+      root: Page as never,
+      routes,
+      template: TEMPLATE,
+      getStaticPaths: async () => ["/blog/hello", "/blog/world"],
+    });
+    expect(pages.map((p) => p.file).sort()).toEqual(["blog/hello/index.html", "blog/world/index.html"]);
+  });
+
+  it("waits for resource() data to settle before serializing", async () => {
+    const routes: RouteDefinition[] = [{ path: "/", component: AsyncPage as never }];
+    const pages = await prerender({ root: AsyncPage as never, routes, template: TEMPLATE });
+    expect(pages[0].html).toContain("loaded content");
+    expect(pages[0].html).not.toContain("pending");
+  });
+
+  it("sets per-route <title> via @Head and does not leak it across routes", async () => {
+    const routes: RouteDefinition[] = [
+      { path: "/", component: Page as never },
+      { path: "/about", component: Page as never },
+    ];
+    const pages = await prerender({ root: Page as never, routes, template: TEMPLATE });
+    const home = pages.find((p) => p.path === "/")!;
+    const about = pages.find((p) => p.path === "/about")!;
+    expect(home.html).toContain("<title>Page: /</title>");
+    expect(about.html).toContain("<title>Page: /about</title>");
+  });
+
+  it("does not leak globalThis.document/window back to the caller's environment", async () => {
+    const outer = document;
+    const routes: RouteDefinition[] = [{ path: "/", component: Page as never }];
+    await prerender({ root: Page as never, routes, template: TEMPLATE });
+    expect(globalThis.document).toBe(outer);
+  });
+
+  it("throws a clear error when the container selector is not found in the template", async () => {
+    const routes: RouteDefinition[] = [{ path: "/", component: Page as never }];
+    await expect(
+      prerender({ root: Page as never, routes, template: "<html><body></body></html>" }),
+    ).rejects.toThrow(/No element matching/);
+  });
+});
+
+describe("withDomGlobals", () => {
+  it("deletes a patched global on restore when it had no prior descriptor, and restores others that did", async () => {
+    const priorDescriptor = Object.getOwnPropertyDescriptor(globalThis, "Comment");
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- simulating a Node environment where this global never existed
+    delete (globalThis as Record<string, unknown>).Comment;
+
+    try {
+      let sawCommentDuring: unknown;
+      await withDomGlobals("<!doctype html><html><body></body></html>", "http://localhost/", async () => {
+        sawCommentDuring = globalThis.Comment;
+        // document existed before this call (vitest's jsdom environment) — restoreGlobals
+        // must put its original descriptor back, not delete it.
+        expect(globalThis.document).toBeDefined();
+      });
+
+      expect(sawCommentDuring).toBeDefined();
+      expect(Object.getOwnPropertyDescriptor(globalThis, "Comment")).toBeUndefined();
+      expect(globalThis.document).toBeDefined();
+    } finally {
+      if (priorDescriptor) Object.defineProperty(globalThis, "Comment", priorDescriptor);
+    }
+  });
+});
+
+describe("prerender() -> render() round trip", () => {
+  it("produces HTML the client can hydrate without recreating the adopted nodes", async () => {
+    const routes: RouteDefinition[] = [{ path: "/", component: Page as never }];
+    const pages = await prerender({ root: Page as never, routes, template: TEMPLATE });
+    const html = pages[0].html;
+
+    const parsed = new DOMParser().parseFromString(html, "text/html");
+    const appHTML = parsed.querySelector("#app")?.innerHTML ?? "";
+
+    const container = document.createElement("div");
+    container.innerHTML = appHTML;
+    container.setAttribute("data-praxis-ssg", "1");
+    document.body.appendChild(container);
+
+    const h1Before = container.querySelector("h1");
+    const btnBefore = container.querySelector("#btn");
+    expect(h1Before?.textContent).toBe("Path: /");
+
+    let clicks = 0;
+    class ClientPage extends StatefulComponent {
+      static __isComponent = true as const;
+      static __isStateless = false;
+      render() {
+        return mountElement("main", {
+          id: "root",
+          children: [
+            mountElement("h1", { children: "Path: /" }, getCurrentScope()),
+            mountElement("button", { id: "btn", onClick: () => { clicks++; }, children: "Click" }, getCurrentScope()),
+          ],
+        }, getCurrentScope());
+      }
+    }
+
+    render(() => mountComponent(ClientPage as never, {}, getCurrentScope()), container);
+
+    expect(container.querySelector("h1")).toBe(h1Before);
+    expect(container.querySelector("#btn")).toBe(btnBefore);
+
+    container.querySelector("#btn")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(clicks).toBe(1);
+
+    document.body.removeChild(container);
+  });
+});

package/src/__tests__/register-fallback.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect, vi } from "vitest";
+
+// Simulates Node < 22.15, which has no module.registerHooks — registerLoaderHook()
+// must fall back to the older, off-thread module.register() API instead.
+const { register } = vi.hoisted(() => ({
+  register: vi.fn(),
+}));
+
+vi.mock("node:module", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:module")>();
+  return { ...actual, registerHooks: undefined, register };
+});
+
+describe("registerLoaderHook() fallback (no module.registerHooks)", () => {
+  it("registers the standalone loader-hook module via module.register()", async () => {
+    const { registerLoaderHook } = await import("../index");
+    registerLoaderHook();
+
+    expect(register).toHaveBeenCalledOnce();
+    const [specifier] = register.mock.calls[0] as [URL];
+    expect(specifier.href).toContain("loader-hook.js");
+  });
+});