akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/routeTreeBuilder.ts

@@ -26,7 +26,7 @@ import {
   type RouteModuleSource,
   resolveRouteModule,
 } from "../client/route/resolveRouteModule";
-import { resolveHeadExport, resolveMetadataHead } from "./metadata";
+import { matchRoutePrefix } from "../common/routeConvention";
 
 type RouteModuleKindWithOverrides = "page" | "layout" | "overrides";
 
@@ -116,7 +116,7 @@ export class RouteTreeBuilder {
     const candidates = fallbackRoutes
       .map((fallbackRoute) => ({
         fallbackRoute,
-        params: RouteTreeBuilder.#matchRoutePrefix(fallbackRoute.path, pathname),
+        params: matchRoutePrefix(fallbackRoute.path, pathname),
       }))
       .filter((entry): entry is { fallbackRoute: LayoutFallbackRoute; params: Record<string, string> } =>
         Boolean(entry.params),
@@ -153,7 +153,6 @@ export class RouteTreeBuilder {
       if (!children) throw new Error("No children");
       return children;
     }, this.#routeMap);
-    if (!targetRouteMap) return;
 
     const targetPath = pathSegments[pathSegments.length - 1];
     if (!targetPath) return;
@@ -261,10 +260,6 @@ export class RouteTreeBuilder {
     };
   }
 
-  /**
-   * A `page()` / `layout()` chain is unfolded into the named-export shape the rest of this file reads. The legacy
-   * shape still loads, and is named once per module so an app finds every file the migration guide covers.
-   */
   static #resolveModule(key: string, kind: RouteModuleKindWithOverrides, mod: RouteModuleSource): ResolvedRouteModule {
     if (kind === "overrides") return { module: mod as RouteModule };
     const parsed = parseRouteModuleKey(key);
@@ -280,7 +275,6 @@ export class RouteTreeBuilder {
 
   static #validateRouteModuleExports(key: string, kind: RouteModuleKindWithOverrides, mod: RouteModule) {
     if (kind === "overrides") {
-      
       if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
       return;
     }
@@ -295,22 +289,25 @@ export class RouteTreeBuilder {
     if ("head" in mod && "generateHead" in mod) {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${key}`);
     }
-    if (
-      !parsed.isInternalRootLayout &&
-      ("head" in mod || "generateHead" in mod) &&
-      ("metadata" in mod || "generateMetadata" in mod)
-    ) {
-      throw new Error(
-        `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${key}`,
-      );
-    }
-    if ("metadata" in mod && "generateMetadata" in mod) {
-      throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${key}`);
-    }
   }
 
   static #makeRouteRender(key: string, kind: "page" | "layout", loader: () => Promise<RouteModuleSource>): RouteRender {
     const loadModule = RouteTreeBuilder.#makeLazyModule(key, kind, loader);
+    const syncFallbacks = (mod: LayoutModule) => {
+      routeRender.NotFound = mod.NotFound;
+      routeRender.Error = mod.Error;
+      return mod;
+    };
+    const loadSynced = async () => {
+      const { module: mod } = await loadModule();
+      routeRender.Loading = mod.Loading as never;
+      if (kind === "layout") syncFallbacks(mod as LayoutModule);
+      return mod;
+    };
+    const pageConfigOf = async () => {
+      const { module: mod } = await loadModule();
+      return "pageConfig" in mod ? mod.pageConfig : undefined;
+    };
     const routeRender: RouteRender = {
       isAsync: true,
       resolveLoading: async () => {
@@ -318,60 +315,22 @@ export class RouteTreeBuilder {
         routeRender.Loading = mod.Loading as never;
       },
       render: async (props: LayoutProps | PageProps) => {
-        const { module: mod } = await loadModule();
-        routeRender.Loading = mod.Loading as never;
-        if (kind === "layout") {
-          const layoutMod = mod as LayoutModule;
-          routeRender.NotFound = layoutMod.NotFound;
-          routeRender.Error = layoutMod.Error;
-        }
+        const mod = await loadSynced();
         if (!mod.default) throw new Error(`[route-convention] ${key} has no default export`);
         return mod.default(props as never);
       },
       resolveHead: async (props: PageProps) => {
-        const { module: mod } = await loadModule();
-        routeRender.Loading = mod.Loading as never;
-        if (kind === "layout") {
-          const layoutMod = mod as LayoutModule;
-          routeRender.NotFound = layoutMod.NotFound;
-          routeRender.Error = layoutMod.Error;
-        }
-        if (mod.generateHead) {
-          const head = await mod.generateHead(props);
-          if (head !== null && head !== undefined) return resolveHeadExport(head, { includeHeadSnapshot: false });
-        }
-        if (mod.generateMetadata) {
-          const metadata = await mod.generateMetadata(props);
-          return metadata === null || metadata === undefined ? metadata : resolveMetadataHead(metadata);
-        }
-        if (mod.head !== undefined)
-          return mod.head === null ? null : resolveHeadExport(mod.head, { includeHeadSnapshot: false });
-        return mod.metadata === undefined ? undefined : resolveMetadataHead(mod.metadata);
+        const mod = await loadSynced();
+        return mod.generateHead ? await mod.generateHead(props) : mod.head;
       },
     };
     if (kind === "page") {
-      routeRender.getPageConfig = async () => {
-        const { module: mod } = await loadModule();
-        return "pageConfig" in mod ? mod.pageConfig : undefined;
-      };
+      routeRender.getPageConfig = pageConfigOf;
       routeRender.getRouteDefinition = async () => (await loadModule()).definition;
     } else {
-      routeRender.getLayoutPageConfig = async () => {
-        const { module: mod } = await loadModule();
-        return "pageConfig" in mod ? mod.pageConfig : undefined;
-      };
-      routeRender.resolveNotFound = async () => {
-        const mod = (await loadModule()).module as LayoutModule;
-        routeRender.NotFound = mod.NotFound;
-        routeRender.Error = mod.Error;
-        return mod.NotFound;
-      };
-      routeRender.resolveError = async () => {
-        const mod = (await loadModule()).module as LayoutModule;
-        routeRender.NotFound = mod.NotFound;
-        routeRender.Error = mod.Error;
-        return mod.Error;
-      };
+      routeRender.getLayoutPageConfig = pageConfigOf;
+      routeRender.resolveNotFound = async () => syncFallbacks((await loadModule()).module as LayoutModule).NotFound;
+      routeRender.resolveError = async () => syncFallbacks((await loadModule()).module as LayoutModule).Error;
     }
     return routeRender;
   }
@@ -399,22 +358,4 @@ export class RouteTreeBuilder {
       return undefined;
     };
   }
