akanjs 0.0.1 → 2.0.0-beta.0

package/server/routeTreeBuilder.ts

@@ -0,0 +1,279 @@
+import type {
+  Head,
+  LayoutProps,
+  PageProps,
+  PageState,
+  PathRoute,
+  ResolveHead,
+  Route,
+  RouteModule,
+  RouteRender,
+} from "akanjs/client";
+import {
+  assertUniqueRoutePatterns,
+  compareRouteSpecificity,
+  matchRoutePattern,
+  parseBasePaths,
+  parseRouteModuleKey,
+  routeSegmentToTreePath,
+} from "akanjs/common";
+
+export type PagesContext = Record<string, () => Promise<RouteModule>>;
+
+export const defaultPageState: PageState = {
+  transition: "none",
+  topSafeArea: 0,
+  bottomSafeArea: 0,
+  topInset: 0,
+  bottomInset: 0,
+  gesture: true,
+  cache: false,
+  topSafeAreaColor: "transparent",
+  bottomSafeAreaColor: "transparent",
+};
+
+export interface RouteModuleCacheStats {
+  moduleCount: number;
+  loadedModuleCount: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheDisabled: boolean;
+  loadedModuleKeys: string[];
+}
+
+export class RouteTreeBuilder {
+  static readonly #pageRouteExports = new Set(["default", "pageConfig", "head", "generateHead", "Loading"]);
+  static readonly #rootLayoutExports = new Set([
+    "default",
+    "head",
+    "generateHead",
+    "fonts",
+    "manifest",
+    "theme",
+    "reconnect",
+    "layoutStyle",
+    "gaTrackingId",
+    "Loading",
+  ]);
+  static readonly #layoutRouteExports = new Set(["default", "head", "generateHead", "Loading"]);
+  static readonly #moduleCacheStats: RouteModuleCacheStats = {
+    moduleCount: 0,
+    loadedModuleCount: 0,
+    cacheHits: 0,
+    cacheMisses: 0,
+    cacheDisabled: process.env.AKAN_ROUTE_MODULE_CACHE === "0",
+    loadedModuleKeys: [],
+  };
+
+  readonly #context: PagesContext;
+  readonly #baseLayoutPaths: string[];
+  readonly #routeMap = new Map<string, Route>();
+  readonly #pagePatterns: { key: string; pattern: string }[] = [];
+
+  constructor(context: PagesContext) {
+    this.#context = context;
+    const basePaths = process.env.AKAN_PUBLIC_BASE_PATHS ? parseBasePaths(process.env.AKAN_PUBLIC_BASE_PATHS) : null;
+    this.#baseLayoutPaths = ["/", "/:lang", ...(basePaths?.map((bp) => `/:lang/${bp}`) ?? [])];
+    this.#routeMap.set("/", { path: "/", children: new Map() });
+  }
+
+  build(): PathRoute[] {
+    RouteTreeBuilder.resetCacheStats();
+    for (const [filePath, loader] of Object.entries(this.#context)) this.#addRouteModule(filePath, loader);
+    assertUniqueRoutePatterns(this.#pagePatterns);
+
+    const rootRoute = this.#routeMap.get("/");
+    if (!rootRoute) throw new Error("No root route");
+    return this.#getPathRoutes(rootRoute).sort((a, b) => compareRouteSpecificity(a.path, b.path));
+  }
+
+  static getCacheStats(): RouteModuleCacheStats {
+    return {
+      ...RouteTreeBuilder.#moduleCacheStats,
+      cacheDisabled: process.env.AKAN_ROUTE_MODULE_CACHE === "0",
+      loadedModuleKeys: [...RouteTreeBuilder.#moduleCacheStats.loadedModuleKeys],
+    };
+  }
+
+  static resetCacheStats() {
+    RouteTreeBuilder.#moduleCacheStats.moduleCount = 0;
+    RouteTreeBuilder.#moduleCacheStats.loadedModuleCount = 0;
+    RouteTreeBuilder.#moduleCacheStats.cacheHits = 0;
+    RouteTreeBuilder.#moduleCacheStats.cacheMisses = 0;
+    RouteTreeBuilder.#moduleCacheStats.cacheDisabled = process.env.AKAN_ROUTE_MODULE_CACHE === "0";
+    RouteTreeBuilder.#moduleCacheStats.loadedModuleKeys = [];
+  }
+
+  static match(
+    pathname: string,
+    pathRoutes: PathRoute[],
+  ): { pathRoute: PathRoute; params: Record<string, string> } | null {
+    for (const pathRoute of pathRoutes) {
+      const params = matchRoutePattern(pathRoute.path, pathname);
+      if (params) return { pathRoute, params };
+    }
+    return null;
+  }
+
+  static parseSearchParams(search: string): Record<string, string | string[]> {
+    const result: Record<string, string | string[]> = {};
+    const urlSearchParams = new URLSearchParams(search);
+    for (const [key, value] of urlSearchParams.entries()) {
+      const existing = result[key];
+      if (existing !== undefined) result[key] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+      else result[key] = value;
+    }
+    return result;
+  }
+
+  #addRouteModule(filePath: string, loader: () => Promise<RouteModule>) {
+    const parsed = parseRouteModuleKey(filePath);
+    if (parsed.kind === "page") this.#pagePatterns.push({ key: filePath, pattern: parsed.pattern });
+    const pathSegments = ["/", ...parsed.routeSegments.map(routeSegmentToTreePath)];
+
+    const targetRouteMap = pathSegments.slice(0, -1).reduce((rMap: Map<string, Route>, p: string) => {
+      if (!rMap.has(p)) rMap.set(p, { path: p, children: new Map() });
+      const children = rMap.get(p)?.children;
+      if (!children) throw new Error("No children");
+      return children;
+    }, this.#routeMap);
+    if (!targetRouteMap) return;
+
+    const targetPath = pathSegments[pathSegments.length - 1];
+    if (!targetPath) return;
+
+    const routeRender = RouteTreeBuilder.#makeRouteRender(filePath, parsed.kind, loader);
+    targetRouteMap.set(targetPath, {
+      ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
+      ...(parsed.kind === "layout"
+        ? { renderLayout: routeRender }
+        : {
+            renderPage: routeRender,
+            pageIncludesOwnLayout: parsed.leaf === "_index",
+            isSpecialRoute: parsed.isSpecialRoute,
+          }),
+    } as Route);
+  }
+
+  #getPathRoutes(
+    route: Route,
+    parentRootLayouts: RouteRender[] = [],
+    parentLayouts: RouteRender[] = [],
+    parentPaths: string[] = [],
+    parentHead?: ResolveHead,
+  ): PathRoute[] {
+    const parentPath = parentPaths.filter((p) => p !== "/").join("");
+    const currentPathSegment = /^\/\(.*\)$/.test(route.path) ? "" : route.path;
+    const isRoot = this.#baseLayoutPaths.includes(parentPath + currentPathSegment) && parentRootLayouts.length < 2;
+    const routePath = parentPath + currentPathSegment;
+    const pathSegments = [...parentPaths, ...(currentPathSegment ? [currentPathSegment] : [])];
+    const currentRootLayout = isRoot && route.renderLayout ? route.renderLayout : null;
+    const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
+    const renderRootLayouts = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
+    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
+    const routeHead = RouteTreeBuilder.#composeHeadResolvers(route.renderLayout?.resolveHead, parentHead);
+    const pageRenderRootLayouts =
+      route.pageIncludesOwnLayout === false && currentRootLayout ? parentRootLayouts : renderRootLayouts;
+    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
+    const pageHead = route.pageIncludesOwnLayout === false ? parentHead : routeHead;
+    return [
+      ...(route.renderPage
+        ? [
+            {
+              path: routePath,
+              pathSegments,
+              renderPage: route.renderPage,
+              renderRootLayouts: pageRenderRootLayouts,
+              renderLayouts: pageRenderLayouts,
+              resolveHead: RouteTreeBuilder.#composeHeadResolvers(route.renderPage.resolveHead, pageHead),
+              isSpecialRoute: route.isSpecialRoute,
+              pageState: route.pageState ?? defaultPageState,
+            },
+          ]
+        : []),
+      ...(route.children.size
+        ? [...route.children.values()].flatMap((child) =>
+            this.#getPathRoutes(child, renderRootLayouts, renderLayouts, pathSegments, routeHead),
+          )
+        : []),
+    ];
+  }
+
+  static #makeLazyModule(key: string, kind: "page" | "layout", loader: () => Promise<RouteModule>) {
+    let cached: RouteModule | null = null;
+    let loaded = false;
+    RouteTreeBuilder.#moduleCacheStats.moduleCount += 1;
+    return async () => {
+      if (cached && process.env.AKAN_ROUTE_MODULE_CACHE !== "0") {
+        RouteTreeBuilder.#moduleCacheStats.cacheHits += 1;
+        return cached;
+      }
+      RouteTreeBuilder.#moduleCacheStats.cacheMisses += 1;
+      const mod = await loader();
+      RouteTreeBuilder.#validateRouteModuleExports(key, kind, mod);
+      if (!loaded) {
+        RouteTreeBuilder.#moduleCacheStats.loadedModuleCount += 1;
+        RouteTreeBuilder.#moduleCacheStats.loadedModuleKeys.push(key);
+        loaded = true;
+      }
+      if (process.env.AKAN_ROUTE_MODULE_CACHE !== "0") cached = mod;
+      return mod;
+    };
+  }
+
+  static #validateRouteModuleExports(key: string, kind: "page" | "layout", mod: RouteModule) {
+    const parsed = parseRouteModuleKey(key);
+    const allowed =
+      kind === "page"
+        ? RouteTreeBuilder.#pageRouteExports
+        : parsed.isInternalRootLayout
+          ? RouteTreeBuilder.#rootLayoutExports
+          : RouteTreeBuilder.#layoutRouteExports;
+    for (const exportName of Object.keys(mod)) {
+      if (!allowed.has(exportName)) {
+        throw new Error(`[route-convention] unsupported export "${exportName}" in ${key}`);
+      }
+    }
+    if (!mod.default) throw new Error(`[route-convention] ${key} has no default export`);
+    if ("head" in mod && "generateHead" in mod) {
+      throw new Error(`[route-convention] head and generateHead cannot both be exported in ${key}`);
+    }
+  }
+
+  static #makeRouteRender(key: string, kind: "page" | "layout", loader: () => Promise<RouteModule>): RouteRender {
+    const loadModule = RouteTreeBuilder.#makeLazyModule(key, kind, loader);
+    const routeRender: RouteRender = {
+      render: async (props: LayoutProps | PageProps) => {
+        const mod = await loadModule();
+        routeRender.Loading = mod.Loading as never;
+        if (!mod.default) throw new Error(`[route-convention] ${key} has no default export`);
+        return mod.default(props as never);
+      },
+      resolveHead: async (props: PageProps) => {
+        const mod = await loadModule();
+        routeRender.Loading = mod.Loading as never;
+        if (mod.generateHead) return mod.generateHead(props);
+        return mod.head as Head | null | undefined;
+      },
+    };
+    if (kind === "page") {
+      routeRender.getPageConfig = async () => {
+        const mod = await loadModule();
+        return "pageConfig" in mod ? mod.pageConfig : undefined;
+      };
+    }
+    return routeRender;
+  }
+
+  static #composeHeadResolvers(...resolvers: (ResolveHead | undefined)[]): ResolveHead | undefined {
+    const chain = resolvers.filter((resolver): resolver is ResolveHead => Boolean(resolver));
+    if (chain.length === 0) return undefined;
+    return async (props) => {
+      for (const resolver of chain) {
+        const head = await resolver(props);
+        if (head !== null && head !== undefined) return head;
+      }
+      return undefined;
+    };
+  }
+}

