alabjs 0.1.0

package/src/commands/ssg.ts

@@ -0,0 +1,177 @@
+/**
+ * `alab ssg` — Static Site Generation
+ *
+ * Pre-renders all static routes (no dynamic `[param]` segments) to HTML files
+ * at build time. Output lands in `dist/` and can be served from any static
+ * host: Netlify, GitHub Pages, Cloudflare Pages, S3, etc.
+ *
+ * Dynamic routes (`/users/[id]`) are skipped — they require a running server.
+ * To pre-render dynamic pages, export `export const staticPaths = [...]` from
+ * the page module (planned for a future release).
+ */
+import { createServer } from "vite";
+import { resolve, join } from "node:path";
+import { mkdir, writeFile, cp } from "node:fs/promises";
+import { scanDevRoutes } from "../ssr/router-dev.js";
+import { htmlShellBefore, htmlShellAfter } from "../ssr/html.js";
+import type { PageMetadata } from "../types/index.js";
+
+interface SsgOptions {
+  cwd: string;
+  /** Output directory. Defaults to `dist`. */
+  outDir?: string;
+}
+
+export async function ssg({ cwd, outDir = "dist" }: SsgOptions) {
+  const appDir = resolve(cwd, "app");
+  const publicDir = resolve(cwd, "public");
+  const outputDir = resolve(cwd, outDir);
+
+  console.log(`  alab  generating static site → ${outDir}/\n`);
+
+  // Spin up a Vite SSR server (no HTTP listener — port 0, ephemeral).
+  const vite = await createServer({
+    root: cwd,
+    appType: "custom",
+    server: { port: 0 },
+    plugins: [(await import("alabjs-vite-plugin")).alabPlugin()],
+  });
+
+  const allRoutes = scanDevRoutes(appDir);
+
+  await mkdir(outputDir, { recursive: true });
+
+  // Load React renderer once.
+  const { renderToString: reactRenderToString } = (await vite.ssrLoadModule(
+    "react-dom/server",
+  )) as { renderToString: (el: unknown) => string };
+  const { createElement } = (await vite.ssrLoadModule("react")) as {
+    createElement: (type: unknown, props: unknown) => unknown;
+  };
+
+  let written = 0;
+  let skipped = 0;
+
+  for (const route of allRoutes) {
+    const mod = (await vite.ssrLoadModule(route.file)) as {
+      default?: unknown;
+      metadata?: PageMetadata;
+      generateMetadata?: (params: Record<string, string>) => PageMetadata | Promise<PageMetadata>;
+      generateStaticParams?: () => Promise<Array<Record<string, string>>>;
+      ssr?: boolean;
+    };
+
+    const Page = mod.default;
+    if (typeof Page !== "function") {
+      console.warn(`  alab  [ssg] skip ${route.file} — no default export`);
+      skipped++;
+      continue;
+    }
+
+    // Derive the URL path from the file path.
+    const urlPath =
+      route.file
+        .replace(appDir, "")
+        .replace(/\/page\.(tsx|ts)$/, "") || "/";
+
+    const routeFile = route.file.replace(cwd, "").replace(/^\//, "");
+
+    // ── Dynamic routes: require generateStaticParams ─────────────────────────
+    if (route.paramNames.length > 0) {
+      if (typeof mod.generateStaticParams !== "function") {
+        console.warn(
+          `  alab  [ssg] skip ${urlPath} — dynamic route missing generateStaticParams()`,
+        );
+        skipped++;
+        continue;
+      }
+
+      let paramSets: Array<Record<string, string>>;
+      try {
+        paramSets = await mod.generateStaticParams();
+      } catch (err) {
+        console.warn(`  alab  [ssg] skip ${urlPath} — generateStaticParams threw: ${String(err)}`);
+        skipped++;
+        continue;
+      }
+
+      for (const params of paramSets) {
+        // Replace [param] segments with actual values.
+        const resolvedPath = urlPath.replace(/\[([^\]]+)\]/g, (_, name) => params[name] ?? name);
+        const segments = resolvedPath === "/" ? [] : resolvedPath.split("/").filter(Boolean);
+        const pageOutputDir = join(outputDir, ...segments);
+        await mkdir(pageOutputDir, { recursive: true });
+        const outputFile = join(pageOutputDir, "index.html");
+
+        const metadata: PageMetadata =
+          typeof mod.generateMetadata === "function"
+            ? await mod.generateMetadata(params)
+            : (mod.metadata ?? {});
+
+        const ssrContent = reactRenderToString(
+          createElement(Page, { params, searchParams: {} }),
+        );
+
+        const shellBefore = htmlShellBefore({
+          metadata,
+          paramsJson: JSON.stringify(params),
+          searchParamsJson: "{}",
+          routeFile,
+          ssr: true,
+        });
+        const shellAfter = htmlShellAfter({});
+
+        await writeFile(outputFile, `${shellBefore}${ssrContent}${shellAfter}`, "utf8");
+        console.log(
+          `  alab  [ssg] ${resolvedPath.padEnd(30)} → ${outputFile.replace(cwd + "/", "")}`,
+        );
+        written++;
+      }
+      continue;
+    }
+
+    // ── Static routes ─────────────────────────────────────────────────────────
+    const metadata: PageMetadata =
+      typeof mod.generateMetadata === "function"
+        ? await mod.generateMetadata({})
+        : (mod.metadata ?? {});
+
+    const ssrContent = reactRenderToString(
+      createElement(Page, { params: {}, searchParams: {} }),
+    );
+
+    const segments = urlPath === "/" ? [] : urlPath.split("/").filter(Boolean);
+    const pageOutputDir = join(outputDir, ...segments);
+    await mkdir(pageOutputDir, { recursive: true });
+    const outputFile = join(pageOutputDir, "index.html");
+
+    const shellBefore = htmlShellBefore({
+      metadata,
+      paramsJson: "{}",
+      searchParamsJson: "{}",
+      routeFile,
+      ssr: true,
+    });
+    const shellAfter = htmlShellAfter({});
+
+    await writeFile(outputFile, `${shellBefore}${ssrContent}${shellAfter}`, "utf8");
+    console.log(`  alab  [ssg] ${urlPath.padEnd(30)} → ${outputFile.replace(cwd + "/", "")}`);
+    written++;
+  }
+
+  // Copy public/ assets into the output directory.
+  try {
+    await cp(publicDir, join(outputDir, "public"), { recursive: true });
+    console.log(`\n  alab  [ssg] copied public/ assets`);
+  } catch {
+    // public/ may not exist — not an error.
+  }
+
+  await vite.close();
+
+  console.log(
+    `\n  alab  ${written} page${written === 1 ? "" : "s"} written` +
+      (skipped > 0 ? `, ${skipped} dynamic route${skipped === 1 ? "" : "s"} skipped` : "") +
+      `\n`,
+  );
+}

