akanjs 3.0.2 → 3.1.0-rc.0

package/server/resolver/signal.resolver.ts

@@ -39,6 +39,7 @@ import { type Endpoint, type EndpointCls, sliceEndpoint } from "../../signal/end
 import type { EndpointInfo } from "../../signal/endpointInfo";
 import { EndpointRateLimit } from "../../signal/endpointRateLimit";
 import type { Internal, InternalCls } from "../../signal/internal";
+import { Machine } from "../../signal/internalArg";
 import type { InternalInfo } from "../../signal/internalInfo";
 import type { MiddlewareCls } from "../../signal/middleware";
 import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal";
@@ -52,6 +53,8 @@ import type {
   WebsocketMessageData,
   WebsocketSubscribeAck,
 } from "../../signal/types";
+import { MachineToken } from "../machine/machineToken";
+import type { RoomReplay } from "../routing/roomReplay";
 import type { HttpRoutes, LocalPublish, SignalRoutes, WebsocketRoutes } from "../types";
 
 type LiveChangeListener = (doc: unknown, type: unknown, previous?: unknown) => void;
@@ -79,8 +82,15 @@ export class SignalResolver {
     const separator = roomId.indexOf("-");
     return SignalResolver.#coalescingRooms.has(separator >= 0 ? roomId.slice(0, separator) : roomId);
   }