package/server/routing/apiRouter.ts

@@ -0,0 +1,226 @@
+import { dayjs } from "akanjs/base";
+import type { Logger } from "akanjs/common";
+import type { InjectRegistry } from "akanjs/service";
+import { Exception, type WebsocketReqData } from "akanjs/signal";
+import type { HmrWsData, HmrWsHub } from "../hmr/wsHub";
+import { copyBunRequestFields, type WebProxyRunner } from "../proxy";
+import { SignalResolver } from "../resolver";
+import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types";
+
+/**
+ * Minimal render-state view the HMR WS hello message needs.
+ * `LazyHmrController` exposes this shape via `state.buildId` / `state.cssAssets`,
+ * so the ws handler can greet freshly-connected clients
+ * without reaching into the full controller.
+ */
+export interface HmrStateSource {
+  readonly state: {
+    buildId: number;
+    cssAssets?: Record<string, { cssUrl: string; cssRelPath: string }>;
+  };
+}
+
+export type NonNullHttpRoutes = NonNullable<HttpRoutes>;
+
+export interface ApiRouteInputs {
+  prefix: string;
+  websocketPrefix: string;
+  routes: HttpRoutes;
+  routeOptions?: Record<string, SignalRouteOptions>;
+  renderEnvRoutes: HttpRoutes;
+  /** Upgrades the incoming request into an app-signal WebSocket. */
+  upgradeAppWs: (req: Request, data: { createdAt: number }) => boolean;
+  webProxyRunner?: WebProxyRunner | null;
+}
+
+type RouteValue = NonNullHttpRoutes[keyof NonNullHttpRoutes];
+type RouteHandler = (req: Request) => Response | Promise<Response | undefined> | undefined;
+
+export interface WebsocketHandlersInputs {
+  wsRoutes: WebsocketRoutes;
+  registry: InjectRegistry;
+  hmrHub: HmrWsHub | null;
+  hmrState: HmrStateSource | null;
+  logger: Logger;
+}
+
+type WsTaggedData = { kind?: string };
+interface ExceptionLike {
+  statusCode: number;
+  toJSON(): object;
+}
+
+const isExceptionLike = (error: unknown): error is ExceptionLike => {
+  return (
+    error instanceof Exception ||
+    (error instanceof Error &&
+      "statusCode" in error &&
+      typeof (error as { statusCode?: unknown }).statusCode === "number" &&
+      typeof (error as { toJSON?: unknown }).toJSON === "function")
+  );
+};
+
+export class ApiRouter {
+  /**
+   * Builds the full route table served by `Bun.serve`. Responsibilities:
+   *   1. Expose the WS upgrade endpoint at `<prefix><websocketPrefix>`.
+   *   2. Prefix every endpoint-generated route with `prefix`.
+   *   3. Merge render-env routes (CSR/SSR) last so they can catch-all `/*`.
+   */
+  static buildRoutes({
+    prefix,
+    websocketPrefix,
+    routes,
+    routeOptions,
+    renderEnvRoutes,
+    upgradeAppWs,
+    webProxyRunner,
+  }: ApiRouteInputs): NonNullHttpRoutes {
+    const endpointEntries = Object.entries(routes ?? {}).map(
+      ([p, handler]) => [ApiRouter.#applyGlobalPrefix(prefix, p, routeOptions?.[p]), handler] as const,
+    );
+    const endpointPaths = new Set(endpointEntries.map(([path]) => path));
+    const routeTable = {
+      [`${prefix}${websocketPrefix}` as "/api/ws"]: (req) => {
+        const upgraded = upgradeAppWs(req, { createdAt: Date.now() });
+        if (upgraded) return;
+        return new Response("Failed to upgrade to WebSocket", { status: 500 });
+      },
+      ...Object.fromEntries(endpointEntries),
+      ...(renderEnvRoutes ?? {}),
+    } as NonNullHttpRoutes;
+    return webProxyRunner
+      ? ApiRouter.#wrapRoutesWithWebProxy(routeTable, webProxyRunner, prefix, endpointPaths)
+      : routeTable;
+  }
+
+  /**
+   * Builds the `websocket` handler config for `Bun.serve`. Multiplexes two
+   * logical channels on the same upgrade port:
+   *   - `kind === "akan-hmr"` — dev HMR, delegated to `HmrWsHub`.
+   *   - everything else — app signal channel, dispatched via `wsRoutes`.
+   */
+  static buildWebsocketHandlers({
+    wsRoutes,
+    registry,
+    hmrHub,
+    hmrState,
+    logger,
+  }: WebsocketHandlersInputs): Bun.WebSocketHandler<WsTaggedData> {
+    return {
+      open: (ws) => {
+
+        const data = ws.data as WsTaggedData | undefined;
+        if (data?.kind === "akan-hmr" && hmrHub && hmrState) {
+          hmrHub.attach(ws as unknown as Bun.ServerWebSocket<HmrWsData>);
+          ws.send(
+            JSON.stringify({
+              type: "hello",
+              buildId: hmrState.state.buildId,
+              cssAssets: hmrState.state.cssAssets,
+            }),
+          );
+          return;
+        }
+        SignalResolver.handleWsOpen(ws, registry);
+      },
+      message: async (ws, message) => {
+        const data = ws.data as WsTaggedData | undefined;
+        if (data?.kind === "akan-hmr") return; 
+        try {
+          if (typeof message === "string") {
+            const msg = JSON.parse(message) as WebsocketReqData;
+            if (!msg.key) throw new Error("Message key is required");
+            const wsRoute = wsRoutes[msg.key];
+            if (!wsRoute) throw new Error(`WebSocket route "${msg.key}" is not registered`);
+            const eventType =
+              typeof msg.subscribe === "boolean" ? (msg.subscribe ? "subscribe" : "unsubscribe") : "message";
+            const result = await wsRoute(ws, msg.data, eventType);
+            ws.send(JSON.stringify(result));
+          } else throw new Error("Message is not a string");
+        } catch (error) {
+          if (isExceptionLike(error)) {
+            ws.send(JSON.stringify({ ...error.toJSON(), timestamp: new Date().toISOString() }));
+            return;
+          }
+          const errMsg = error instanceof Error ? error.message : String(error);
+          logger.error(errMsg);
+          console.error(error);
+          ws.send(JSON.stringify({ error: errMsg, statusCode: 500, timestamp: new Date().toISOString(), at: dayjs() }));
+        }
+      },
+      close: (ws) => {
+        const data = ws.data as WsTaggedData | undefined;
+        if (data?.kind === "akan-hmr" && hmrHub) {
+          hmrHub.detach(ws as unknown as Bun.ServerWebSocket<HmrWsData>);
+          return;
+        }
+        SignalResolver.handleWsClose(ws, registry);
+      },
+    };
+  }
+
+  static #applyGlobalPrefix(prefix: string, path: string, options?: SignalRouteOptions): string {
+    if (options?.globalPrefix === false) return ApiRouter.#normalizeRoutePath(path);
+    return ApiRouter.#joinRoutePath(prefix, path);
+  }
+
+  static #joinRoutePath(prefix: string, path: string): string {
+    const normalizedPrefix = ApiRouter.#normalizeRoutePath(prefix).replace(/\/$/, "");
+    const normalizedPath = ApiRouter.#normalizeRoutePath(path);
+    if (normalizedPrefix === "/") return normalizedPath;
+    if (normalizedPath === "/") return normalizedPrefix;
+    return `${normalizedPrefix}${normalizedPath}`;
+  }
+
+  static #normalizeRoutePath(path: string): string {
+    const trimmed = path.trim();
+    if (!trimmed || trimmed === "/") return "/";
+    return `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+  }
+
+  static #wrapRoutesWithWebProxy(
+    routes: NonNullHttpRoutes,
+    runner: WebProxyRunner,
+    apiPrefix: string,
+    endpointPaths: Set<string>,
+  ): NonNullHttpRoutes {
+    return Object.fromEntries(
+      Object.entries(routes).map(([path, route]) => [
+        path,
+        endpointPaths.has(path) || ApiRouter.#isApiRoute(path, apiPrefix) || ApiRouter.#isInternalRenderRoute(path)
+          ? route
+          : ApiRouter.#wrapRoute(route, runner),
+      ]),
+    ) as NonNullHttpRoutes;
+  }
+
+  static #isApiRoute(path: string, apiPrefix: string): boolean {
+    const normalized = apiPrefix.replace(/\/$/, "");
+    return path === normalized || path.startsWith(`${normalized}/`);
+  }
+
+  static #isInternalRenderRoute(path: string): boolean {
+    return path === "/__csr" || path === "/__rsc" || path.startsWith("/__rsc/") || path.startsWith("/_akan/");
+  }
+
+  static #wrapRoute(route: RouteValue, runner: WebProxyRunner): RouteValue {
+    if (typeof route === "function") return ApiRouter.#wrapHandler(route as RouteHandler, runner) as RouteValue;
+    if (route instanceof Response) return ApiRouter.#wrapHandler(() => route, runner) as RouteValue;
+    if (!route || typeof route !== "object") return route;
+    return Object.fromEntries(
+      Object.entries(route).map(([method, handler]) => [
+        method,
+        typeof handler === "function" ? ApiRouter.#wrapHandler(handler as RouteHandler, runner) : handler,
+      ]),
+    ) as RouteValue;
+  }
+
+  static #wrapHandler(handler: RouteHandler, runner: WebProxyRunner): RouteHandler {
+    return async (req) => {
+      const result = await runner.run(req);
+      if (result.response) return result.response;
+      return await handler(copyBunRequestFields(result.request, req));
+    };
+  }
+}

package/server/rscClient.tsx

@@ -0,0 +1,140 @@
+import { createElement, type ReactNode, startTransition, use, useLayoutEffect, useState } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+
+declare global {
+  var __RSC_CHUNKS__: string[] | undefined;
+  var __RSC_CLOSED__: boolean | undefined;
+  var __RSC_PUSH__: ((b64: string) => void) | undefined;
+  var __RSC_CLOSE__: (() => void) | undefined;
+  var __AKAN_RSC_NAVIGATE__:
+    | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void>)
+    | undefined;
+  var __AKAN_RSC_REFRESH__: ((options?: { buildId?: number }) => Promise<void>) | undefined;
+  var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+}
+
+function decodeBase64(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+type RscThenable = Promise<ReactNode>;
+type RscFetchResult = { type: "rsc"; thenable: RscThenable } | { type: "redirected" };
+const MAX_RSC_CACHE_ENTRIES = 32;
+
+function createInitialRscStream(): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      const queued = globalThis.__RSC_CHUNKS__ ?? [];
+      for (const b64 of queued) controller.enqueue(decodeBase64(b64));
+      globalThis.__RSC_CHUNKS__ = [];
+
+      if (globalThis.__RSC_CLOSED__) {
+        controller.close();
+        return;
+      }
+
+      globalThis.__RSC_PUSH__ = (b64: string) => controller.enqueue(decodeBase64(b64));
+      globalThis.__RSC_CLOSE__ = () => controller.close();
+    },
+  });
+}
+
+function normalizeHref(href: string): string {
+  return new URL(href, window.location.origin).href;
+}
+
+function createRscThenable(stream: ReadableStream<Uint8Array>): RscThenable {
+  return createFromReadableStream<ReactNode>(stream) as RscThenable;
+}
+
+async function fetchRsc(href: string, options: { buildId?: number } = {}): Promise<RscFetchResult> {
+  const endpoint = new URL("/__rsc", window.location.origin);
+  endpoint.searchParams.set("url", href);
+  if (options.buildId !== undefined) endpoint.searchParams.set("buildId", String(options.buildId));
+  const res = await fetch(endpoint, {
+    headers: { Accept: "text/x-component", "Cache-Control": "no-cache" },
+    credentials: "same-origin",
+    cache: "no-store",
+  });
+  const redirect = res.headers.get("X-Akan-Redirect");
+  if (redirect) {
+    const method = res.headers.get("X-Akan-Redirect-Method");
+    await globalThis.__AKAN_RSC_NAVIGATE__?.(redirect, { replace: method !== "push", scrollToTop: true });
+    return { type: "redirected" };
+  }
+  if (!res.ok || !res.body) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
+  return { type: "rsc", thenable: createRscThenable(res.body) };
+}
+
+const rscCache = new Map<string, RscThenable>();
+const initialThenable = createRscThenable(createInitialRscStream());
+rscCache.set(normalizeHref(window.location.href), initialThenable);
+
+function rememberRsc(href: string, thenable: RscThenable): void {
+  rscCache.delete(href);
+  rscCache.set(href, thenable);
+  while (rscCache.size > MAX_RSC_CACHE_ENTRIES) {
+    const oldest = rscCache.keys().next().value;
+    if (!oldest) break;
+    rscCache.delete(oldest);
+  }
+}
+
+function Root(): ReactNode {
+  const [thenable, setThenable] = useState<RscThenable>(initialThenable);
+  const [scrollToTopTick, setScrollToTopTick] = useState(0);
+
+  useLayoutEffect(() => {
+    if (!scrollToTopTick) return;
+    window.scrollTo(0, 0);
+  }, [scrollToTopTick]);
+
+  globalThis.__AKAN_RSC_CLEAR_CACHE__ = () => {
+    rscCache.clear();
+    rscCache.set(normalizeHref(window.location.href), thenable);
+  };
+
+  globalThis.__AKAN_RSC_REFRESH__ = async (options = {}) => {
+    const target = normalizeHref(window.location.href);
+    rscCache.delete(target);
+    const next = await fetchRsc(target, options);
+    if (next.type === "redirected") return;
+    rememberRsc(target, next.thenable);
+    startTransition(() => {
+      setThenable(next.thenable);
+    });
+  };
+
+  globalThis.__AKAN_RSC_NAVIGATE__ = async (href, options = {}) => {
+    const target = normalizeHref(href);
+    const scrollToTop = options.scrollToTop ?? true;
+    let next = rscCache.get(target);
+    if (!next) {
+      const fetched = await fetchRsc(target);
+      if (fetched.type === "redirected") return;
+      next = fetched.thenable;
+      rememberRsc(target, next);
+    } else {
+      rememberRsc(target, next);
+    }
+    startTransition(() => {
+      setThenable(next as RscThenable);
+      if (options.replace) window.history.replaceState(null, "", target);
+      else window.history.pushState(null, "", target);
+      if (scrollToTop) setScrollToTopTick((tick) => tick + 1);
+    });
+  };
+
+  return use(thenable);
+}
+
+window.addEventListener("popstate", () => {
+  void globalThis.__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false });
+});
+
+const hydrate = () => hydrateRoot(document, createElement(Root));
+void Promise.resolve(initialThenable).then(hydrate, hydrate);