alabjs 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alabjs",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "AlabJS — full-stack React framework powered by a Rust compiler",
   "keywords": [
     "react",
@@ -61,6 +61,10 @@
       "import": "./dist/server/cache.js",
       "types": "./dist/server/cache.d.ts"
     },
+    "./analytics": {
+      "import": "./dist/analytics/store.js",
+      "types": "./dist/analytics/store.d.ts"
+    },
     "./adapters/cloudflare": {
       "import": "./dist/adapters/cloudflare.js",
       "types": "./dist/adapters/cloudflare.d.ts"

package/src/analytics/handler.ts

@@ -0,0 +1,110 @@
+/**
+ * H3 route handlers for the AlabJS analytics endpoints.
+ *
+ * POST /_alabjs/vitals  — receives Core Web Vitals beacons from the browser.
+ * GET  /_alabjs/analytics — returns aggregated per-route stats (requires auth).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { recordMetric, getSnapshot, type MetricName } from "./store.js";
+
+const METRIC_NAMES = new Set<string>(["LCP", "CLS", "INP", "TTFB", "FCP"]);
+
+/** Read the raw request body as a UTF-8 string. */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+/**
+ * POST /_alabjs/vitals
+ *
+ * Accepts a JSON beacon: { name, value, route }
+ * Called by the browser via navigator.sendBeacon — no auth required.
+ * Always responds 204 so the browser doesn't wait.
+ */
+export async function handleVitalsBeacon(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  res.setHeader("access-control-allow-origin", "*");
+
+  if (req.method === "OPTIONS") {
+    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.end();
+    return;
+  }
+
+  try {
+    const raw = await readBody(req);
+    // sendBeacon may batch multiple events as a JSON array or single object.
+    const parsed: unknown = JSON.parse(raw);
+    const events = Array.isArray(parsed) ? parsed : [parsed];
+
+    for (const ev of events) {
+      if (
+        ev !== null &&
+        typeof ev === "object" &&
+        "name" in ev && typeof ev.name === "string" &&
+        "value" in ev && typeof ev.value === "number" &&
+        "route" in ev && typeof ev.route === "string" &&
+        METRIC_NAMES.has(ev.name)
+      ) {
+        recordMetric(
+          ev.route.slice(0, 256),        // cap length for safety
+          ev.name as MetricName,
+          ev.value,
+        );
+      }
+    }
+  } catch {
+    // Malformed beacon — swallow silently, still return 204.
+  }
+
+  res.statusCode = 204;
+  res.end();
+}
+
+/**
+ * GET /_alabjs/analytics
+ *
+ * Returns a JSON snapshot of all collected metrics.
+ * Protected by Authorization: Bearer <ALAB_ANALYTICS_SECRET>.
+ * Falls back to ALAB_REVALIDATE_SECRET if ALAB_ANALYTICS_SECRET is unset.
+ */
+export function handleAnalyticsDashboard(
+  req: IncomingMessage,
+  res: ServerResponse,
+): void {
+  const secret =
+    process.env["ALAB_ANALYTICS_SECRET"] ??
+    process.env["ALAB_REVALIDATE_SECRET"];
+
+  if (secret) {
+    const auth = req.headers["authorization"] ?? "";
+    const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+    if (token !== secret) {
+      res.statusCode = 401;
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify({ error: "Unauthorized. Set Authorization: Bearer <ALAB_ANALYTICS_SECRET>." }));
+      return;
+    }
+  }
+
+  res.statusCode = 200;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.setHeader("cache-control", "no-store");
+  res.end(JSON.stringify(getSnapshot(), null, 2));
+}