-
-  static #matchRoutePrefix(pattern: string, pathname: string): Record<string, string> | null {
-    const patternParts = pattern.split("/").filter(Boolean);
-    const pathParts = pathname.split("/").filter(Boolean);
-    if (patternParts.length > pathParts.length) return null;
-    const params: Record<string, string> = {};
-    for (let index = 0; index < patternParts.length; index++) {
-      const patternPart = patternParts[index];
-      const pathPart = pathParts[index];
-      if (!patternPart || !pathPart) return null;
-      if (patternPart.startsWith(":")) {
-        params[patternPart.slice(1)] = decodeURIComponent(pathPart);
-        continue;
-      }
-      if (patternPart !== pathPart) return null;
-    }
-    return params;
-  }
 }

package/server/routing/apiRouter.ts

@@ -1,5 +1,5 @@
 import { dayjs } from "akanjs/base";
-import { type Logger, websocketAuthContract } from "akanjs/common";
+import { type Logger, websocketAuthContract, websocketHeartbeatContract } from "akanjs/common";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
 import { isExceptionLike, SignalContext, SignalFailure, type WebsocketReqData } from "akanjs/signal";
 import { compressResponse } from "../contentEncoding";
@@ -9,12 +9,6 @@ import { SignalResolver } from "../resolver";
 import type { HttpRoutes, SignalRouteOptions, WebsocketRoutes } from "../types";
 import { AppWsData } from "./appWsData";
 
