feat(router): make router hydratable

Author: yzuyr

packages/router/src/index.test.ts

@@ -53,6 +53,14 @@ const userPage = ilha.render(() => {
 });
 const notFound = ilha.render(() => `<p>404</p>`);
 
+// shared registry used across hydratable tests
+const registry: Record<string, typeof homePage> = {
+  home: homePage,
+  about: aboutPage,
+  user: userPage,
+  notFound: notFound,
+};
+
 // ─────────────────────────────────────────────
 // route matching
 // ─────────────────────────────────────────────
@@ -614,3 +622,120 @@ describe("SSR render()", () => {
     expect(search()).toBe("?sort=asc");
   });
 });
+
+// ─────────────────────────────────────────────
+// SSR — router().renderHydratable()
+// ─────────────────────────────────────────────
+
+describe("SSR renderHydratable()", () => {
+  it("returns a string (is async)", async () => {
+    const html = await router()
+      .route("/", homePage)
+      .route("/**", notFound)
+      .renderHydratable("/", registry);
+    expect(typeof html).toBe("string");
+  });
+
+  it("wraps output in data-router-view", async () => {
+    const html = await router().route("/", homePage).renderHydratable("/", registry);
+    expect(html).toContain("data-router-view");
+  });
+
+  it("includes data-ilha attribute with the island name", async () => {
+    const html = await router().route("/", homePage).renderHydratable("/", registry);
+    expect(html).toContain(`data-ilha="home"`);
+  });
+
+  it("includes island content in the output", async () => {
+    const html = await router().route("/", homePage).renderHydratable("/", registry);
+    expect(html).toContain("home");
+  });
+
+  it("resolves correct island for /about", async () => {
+    const html = await router()
+      .route("/", homePage)
+      .route("/about", aboutPage)
+      .route("/**", notFound)
+      .renderHydratable("/about", registry);
+    expect(html).toContain(`data-ilha="about"`);
+    expect(html).toContain("about");
+    expect(html).not.toContain(`data-ilha="home"`);
+  });
+
+  it("renders data-router-empty when no route matches", async () => {
+    const html = await router().route("/", homePage).renderHydratable("/unknown", registry);
+    expect(html).toContain("data-router-empty");
+    expect(html).not.toContain("data-ilha");
+  });
+
+  it("populates route signals identically to render()", async () => {
+    await router().route("/user/:id", userPage).renderHydratable("/user/42", registry);
+    expect(routePath()).toBe("/user/42");
+    expect(routeParams()).toEqual({ id: "42" });
+  });
+
+  it("populates routeSearch signal", async () => {
+    await router().route("/about", aboutPage).renderHydratable("/about?tab=docs", registry);
+    expect(routeSearch()).toBe("?tab=docs");
+  });
+
+  it("accepts a full URL string", async () => {
+    const html = await router()
+      .route("/about", aboutPage)
+      .renderHydratable("http://example.com/about", registry);
+    expect(html).toContain(`data-ilha="about"`);
+  });
+
+  it("accepts a URL object", async () => {
+    const html = await router()
+      .route("/about", aboutPage)
+      .renderHydratable(new URL("http://example.com/about"), registry);
+    expect(html).toContain(`data-ilha="about"`);
+  });
+
+  it("falls back to plain SSR and warns when island is not in registry", async () => {
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    const unregistered = ilha.render(() => `<p>unregistered</p>`);
+    const html = await router().route("/", unregistered).renderHydratable("/", registry);
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[ilha-router]"));
+    expect(html).toContain("data-router-view");
+    expect(html).toContain("unregistered");
+    expect(html).not.toContain("data-ilha");
+    warn.mockRestore();
+  });
+
+  it("does not include data-ilha when falling back to plain SSR", async () => {
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    const unregistered = ilha.render(() => `<p>x</p>`);
+    const html = await router().route("/", unregistered).renderHydratable("/", {});
+    expect(html).not.toContain("data-ilha");
+    warn.mockRestore();
+  });
+
+  it("snapshot option is forwarded — data-ilha-state present", async () => {
+    const stateful = ilha.state("count", 0).render(() => `<p>count</p>`);
+    const reg = { stateful };
+    const html = await router().route("/", stateful).renderHydratable("/", reg, { snapshot: true });
+    expect(html).toContain("data-ilha-state");
+  });
+
+  it("snapshot: false omits data-ilha-state", async () => {
+    const stateful = ilha.state("count", 0).render(() => `<p>count</p>`);
+    const reg = { stateful };
+    const html = await router()
+      .route("/", stateful)
+      .renderHydratable("/", reg, { snapshot: false });
+    expect(html).not.toContain("data-ilha-state");
+  });
+
+  it("each call is independent — registry lookup uses active island", async () => {
+    const r = router().route("/", homePage).route("/about", aboutPage);
+
+    const h1 = await r.renderHydratable("/", registry);
+    const h2 = await r.renderHydratable("/about", registry);
+
+    expect(h1).toContain(`data-ilha="home"`);
+    expect(h2).toContain(`data-ilha="about"`);
+  });
+});

