alabjs 0.2.3 → 0.2.5

package/src/commands/dev.ts

@@ -8,7 +8,7 @@ import {
   findLayoutFiles, findErrorFile, findLoadingFile,
   scanDevApiRoutes, matchDevApiRoute,
 } from "../ssr/router-dev.js";
-import { htmlShellBefore, htmlShellAfter } from "../ssr/html.js";
+import { htmlShellBefore, htmlShellAfter, injectIntoFullDocument } from "../ssr/html.js";
 import { generateSitemap } from "../server/sitemap.js";
 import { handleImageRequest } from "../server/image.js";
 import type { MiddlewareModule } from "../server/middleware.js";
@@ -181,7 +181,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
             found = true;
             const url = new URL(rawUrl, `http://${host}:${port}`);
             const params = Object.fromEntries(url.searchParams.entries());
-            const input = req.method === "POST" ? await readJsonBody(req) : undefined;
+            const input = req.method === "POST" ? await readJsonBody(req) : (Object.keys(params).length ? params : undefined);
             const ctx = {
               params,
               query: params,
@@ -205,7 +205,8 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
                 res.statusCode = 500;
                 res.setHeader("content-type", "application/json");
                 const msg = err instanceof Error ? err.message : String(err);
-              res.end(JSON.stringify({ error: msg }));
+                console.error(`[alabjs] server fn "${fnName}" threw:`, err);
+                res.end(JSON.stringify({ error: msg }));
               }
             }
             break;
@@ -219,6 +220,32 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
         return;
       }
 