package/src/analytics/store.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { recordMetric, getSnapshot, clearStore } from "./store.js";
+
+beforeEach(() => clearStore());
+
+describe("recordMetric / getSnapshot", () => {
+  it("records a single LCP and counts it as a pageview", () => {
+    recordMetric("/blog", "LCP", 1200);
+    const snap = getSnapshot();
+    expect(snap.routes["/blog"]?.pageviews).toBe(1);
+    expect(snap.routes["/blog"]?.lcp_p75).toBe(1200);
+  });
+
+  it("computes p75 correctly across multiple samples", () => {
+    // 4 samples: [100, 200, 300, 400] → sorted → index floor(4*0.75)=3 → 400
+    for (const v of [300, 100, 400, 200]) recordMetric("/", "LCP", v);
+    const snap = getSnapshot();
+    expect(snap.routes["/"]?.lcp_p75).toBe(400);
+  });
+
+  it("evicts oldest sample when ring buffer is full", () => {
+    // Fill 500 samples with value 1, then add one with value 9999
+    for (let i = 0; i < 500; i++) recordMetric("/test", "FCP", 1);
+    recordMetric("/test", "FCP", 9999);
+    const snap = getSnapshot();
+    // Ring should still have exactly 500 entries (oldest 1 evicted, 9999 added)
+    // p75 of 499×1 + 1×9999 = index 374 → 1
+    expect(snap.routes["/test"]?.fcp_p75).toBe(1);
+  });
+
+  it("ignores unknown metric names", () => {
+    // @ts-expect-error intentionally invalid
+    recordMetric("/x", "UNKNOWN", 100);
+    const snap = getSnapshot();
+    expect(snap.routes["/x"]).toBeUndefined();
+  });
+
+  it("tracks multiple routes independently", () => {
+    recordMetric("/a", "CLS", 0.05);
+    recordMetric("/b", "CLS", 0.2);
+    const snap = getSnapshot();
+    expect(snap.routes["/a"]?.cls_p75).toBe(0.05);
+    expect(snap.routes["/b"]?.cls_p75).toBe(0.2);
+  });
+});

package/src/analytics/store.ts

@@ -0,0 +1,94 @@
+/**
+ * In-memory analytics store.
+ *
+ * Keeps a ring buffer of the last RING_SIZE samples for each
+ * (route, metric) pair and exposes p75 aggregates.
+ *
+ * All writes are synchronous and happen in the same Node.js event-loop
+ * turn as the beacon POST — no blocking, no external I/O.
+ */
+
+/** Maximum samples retained per (route, metric) bucket. */
+const RING_SIZE = 500;
+
+export type MetricName = "LCP" | "CLS" | "INP" | "TTFB" | "FCP";
+
+const METRIC_NAMES: MetricName[] = ["LCP", "CLS", "INP", "TTFB", "FCP"];
+
+interface RouteBucket {
+  /** Ring buffers — one per metric. */
+  samples: Record<MetricName, number[]>;
+  /** Number of LCP events received (proxy for page-view count). */
+  pageviews: number;
+}
+
+/** route path → bucket */
+const store = new Map<string, RouteBucket>();
+
+function getBucket(route: string): RouteBucket {
+  let bucket = store.get(route);
+  if (!bucket) {
+    const samples = {} as Record<MetricName, number[]>;
+    for (const m of METRIC_NAMES) samples[m] = [];
+    bucket = { samples, pageviews: 0 };
+    store.set(route, bucket);
+  }
+  return bucket;
+}
+
+/**
+ * Record one metric sample for a route.
+ * If the ring buffer is full, the oldest sample is evicted.
+ */
+export function recordMetric(route: string, name: MetricName, value: number): void {
+  if (!METRIC_NAMES.includes(name)) return;
+  const bucket = getBucket(route);
+  const buf = bucket.samples[name];
+  buf.push(value);
+  if (buf.length > RING_SIZE) buf.shift();
+  if (name === "LCP") bucket.pageviews++;
+}
+
+/** Compute the p75 of an array of numbers, or null if empty. */
+function p75(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.floor(sorted.length * 0.75);
+  return Math.round((sorted[idx] ?? sorted[sorted.length - 1]!) * 100) / 100;
+}
+
+export interface RouteStats {
+  pageviews: number;
+  lcp_p75: number | null;
+  cls_p75: number | null;
+  inp_p75: number | null;
+  ttfb_p75: number | null;
+  fcp_p75: number | null;
+}
+
+export interface AnalyticsSnapshot {
+  routes: Record<string, RouteStats>;
+  /** ISO timestamp of when the snapshot was taken. */
+  asOf: string;
+}
+
+/** Return an aggregated snapshot of all collected metrics. */
+export function getSnapshot(): AnalyticsSnapshot {
+  const routes: Record<string, RouteStats> = {};
+  for (const [route, bucket] of store.entries()) {
+    routes[route] = {
+      pageviews:  bucket.pageviews,
+      lcp_p75:   p75(bucket.samples.LCP),
+      cls_p75:   p75(bucket.samples.CLS),
+      inp_p75:   p75(bucket.samples.INP),
+      ttfb_p75:  p75(bucket.samples.TTFB),
+      fcp_p75:   p75(bucket.samples.FCP),
+    };
+  }
+  return { routes, asOf: new Date().toISOString() };
+}
+
+/** Clear all stored data (useful in tests). */
+export function clearStore(): void {
+  store.clear();
+}