-/**
- * 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;
@@ -31,7 +25,6 @@ export interface ApiRouteInputs {
   builtinRoutes?: HttpRoutes;
   routeOptions?: Record<string, SignalRouteOptions>;
   renderEnvRoutes: HttpRoutes;
-  /** Upgrades the incoming request into an app-signal WebSocket. */
   upgradeAppWs: (req: Request, data: AppWsData) => boolean;
   webProxyRunner?: WebProxyRunner | null;
 }
@@ -42,7 +35,6 @@ type RouteHandler = (req: Request) => Response | Promise<Response | undefined> |
 export interface WebsocketHandlersInputs {
   wsRoutes: WebsocketRoutes;
   registry: InjectRegistry;
-  /** Only live rooms need it — a room is released from the routing table when its last socket goes. */
   live?: LiveRegistry;
   hmrHub: HmrWsHub | null;
   hmrState: HmrStateSource | null;
@@ -53,12 +45,7 @@ export interface WebsocketHandlersInputs {
 type WsTaggedData = { kind?: string };
 
 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,
@@ -71,7 +58,7 @@ export class ApiRouter {
   }: ApiRouteInputs): NonNullHttpRoutes {
     const endpointEntries = Object.entries(routes ?? {}).map(
       ([p, handler]) =>
-        [ApiRouter.#applyGlobalPrefix(prefix, p, routeOptions?.[p]), ApiRouter.#compressRoute(handler)] as const,
+        [ApiRouter.applyGlobalPrefix(prefix, p, routeOptions?.[p]), ApiRouter.#compressRoute(handler)] as const,
     );
     const builtinEntries = Object.entries(builtinRoutes ?? {}).map(
       ([path, handler]) => [path, ApiRouter.#compressRoute(handler)] as const,
@@ -92,12 +79,6 @@ export class ApiRouter {
       : 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,
@@ -111,7 +92,7 @@ export class ApiRouter {
       
       drain: () => onDrain?.(),
       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>);
@@ -137,12 +118,16 @@ export class ApiRouter {
             const msg = JSON.parse(message) as WebsocketReqData;
             if (!msg.key) throw new Error("Message key is required");
             if (msg.key === websocketAuthContract.key) {
-
+              
               AppWsData.applyCredential(AppWsData.of(ws), websocketAuthContract.readJwt(msg.data));
               const revokedRooms = await SignalResolver.revalidateWsRooms(ws, registry, live);
               ws.send(JSON.stringify(websocketAuthContract.makeAck(revokedRooms)));
               return;
             }
+            if (msg.key === websocketHeartbeatContract.key) {
+              ws.send(JSON.stringify(websocketHeartbeatContract.makeAck()));
+              return;
+            }
             const wsRoute = wsRoutes[msg.key];
             if (!wsRoute) throw new Error(`WebSocket route "${msg.key}" is not registered`);
             const eventType =
@@ -173,12 +158,12 @@ export class ApiRouter {
     };
   }
 
-  static #applyGlobalPrefix(prefix: string, path: string, options?: SignalRouteOptions): string {
+  static applyGlobalPrefix(prefix: string, path: string, options?: SignalRouteOptions): string {
     if (options?.globalPrefix === false) return ApiRouter.#normalizeRoutePath(path);
-    return ApiRouter.#joinRoutePath(prefix, path);
+    return ApiRouter.joinRoutePath(prefix, path);
   }
 
-  static #joinRoutePath(prefix: string, path: string): string {
+  static joinRoutePath(prefix: string, path: string): string {
     const normalizedPrefix = ApiRouter.#normalizeRoutePath(prefix).replace(/\/$/, "");
     const normalizedPath = ApiRouter.#normalizeRoutePath(path);
     if (normalizedPrefix === "/") return normalizedPath;
@@ -203,7 +188,11 @@ export class ApiRouter {
         path,
         endpointPaths.has(path) || ApiRouter.#isApiRoute(path, apiPrefix) || ApiRouter.#isInternalRenderRoute(path)
           ? route
-          : ApiRouter.#wrapRoute(route, runner),
+          : ApiRouter.#mapRoute(route, (handler) => async (req) => {
+              const result = await runner.run(req);
+              if (result.response) return result.response;
+              return await handler(copyBunRequestFields(result.request, req));
+            }),
       ]),
     ) as NonNullHttpRoutes;
   }
@@ -217,27 +206,6 @@ export class ApiRouter {
     return path === "/__csr" || path === "/__rsc" || path.startsWith("/__rsc/") || path.startsWith("/_akan/");
   }
 
-  static #wrapRoute(route: RouteValue, runner: WebProxyRunner): RouteValue {
-    return ApiRouter.#mapRoute(route, (handler) => ApiRouter.#wrapHandler(handler, runner));
-  }
-
-  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));
-    };
-  }
-
-  /**
-   * Signal endpoints answer with a fully-built JSON body, so this is the one place every model response passes
-   * through with the request still in hand. The web routes are deliberately left out: their bodies stream, and
-   * `compressResponse` buffers.
-   *
-   * Behind the gateway this finds `Accept-Encoding: identity` and does nothing — the gateway asks for an
-   * identity body because Bun's `fetch` decodes any `Content-Encoding` it is handed, so a child that
-   * compressed here would only be paying to have the gateway undo it. The gateway compresses instead.
-   */
   static #compressRoute(route: RouteValue): RouteValue {
     return ApiRouter.#mapRoute(route, (handler) => async (req) => {
       const response = await handler(req);