+      // ── /_alabjs/vitals — Core Web Vitals beacon from <Analytics> component ───
+      if (pathname === "/_alabjs/vitals") {
+        if (req.method === "OPTIONS") {
+          res.setHeader("access-control-allow-origin", "*");
+          res.setHeader("access-control-allow-methods", "POST, OPTIONS");
+          res.setHeader("access-control-allow-headers", "content-type");
+          res.statusCode = 204;
+          res.end();
+          return;
+        }
+        if (req.method !== "POST") {
+          res.statusCode = 405;
+          res.setHeader("allow", "POST");
+          res.end();
+          return;
+        }
+        // Silently accept the beacon — dev mode doesn't aggregate metrics.
+        const vitalsBody = await readJsonBody(req);
+        console.debug("[alabjs] vitals beacon:", vitalsBody);
+        res.setHeader("access-control-allow-origin", "*");
+        res.setHeader("content-type", "application/json");
+        res.statusCode = 200;
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+
       // ── /_alabjs/image — Rust-powered image optimisation ───────────────────────
       if (pathname === "/_alabjs/image") {
         const publicDir = resolve(cwd, "public");
@@ -276,8 +303,12 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
       }
 
       // ── API routes (route.ts) ─────────────────────────────────────────────────
+      // Browser navigations (Accept: text/html) skip API routing so a path can
+      // serve both a React page AND an API endpoint (e.g. /activity as a page
+      // and GET /activity as an SSE stream).
+      const wantsHtml = (req.headers["accept"] ?? "").includes("text/html");
       const apiRoutes = scanDevApiRoutes(appDir);
-      const matchedApi = matchDevApiRoute(apiRoutes, pathname);
+      const matchedApi = !wantsHtml ? matchDevApiRoute(apiRoutes, pathname) : null;
       if (matchedApi) {
         const apiMod = await vite.ssrLoadModule(matchedApi.route.file) as Record<string, unknown>;
         const method = (req.method ?? "GET").toUpperCase();
@@ -333,7 +364,6 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
 
       // ── Not-found page ────────────────────────────────────────────────────────
       if (!matched) {
-        const wantsHtml = (req.headers["accept"] ?? "").includes("text/html");
         if (!wantsHtml) return next();
 
         const notFoundFile = resolve(appDir, "not-found.tsx");
@@ -374,7 +404,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
       const mod = await vite.ssrLoadModule(route.file) as {
         default?: unknown;
         metadata?: PageMetadata;
-        generateMetadata?: (params: Record<string, string>) => PageMetadata | Promise<PageMetadata>;
+        generateMetadata?: (ctx: { params: Record<string, string> }) => PageMetadata | Promise<PageMetadata>;
         ssr?: boolean;
         /** ISR: seconds before a cached page is considered stale. Omit to disable caching. */
         revalidate?: number;
@@ -389,7 +419,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
       // Support both static `export const metadata` and dynamic `export async function generateMetadata`.
       const metadata: PageMetadata =
         typeof mod.generateMetadata === "function"
-          ? await mod.generateMetadata(params)
+          ? await mod.generateMetadata({ params })
           : (mod.metadata ?? {});
 
       // Make the server's base URL available to useServerData during SSR,
@@ -492,19 +522,29 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
 
       // ── Render helper (used for both fresh render + background revalidation) ─
       const revalidateSecs = typeof mod.revalidate === "number" ? mod.revalidate : null;
+      // Detect whether the SSR output is a full document (layout returns <html>).
+      // In that case we inject the alab meta tags and client script directly into
+      // the user-controlled <head>/<body> rather than wrapping in the shell div,
+      // which would produce invalid "html cannot be child of div" nesting.
+      const isFullDocument = ssrEnabled && ssrContent.trimStart().toLowerCase().startsWith("<html");
+      const shellOpts = {
+        paramsJson: JSON.stringify(params),
+        searchParamsJson: JSON.stringify(searchParams),
+        routeFile,
+        layoutsJson,
+        loadingFile,
+        ssr: ssrEnabled,
+        buildId: devBuildId,
+      };
       const renderPageHtml = async (): Promise<string> => {
-        const shellBefore = htmlShellBefore({
-          metadata,
-          paramsJson: JSON.stringify(params),
-          searchParamsJson: JSON.stringify(searchParams),
-          routeFile,
-          layoutsJson,
-          loadingFile,
-          ssr: ssrEnabled,
-          buildId: devBuildId,
-        });
-        const shellAfter = htmlShellAfter({});
-        const rawHtml = `${shellBefore}${ssrContent}${shellAfter}`;
+        let rawHtml: string;
+        if (isFullDocument) {
+          rawHtml = injectIntoFullDocument(ssrContent, shellOpts);
+        } else {
+          const shellBefore = htmlShellBefore({ metadata, headExtra: undefined, ...shellOpts });
+          const shellAfter = htmlShellAfter({});
+          rawHtml = `${shellBefore}${ssrContent}${shellAfter}`;
+        }
         return vite.transformIndexHtml(pathname, rawHtml);
       };
 

package/src/components/Font.tsx

@@ -82,10 +82,20 @@ function buildGoogleFontsUrl(props: FontProps): string {
 /**
  * Renders the `<link>` tags needed to load a Google Font.
  *
- * In production (`alab build --self-host-fonts`), the alab Vite plugin
- * replaces this with self-hosted CSS so no Google request is made.
+ * Only active in development (Vite dev server). In production (`alab build`),
+ * the build step self-hosts the font files, so this component renders nothing.
+ * Gating on `import.meta.env.DEV` ensures the server and client always agree:
+ * both render the links in dev, both render nothing in production — preventing
+ * a hydration mismatch that occurs when the server loads the pre-built dist
+ * (where `import.meta.env.DEV` is `false`) while the client gets live Vite
+ * processing (where it is `true`).
  */
 export function Font(props: FontProps) {
+  // Return nothing in production — self-hosted fonts are injected by the build.
+  // This must be checked before building the URL so the server and client
+  // always produce identical output (both null in prod, both links in dev).
+  if (!import.meta.env?.DEV) return null;
+
   const href = buildGoogleFontsUrl(props);
 
   return (

package/src/components/Script.tsx

@@ -1,8 +1,7 @@
-import { useEffect, type HTMLAttributes } from "react";
+import { useEffect, type HTMLAttributes, type ReactNode } from "react";
 
-export interface ScriptProps extends Omit<HTMLAttributes<HTMLScriptElement>, "src"> {
-  /** URL of the external script to load. */
-  src: string;
+/** Props shared by both external-src and inline-children variants. */
+interface ScriptBaseProps extends Omit<HTMLAttributes<HTMLScriptElement>, "src"> {
   /**
    * Loading strategy:
    * - `"beforeInteractive"` — injected into `<head>` during SSR; blocks page rendering.
@@ -13,12 +12,27 @@ export interface ScriptProps extends Omit<HTMLAttributes<HTMLScriptElement>, "sr
    *   Best for low-priority scripts like A/B testing, heatmaps, social embeds.
    */
   strategy?: "beforeInteractive" | "afterInteractive" | "lazyOnload";
-  /** Called once the script has loaded successfully. */
+  /** Called once the script has loaded successfully (external scripts only). */
   onLoad?: () => void;
-  /** Called if the script fails to load. */
+  /** Called if the script fails to load (external scripts only). */
   onError?: () => void;
 }
 
+/** External script variant — `src` is required and `children` must be absent. */
+interface ExternalScriptProps extends ScriptBaseProps {
+  /** URL of the external script to load. */
+  src: string;
+  children?: never;
+}
+
+/** Inline script variant — `children` contains the script body; `src` must be absent. */
+interface InlineScriptProps extends ScriptBaseProps {
+  src?: never;
+  children: ReactNode;
+}
+
+export type ScriptProps = ExternalScriptProps | InlineScriptProps;
+
 /**
  * Load a third-party script with strategy control.
  *
@@ -40,8 +54,35 @@ export function Script({
   strategy = "afterInteractive",
   onLoad,
   onError,
+  children,
   ...rest
 }: ScriptProps) {
+  // ── Inline script: render <script>{children}</script> directly ──────────────
+  // Inline scripts have no loading strategy — they are always rendered as-is.
+  // For SSR (beforeInteractive) they land in the HTML stream; for client
+  // renders they are injected once via useEffect.
+  if (!src) {
+    if (strategy === "beforeInteractive") {
+      if (typeof window !== "undefined") return null;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return <script {...(rest as any)}>{children}</script>;
+    }
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useEffect(() => {
+      const el = document.createElement("script");
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      if (typeof children === "string") el.textContent = children;
+      for (const [k, v] of Object.entries(rest)) {
+        if (typeof v === "string") el.setAttribute(k, v);
+      }
+      document.head.appendChild(el);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return null;
+  }
+
+  // ── External script ─────────────────────────────────────────────────────────
+
   // `beforeInteractive` is handled at SSR time by rendering a real <script> tag.
   // The component returns null on the client to avoid duplicate injection.
   if (strategy === "beforeInteractive") {

package/src/ssr/html.ts

@@ -101,6 +101,61 @@ export function htmlShellAfter(opts: { nonce?: string | undefined }): string {
 </html>`;
 }
 
+/**
+ * Build just the alab `<meta>` tags used for client hydration.
+ * Used when the page component renders a full `<html>` document so the tags
+ * can be injected into the user-controlled `<head>` rather than the shell.
+ */
+export function buildAlabMetaTags(opts: Omit<HtmlShellOptions, "metadata" | "headExtra">): string {
+  const { routeFile, ssr, paramsJson, searchParamsJson, layoutsJson, loadingFile, buildId } = opts;
+  return [
+    `<meta name="alabjs-route" content="${escAttr(routeFile)}" />`,
+    `<meta name="alabjs-ssr" content="${ssr ? "true" : "false"}" />`,
+    `<meta name="alabjs-params" content="${escAttr(paramsJson)}" />`,
+    `<meta name="alabjs-search-params" content="${escAttr(searchParamsJson)}" />`,
+    layoutsJson ? `<meta name="alabjs-layouts" content="${escAttr(layoutsJson)}" />` : "",
+    loadingFile ? `<meta name="alabjs-loading" content="${escAttr(loadingFile)}" />` : "",
+    buildId ? `<meta name="alabjs-build-id" content="${escAttr(buildId)}" />` : "",
+    // Signal to the client bootstrap that it must use hydrateRoot(document, …)
+    // instead of mounting into <div id="alabjs-root">.
+    `<meta name="alabjs-full-document" content="true" />`,
+  ].filter(Boolean).join("\n    ");
+}
+
+/**
+ * Inject alab hydration meta tags and the client bootstrap script into a
+ * full-document SSR string (i.e. one whose root element is `<html>`).
+ *
+ * The meta tags are appended before `</head>` and the client script before
+ * `</body>`.  If neither marker is found the strings are appended verbatim.
+ */
+export function injectIntoFullDocument(
+  ssrHtml: string,
+  opts: Omit<HtmlShellOptions, "metadata" | "headExtra">,
+): string {
+  const metaTags = buildAlabMetaTags(opts);
+  const nonceAttr = opts.nonce ? ` nonce="${escAttr(opts.nonce)}"` : "";
+  const clientScript = `<script type="module" src="/@alabjs/client"${nonceAttr}></script>`;
+
+  let result = ssrHtml;
+
+  // Inject meta tags before </head> (case-insensitive).
+  if (/<\/head>/i.test(result)) {
+    result = result.replace(/<\/head>/i, `  ${metaTags}\n  </head>`);
+  } else {
+    result = metaTags + "\n" + result;
+  }
+
+  // Inject client bootstrap script before </body>.
+  if (/<\/body>/i.test(result)) {
+    result = result.replace(/<\/body>/i, `  ${clientScript}\n  </body>`);
+  } else {
+    result = result + "\n" + clientScript;
+  }
+
+  return result;
+}
+
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
 function escHtml(s: string): string {

package/src/types/plugins.d.ts

@@ -1,3 +1,19 @@
 declare module "alabjs-vite-plugin" {
   export function alabPlugin(options?: { mode?: "dev" | "build" }): import("vite").Plugin[];
 }
+
+// Augment ImportMeta so `import.meta.env.DEV` (injected by Vite at build time)
+// is recognised by TypeScript when compiling alabjs component source files.
+// Vite replaces `import.meta.env.DEV` with a literal boolean at bundle time;
+// this declaration just provides the compile-time type so TS does not error.
+interface ImportMeta {
+  readonly env: {
+    /** `true` in Vite dev server, `false` in production builds. */
+    readonly DEV: boolean;
+    readonly PROD: boolean;
+    readonly SSR: boolean;
+    readonly MODE: string;
+    readonly BASE_URL: string;
+    readonly [key: string]: unknown;
+  };
+}