akanjs 2.3.0 → 2.3.1-rc.0

package/server/rscClient.tsx

@@ -1,13 +1,38 @@
-import { createElement, type ReactNode, startTransition, use, useLayoutEffect, useState } from "react";
+import { createElement, type ReactNode, startTransition, use, type Usable, useLayoutEffect, useState } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+import {
+  type AkanHeadSnapshotV1,
+  type AkanRouterStateV1,
+  type AkanRscPatchMetadata,
+  decodeAkanRouterState,
+  readAkanRouterStateResponseHeader,
+} from "./routeState";
+import { fetchRscNavigationResponse } from "./rscClientFetch";
+import { validateRscPatchForGuardedCommit } from "./rscClientPatch";
+import {
+  commitPreparedAkanHeadSnapshotPatch,
+  getAkanHeadSnapshotPatchFailureReason,
+  prepareAkanHeadSnapshotPatch,
+  rollbackPreparedAkanHeadSnapshotPatch,
+} from "./rscHeadPatch";
 import { getRscPayloadStream, guardRscRedirectRows, type RscRedirectRow } from "./rscHttp";
 import {
+  type AkanSegmentCacheNode,
   commitLatestRscNavigation,
+  createAkanSegmentCacheTree,
+  createRscNavigationCacheNode,
+  createRscPatchNavigationCacheNode,
   deleteRscCacheEntryIfCurrent,
-  observeRscNavigation,
-  rememberRscCacheEntry,
+  observeRscNavigationNode,
+  type RscNavigationCacheNode,
+  type RscPatchNavigationCacheNode,
+  rememberRscCacheNode,
+  rememberRscPatchCacheNode,
+  resolveCachedRscPatchNavigation,
 } from "./rscNavigationState";
+import { isAkanRscPartialCommitEnabled } from "./rscPartialCommit";
+import { commitAkanSegmentOutletPatch, resetAkanSegmentOutletPatches } from "./rscSegmentOutlet";
 
 type InlineRscChunk = [1, string] | [3, string];
 
@@ -16,6 +41,7 @@ declare global {
   var __RSC_CLOSED__: boolean | undefined;
   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;
@@ -35,8 +61,24 @@ function decodeInlineRscChunk([type, data]: InlineRscChunk): Uint8Array {
   return decodeBase64(data);
 }
 
-type RscThenable = Promise<ReactNode>;
-type RscFetchResult = { type: "rsc"; thenable: RscThenable } | { type: "redirected"; status?: number };
+type RscThenable = Promise<ReactNode> & {
+  status?: "pending" | "fulfilled" | "rejected";
+  value?: ReactNode;
+  reason?: unknown;
+};
+type RscCacheNode = RscNavigationCacheNode<RscThenable>;
+type RscSegmentCacheNode = AkanSegmentCacheNode<RscThenable>;
+type RscFetchResult =
+  | { type: "rsc"; node: RscCacheNode }
+  | {
+      type: "patched";
+      tree: RscSegmentCacheNode;
+      patchedNode: RscSegmentCacheNode;
+      patch: AkanRscPatchMetadata;
+      outletKey: string;
+      headSnapshot: AkanHeadSnapshotV1;
+    }
+  | { type: "redirected"; status?: number };
 const MAX_RSC_CACHE_ENTRIES = 32;
 let documentNavigationFallbackInFlight = false;
 
@@ -69,8 +111,35 @@ 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";
+  thenable.then(
+    (value) => {
+      thenable.status = "fulfilled";
+      thenable.value = value;
+    },
+    (reason) => {
+      thenable.status = "rejected";
+      thenable.reason = reason;
+    },
+  );
+  return thenable;
+}
+
 function createRscThenable(stream: ReadableStream<Uint8Array>): RscThenable {
-  return createFromReadableStream<ReactNode>(stream) as RscThenable;
+  return trackRscThenable(createFromReadableStream<ReactNode>(stream) as RscThenable);
 }
 
 function hardNavigateAfterRscFailure(target: string, replace = false, error?: unknown): void {
@@ -93,35 +162,105 @@ function navigateAfterRscRedirect(target: string, replace = true): void {
   });
 }
 