package/src/commands/build.ts

@@ -1,7 +1,9 @@
 import { build as viteBuild, type PluginOption } from "vite";
 import { resolve } from "node:path";
-import { spawn } from "node:child_process";
-import { existsSync, writeFileSync } from "node:fs";
+import { spawn, execSync } from "node:child_process";
+import { existsSync, writeFileSync, readFileSync } from "node:fs";
+import { preRenderPPRShell, findBuildLayoutFiles, PPR_CACHE_SUBDIR } from "../ssr/ppr.js";
+import type { RouteManifest } from "../router/manifest.js";
 
 interface BuildOptions {
   cwd: string;
@@ -165,6 +167,12 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
 
   await Promise.all(tasks);
 
+  // Write a stable build ID for skew protection (must run after Vite so the
+  // route-manifest.json is in place for the content-hash fallback path).
+  const distDir = resolve(cwd, ".alabjs/dist");
+  await writeBuildId(distDir, cwd);
+  await buildPPRShells(distDir, cwd);
+
   // Bundle the offline service worker as a separate iife chunk.
   // Output: .alabjs/dist/client/_alabjs/offline-sw.js (served at /_alabjs/offline-sw.js)
   await buildOfflineSw(cwd);
@@ -172,6 +180,113 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
   console.log("\n  alab  build complete → .alabjs/dist");
 }
 
