@k2b/ssr 0.12.0-rc.0

package/src/adapter/client.js

@@ -0,0 +1,421 @@
+// Dev mode live-reload client
+if (!window.__ssr_reload) {
+  window.__ssr_reload = true;
+
+  (function () {
+    const ssrPath = globalThis.__SSR_CONFIG?.ssrPath || "/_ssr";
+
+    // Settings
+    const STORAGE_KEY = `_ssr:${ssrPath}`;
+    const defaults = {
+      autoReload: true,
+      highlightIslands: false,
+      highlightClients: false,
+      position: "bl",
+    };
+
+    const readStorage = (key) => {
+      try {
+        return localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    };
+    const writeStorage = (key, value) => {
+      try {
+        localStorage.setItem(key, value);
+      } catch {
+        // Dev tools still work when storage is unavailable.
+      }
+    };
+    const load = () => {
+      try {
+        return {
+          ...defaults,
+          ...JSON.parse(readStorage(STORAGE_KEY) || "{}"),
+        };
+      } catch {
+        return { ...defaults };
+      }
+    };
+    const save = (s) => writeStorage(STORAGE_KEY, JSON.stringify(s));
+    let settings = load();
+
+    // Highlight Styles
+    const style = document.head.appendChild(document.createElement("style"));
+
+    const highlightCSS = (tag, color) => `
+      ${tag} {
+        display: block !important;
+        box-shadow: 0 0 0 1px ${color} !important;
+        position: relative !important;
+      }
+      ${tag}::before {
+        content: attr(data-file);
+        position: absolute;
+        top: -17px;
+        left: -1px;
+        font-size: 10px;
+        font-family: monospace;
+        color: black;
+        background: ${color};
+        padding: 1px 4px;
+        white-space: nowrap;
+      }
+    `;
+
+    const updateStyles = () => {
+      style.textContent = [
+        settings.highlightIslands && highlightCSS("solid-island", "#22c55e"),
+        settings.highlightClients && highlightCSS("solid-client", "#3b82f6"),
+      ]
+        .filter(Boolean)
+        .join("");
+    };
+    updateStyles();
+
+    // Position
+    const positions = {
+      tl: { top: "8px", left: "8px" },
+      tr: { top: "8px", right: "8px" },
+      bl: { bottom: "8px", left: "8px" },
+      br: { bottom: "8px", right: "8px" },
+    };
+
+    const applyPosition = () => {
+      const reset = { top: "", bottom: "", left: "", right: "" };
+      const pos = positions[settings.position] ?? positions.bl;
+      Object.assign(badge.style, reset, pos);
+      Object.assign(
+        panel.style,
+        reset,
+        pos,
+        pos.top ? { top: "32px" } : { bottom: "32px" },
+      );
+    };
+
+    // UI
+    const islandCount = document.querySelectorAll("solid-island").length;
+    const clientCount = document.querySelectorAll("solid-client").length;
+
+    const el = (tag, props = {}, parent = document.body) =>
+      Object.assign(parent.appendChild(document.createElement(tag)), props);
+
+    const checkbox = (id, label, checked) => `
+      <label style="display:block;margin:4px 0;cursor:pointer">
+        <input type="checkbox" id="${id}" ${checked ? "checked" : ""}> ${label}
+      </label>
+    `;
+
+    const panel = el("div", {
+      innerHTML: `
+        <div style="margin-bottom:8px;font-weight:bold">SSR Dev Tools</div>
+        ${checkbox("_ssr_reload", "Auto reload", settings.autoReload)}
+        ${checkbox("_ssr_islands", `Highlight islands (${islandCount})`, settings.highlightIslands)}
+        ${checkbox("_ssr_clients", `Highlight clients (${clientCount})`, settings.highlightClients)}
+        <div style="margin-top:8px;border-top:1px solid #333;padding-top:8px">
+          <label style="color:#888">Position:
+            <select id="_ssr_pos" style="background:#222;color:#ccc;border:1px solid #444;padding:2px;margin-left:4px">
+              ${Object.keys(positions)
+                .map(
+                  (p) =>
+                    `<option value="${p}" ${settings.position === p ? "selected" : ""}>${p.toUpperCase()}</option>`,
+                )
+                .join("")}
+            </select>
+          </label>
+        </div>
+      `,
+    });
+    Object.assign(panel.style, {
+      fontFamily: "monospace",
+      fontSize: "12px",
+      color: "#ccc",
+      background: "#111",
+      padding: "12px",
+      border: "1px solid #333",
+      borderRadius: "4px",
+      position: "fixed",
+      zIndex: "9999",
+      display: "none",
+    });
+
+    const badge = el("div", {
+      innerText: "[ssr]",
+      onclick: () =>
+        (panel.style.display =
+          panel.style.display === "none" ? "block" : "none"),
+    });
+    Object.assign(badge.style, {
+      fontFamily: "monospace",
+      fontSize: "12px",
+      color: "#555",
+      position: "fixed",
+      zIndex: "9999",
+      cursor: "pointer",
+    });
+
+    applyPosition();
+
+    // Event Handlers
+    const bind = (id, key, onChange) => {
+      panel.querySelector(`#${id}`).onchange = (e) => {
+        settings[key] =
+          e.target.type === "checkbox" ? e.target.checked : e.target.value;
+        save(settings);
+        onChange?.();
+      };
+    };
+
+    bind("_ssr_islands", "highlightIslands", updateStyles);
+    bind("_ssr_clients", "highlightClients", updateStyles);
+    bind("_ssr_pos", "position", applyPosition);
+
+    // Live Reload (SSE)
+    const reloadId = globalThis.__SSR_CONFIG?.reloadId;
+    const reloadIdKey = `${STORAGE_KEY}:reload-id`;
+    const reloadLockName = `${STORAGE_KEY}:reload-lock`;
+    let es, retryTimer, retryController, animationInterval;
+    let lockController, releaseLock;
+    let retryAttempt = 0;
+    let retryGeneration = 0;
+    let ownsLock = false;
+    let pageActive = true;
+    let reloadRequested = false;
+    const spinFrames = ["[ / ]", "[ – ]", "[ \\ ]", "[ | ]"];
+    let spinIndex = 0;
+
+    // A fresh document already represents this server generation. Publishing
+    // it first wakes stale tabs without making the fresh document reload.
+    if (reloadId) writeStorage(reloadIdKey, reloadId);
+
+    const stopAnimation = () => {
+      clearInterval(animationInterval);
+      animationInterval = null;
+    };
+
+    const startAnimation = () => {
+      if (animationInterval) return;
+      spinIndex = 0;
+      animationInterval = setInterval(() => {
+        badge.innerText = spinFrames[spinIndex++ % spinFrames.length];
+      }, 150);
+    };
+
+    const shouldParticipate = () =>
+      pageActive &&
+      !reloadRequested &&
+      settings.autoReload &&
+      document.visibilityState === "visible";
+    const canConnect = () => shouldParticipate() && ownsLock;
+
+    const closeSource = () => {
+      const source = es;
+      es = null;
+      source?.close();
+    };
+
+    const cancelRetry = () => {
+      retryGeneration += 1;
+      clearTimeout(retryTimer);
+      retryTimer = null;
+      const controller = retryController;
+      retryController = null;
+      controller?.abort();
+    };
+
+    const stopConnection = () => {
+      closeSource();
+      cancelRetry();
+      retryAttempt = 0;
+      stopAnimation();
+      badge.innerText = "[ssr]";
+    };
+
+    const releaseLeadership = () => {
+      const pendingLock = lockController;
+      lockController = null;
+      pendingLock?.abort();
+
+      const release = releaseLock;
+      releaseLock = null;
+      ownsLock = false;
+      release?.();
+      stopConnection();
+    };
+
+    const requestReload = () => {
+      if (reloadRequested) return;
+      reloadRequested = true;
+      releaseLeadership();
+      location.reload();
+    };
+
+    const acceptReloadId = (nextReloadId) => {
+      if (!nextReloadId) return;
+      writeStorage(reloadIdKey, nextReloadId);
+      if (reloadId && nextReloadId !== reloadId) requestReload();
+    };
+
+    const retryDelay = () =>
+      Math.min(2_000, 300 * 2 ** Math.min(retryAttempt, 3));
+
+    const scheduleRetry = () => {
+      if (!canConnect() || retryTimer || retryController) return;
+
+      const generation = retryGeneration;
+      retryTimer = setTimeout(async () => {
+        retryTimer = null;
+        if (generation !== retryGeneration || !canConnect()) return;
+
+        const controller = new AbortController();
+        retryController = controller;
+        try {
+          const response = await fetch(`${ssrPath}/_ping`, {
+            cache: "no-store",
+            signal: controller.signal,
+          });
+          if (response.ok && canConnect()) {
+            acceptReloadId(response.headers.get("X-SSR-Reload-ID"));
+            if (!reloadRequested) requestReload();
+            return;
+          }
+        } catch {
+          // A stopped or unavailable dev server is expected during reload.
+        } finally {
+          if (retryController === controller) retryController = null;
+        }
+
+        if (generation !== retryGeneration || !canConnect()) return;
+        retryAttempt += 1;
+        scheduleRetry();
+      }, retryDelay());
+    };
+
+    const startRetry = () => {
+      if (!canConnect()) return;
+      startAnimation();
+      scheduleRetry();
+    };
+
+    const start = () => {
+      if (!canConnect() || es || retryTimer || retryController) return;
+
+      let source;
+      try {
+        source = new EventSource(`${ssrPath}/_reload`);
+        es = source;
+        stopAnimation();
+        badge.innerText = "[ssr]";
+      } catch {
+        startRetry();
+        return;
+      }
+
+      source.onopen = () => {
+        if (es !== source) return;
+        retryAttempt = 0;
+        stopAnimation();
+        badge.innerText = "[ssr]";
+      };
+
+      source.onmessage = (event) => {
+        if (es !== source) return;
+        acceptReloadId(event.data);
+      };
+
+      source.onerror = (event) => {
+        if (es !== source) return;
+        event.preventDefault();
+        closeSource();
+        retryAttempt = 0;
+        startRetry();
+      };
+    };
+
+    const requestLeadership = () => {
+      if (!shouldParticipate()) return;
+      if (ownsLock) {
+        start();
+        return;
+      }
+      if (lockController) return;
+
+      if (!navigator.locks?.request) {
+        ownsLock = true;
+        start();
+        return;
+      }
+
+      const controller = new AbortController();
+      lockController = controller;
+      void navigator.locks
+        .request(
+          reloadLockName,
+          { mode: "exclusive", signal: controller.signal },
+          async () => {
+            if (lockController === controller) lockController = null;
+            if (controller.signal.aborted || !shouldParticipate()) return;
+
+            ownsLock = true;
+            start();
+            await new Promise((resolve) => {
+              releaseLock = resolve;
+            });
+            releaseLock = null;
+            ownsLock = false;
+            stopConnection();
+          },
+        )
+        .catch((error) => {
+          if (lockController === controller) lockController = null;
+          if (error?.name === "AbortError" || !shouldParticipate()) return;
+
+          // If Web Locks is unavailable at runtime, retain per-tab behavior.
+          ownsLock = true;
+          start();
+        });
+    };
+
+    const syncConnection = () => {
+      const knownReloadId = readStorage(reloadIdKey);
+      if (
+        shouldParticipate() &&
+        reloadId &&
+        knownReloadId &&
+        knownReloadId !== reloadId
+      ) {
+        requestReload();
+        return;
+      }
+
+      if (shouldParticipate()) requestLeadership();
+      else releaseLeadership();
+    };
+
+    syncConnection();
+
+    panel.querySelector("#_ssr_reload").onchange = (e) => {
+      settings.autoReload = e.target.checked;
+      save(settings);
+      syncConnection();
+    };
+
+    document.addEventListener("visibilitychange", syncConnection);
+    window.addEventListener("storage", (event) => {
+      if (event.key !== reloadIdKey || !event.newValue) return;
+      if (reloadId && event.newValue !== reloadId && shouldParticipate()) {
+        requestReload();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      pageActive = false;
+      releaseLeadership();
+    });
+    window.addEventListener("pageshow", () => {
+      pageActive = true;
+      reloadRequested = false;
+      syncConnection();
+    });
+  })();
+}

package/src/adapter/elysia.ts

@@ -0,0 +1,39 @@
+/**
+ * Elysia adapter - provides Elysia plugin with SSR routes.
+ * Uses the shared BunFile-backed asset response path.
+ */
+import { Elysia } from "elysia";
+import type { SsrConfig } from "../index";
+import {
+  createAssetResponse,
+  createPingResponse,
+  getSsrDir,
+  createReloadResponse,
+  notFound,
+} from "./utils";
+
+/**
+ * Creates Elysia plugin with SSR routes.
+ *
+ * @example
+ * ```ts
+ * import { routes } from "@k2b/ssr/elysia";
+ * new Elysia()
+ *   .use(routes(config))
+ *   .get("/", () => html(() => <Home />))
+ *   .listen(3000);
+ * ```
+ */
+export const routes = (config: SsrConfig) => {
+  const { dev, ssrPath } = config;
+  const ssrDir = getSsrDir(config);
+
+  return new Elysia({ name: "ssr" })
+    .get(`${ssrPath}/_reload`, ({ request }) =>
+      dev ? createReloadResponse(request.signal) : notFound(),
+    )
+    .get(`${ssrPath}/_ping`, () => (dev ? createPingResponse() : notFound()))
+    .get(`${ssrPath}/*`, ({ request, params }) =>
+      createAssetResponse(request, ssrDir, params["*"], dev),
+    );
+};

package/src/adapter/hono.ts

@@ -0,0 +1,190 @@
+/**
+ * Hono adapter - provides Hono app to mount at /_ssr and SSR handler factory.
+ * Serves island chunks and dev tools endpoints.
+ */
+import { Hono } from "hono";
+import { createFactory } from "hono/factory";
+import type { Context, Env, Handler, MiddlewareHandler, TypedResponse } from "hono";
+import type { SsrConfig, HtmlFn, RenderFn } from "../index";
+import { createAssetResponse, createPingResponse, getSsrDir, createReloadResponse } from "./utils";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Environment extension for page options in context */
+type PageEnv<T extends object> = {
+  Variables: {
+    page: Partial<T>;
+  };
+};
+
+/** SSR handler return type - render function or Response (for redirects etc.) */
+type SsrHandlerResult = RenderFn | Response | TypedResponse;
+
+/** SSR handler function signature */
+type SsrHandler<E extends Env, T extends object> = (
+  c: Context<E & PageEnv<T>>,
+) => SsrHandlerResult | Promise<SsrHandlerResult>;
+
+/** Return type of ssr() - tuple of middlewares + handler for spread operator */
+type SsrHandlers = [MiddlewareHandler, ...MiddlewareHandler[], Handler];
+
+// ============================================================================
+// createSSRHandler() - Factory for type-safe SSR page handlers
+// ============================================================================
+
+/**
+ * Creates an `ssr()` helper for type-safe JSX pages with Hono.
+ *
+ * Features:
+ * - Full compatibility with Hono middlewares/validators
+ * - Type-safe page options via `c.get("page")`
+ * - Return a render function or Response for redirects
+ * - No manual `html()` call needed
+ *
+ * @example
+ * ```ts
+ * // config.ts
+ * import { createConfig } from "@k2b/ssr";
+ * import { createSSRHandler, routes } from "@k2b/ssr/hono";
+ *
+ * type PageOptions = { title?: string; description?: string };
+ *
+ * export const { config, plugin, html } = createConfig<PageOptions>({
+ *   dev: process.env.NODE_ENV === "development",
+ *   template: ({ body, scripts, title, description }) => `
+ *     <!DOCTYPE html>
+ *     <html>
+ *       <head>
+ *         <title>${title ?? "App"}</title>
+ *         <meta name="description" content="${description ?? ""}">
+ *       </head>
+ *       <body>${body}${scripts}</body>
+ *     </html>
+ *   `,
+ * });
+ *
+ * export const ssr = createSSRHandler(html);
+ * export { routes };
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // pages/room.tsx
+ * import { ssr } from "../config";
+ * import { zValidator } from "@hono/zod-validator";
+ * import { z } from "zod";
+ *
+ * const paramsSchema = z.object({ roomId: z.string() });
+ *
+ * export const roomPage = ssr(
+ *   zValidator("param", paramsSchema),
+ *   async (c) => {
+ *     const { roomId } = c.req.valid("param");
+ *     const room = await db.getRoom(roomId);
+ *
+ *     c.get("page").title = room.name;
+ *     c.get("page").description = `Welcome to ${room.name}`;
+ *
+ *     return () => <RoomView room={room} />;
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // app.ts
+ * import { Hono } from "hono";
+ * import { config, routes } from "./config";
+ * import { roomPage } from "./pages/room";
+ *
+ * const app = new Hono()
+ *   .route("/_ssr", routes(config))
+ *   .get("/room/:roomId", ...roomPage);
+ * ```
+ */
+export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
+  const factory = createFactory<PageEnv<T>>();
+
+  /**
+   * Creates a type-safe SSR page handler with optional middlewares.
+   *
+   * @param args - Middlewares followed by the final handler
+   * @returns Tuple of handlers to spread into Hono route: `...ssr(handler)`
+   */
+  return <E extends Env = Env>(...args: [...MiddlewareHandler<E>[], SsrHandler<E, T>]): SsrHandlers => {
+    // Extract middlewares and final handler
+    const middlewares = args.slice(0, -1) as MiddlewareHandler[];
+    const finalHandler = args[args.length - 1] as SsrHandler<E, T>;
+
+    // Middleware that initializes c.get("page") with empty object
+    const pageMiddleware = factory.createMiddleware(async (c, next) => {
+      c.set("page", {} as Partial<T>);
+      await next();
+    });
+
+    // Wrapped handler: render function → html(), Response → passthrough
+    const wrappedHandler: Handler = async (c) => {
+      const result = await finalHandler(c as Context<E & PageEnv<T>>);
+
+      // If handler returns Response (e.g., redirect), pass through
+      if (result instanceof Response) {
+        return result;
+      }
+
+      if (typeof result !== "function") {
+        throw new Error("[ssr] ssr() handlers must return a render function: return () => <Page />");
+      }
+
+      if (result.constructor.name === "AsyncFunction") {
+        throw new Error("[ssr] ssr() render functions must be synchronous: return () => <Page />");
+      }
+
+      return html(result as RenderFn, c.get("page") as T);
+    };
+
+    // Return tuple for spread: .get('/path', ...ssr(handler))
+    return [pageMiddleware, ...middlewares, wrappedHandler] as SsrHandlers;
+  };
+};
+
+// ============================================================================
+// routes() - SSR routes for Hono
+// ============================================================================
+
+/**
+ * Creates Hono app with SSR routes.
+ *
+ * @example
+ * ```ts
+ * import { routes } from "@k2b/ssr/hono";
+ * const app = new Hono()
+ *   .route("/_ssr", routes(config))
+ *   .get("/", () => html(() => <Home />));
+ * ```
+ */
+export const routes = (config: SsrConfig) => {
+  const { dev } = config;
+  const ssrDir = getSsrDir(config);
+
+  const app = new Hono();
+
+  // Dev mode endpoints
+  if (dev) {
+    app.get("/_reload", (c) => createReloadResponse(c.req.raw.signal));
+    app.get("/_ping", () => createPingResponse());
+  }
+
+  const serveAsset = (c: Context) => {
+    const filename = c.req.param("filename");
+    if (!filename) return c.notFound();
+
+    return createAssetResponse(c.req.raw, ssrDir, filename, dev);
+  };
+
+  app.get("/:filename{.+\\.js$}", serveAsset);
+  app.get("/:filename{.+\\.js\\.map$}", serveAsset);
+
+  return app;
+};