package/server/routing/appWsData.ts

@@ -8,16 +8,10 @@ import {
 
 const CREDENTIAL_HEADERS = ["authorization", "cookie", "user-agent"] as const;
 
-/**
- * Credential snapshot taken at the websocket handshake and carried on `ws.data` for the life of the
- * socket, so auth middleware and guards can read the caller the same way they read an HTTP request.
- * Only the credential headers are copied — retaining the whole `Request` would pin it for as long
- * as the socket stays open.
- */
 export class AppWsData {
   static fromRequest(req: Request): AppWsData {
     const headers = new Headers();
-
+    
     for (const key of [...CREDENTIAL_HEADERS, ...forwardedHeaders]) {
       const value = req.headers.get(key);
       if (value) headers.set(key, value);
@@ -27,16 +21,11 @@ export class AppWsData {
   static of(ws: Bun.ServerWebSocket<unknown>): AppWsData {
     return ws.data as AppWsData;
   }
-  /**
-   * Swaps the credential the socket authenticates with. Callers must run this synchronously on the
-   * auth frame: frames arrive in order, so a subscribe sent right after the credential must not be
-   * able to observe the previous one.
-   */
   static applyCredential(data: AppWsData, jwt: string | null) {
     if (jwt) data.headers.set("authorization", `Bearer ${jwt}`);
     else {
       data.headers.delete("authorization");
-
+      
       for (const name of [...data.cookies].map(([name]) => name)) {
         if (isAuthTokenKey(name)) data.cookies.delete(name);
       }
@@ -50,28 +39,15 @@ export class AppWsData {
   headers: Headers;
   cookies: Bun.CookieMap;
   account?: unknown;
-  /**
-   * Identity of this connection, minted here so every app socket carries one from its first frame and
-   * adaptors and endpoints only ever read it. Per-connection and process-local — a reconnect gets a new
-   * one, and the federation gateway's own socket is a different one — so it is never a caller identity.
-   * It outlives a credential swap on purpose: the socket is still the same socket.
-   */
+  
   socketId: string;
-  /**
-   * The caller's address as the nearest proxy recorded it, or null when nothing did.
-   *
-   * The handshake headers alone cannot say whether a proxy wrote them or the client did, so this trusts them —
-   * a socket that reached a child came through the gateway, which already resolved the question. `ipOf` is what
-   * an endpoint should read: it has the peer, so it can decide.
-   */
+
   get ip(): string | null {
     return clientAddressFromHeaders(this.headers);
   }
-  /** The caller's source port as the nearest proxy recorded it, or null when nothing did. */
   get port(): number | null {
     return clientPortFromHeaders(this.headers);
   }
-  /** The address to answer on: what a proxy recorded, else this socket's own peer. */
   ipOf(ws: Bun.ServerWebSocket<unknown>): string | null {
     return TrustedProxy.clientAddress(this.headers, ws.remoteAddress);
   }

package/server/routing/soloAppRoutes.ts

@@ -1,4 +1,6 @@
 import type { AkanChildRole, AkanMetricsReport } from "akanjs/service";
+import { AppInfo } from "../ops/appInfo";
+import type { OpsRoute } from "../ops/opsRoute";
 import type { HttpRoutes } from "../types";
 
 export interface SoloAppStatus {
@@ -9,14 +11,10 @@ export interface SoloAppStatus {
   metrics: AkanMetricsReport;
 }
 
-/**
- * The gateway's `/_akan/app/*` surface, answered by a process nothing is proxying. The payload keeps the
- * gateway's own shape — a `children` array with this process as its only entry — so a probe, a k8s check and
- * `akan` tooling read one contract whether or not a gateway is in front.
- */
 export const createSoloAppRoutes = (
   read: () => SoloAppStatus,
   logStream: { handle(req: Request): Response } | null = null,
+  ops: OpsRoute | null = null,
 ): HttpRoutes => {
   const child = () => {
     const { role, running, status, port } = read();
@@ -44,7 +42,9 @@ export const createSoloAppRoutes = (
           children: [{ ...child(), metrics: read().metrics }],
         }),
     },
+    [AppInfo.publicPath]: { GET: () => AppInfo.handlePublic() },
     "/_akan/bench/ping": { GET: () => new Response("ok") },
     ...(logStream ? { "/_akan/app/logs": { GET: (req: Request) => logStream.handle(req) } } : {}),
+    ...(ops ? { "/_akan/ops/*": (req: Request) => ops.handle(req) } : {}),
   };
 };

package/server/rscClient.tsx

@@ -1,11 +1,13 @@
 import { createElement, type ReactNode, startTransition, type Usable, use, useLayoutEffect, useState } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+import type {} from "../client/rscNavigation";
 import {
   type AkanHeadSnapshotV1,
   type AkanRouterStateV1,
   type AkanRscPatchMetadata,
   decodeAkanRouterState,
+  isAkanRscPartialCommitEnabled,
   readAkanRouterStateResponseHeader,
 } from "./routeState";
 import { fetchRscNavigationResponse } from "./rscClientFetch";
@@ -28,10 +30,8 @@ import {
   type RscNavigationCacheNode,
   type RscPatchNavigationCacheNode,
   rememberRscCacheNode,
-  rememberRscPatchCacheNode,
   resolveCachedRscPatchNavigation,
 } from "./rscNavigationState";
-import { isAkanRscPartialCommitEnabled } from "./rscPartialCommit";
 import { commitAkanSegmentOutletPatch, resetAkanSegmentOutletPatches } from "./rscSegmentOutlet";
 
 type InlineRscChunk = [1, string] | [3, string];
@@ -42,29 +42,17 @@ declare global {
   var __RSC_PUSH__: ((type: InlineRscChunk[0], data: string) => void) | undefined;
   var __RSC_CLOSE__: (() => void) | undefined;
   var __AKAN_RSC_INITIAL_STATE__: string | 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;
-  var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
-  var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
-  var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
-  var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
 }
 
-function decodeBase64(b64: string): Uint8Array {
-  const binary = atob(b64);
+function decodeInlineRscChunk([type, data]: InlineRscChunk): Uint8Array {
+  if (type === 1) return new TextEncoder().encode(data);
+  const binary = atob(data);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
   return bytes;
 }
 
-function decodeInlineRscChunk([type, data]: InlineRscChunk): Uint8Array {
-  if (type === 1) return new TextEncoder().encode(data);
-  return decodeBase64(data);
-}
-
 type RscThenable = Promise<ReactNode> & {
   status?: "pending" | "fulfilled" | "rejected";
   value?: ReactNode;
@@ -82,6 +70,7 @@ type RscFetchResult =
       outletKey: string;
       headSnapshot: AkanHeadSnapshotV1;
     }
+  | { type: "not-found" }
   | { type: "redirected"; status?: number };
 const MAX_RSC_CACHE_ENTRIES = 32;
 let documentNavigationFallbackInFlight = false;
@@ -93,6 +82,13 @@ class RscRedirectNavigationStarted extends Error {
   }
 }
 
+class RscRouteNotFound extends Error {
+  constructor(readonly href: string) {
+    super(`[rscClient] no route at ${href}`);
+    this.name = "RscRouteNotFound";
+  }
+}
+
 function createInitialRscStream(): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
     start(controller) {
@@ -115,17 +111,6 @@ function normalizeHref(href: string): string {
   return new URL(href, window.location.origin).href;
 }
 
-/**
- * Mirror React's thenable protocol (status/value/reason) onto the Flight thenable.
- *
- * Without this, `use(thenable)` cannot tell an already-resolved native Promise apart
- * from a pending one: it suspends the root transition once and relies on React's
- * ping -> retry -> re-commit path. That path intermittently lost the re-commit when
- * sync store updates raced the suspended transition, leaving the previous page DOM
- * visible even though the navigation pipeline completed. With the status tracked,
- * `use()` returns the fulfilled payload synchronously and the committed transition
- * renders the new tree in a single pass.
- */
 function trackRscThenable(thenable: RscThenable): RscThenable {
   if (thenable.status !== undefined) return thenable;
   thenable.status = "pending";
@@ -189,9 +174,7 @@ function commitRscPatchNavigation({
   startTransition(() => {
     try {
       headApplied = commitPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
-      if (!headApplied) {
-        return;
-      }
+      if (!headApplied) return;
       outletCommitted = commitAkanSegmentOutletPatch(patch.outletKey, patchThenable);
       if (!outletCommitted) {
         rollbackPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
@@ -228,7 +211,7 @@ async function fetchRsc(
     sendRouterState: options.sendRouterState,
     shouldApplyNavigation,
   });
-  if (responseResult.type === "redirected") return responseResult;
+  if (responseResult.type === "redirected" || responseResult.type === "not-found") return responseResult;
   if (responseResult.type === "patch") {
     const patchResult = await validateRscPatchForGuardedCommit({
       partialCommitEnabled: isAkanRscPartialCommitEnabled(),
@@ -364,6 +347,10 @@ function Root(): ReactNode {
         shouldApplyNavigation: () => navId === navigationSeq,
       });
       if (next.type === "redirected") return;
+      if (next.type === "not-found") {
+        console.warn(`[rscClient] refresh target ${target} no longer resolves; keeping the current page`);
+        return;
+      }
       if (next.type === "patched") return;
       observeRscNavigationNode({
         cache: rscCache,
@@ -373,7 +360,7 @@ function Root(): ReactNode {
         isExpectedNavigationError: (error) => error instanceof RscRedirectNavigationStarted,
         onLatestError: (error) => hardNavigateAfterRscFailure(target, true, error),
       });
-
+      
       await next.node.thenable;
       const committed = commitLatestRscNavigation({
         cache: rscCache,
@@ -433,7 +420,7 @@ function Root(): ReactNode {
             ) {
               currentCommitFromCache = true;
               rememberPatchedRouteState(patchResult.tree, patchResult.patchedNode);
-              rememberRscPatchCacheNode(rscPatchCache, cachedPatch, MAX_RSC_CACHE_ENTRIES);
+              rememberRscCacheNode(rscPatchCache, cachedPatch, MAX_RSC_CACHE_ENTRIES);
               return;
             }
           }
@@ -445,6 +432,7 @@ function Root(): ReactNode {
           shouldApplyNavigation: () => navId === navigationSeq,
         });
         if (fetched.type === "redirected") return;
+        if (fetched.type === "not-found") throw new RscRouteNotFound(target);
         if (fetched.type === "patched") {
           if (navId !== navigationSeq) return;
           if (
@@ -465,7 +453,7 @@ function Root(): ReactNode {
               outletKey: fetched.outletKey,
               headSnapshot: fetched.headSnapshot,
             });
-            if (patchCacheNode) rememberRscPatchCacheNode(rscPatchCache, patchCacheNode, MAX_RSC_CACHE_ENTRIES);
+            if (patchCacheNode) rememberRscCacheNode(rscPatchCache, patchCacheNode, MAX_RSC_CACHE_ENTRIES);
             return;
           }
           rscPatchCache.delete(target);
@@ -476,6 +464,7 @@ function Root(): ReactNode {
             shouldApplyNavigation: () => navId === navigationSeq,
           });
           if (fallback.type === "redirected") return;
+          if (fallback.type === "not-found") throw new RscRouteNotFound(target);
           if (fallback.type === "patched") throw new Error("[rscClient] full fallback unexpectedly returned a patch");
           nextNode = fallback.node;
         } else {
@@ -492,7 +481,7 @@ function Root(): ReactNode {
         isExpectedNavigationError: (error) => error instanceof RscRedirectNavigationStarted,
         onLatestError: (error) => hardNavigateAfterRscFailure(target, options.replace, error),
       });
-
+      
       await nextNode.thenable;
       const committed = commitLatestRscNavigation({
         cache: rscCache,
@@ -517,6 +506,8 @@ function Root(): ReactNode {
       if (committed) rememberCommittedRouteState(nextNode);
     } catch (error) {
       if (error instanceof RscRedirectNavigationStarted) return;
+      
+      if (error instanceof RscRouteNotFound) throw error;
       if (navId === navigationSeq) hardNavigateAfterRscFailure(target, options.replace, error);
     }
   };
@@ -525,7 +516,10 @@ function Root(): ReactNode {
 }
 
 window.addEventListener("popstate", () => {
-  void globalThis.__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false });
+  
+  void globalThis
+    .__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false })
+    ?.catch((error: unknown) => hardNavigateAfterRscFailure(window.location.href, true, error));
   window.setTimeout(() => {
     if (globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__) return;
     const href = globalThis.__AKAN_GET_SYNC_ROUTE_HREF__?.(window.location.href) ?? window.location.href;

package/server/rscClientFetch.ts

@@ -5,11 +5,10 @@ import {
   readAkanRscPatchMetadataResponseHeaders,
 } from "./routeState";
 
-type RscNavigate = (href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void> | void;
-
 export type RscClientFetchResponseResult =
   | { type: "response"; response: Response }
   | { type: "patch"; response: Response; patch: AkanRscPatchMetadata }
+  | { type: "not-found" }
   | { type: "redirected"; status?: number };
 
 export async function fetchRscNavigationResponse(
@@ -17,7 +16,7 @@ export async function fetchRscNavigationResponse(
   options: {
     buildId?: number;
     currentRouterState: AkanRouterStateV1 | null;
-    navigate?: RscNavigate;
+    navigate?: (href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void> | void;
     sendRouterState?: boolean;
     shouldApplyNavigation?: () => boolean;
   },
@@ -41,6 +40,11 @@ export async function fetchRscNavigationResponse(
     if (shouldApplyNavigation()) await options.navigate?.(redirect, { replace: method !== "push", scrollToTop: true });
     return { type: "redirected", status };
   }
+  
+  if (response.status === 404) {
+    await response.body?.cancel();
+    return { type: "not-found" };
+  }
   if (response.headers.get("X-Akan-Rsc-Partial") === "patch") {
     const patch = readAkanRscPatchMetadataResponseHeaders(response.headers);
     if (options.sendRouterState === false) throw new Error("[rscClient] RSC full fallback returned a patch response");