package/src/commands/start.ts

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { createApp } from "../server/app.js";
+import type { RouteManifest } from "../router/manifest.js";
+
+interface StartOptions {
+  cwd: string;
+  port?: number;
+}
+
+export async function start({ cwd, port = 3000 }: StartOptions) {
+  const manifestPath = resolve(cwd, ".alabjs/route-manifest.json");
+
+  let manifest: RouteManifest;
+  try {
+    const { readFileSync } = await import("node:fs");
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as RouteManifest;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      console.error("  alab  no build found. Run `alab build` first.");
+    } else {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`  alab  failed to load route manifest: ${msg}`);
+      console.error("  alab  try running `alab build` again.");
+    }
+    process.exit(1);
+  }
+
+  const distDir = resolve(cwd, ".alabjs/dist");
+  const app = createApp(manifest, distDir);
+  app.listen(port);
+}

package/src/commands/test.ts

@@ -0,0 +1,102 @@
+/**
+ * `alab test` — zero-config test runner.
+ *
+ * Runs Vitest with the correct environment pre-configured for Alab apps:
+ * - SSR modules tested in `node` environment (React server rendering)
+ * - Client modules tested in `jsdom` environment (React DOM)
+ * - Alab's Vite plugin wired in so `.server.ts` boundary rules apply
+ * - `alab/test` utilities (`mockServerFn`, `renderPage`) available globally
+ *
+ * Usage:
+ *   alab test              — run all tests once
+ *   alab test --watch      — watch mode
+ *   alab test --ui         — Vitest UI
+ *   alab test src/foo.test.ts  — run specific file(s)
+ */
+
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { existsSync, writeFileSync } from "node:fs";
+
+interface TestOptions {
+  cwd: string;
+  watch?: boolean;
+  ui?: boolean;
+  files?: string[];
+}
+
+/**
+ * Generate a `vitest.config.ts` in the project root if one doesn't exist.
+ * This is written to a temp path and passed via `--config` so it doesn't
+ * overwrite an existing user config.
+ */
+function generateVitestConfig(cwd: string): string {
+  const configPath = resolve(cwd, ".alabjs/vitest.config.ts");
+  const config = `// Auto-generated by \`alab test\` — do not edit manually.
+// Customise by creating your own vitest.config.ts in the project root.
+import { defineConfig } from "vitest/config";
+import { alabPlugin } from "alabjs-vite-plugin";
+
+export default defineConfig({
+  plugins: [alabPlugin()],
+  test: {
+    globals: true,
+    environment: "node",
+    environmentMatchGlobs: [
+      // Client-side component tests run in jsdom
+      ["**/*.client.test.{ts,tsx}", "jsdom"],
+      ["**/*.browser.test.{ts,tsx}", "jsdom"],
+    ],
+    setupFiles: [],
+    include: ["**/*.{test,spec}.{ts,tsx}"],
+    exclude: ["node_modules", ".alabjs"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html"],
+    },
+  },
+});
+`;
+  writeFileSync(configPath, config, "utf8");
+  return configPath;
+}
+
+export async function test({ cwd, watch = false, ui = false, files = [] }: TestOptions) {
+  // Ensure .alabjs/ exists
+  const dotAlab = resolve(cwd, ".alabjs");
+  if (!existsSync(dotAlab)) {
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(dotAlab, { recursive: true });
+  }
+
+  // Use the project's local vitest if available, otherwise fall back to npx.
+  const vitestBin = resolve(cwd, "node_modules/.bin/vitest");
+  const bin = existsSync(vitestBin) ? vitestBin : "npx";
+  const binArgs = existsSync(vitestBin) ? [] : ["vitest"];
+
+  // If the user already has a vitest config, respect it.
+  const userConfig = ["vitest.config.ts", "vitest.config.js"].find((f) =>
+    existsSync(resolve(cwd, f)),
+  );
+
+  const configPath = userConfig ? resolve(cwd, userConfig) : generateVitestConfig(cwd);
+
+  const args: string[] = [
+    ...binArgs,
+    ...(ui ? ["--ui"] : []),
+    ...(watch ? [] : ["run"]),
+    "--config", configPath,
+    ...files,
+  ];
+
+  console.log(`  alab  running tests${watch ? " (watch)" : ""}...\n`);
+
+  await new Promise<void>((ok, fail) => {
+    const child = spawn(bin, args, { cwd, stdio: "inherit", shell: true });
+    child.on("close", (code) => {
+      if (code === 0 || watch) ok();
+      else fail(new Error(`[alabjs] Tests failed (vitest exited ${code})`));
+    });
+    child.on("error", fail);
+  });
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,73 @@
+import { Component, type ReactNode, type ErrorInfo } from "react";
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** Custom fallback UI. Receives the error and a reset callback. */
+  fallback?: (props: { error: Error; reset: () => void }) => ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+/**
+ * React class error boundary that wraps the Alab page root.
+ *
+ * Catches unhandled errors thrown during rendering, inside event handlers called
+ * during the commit phase, and inside lifecycle methods. Renders the nearest
+ * `error.tsx` fallback (or a minimal built-in fallback) instead of crashing.
+ *
+ * Usage (automatic — wired by the `/@alabjs/client` virtual module):
+ *   The virtual client module wraps `<Page>` in this boundary automatically.
+ *   You do not need to add it manually unless building a custom entry point.
+ *
+ * Manual usage:
+ *   import { ErrorBoundary } from "alabjs/components";
+ *   <ErrorBoundary fallback={({ error, reset }) => <p onClick={reset}>{error.message}</p>}>
+ *     <MyComponent />
+ *   </ErrorBoundary>
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+    this.reset = this.reset.bind(this);
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.error("[alabjs] Unhandled render error:", error, info.componentStack);
+  }
+
+  reset(): void {
+    this.setState({ error: null });
+  }
+
+  override render(): ReactNode {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+
+    if (this.props.fallback) {
+      return this.props.fallback({ error, reset: this.reset });
+    }
+
+    // Built-in minimal fallback
+    return (
+      <div style={{ padding: "2rem", fontFamily: "monospace" }}>
+        <h2 style={{ color: "#e11d48" }}>Something went wrong</h2>
+        <pre style={{ background: "#fef2f2", padding: "1rem", borderRadius: "0.5rem", overflow: "auto" }}>
+          {error.message}
+        </pre>
+        <button
+          onClick={this.reset}
+          style={{ marginTop: "1rem", padding: "0.5rem 1rem", cursor: "pointer" }}
+        >
+          Try again
+        </button>
+      </div>
+    );
+  }
+}

package/src/components/Font.tsx

@@ -0,0 +1,100 @@
+/**
+ * Font — self-hosted web font loader.
+ *
+ * In development this renders preconnect + Google Fonts stylesheet links so
+ * fonts load immediately with `font-display: swap`.
+ *
+ * In production (`alab build`) the build step downloads the font files to
+ * `public/_fonts/` and generates self-hosted `@font-face` CSS, so no
+ * third-party network request is made at runtime.
+ *
+ * Usage (inside a layout or page `<head>`-equivalent):
+ * ```tsx
+ * import { Font } from "alabjs/components";
+ *
+ * // Single family
+ * <Font family="Inter" weights={[400, 500, 700]} />
+ *
+ * // Multiple families
+ * <Font family="Inter" weights={[400, 700]} />
+ * <Font family="Fira Code" weights={[400]} subsets={["latin"]} />
+ * ```
+ */
+
+export interface FontProps {
+  /**
+   * Google Fonts family name, exactly as it appears on fonts.google.com.
+   * e.g. `"Inter"`, `"Roboto"`, `"Fira Code"`
+   */
+  family: string;
+  /**
+   * Font weights to load. Defaults to `[400]`.
+   * Numeric weights (100–900). Pass `[400, 700]` for regular + bold.
+   */
+  weights?: number[];
+  /**
+   * Unicode subsets to include. Defaults to `["latin"]`.
+   * Adding extra subsets (e.g. `"latin-ext"`, `"cyrillic"`) increases file size.
+   */
+  subsets?: string[];
+  /**
+   * CSS `font-display` value. Defaults to `"swap"` which prevents invisible
+   * text during font load (FOIT → FOUT is a better user experience).
+   */
+  display?: "auto" | "block" | "swap" | "fallback" | "optional";
+  /**
+   * Whether to load italic variants in addition to the requested weights.
+   * Defaults to `false`.
+   */
+  italic?: boolean;
+}
+
+/**
+ * Build the Google Fonts v2 URL for the requested family + weights.
+ * Format: fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap
+ */
+function buildGoogleFontsUrl(props: FontProps): string {
+  const {
+    family,
+    weights = [400],
+    subsets = ["latin"],
+    display = "swap",
+    italic = false,
+  } = props;
+
+  const encodedFamily = family.replace(/ /g, "+");
+
+  // Google Fonts v2 axis syntax: "ital,wght@0,400;0,700;1,400;1,700"
+  const axes: string[] = [];
+  const sortedWeights = [...weights].sort((a, b) => a - b);
+
+  if (italic) {
+    for (const w of sortedWeights) axes.push(`0,${w}`);
+    for (const w of sortedWeights) axes.push(`1,${w}`);
+    const axisTag = `ital,wght@${axes.join(";")}`;
+    return `https://fonts.googleapis.com/css2?family=${encodedFamily}:${axisTag}&display=${display}&subset=${subsets.join(",")}`;
+  }
+
+  const wghtValues = sortedWeights.join(";");
+  return `https://fonts.googleapis.com/css2?family=${encodedFamily}:wght@${wghtValues}&display=${display}&subset=${subsets.join(",")}`;
+}
+
+/**
+ * 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.
+ */
+export function Font(props: FontProps) {
+  const href = buildGoogleFontsUrl(props);
+
+  return (
+    <>
+      {/* Speed up the Google Fonts connection. */}
+      <link rel="preconnect" href="https://fonts.googleapis.com" />
+      <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+      {/* The actual font stylesheet — renders server-side, no layout shift. */}
+      <link rel="stylesheet" href={href} />
+    </>
+  );
+}

package/src/components/Image.tsx

@@ -0,0 +1,141 @@
+import { createElement } from "react";
+
+export interface ImageProps {
+  /** Source path — relative to `/public` or an absolute URL. */
+  src: string;
+  alt: string;
+  /** Intrinsic width in pixels. Used to generate the srcset breakpoints. */
+  width: number;
+  /** Intrinsic height in pixels. Used to preserve layout before load. */
+  height: number;
+  /**
+   * The `sizes` attribute passed to the `<img>` element.
+   * @example "(max-width: 768px) 100vw, 50vw"
+   */
+  sizes?: string | undefined;
+  /**
+   * Mark the image as the LCP element. Sets `loading="eager"` and
+   * `fetchpriority="high"` — omit the blur-up placeholder to avoid CLS.
+   */
+  priority?: boolean | undefined;
+  /** Additional class names. */
+  className?: string | undefined;
+  /** Quality 1–100. Defaults to 80. */
+  quality?: number | undefined;
+  /**
+   * Base64-encoded tiny placeholder generated by `generateBlurPlaceholder()`.
+   * When provided, the image fades in over the blurred placeholder for an
+   * instant-load feel without layout shift.
+   */
+  blurDataURL?: string | undefined;
+}
+
+// Standard responsive breakpoints (matches Tailwind + common viewport widths).
+const BREAKPOINTS = [320, 640, 750, 828, 1080, 1200, 1920];
+
+/**
+ * Rust-powered optimised image component.
+ *
+ * - Generates a `srcset` of WebP variants via `/_alabjs/image` (Rust napi).
+ * - Blur-up placeholder support: pass `blurDataURL` from `generateBlurPlaceholder()`.
+ * - `loading="lazy"` by default; use `priority` for LCP images.
+ * - Always sets `width` + `height` to eliminate CLS (Cumulative Layout Shift).
+ *
+ * @example
+ * ```tsx
+ * import { Image, generateBlurPlaceholder } from "alabjs/components";
+ *
+ * // In a server function — runs on the server at build/request time:
+ * const blur = await generateBlurPlaceholder("/hero.jpg");
+ *
+ * // In the page component:
+ * <Image src="/hero.jpg" alt="Hero" width={1200} height={600} priority blurDataURL={blur} />
+ * ```
+ */
+export function Image({
+  src,
+  alt,
+  width,
+  height,
+  sizes,
+  priority = false,
+  className,
+  quality = 80,
+  blurDataURL,
+}: ImageProps) {
+  const q = Math.max(1, Math.min(100, quality));
+  const encodedSrc = encodeURIComponent(src);
+
+  // Build srcset: breakpoints ≤ intrinsic width + the intrinsic width itself.
+  const widths = Array.from(
+    new Set([...BREAKPOINTS.filter((w) => w < width), width]),
+  ).sort((a, b) => a - b);
+
+  const srcset = widths
+    .map((w) => `/_alabjs/image?src=${encodedSrc}&w=${w}&q=${q}&fmt=webp ${w}w`)
+    .join(", ");
+
+  const defaultSrc = `/_alabjs/image?src=${encodedSrc}&w=${width}&q=${q}&fmt=webp`;
+
+  const style: Record<string, string> = {
+    maxWidth: "100%",
+    height: "auto",
+  };
+
+  // Blur-up: show the tiny placeholder as a CSS background while the real image loads.
+  if (blurDataURL && !priority) {
+    style["backgroundImage"] = `url(${blurDataURL})`;
+    style["backgroundSize"] = "cover";
+    style["backgroundPosition"] = "center";
+  }
+
+  return createElement("img", {
+    src: defaultSrc,
+    srcSet: srcset,
+    sizes: sizes ?? `${width}px`,
+    alt,
+    width,
+    height,
+    loading: priority ? "eager" : "lazy",
+    fetchPriority: priority ? "high" : undefined,
+    decoding: "async",
+    className,
+    style,
+  });
+}
+
+/**
+ * Generate a Base64 blur-up placeholder for an image in `public/`.
+ *
+ * Calls the Rust napi binding to resize the image to 8px wide and encode it
+ * as a tiny WebP, then Base64-encodes it into a data URL ready for `blurDataURL`.
+ *
+ * Run this in a server function — it reads from disk and must not run in the browser.
+ *
+ * @param src - Path relative to `public/` (e.g. `"/hero.jpg"`)
+ * @param publicDir - Absolute path to the `public/` directory
+ */
+export async function generateBlurPlaceholder(
+  src: string,
+  publicDir: string,
+): Promise<string> {
+  const { readFile } = await import("node:fs/promises");
+  const { resolve } = await import("node:path");
+
+  const safeSrc = src.replace(/\.\./g, "").replace(/^\/+/, "");
+  const filePath = resolve(publicDir, safeSrc);
+
+  const input = await readFile(filePath);
+
+  let napi: { optimizeImage: (b: Buffer, q: number | null, w: number | null, h: null, fmt: string) => Promise<Buffer> };
+  try {
+    napi = (await import("@alabjs/compiler")) as typeof napi;
+  } catch {
+    // napi not built — return empty string (image still loads, just no blur effect)
+    return "";
+  }
+
+  const tiny = await napi.optimizeImage(input, 40, 8, null, "webp");
+  const b64 = Buffer.from(tiny).toString("base64");
+  return `data:image/webp;base64,${b64}`;
+}

package/src/components/Link.tsx

@@ -0,0 +1,64 @@
+import type { AnchorHTMLAttributes, MouseEvent } from "react";
+
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  href: string;
+  /** Prefetch the target page on hover (default: true). */
+  prefetch?: boolean;
+}
+
+declare global {
+  interface Window {
+    __alabjs_navigate?: (href: string) => Promise<void>;
+  }
+}
+
+/**
+ * Client-side navigation link for AlabJS.
+ *
+ * Intercepts same-origin clicks and swaps the page content without a full
+ * browser reload. Falls back to a standard `<a>` navigation when JavaScript
+ * is unavailable or when the user holds a modifier key (Cmd/Ctrl/Shift/Alt).
+ *
+ * On hover (with `prefetch`, default true), the target page is fetched in the
+ * background so the browser caches it before the user clicks.
+ */
+export function Link({ href, children, prefetch = true, onClick, ...rest }: LinkProps) {
+  const isSameOrigin = (url: string): boolean => {
+    if (url.startsWith("/")) return true;
+    try {
+      return new URL(url).origin === window.location.origin;
+    } catch {
+      return false;
+    }
+  };
+
+  const handleClick = async (e: MouseEvent<HTMLAnchorElement>) => {
+    // Let the browser handle modifier-key clicks (open in new tab etc.)
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    if (!isSameOrigin(href)) return;
+
+    e.preventDefault();
+    onClick?.(e);
+
+    if (typeof window.__alabjs_navigate === "function") {
+      await window.__alabjs_navigate(href);
+    } else {
+      window.location.href = href;
+    }
+  };
+
+  const handleMouseEnter = prefetch
+    ? () => {
+        if (typeof window.__alabjs_navigate === "function") {
+          // Fire-and-forget; browser caches the response automatically.
+          fetch(href, { priority: "low" } as RequestInit).catch(() => {});
+        }
+      }
+    : undefined;
+
+  return (
+    <a href={href} onClick={handleClick} onMouseEnter={handleMouseEnter} {...rest}>
+      {children}
+    </a>
+  );
+}