packages/router/src/index.ts

@@ -1,5 +1,5 @@
 import { context } from "ilha";
-import type { Island } from "ilha";
+import type { Island, HydratableOptions } from "ilha";
 import ilha, { html } from "ilha";
 import { createRouter, addRoute, findRoute } from "rou3";
 
@@ -22,12 +22,24 @@ export interface NavigateOptions {
   replace?: boolean;
 }
 
+export interface HydratableRenderOptions extends Partial<Omit<HydratableOptions, "name">> {}
+
 export interface RouterBuilder {
   route(pattern: string, island: Island<any, any>): RouterBuilder;
   /** Client-side: mount into a DOM element or selector, returns unmount fn */
   mount(target: string | Element): () => void;
   /** Server-side: resolve a URL to an HTML string */
   render(url: string | URL): string;
+  /**
+   * Server-side: resolve a URL and render with hydration markers.
+   * Requires an island registry (name → island) shared with the client.
+   * Use with ilha.mount(registry) on the client for zero-flash hydration.
+   */
+  renderHydratable(
+    url: string | URL,
+    registry: Record<string, Island<any, any>>,
+    options?: HydratableRenderOptions,
+  ): Promise<string>;
 }
 
 // ─────────────────────────────────────────────
@@ -69,7 +81,6 @@ function syncRouteFromURL(url: string | URL): void {
   const match = findRoute(_rou3, "GET", path);
   const island = match?.data ?? null;
 
-  // rou3 returns decoded param values already; re-decode just in case
   const params: Record<string, string> = {};
   for (const [k, v] of Object.entries(match?.params ?? {})) {
     params[k] = decodeURIComponent(v as string);
@@ -185,7 +196,7 @@ export function router(): RouterBuilder {
     mount(target: string | Element): () => void {
       if (!isBrowser) {
         console.warn(
-          "[ilha-router] mount() called in a non-browser environment — use render() for SSR",
+          "[ilha-router] mount() called in a non-browser environment — use render() or renderHydratable() for SSR",
         );
         return () => {};
       }
@@ -202,7 +213,6 @@ export function router(): RouterBuilder {
       const popHandler = () => syncRoute();
       window.addEventListener("popstate", popHandler);
       _popstateCleanup = () => window.removeEventListener("popstate", popHandler);
-
       _linkCleanup = enableLinkInterception(document);
 
       const unmountView = RouterView.mount(host);
@@ -216,11 +226,47 @@ export function router(): RouterBuilder {
       };
     },
 
-    // ── Server-side ───────────────────────────
+    // ── Server-side — plain SSR ───────────────
     render(url: string | URL): string {
       syncRouteFromURL(url);
       return RouterView.toString();
     },
+
+    // ── Server-side — hydratable SSR ─────────
+    async renderHydratable(
+      url: string | URL,
+      registry: Record<string, Island<any, any>>,
+      options: HydratableRenderOptions = {},
+    ): Promise<string> {
+      syncRouteFromURL(url);
+
+      const island = activeIsland();
+
+      if (!island) return `<div data-router-empty></div>`;
+
+      const name = Object.entries(registry).find(([, v]) => v === island)?.[0];
+
+      if (!name) {
+        // island not registered — fall back to plain SSR, no hydration
+        console.warn(
+          `[ilha-router] renderHydratable: active island for "${routePath()}" is not in the registry. ` +
+            `Falling back to plain SSR — the island will not be interactive on the client.`,
+        );
+        return `<div data-router-view>${island.toString()}</div>`;
+      }
+
+      const html = await island.hydratable(
+        {},
+        {
+          name,
+          as: "div",
+          snapshot: true,
+          ...options,
+        },
+      );
+
+      return `<div data-router-view>${html}</div>`;
+    },
   };
 
   return builder;