+function commitRscPatchNavigation({
+  target,
+  patch,
+  replace,
+  scrollToTop,
+  bumpScrollToTop,
+}: {
+  target: string;
+  patch: Extract<RscFetchResult, { type: "patched" }>;
+  replace?: boolean;
+  scrollToTop?: boolean;
+  bumpScrollToTop?: () => void;
+}): boolean {
+  const patchThenable = patch.patchedNode.thenable;
+  if (!patchThenable) throw new Error("[rscClient] validated RSC patch is missing a thenable");
+  const preparedHeadPatch = prepareAkanHeadSnapshotPatch(patch.headSnapshot);
+  if (!preparedHeadPatch) return false;
+
+  let outletCommitted = false;
+  let headApplied = false;
+  startTransition(() => {
+    try {
+      headApplied = commitPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
+      if (!headApplied) {
+        return;
+      }
+      outletCommitted = commitAkanSegmentOutletPatch(patch.outletKey, patchThenable);
+      if (!outletCommitted) {
+        rollbackPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
+        return;
+      }
+      if (replace) window.history.replaceState(null, "", target);
+      else window.history.pushState(null, "", target);
+      if (scrollToTop) bumpScrollToTop?.();
+    } catch {
+      if (headApplied) rollbackPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
+      if (outletCommitted) resetAkanSegmentOutletPatches();
+      headApplied = false;
+      outletCommitted = false;
+    }
+  });
+  return outletCommitted && headApplied;
+}
+
 async function fetchRsc(
   href: string,
-  options: { buildId?: number; replaceOnRedirect?: boolean; shouldApplyNavigation?: () => boolean } = {},
+  options: {
+    buildId?: number;
+    replaceOnRedirect?: boolean;
+    shouldApplyNavigation?: () => boolean;
+    sendRouterState?: boolean;
+    navId?: number;
+  } = {},
 ): Promise<RscFetchResult> {
   const shouldApplyNavigation = options.shouldApplyNavigation ?? (() => true);
-  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 responseResult = await fetchRscNavigationResponse(href, {
+    buildId: options.buildId,
+    currentRouterState,
+    navigate: globalThis.__AKAN_RSC_NAVIGATE__,
+    sendRouterState: options.sendRouterState,
+    shouldApplyNavigation,
   });
-  const redirect = res.headers.get("X-Akan-Redirect");
-  if (redirect) {
-    const method = res.headers.get("X-Akan-Redirect-Method");
-    const statusHeader = res.headers.get("X-Akan-Redirect-Status");
-    const status = statusHeader ? Number(statusHeader) : undefined;
-    if (shouldApplyNavigation())
-      await globalThis.__AKAN_RSC_NAVIGATE__?.(redirect, { replace: method !== "push", scrollToTop: true });
-    return { type: "redirected", status };
+  if (responseResult.type === "redirected") return responseResult;
+  if (responseResult.type === "patch") {
+    const patchResult = await validateRscPatchForGuardedCommit({
+      partialCommitEnabled: isAkanRscPartialCommitEnabled(),
+      currentTree: currentSegmentTree,
+      response: responseResult.response,
+      patch: responseResult.patch,
+      href,
+      createThenable: createRscThenable,
+      navId: options.navId,
+      getCurrentNavId: () => navigationSeq,
+      getHeadSnapshotPatchFailureReason: getAkanHeadSnapshotPatchFailureReason,
+    });
+    if (patchResult.status === "patched") {
+      if (!patchResult.headSnapshot) throw new Error("[rscClient] validated RSC patch is missing a head snapshot");
+      return {
+        type: "patched",
+        tree: patchResult.tree,
+        patchedNode: patchResult.patchedNode,
+        patch: responseResult.patch,
+        outletKey: patchResult.outletKey,
+        headSnapshot: patchResult.headSnapshot,
+      };
+    }
+    return fetchRsc(href, {
+      ...options,
+      sendRouterState: false,
+    });
   }
+  const res = responseResult.response;
   const stream = getRscPayloadStream(res);
   if (!stream) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
-  let thenable: RscThenable | undefined;
+  const nodeRef: { current?: RscCacheNode } = {};
   const handleRedirect = (redirect: RscRedirectRow) => {
     if (!shouldApplyNavigation()) return;
     const location = redirect.location ? normalizeHref(redirect.location) : href;
-    if (thenable) deleteRscCacheEntryIfCurrent(rscCache, href, thenable);
+    if (nodeRef.current) deleteRscCacheEntryIfCurrent(rscCache, href, nodeRef.current);
     navigateAfterRscRedirect(
       location,
       redirect.method ? redirect.method !== "push" : (options.replaceOnRedirect ?? true),
@@ -130,18 +269,50 @@ async function fetchRsc(
   const guardedStream = guardRscRedirectRows(stream, {
     onRedirect: handleRedirect,
   });
-  thenable = createRscThenable(guardedStream);
+  const thenable = createRscThenable(guardedStream);
+  const node = createRscNavigationCacheNode({
+    href,
+    thenable,
+    routerState: readAkanRouterStateResponseHeader(res.headers),
+  });
+  nodeRef.current = node;
   return {
     type: "rsc",
-    thenable,
+    node,
   };
 }
 
-const rscCache = new Map<string, RscThenable>();
+const rscCache = new Map<string, RscCacheNode>();
+const rscPatchCache = new Map<string, RscPatchNavigationCacheNode<RscThenable>>();
 const initialThenable = createRscThenable(createInitialRscStream());
-rscCache.set(normalizeHref(window.location.href), initialThenable);
+const initialRouterState = decodeAkanRouterState(globalThis.__AKAN_RSC_INITIAL_STATE__);
+const initialNode = createRscNavigationCacheNode({
+  href: normalizeHref(window.location.href),
+  thenable: initialThenable,
+  routerState: initialRouterState,
+});
+rscCache.set(initialNode.href, initialNode);
+let currentRouterState: AkanRouterStateV1 | null = initialRouterState;
+let currentSegmentTree: RscSegmentCacheNode | null = createAkanSegmentCacheTree(initialNode);
+let currentFullNode: RscCacheNode = initialNode;
+let currentCommitKind: "full" | "patch" = "full";
 let navigationSeq = 0;
 
+function rememberCommittedRouteState(node: RscCacheNode): void {
+  rscPatchCache.clear();
+  if (!node.routerState) return;
+  currentRouterState = node.routerState;
+  currentSegmentTree = createAkanSegmentCacheTree(node);
+  currentFullNode = node;
+  currentCommitKind = "full";
+}
+
+function rememberPatchedRouteState(tree: RscSegmentCacheNode, patchedNode: RscSegmentCacheNode): void {
+  currentRouterState = patchedNode.routerState;
+  currentSegmentTree = tree;
+  currentCommitKind = "patch";
+}
+
 function Root(): ReactNode {
   const [thenable, setThenable] = useState<RscThenable>(initialThenable);
   const [scrollToTopTick, setScrollToTopTick] = useState(0);
@@ -153,39 +324,64 @@ function Root(): ReactNode {
 
   globalThis.__AKAN_RSC_CLEAR_CACHE__ = () => {
     rscCache.clear();
-    rscCache.set(normalizeHref(window.location.href), thenable);
+    rscPatchCache.clear();
+    if (currentCommitKind === "patch") {
+      void globalThis.__AKAN_RSC_REFRESH__?.();
+      return;
+    }
+    const href = normalizeHref(window.location.href);
+    const currentFullState = currentFullNode.routerState;
+    const canRestoreFullNode =
+      currentFullNode.href === href &&
+      ((!currentFullState && !currentRouterState) ||
+        (currentFullState !== null &&
+          currentRouterState !== null &&
+          currentFullState.routeId === currentRouterState.routeId));
+    if (canRestoreFullNode) {
+      resetAkanSegmentOutletPatches();
+      rscCache.set(href, currentFullNode);
+    }
   };
 
   globalThis.__AKAN_RSC_REFRESH__ = async (options = {}) => {
     const navId = ++navigationSeq;
     const target = normalizeHref(window.location.href);
     rscCache.delete(target);
+    rscPatchCache.clear();
     try {
       const next = await fetchRsc(target, {
         ...options,
         replaceOnRedirect: true,
+        sendRouterState: false,
+        navId,
         shouldApplyNavigation: () => navId === navigationSeq,
       });
       if (next.type === "redirected") return;
-      observeRscNavigation({
+      if (next.type === "patched") return;
+      observeRscNavigationNode({
         cache: rscCache,
-        href: target,
-        thenable: next.thenable,
+        node: next.node,
         navId,
         getCurrentNavId: () => navigationSeq,
         isExpectedNavigationError: (error) => error instanceof RscRedirectNavigationStarted,
         onLatestError: (error) => hardNavigateAfterRscFailure(target, true, error),
       });
-      commitLatestRscNavigation({
+
+      await next.node.thenable;
+      const committed = commitLatestRscNavigation({
         cache: rscCache,
         href: target,
-        thenable: next.thenable,
+        thenable: next.node,
         maxEntries: MAX_RSC_CACHE_ENTRIES,
         startTransition,
-        commitThenable: setThenable,
+        commitThenable: (node) => {
+          resetAkanSegmentOutletPatches();
+          setThenable(node.thenable);
+        },
         navId,
         getCurrentNavId: () => navigationSeq,
       });
+      if (committed) rememberCommittedRouteState(next.node);
     } catch (error) {
       if (error instanceof RscRedirectNavigationStarted) return;
       if (navId === navigationSeq) hardNavigateAfterRscFailure(target, true, error);
@@ -197,33 +393,106 @@ function Root(): ReactNode {
     const target = normalizeHref(href);
     const scrollToTop = options.scrollToTop ?? true;
     try {
-      let next = rscCache.get(target);
-      if (!next) {
+      let nextNode = rscCache.get(target);
+      if (!nextNode) {
+        const cachedPatch = rscPatchCache.get(target);
+        if (cachedPatch) {
+          const patchResult = resolveCachedRscPatchNavigation({
+            currentTree: currentSegmentTree,
+            node: cachedPatch,
+            partialCommitEnabled: isAkanRscPartialCommitEnabled(),
+            navId,
+            getCurrentNavId: () => navigationSeq,
+          });
+          if (patchResult.status === "patched") {
+            const replayedPatch = {
+              type: "patched" as const,
+              tree: patchResult.tree,
+              patchedNode: patchResult.patchedNode,
+              patch: cachedPatch.patch,
+              outletKey: patchResult.outletKey,
+              headSnapshot: patchResult.headSnapshot,
+            };
+            if (
+              commitRscPatchNavigation({
+                target,
+                patch: replayedPatch,
+                replace: options.replace,
+                scrollToTop,
+                bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
+              })
+            ) {
+              rememberPatchedRouteState(patchResult.tree, patchResult.patchedNode);
+              rememberRscPatchCacheNode(rscPatchCache, cachedPatch, MAX_RSC_CACHE_ENTRIES);
+              return;
+            }
+          }
+          rscPatchCache.delete(target);
+        }
         const fetched = await fetchRsc(target, {
           replaceOnRedirect: options.replace,
+          navId,
           shouldApplyNavigation: () => navId === navigationSeq,
         });
         if (fetched.type === "redirected") return;
-        next = fetched.thenable;
+        if (fetched.type === "patched") {
+          if (navId !== navigationSeq) return;
+          if (
+            commitRscPatchNavigation({
+              target,
+              patch: fetched,
+              replace: options.replace,
+              scrollToTop,
+              bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
+            })
+          ) {
+            rememberPatchedRouteState(fetched.tree, fetched.patchedNode);
+            const patchCacheNode = createRscPatchNavigationCacheNode({
+              href: target,
+              patch: fetched.patch,
+              patchedNode: fetched.patchedNode,
+              outletKey: fetched.outletKey,
+              headSnapshot: fetched.headSnapshot,
+            });
+            if (patchCacheNode) rememberRscPatchCacheNode(rscPatchCache, patchCacheNode, MAX_RSC_CACHE_ENTRIES);
+            return;
+          }
+          rscPatchCache.delete(target);
+          const fallback = await fetchRsc(target, {
+            replaceOnRedirect: options.replace,
+            sendRouterState: false,
+            navId,
+            shouldApplyNavigation: () => navId === navigationSeq,
+          });
+          if (fallback.type === "redirected") return;
+          if (fallback.type === "patched") throw new Error("[rscClient] full fallback unexpectedly returned a patch");
+          nextNode = fallback.node;
+        } else {
+          nextNode = fetched.node;
+        }
       } else {
-        rememberRscCacheEntry(rscCache, target, next, MAX_RSC_CACHE_ENTRIES);
+        rememberRscCacheNode(rscCache, nextNode, MAX_RSC_CACHE_ENTRIES);
       }
-      observeRscNavigation({
+      observeRscNavigationNode({
         cache: rscCache,
-        href: target,
-        thenable: next,
+        node: nextNode,
         navId,
         getCurrentNavId: () => navigationSeq,
         isExpectedNavigationError: (error) => error instanceof RscRedirectNavigationStarted,
         onLatestError: (error) => hardNavigateAfterRscFailure(target, options.replace, error),
       });
-      commitLatestRscNavigation({
+
+      await nextNode.thenable;
+      const committed = commitLatestRscNavigation({
         cache: rscCache,
         href: target,
-        thenable: next,
+        thenable: nextNode,
         maxEntries: MAX_RSC_CACHE_ENTRIES,
         startTransition,
-        commitThenable: setThenable,
+        commitThenable: (node) => {
+          resetAkanSegmentOutletPatches();
+          setThenable(node.thenable);
+        },
         updateHistory: () => {
           if (options.replace) window.history.replaceState(null, "", target);
           else window.history.pushState(null, "", target);
@@ -233,13 +502,14 @@ function Root(): ReactNode {
         navId,
         getCurrentNavId: () => navigationSeq,
       });
+      if (committed) rememberCommittedRouteState(nextNode);
     } catch (error) {
       if (error instanceof RscRedirectNavigationStarted) return;
       if (navId === navigationSeq) hardNavigateAfterRscFailure(target, options.replace, error);
     }
   };
 
-  return use(thenable);
+  return use(thenable as Usable<ReactNode>);
 }
 
 window.addEventListener("popstate", () => {

package/server/rscClientFetch.ts

@@ -0,0 +1,57 @@
+import {
+  type AkanRouterStateV1,
+  type AkanRscPatchMetadata,
+  appendAkanRouterStateRequestHeaders,
+  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: "redirected"; status?: number };
+
+export async function fetchRscNavigationResponse(
+  href: string,
+  options: {
+    buildId?: number;
+    currentRouterState: AkanRouterStateV1 | null;
+    navigate?: RscNavigate;
+    sendRouterState?: boolean;
+    shouldApplyNavigation?: () => boolean;
+  },
+): Promise<RscClientFetchResponseResult> {
+  const shouldApplyNavigation = options.shouldApplyNavigation ?? (() => true);
+  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 headers = new Headers({ Accept: "text/x-component", "Cache-Control": "no-cache" });
+  if (options.sendRouterState !== false) appendAkanRouterStateRequestHeaders(headers, options.currentRouterState);
+  const response = await fetch(endpoint, {
+    headers,
+    credentials: "same-origin",
+    cache: "no-store",
+  });
+  const redirect = response.headers.get("X-Akan-Redirect");
+  if (redirect) {
+    const method = response.headers.get("X-Akan-Redirect-Method");
+    const statusHeader = response.headers.get("X-Akan-Redirect-Status");
+    const status = statusHeader ? Number(statusHeader) : undefined;
+    if (shouldApplyNavigation()) await options.navigate?.(redirect, { replace: method !== "push", scrollToTop: true });
+    return { type: "redirected", status };
+  }
+  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");
+    if (!patch) {
+      await response.body?.cancel();
+      return fetchRscNavigationResponse(href, {
+        ...options,
+        sendRouterState: false,
+      });
+    }
+    return { type: "patch", response, patch };
+  }
+  return { type: "response", response };
+}