+/**
+ * Generate a stable build ID and write it to `.alabjs/dist/BUILD_ID`.
+ *
+ * Strategy (in priority order):
+ *  1. Git short SHA — deterministic, human-readable, zero CPU cost.
+ *  2. Rust FNV-1a hash of the route-manifest JSON via `@alabjs/compiler`
+ *     (napi binary) — content-addressed, no git required.
+ *  3. Base-36 millisecond timestamp — last resort when both git and napi
+ *     are unavailable (e.g. first-time contributor without Rust toolchain).
+ */
+async function writeBuildId(distDir: string, cwd: string): Promise<void> {
+  let buildId: string;
+
+  // 1. Git SHA (preferred — zero cost, guaranteed unique per commit)
+  try {
+    buildId = execSync("git rev-parse --short HEAD", { cwd, encoding: "utf8" }).trim();
+  } catch {
+    // 2. Rust FNV-1a hash of the route manifest (content-addressed)
+    try {
+      const manifestPath = resolve(distDir, "route-manifest.json");
+      const manifestContent = readFileSync(manifestPath, "utf8");
+      type NapiWithHash = { hashBuildId(s: string): string };
+      const mod = await import("@alabjs/compiler") as unknown as { default?: NapiWithHash } & NapiWithHash;
+      const napi: NapiWithHash = (mod.default ?? mod) as NapiWithHash;
+      if (typeof napi.hashBuildId === "function") {
+        buildId = napi.hashBuildId(manifestContent);
+      } else {
+        throw new Error("hashBuildId not available");
+      }
+    } catch {
+      // 3. Timestamp fallback
+      buildId = Date.now().toString(36);
+    }
+  }
+
+  writeFileSync(resolve(distDir, "BUILD_ID"), buildId, "utf8");
+  console.log(`  alab  build ID → ${buildId}`);
+}
+
+/**
+ * Pre-render static HTML shells for every page that exports `ppr = true`.
+ *
+ * Runs AFTER the Vite SSR bundle so compiled page modules are available in
+ * `.alabjs/dist/server/`. Each shell is saved to `.alabjs/ppr-cache/`.
+ */
+async function buildPPRShells(distDir: string, cwd: string): Promise<void> {
+  const manifestPath = resolve(distDir, "route-manifest.json");
+  if (!existsSync(manifestPath)) return;
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as RouteManifest;
+  const pageRoutes = manifest.routes.filter((r) => r.kind === "page");
+  const pprCacheDir = resolve(cwd, PPR_CACHE_SUBDIR);
+  let count = 0;
+
+  for (const route of pageRoutes) {
+    const modulePath = resolve(distDir, "server", route.file);
+    if (!existsSync(modulePath)) continue;
+
+    // Dynamic import — module is compiled ESM, importable by Node directly.
+    const mod = await import(modulePath) as {
+      default?: unknown;
+      ppr?: unknown;
+      metadata?: Record<string, unknown>;
+    };
+
+    if (mod.ppr !== true) continue;
+    if (typeof mod.default !== "function") {
+      console.warn(`  alab  ppr: ${route.file} has no default export — skipping.`);
+      continue;
+    }
+
+    // Load layout modules (outermost → innermost).
+    const layoutPaths = findBuildLayoutFiles(route.file, distDir);
+    const layoutMods = await Promise.all(
+      layoutPaths.map((p) => import(resolve(distDir, "server", p))),
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const layouts = layoutMods.map((m: any) => m.default).filter((c: unknown) => typeof c === "function");
+
+    try {
+      await preRenderPPRShell({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        Page: mod.default as any,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        layouts: layouts as any[],
+        shellOpts: {
+          metadata: (mod.metadata as never) ?? {},
+          paramsJson: "{}",
+          searchParamsJson: "{}",
+          routeFile: route.file,
+          ssr: true,
+        },
+        pprCacheDir,
+        routePath: route.path,
+      });
+      count++;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`  alab  ppr: failed to pre-render ${route.path}: ${msg}`);
+    }
+  }
+
+  if (count > 0) {
+    console.log(`  alab  ppr  → ${count} shell${count === 1 ? "" : "s"} written to ${PPR_CACHE_SUBDIR}`);
+  }
+}
+
 /** Compile the offline service worker to a standalone iife bundle. */
 async function buildOfflineSw(cwd: string): Promise<void> {
   const swEntry = new URL("../client/offline-sw.js", import.meta.url).pathname;

package/src/commands/dev.ts

@@ -63,6 +63,12 @@ async function readJsonBody(req: IncomingMessage): Promise<unknown> {
 export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions) {
   console.log("  alab  starting dev server...\n");
 
+  // Per-session build ID for skew protection in dev.
+  // A new ID is generated each time the dev server starts so that a browser
+  // tab left open across a restart will hard-reload on the next navigation
+  // rather than silently rendering with stale JS.
+  const devBuildId = `dev-${Date.now().toString(36)}`;
+
   const appDir = resolve(cwd, "app");
 
   const vite = await createServer({
@@ -459,6 +465,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
           layoutsJson,
           loadingFile,
           ssr: ssrEnabled,
+          buildId: devBuildId,
         });
         const shellAfter = htmlShellAfter({});
         const rawHtml = `${shellBefore}${ssrContent}${shellAfter}`;

package/src/components/Analytics.tsx

@@ -0,0 +1,164 @@
+/**
+ * Alab Analytics — Core Web Vitals collection component.
+ *
+ * Drop `<Analytics />` into your root layout to start collecting
+ * LCP, CLS, INP, TTFB, and FCP from real users. Metrics are sent
+ * to `/_alabjs/vitals` via `navigator.sendBeacon` and aggregated
+ * in memory on the server.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // app/layout.tsx
+ * import { Analytics } from "alabjs/components";
+ *
+ * export default function RootLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <>
+ *       {children}
+ *       <Analytics />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * ## Viewing metrics
+ *
+ * ```sh
+ * curl -H "Authorization: Bearer $ALAB_ANALYTICS_SECRET" \
+ *      http://localhost:3000/_alabjs/analytics
+ * ```
+ */
+
+import { useEffect } from "react";
+
+export interface AnalyticsProps {
+  /**
+   * Override the beacon endpoint.
+   * @default "/_alabjs/vitals"
+   */
+  endpoint?: string;
+}
+
+/**
+ * Collects Core Web Vitals (LCP, CLS, INP, TTFB, FCP) using the browser's
+ * `PerformanceObserver` API and sends them to the AlabJS vitals endpoint.
+ *
+ * Uses `navigator.sendBeacon` so beacons are fire-and-forget and survive
+ * page unloads. Implements `buffered: true` so metrics already emitted
+ * before the observer attached are still captured.
+ */
+export function Analytics({ endpoint = "/_alabjs/vitals" }: AnalyticsProps) {
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof PerformanceObserver === "undefined") return;
+
+    const route = window.location.pathname;
+
+    function send(name: string, value: number) {
+      const payload = JSON.stringify({ name, value, route });
+      if (navigator.sendBeacon) {
+        navigator.sendBeacon(endpoint, new Blob([payload], { type: "application/json" }));
+      } else {
+        // Fallback for environments without sendBeacon (rare).
+        void fetch(endpoint, {
+          method: "POST",
+          body: payload,
+          headers: { "content-type": "application/json" },
+          keepalive: true,
+        }).catch(() => {});
+      }
+    }
+
+    const observers: PerformanceObserver[] = [];
+
+    function observe(type: string, cb: (entries: PerformanceObserverEntryList) => void) {
+      try {
+        const po = new PerformanceObserver(cb);
+        po.observe({ type, buffered: true });
+        observers.push(po);
+      } catch {
+        // Entry type not supported in this browser — skip silently.
+      }
+    }
+
+    // ── LCP — Largest Contentful Paint ─────────────────────────────────────
+    // We report the last entry since LCP can be updated multiple times.
+    let lcpValue = 0;
+    observe("largest-contentful-paint", (list) => {
+      const entries = list.getEntries();
+      const last = entries[entries.length - 1] as PerformancePaintTiming | undefined;
+      if (last) lcpValue = last.startTime;
+    });
+
+    // ── CLS — Cumulative Layout Shift ───────────────────────────────────────
+    // Accumulate shift values across all layout-shift entries.
+    let clsValue = 0;
+    let clsSessionGap = 0;
+    let clsSessionValue = 0;
+    let clsLastTime = 0;
+    observe("layout-shift", (list) => {
+      for (const entry of list.getEntries()) {
+        const ls = entry as PerformanceEntry & { value: number; hadRecentInput: boolean };
+        if (ls.hadRecentInput) continue;
+        const gap = ls.startTime - clsLastTime;
+        if (gap > 1000 || ls.startTime - clsSessionGap > 5000) {
+          clsSessionValue = ls.value;
+          clsSessionGap = ls.startTime;
+        } else {
+          clsSessionValue += ls.value;
+        }
+        clsLastTime = ls.startTime;
+        if (clsSessionValue > clsValue) clsValue = clsSessionValue;
+      }
+    });
+
+    // ── INP — Interaction to Next Paint ────────────────────────────────────
+    // Track the worst interaction duration (p98 heuristic: worst of all events).
+    let inpValue = 0;
+    observe("event", (list) => {
+      for (const entry of list.getEntries()) {
+        const e = entry as PerformanceEntry & { duration: number };
+        if (e.duration > inpValue) inpValue = e.duration;
+      }
+    });
+
+    // ── TTFB — Time to First Byte ───────────────────────────────────────────
+    // Read directly from navigation timing — available immediately after load.
+    const sendTtfb = () => {
+      const nav = performance.getEntriesByType("navigation")[0] as
+        | PerformanceNavigationTiming
+        | undefined;
+      if (nav) send("TTFB", nav.responseStart);
+    };
+
+    // ── FCP — First Contentful Paint ───────────────────────────────────────
+    observe("paint", (list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.name === "first-contentful-paint") {
+          send("FCP", entry.startTime);
+        }
+      }
+    });
+
+    // Flush LCP, CLS, and INP on page hide (navigating away / tab close).
+    // This gives us the most accurate final values.
+    const flush = () => {
+      if (lcpValue > 0) send("LCP", lcpValue);
+      if (clsValue > 0) send("CLS", Math.round(clsValue * 10000) / 10000);
+      if (inpValue > 0) send("INP", inpValue);
+    };
+
+    sendTtfb();
+    window.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") flush();
+    }, { once: true });
+
+    return () => {
+      for (const po of observers) po.disconnect();
+    };
+  // endpoint is intentionally captured once on mount only.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return null;
+}