-  static setLocalPublish(localPublish: LocalPublish, websocket: WebsocketAdaptor, live?: LiveRegistry) {
+  static #roomReplay: RoomReplay | null = null;
+  static setLocalPublish(
+    localPublish: LocalPublish,
+    websocket: WebsocketAdaptor,
+    live?: LiveRegistry,
+    roomReplay: RoomReplay | null = null,
+  ) {
     SignalResolver.#localPublish = localPublish;
+    SignalResolver.#roomReplay = roomReplay;
     websocket.setEventHandler((roomId, data) => localPublish(roomId, data as object | object[] | Uint8Array));
     
     websocket.onRecovered?.(() => {
@@ -245,12 +255,14 @@ export class SignalResolver {
           if (!internalInfo.execFn) throw new Error(`Exec function is not set for ${key}`);
           const execFn = internalInfo.execFn.bind(internal);
           
+          const { onFailed } = internalInfo.signalOption;
           internal.queue.registerProcessWorker(
             key,
             SignalResolver.#traced(
               key,
               async (job) => await execFn(...SignalResolver.#getJobArgs(key, internalInfo, job), job),
             ),
+            onFailed ? { onFailed: (job, error) => onFailed.call(internal, job, error) } : {},
           );
           break;
         }
@@ -626,6 +638,7 @@ export class SignalResolver {
     const wsRoutes: WebsocketRoutes = {};
     const defaultPrefix = endpointCls.srv.cnst?.refName;
     SignalResolver.#warnUnguarded(endpointMeta);
+    SignalResolver.#warnMachineKeyless(endpointMeta);
     Object.entries(endpointMeta).forEach(([key, endpointInfo]) => {
       const path = endpointInfo.getRoutePath(key, defaultPrefix);
       if (endpointInfo.signalOption.globalPrefix !== undefined) {
@@ -686,7 +699,7 @@ export class SignalResolver {
           );
           break;
         case "pubsub":
-          wsRoutes[key] = async (ws, message, event) =>
+          wsRoutes[key] = async (ws, message, event, request) =>
             await SignalContext.run(endpoint, endpointInfo, key, "websocket", async () => {
               const websocket = SignalResolver.#getWebsocket(registry);
               const context = await new SignalContext(
@@ -710,14 +723,28 @@ export class SignalResolver {
                     roomId,
                     query: query as never,
                     fallback: liveOption.fallback,
+                    payload: liveOption.payload,
                     fields: SignalResolver.#queryFieldsOf(live, liveOption.refName),
                   });
+                const replay = SignalResolver.#roomReplay;
+                replay?.watch(roomId);
                 ws.subscribe(roomId);
+                
+                const missed = request?.since && replay ? replay.since(roomId, request.since) : null;
+                for (const frame of missed ?? []) ws.send(frame);
                 roomCtxMap.set(roomId, context);
                 SignalResolver.#liveWsPubsubRoomCtx.set(ws, roomCtxMap);
                 websocket.joinRoom(ws, roomId);
                 SignalResolver.logger.verbose(`WebSocket subscribed to room ${roomId}`);
-                const ack: WebsocketSubscribeAck = { type: "sub", roomId, requestRoomId, subscribe };
+                const cursor = replay?.cursor(roomId);
+                const ack: WebsocketSubscribeAck = {
+                  type: "sub",
+                  roomId,
+                  requestRoomId,
+                  subscribe,
+                  ...(cursor ? { cursor } : {}),
+                  ...(request?.since ? { replayed: !!missed } : {}),
+                };
                 return ack;
               }
               if (liveOption) await context.resolveInternalArgs();
@@ -768,6 +795,16 @@ export class SignalResolver {
       `${open.join(", ")} declare${open.length === 1 ? "s" : ""} no guards, so anyone can call ${open.length === 1 ? "it" : "them"} over HTTP and WebSocket. Name the guards, or \`guards: [Public]\` to keep one open on purpose.`,
     );
   }
+  static #warnMachineKeyless(endpointMeta: { [key: string]: EndpointInfo }) {
+    if (MachineToken.canVerify()) return;
+    const machineOnly = Object.entries(endpointMeta)
+      .filter(([, endpointInfo]) => endpointInfo.internalArgs.some((arg) => arg.argRef === Machine))
+      .map(([key]) => key);
+    if (!machineOnly.length) return;
+    SignalResolver.logger.error(
+      `${machineOnly.join(", ")} take${machineOnly.length === 1 ? "s" : ""} .with(Machine), and this server has neither AKAN_MACHINE_PUBLIC_KEY nor AKAN_MACHINE_PRIVATE_KEY to verify a machine token: every machine call to ${machineOnly.length === 1 ? "it" : "them"} is refused.`,
+    );
+  }
   static #selectCache = new WeakMap<Cls, Record<string, true>>();
   static #selectForConstant(constant: Cls): Record<string, true> | undefined {
     const cached = SignalResolver.#selectCache.get(constant);

package/server/routeElementComposer.tsx

@@ -19,6 +19,14 @@ import {
 } from "./routeState";
 import { AkanSegmentOutletReference } from "./rscSegmentOutletReference";
 
+/** How a render reached after the layouts streamed answers `router.notFound()` — in place, since its parents are out. */
+export interface RouteNotFoundInPlace {
+  pathname: string;
+  /** Rendered when no layout above the thrower declares `.notFound()`. */
+  systemFallback: () => ReactNode;
+  onNotFound: () => void;
+}
+
 export class RouteElementComposer {
   static async resolveSsrFramePathRoute({
     pathRoute,
@@ -63,11 +71,13 @@ export class RouteElementComposer {
     params,
     searchParams,
     navKey,
+    notFound,
   }: {
     pathRoute: PathRoute;
     params: Record<string, string>;
     searchParams: Record<string, string | string[]>;
     navKey?: string;
+    notFound?: RouteNotFoundInPlace;
   }): ReactNode {
     return RouteElementComposer.composeRenders({
       renders: RouteElementComposer.#getRenderStack(pathRoute),
@@ -75,29 +85,50 @@ export class RouteElementComposer {
       params,
       searchParams,
       navKey,
+      notFound,
     });
   }
 
+  static async checkArgs({
+    pathRoute,
+    params,
+    searchParams,
+  }: {
+    pathRoute: PathRoute;
+    params: Record<string, string>;
+    searchParams: Record<string, string | string[]>;
+  }): Promise<void> {
+    await Promise.all(
+      RouteElementComposer.#getRenderStack(pathRoute).map((routeRender) =>
+        routeRender?.checkArgs?.({ params, searchParams }),
+      ),
+    );
+  }
+
   static composeSuffix({
     pathRoute,
     params,
     searchParams,
     patchStartIndex,
     navKey,
+    notFound,
   }: {
     pathRoute: PathRoute;
     params: Record<string, string>;
     searchParams: Record<string, string | string[]>;
     patchStartIndex: number;
     navKey?: string;
+    notFound?: RouteNotFoundInPlace;
   }): ReactNode | null {
     const renders = RouteElementComposer.#getRenderStack(pathRoute);
     if (!Number.isInteger(patchStartIndex) || patchStartIndex < 0 || patchStartIndex >= renders.length) return null;
     return RouteElementComposer.composeRenders({
       renders: renders.slice(patchStartIndex),
+      owners: renders.slice(0, patchStartIndex),
       params,
       searchParams,
       navKey,
+      notFound,
     });
   }
 
@@ -174,16 +205,21 @@ export class RouteElementComposer {
 
   static composeRenders({
     renders,
+    owners = [],
     segments,
     params,
     searchParams,
     navKey,
+    notFound,
   }: {
     renders: RouteRender[];
+    /** Layouts above `renders` that this element leaves out (a patch) but whose `.notFound()` still applies. */
+    owners?: RouteRender[];
     segments?: AkanRouteSegmentState[];
     params: Record<string, string>;
     searchParams: Record<string, string | string[]>;
     navKey?: string;
+    notFound?: RouteNotFoundInPlace;
   }): ReactNode {
     let element: ReactNode = null;
     for (let i = renders.length - 1; i >= 0; i--) {
@@ -194,7 +230,12 @@ export class RouteElementComposer {
         navKey && loadingFallback != null && i === renders.length - 1 ? `akan-loading:${navKey}` : undefined;
       element = (
         <Suspense key={suspenseKey} fallback={loadingFallback}>
-          <RouteElementComposer.AsyncRender routeRender={routeRender} params={params} searchParams={searchParams}>
+          <RouteElementComposer.AsyncRender
+            routeRender={routeRender}
+            params={params}
+            searchParams={searchParams}
+            notFound={notFound ? { ...notFound, owners: [...owners, ...renders.slice(0, i)] } : undefined}
+          >
             {element}
           </RouteElementComposer.AsyncRender>
         </Suspense>
@@ -217,12 +258,47 @@ export class RouteElementComposer {
     children,
     params,
     searchParams,
+    notFound,
   }: {
     routeRender: RouteRender;
     children: ReactNode;
     params: Record<string, string>;
     searchParams: Record<string, string | string[]>;
-  }) => RouteElementComposer.#normalizeReactNode(await routeRender.render({ children, params, searchParams } as never));
+    notFound?: RouteNotFoundInPlace & { owners: RouteRender[] };
+  }) => {
+    try {
+      return RouteElementComposer.#normalizeReactNode(
+        await routeRender.render({ children, params, searchParams } as never),
+      );
+    } catch (error) {
+      if (!notFound || (error as { digest?: unknown } | null)?.digest !== "AKAN_NOT_FOUND") throw error;
+      notFound.onNotFound();
+      return await RouteElementComposer.#renderNotFoundInPlace(notFound, params, searchParams);
+    }
+  };
+
+  static async #renderNotFoundInPlace(
+    { owners, pathname, systemFallback }: RouteNotFoundInPlace & { owners: RouteRender[] },
+    params: Record<string, string>,
+    searchParams: Record<string, string | string[]>,
+  ): Promise<ReactNode> {
+    for (let index = owners.length - 1; index >= 0; index--) {
+      const fallback = await owners[index]?.resolveNotFound?.();
+      if (!fallback) continue;
+      return (
+        <>
+          <meta name="robots" content="noindex" />
+          {RouteElementComposer.#normalizeReactNode(await fallback({ params, searchParams, pathname }))}
+        </>
+      );
+    }
+    return (
+      <>
+        <meta name="robots" content="noindex" />
+        {systemFallback()}
+      </>
+    );
+  }
 
   static #makeFallbackRouteRender({
     kind,

package/server/routeState.ts

@@ -27,6 +27,8 @@ export interface AkanRouterStateV1 {
   href: string;
   routeId: string;
   segments: AkanRouteSegmentState[];
+  /** The route's `.config({ transition })`, which the browser plays as a view transition on the way in and out. */
+  transition?: string;
 }
 
 export type AkanHeadSnapshotTag = "title" | "meta" | "link";
@@ -132,6 +134,7 @@ export function isAkanRouterStateV1(value: unknown): value is AkanRouterStateV1
     (state.buildId === undefined || typeof state.buildId === "number") &&
     typeof state.href === "string" &&
     typeof state.routeId === "string" &&
+    (state.transition === undefined || typeof state.transition === "string") &&
     Array.isArray(state.segments) &&
     state.segments.every(isSegmentState)
   );
@@ -207,10 +210,12 @@ export function createAkanRouterState({
   pathRoute,
   href,
   buildId,
+  transition,
 }: {
   pathRoute: PathRoute;
   href: string;
   buildId?: number;
+  transition?: string;
 }): AkanRouterStateV1 {
   return {
     version: AKAN_RSC_STATE_VERSION,
@@ -218,6 +223,7 @@ export function createAkanRouterState({
     href,
     routeId: pathRoute.path,
     segments: createAkanRouteSegments(pathRoute),
+    ...(transition && transition !== "none" ? { transition } : {}),
   };
 }
 

package/server/routeTreeBuilder.ts

@@ -8,6 +8,8 @@ import type {
   Route,
   RouteModule,
   RouteRender,
+  RouteViewport,
+  WebAppManifest,
 } from "akanjs/client";
 import {
   assertUniqueRoutePatterns,
@@ -22,6 +24,7 @@ import {
 } from "akanjs/common";
 import { createElement } from "react";
 import { defaultPageState, validatePageConfig } from "../client/frameConfig";
+import { RouteHead } from "../client/route/RouteHead";
 import {
   type ResolvedRouteModule,
   type RouteModuleSource,
@@ -291,7 +294,18 @@ export class RouteTreeBuilder {
       },
       resolveHead: async (props: PageProps) => {
         const mod = await loadSynced();
-        return mod.generateHead ? await mod.generateHead(props) : mod.head;
+        try {
+          return mod.generateHead ? await mod.generateHead(props) : mod.head;
+        } catch (error) {
+
+          const digest = (error as { digest?: unknown } | null)?.digest;
+          if (digest === "AKAN_REDIRECT" || digest === "AKAN_NOT_FOUND") throw error;
+          RouteTreeBuilder.logger.warn(`${key}: .head() threw, so the route renders without it: ${String(error)}`);
+          return undefined;
+        }
+      },
+      checkArgs: async ({ params, searchParams }: PageProps) => {
+        (await loadModule()).definition?.resolveArgs({ params, searchParams });
       },
     };
     if (kind === "page") {
@@ -303,6 +317,14 @@ export class RouteTreeBuilder {
         const { module: mod } = await loadModule();
         return "theme" in mod ? (mod.theme as string | undefined) : undefined;
       };
+      routeRender.getLayoutViewport = async () => {
+        const { module: mod } = await loadModule();
+        return "viewport" in mod ? (mod.viewport as RouteViewport | undefined) : undefined;
+      };
+      routeRender.getLayoutManifest = async () => {
+        const { module: mod } = await loadModule();
+        return "manifest" in mod ? (mod.manifest as WebAppManifest | undefined) : undefined;
+      };
       routeRender.resolveNotFound = async () => syncFallbacks((await loadModule()).module as LayoutModule).NotFound;
       routeRender.resolveError = async () => syncFallbacks((await loadModule()).module as LayoutModule).Error;
     }
@@ -321,15 +343,10 @@ export class RouteTreeBuilder {
     };
   }
 
+  /** `resolvers` run leaf first; their heads merge root first, so a deeper level takes over each tag it writes. */
   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;
-    };
+    if (chain.length <= 1) return chain[0];
+    return async (props) => RouteHead.merge(await Promise.all(chain.toReversed().map((resolver) => resolver(props))));
   }
 }

package/server/routing/apiRouter.ts

@@ -140,10 +140,13 @@ export class ApiRouter {
           if (typeof message === "string" && typeof hmrHub?.handleMessage === "function") hmrHub.handleMessage(message);
           return;
         }
+        
+        let failedKey: string | undefined;
         try {
           if (typeof message === "string") {
             const msg = JSON.parse(message) as WebsocketReqData;
             if (!msg.key) throw new Error("Message key is required");
+            failedKey = msg.key;
             if (msg.key === websocketAuthContract.key) {
               
               AppWsData.applyCredential(AppWsData.of(ws), websocketAuthContract.readJwt(msg.data));
@@ -159,19 +162,19 @@ export class ApiRouter {
             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);
+            const result = await wsRoute(ws, msg.data, eventType, { since: msg.since });
             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() }));
+            ws.send(JSON.stringify({ ...error.toJSON(), key: failedKey, timestamp: new Date().toISOString() }));
             return;
           }
           if (!SignalContext.wasReported(error)) {
             logger.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
           }
           
-          ws.send(JSON.stringify({ ...SignalFailure.body(error), at: dayjs() }));
+          ws.send(JSON.stringify({ ...SignalFailure.body(error), key: failedKey, at: dayjs() }));
         }
       },
       close: (ws) => {

package/server/routing/roomReplay.ts

@@ -0,0 +1,88 @@
+import type { WebsocketPublishData, WebsocketRoomCursor } from "akanjs/signal";
+
+interface RoomLog {
+  /** Names this numbering: a room log that expired and started over counts from 1 again under another epoch. */
+  epoch: string;
+  seq: number;
+  watchedAt: number;
+  frames: { seq: number; at: number; frame: string }[];
+}
+
+export interface RoomReplayOptions {
+  /** Whether this process sees every publish to a room, so a run of sequence numbers it holds has no hole. */
+  vouches: boolean;
+  /** Frames kept per room. */
+  depth?: number;
+  /** How long a room nobody subscribes to here keeps numbering and keeping its frames. */
+  retainMs?: number;
+  /** Rooms tracked at once; the least recently watched goes first. */
+  rooms?: number;
+}
+
+export class RoomReplay {
+  readonly #process = crypto.randomUUID();
+  #generation = 0;
+  readonly vouches: boolean;
+  readonly #depth: number;
+  readonly #retainMs: number;
+  readonly #maxRooms: number;
+  readonly #rooms = new Map<string, RoomLog>();
+
+  constructor({ vouches, depth = 128, retainMs = 5 * 60_000, rooms = 10_000 }: RoomReplayOptions) {
+    this.vouches = vouches;
+    this.#depth = depth;
+    this.#retainMs = retainMs;
+    this.#maxRooms = rooms;
+  }
+
+  /** A socket subscribed here: the room is numbered from now on, and for `retainMs` after its last subscriber left. */
+  watch(roomId: string, now = Date.now()) {
+    const room = this.#rooms.get(roomId) ?? {
+      epoch: `${this.#process}.${++this.#generation}`,
+      seq: 0,
+      watchedAt: now,
+      frames: [],
+    };
+    room.watchedAt = now;
+    this.#rooms.delete(roomId);
+    this.#rooms.set(roomId, room);
+    while (this.#rooms.size > this.#maxRooms) {
+      const oldest = this.#rooms.keys().next().value;
+      if (oldest === undefined) break;
+      this.#rooms.delete(oldest);
+    }
+  }
+
+  /** The frame to send for one publish; numbered, and kept, while the room is watched. */
+  frameOf(publishData: WebsocketPublishData, subscribed: boolean, now = Date.now()): string {
+    const room = this.#rooms.get(publishData.roomId);
+    if (room && subscribed) room.watchedAt = now;
+    if (!room || now - room.watchedAt > this.#retainMs) {
+      if (room) this.#rooms.delete(publishData.roomId);
+      return JSON.stringify(publishData);
+    }
+    room.seq += 1;
+    const frame = JSON.stringify({ ...publishData, seq: room.seq });
+    room.frames.push({ seq: room.seq, at: now, frame });
+    while (room.frames.length > this.#depth || (room.frames[0] && now - room.frames[0].at > this.#retainMs))
+      room.frames.shift();
+    return frame;
+  }
+
+  /** Where the room's numbering stands here, for a subscribe's ack; `null` for a room nobody watches. */
+  cursor(roomId: string): WebsocketRoomCursor | null {
+    const room = this.#rooms.get(roomId);
+    return room ? { epoch: room.epoch, seq: room.seq } : null;
+  }
+
+  /** The frames numbered after the cursor, or `null` when this process cannot tell whether that is all of them. */
+  since(roomId: string, { epoch, seq }: WebsocketRoomCursor): string[] | null {
+    const room = this.#rooms.get(roomId);
+    if (!this.vouches || !room || epoch !== room.epoch || !Number.isSafeInteger(seq) || seq < 0 || seq > room.seq)
+      return null;
+    if (seq === room.seq) return [];
+    const first = room.frames[0];
+    if (!first || first.seq > seq + 1) return null;
+    return room.frames.filter((entry) => entry.seq > seq).map((entry) => entry.frame);
+  }
+}

package/server/rscClient.tsx

@@ -1,3 +1,4 @@
+import * as React from "react";
 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";
@@ -179,8 +180,7 @@ function commitRscPatchNavigation({
         rollbackPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
         return;
       }
-      if (replace) window.history.replaceState(null, "", target);
-      else window.history.pushState(null, "", target);
+      commitHistory(target, replace);
       if (scrollToTop) bumpScrollToTop?.();
     } catch {
       if (headApplied) rollbackPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
@@ -192,6 +192,37 @@ function commitRscPatchNavigation({
   return outletCommitted && headApplied;
 }
 
+function akanHistoryState(replace: boolean, shallow = false) {
+  const idx = (window.history.state as { __akanRouter?: { idx?: unknown } } | null)?.__akanRouter?.idx;
+  const current = Number.isInteger(idx) ? (idx as number) : 0;
+  return { __akanRouter: { idx: replace ? current : current + 1, ...(shallow ? { shallow: true } : {}) } };
+}
+
+let renderedHref = normalizeHref(window.location.href);
+const pathnameOf = (href: string) => new URL(href).pathname;
+
+function commitHistory(target: string, replace: boolean | undefined) {
+  if (replace) window.history.replaceState(akanHistoryState(true), "", target);
+  else window.history.pushState(akanHistoryState(false), "", target);
+  renderedHref = target;
+}
+
+const addTransitionType = (React as { addTransitionType?: (type: string) => void }).addTransitionType;
+
+function viewTransitionTypeOf(transition: string | undefined, push: boolean): string | null {
+  if (!transition || transition === "none") return null;
+  if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return null;
+  return `akan-${transition}-${push ? "push" : "pop"}`;
+}
+
+/** Writes the entry without asking the server for the page; only a change that keeps the rendered path qualifies. */
+function navigateShallow(target: string, replace: boolean | undefined): boolean {
+  if (pathnameOf(target) !== pathnameOf(renderedHref)) return false;
+  if (replace) window.history.replaceState(akanHistoryState(true, true), "", target);
+  else window.history.pushState(akanHistoryState(false, true), "", target);
+  return true;
+}
+
 async function fetchRsc(
   href: string,
   options: {
@@ -383,6 +414,7 @@ function Root(): ReactNode {
   };
 
   globalThis.__AKAN_RSC_NAVIGATE__ = async (href, options = {}) => {
+    if (options.shallow && navigateShallow(normalizeHref(href), options.replace)) return;
     const navId = ++navigationSeq;
     const target = normalizeHref(href);
     const scrollToTop = options.scrollToTop ?? true;
@@ -482,6 +514,11 @@ function Root(): ReactNode {
       });
       
       await nextNode.thenable;
+      
+      const viewTransitionType = viewTransitionTypeOf(
+        options.pop ? currentRouterState?.transition : nextNode.routerState?.transition,
+        !options.pop,
+      );
       const committed = commitLatestRscNavigation({
         cache: rscCache,
         href: target,
@@ -489,13 +526,16 @@ function Root(): ReactNode {
         maxEntries: MAX_RSC_CACHE_ENTRIES,
         startTransition,
         commitThenable: (node) => {
+          if (viewTransitionType && addTransitionType) {
+            addTransitionType("akan-nav");
+            addTransitionType(viewTransitionType);
+          }
           currentCommitFromCache = servedFromCache;
           resetAkanSegmentOutletPatches();
           setThenable(node.thenable);
         },
         updateHistory: () => {
-          if (options.replace) window.history.replaceState(null, "", target);
-          else window.history.pushState(null, "", target);
+          commitHistory(target, options.replace);
         },
         scrollToTop,
         bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
@@ -514,11 +554,16 @@ function Root(): ReactNode {
   return use(thenable as Usable<ReactNode>);
 }
 
-window.addEventListener("popstate", () => {
+window.addEventListener("popstate", (event) => {
+  const here = normalizeHref(window.location.href);
+  const shallowEntry = (event.state as { __akanRouter?: { shallow?: boolean } } | null)?.__akanRouter?.shallow;
+  
+  const keepsPage = pathnameOf(here) === pathnameOf(renderedHref) && (shallowEntry || here === renderedHref);
   
-  void globalThis
-    .__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false })
-    ?.catch((error: unknown) => hardNavigateAfterRscFailure(window.location.href, true, error));
+  if (!keepsPage)
+    void globalThis
+      .__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false, pop: true })
+      ?.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;