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

package/server/resolver/signal.resolver.ts

@@ -19,11 +19,14 @@ import { baseDocumentColumns, documentQueryHelper, getFilterSortByKey, type Quer
 import {
   type AkanJob,
   type AkanJobOptions,
+  type DocumentStore,
   type InjectRegistry,
+  type LiveChange,
   type LiveRegistry,
   type WebsocketAdaptor,
   WebsocketAdaptorRole,
 } from "akanjs/service";
+import { websocketRoomContract } from "../../common/websocketContract";
 import { type Endpoint, type EndpointCls, sliceEndpoint } from "../../signal/endpoint";
 import type { EndpointInfo } from "../../signal/endpointInfo";
 import type { Internal, InternalCls } from "../../signal/internal";
@@ -42,20 +45,25 @@ import type {
 } from "../../signal/types";
 import type { HttpRoutes, LocalPublish, SignalRoutes, WebsocketRoutes } from "../types";
 
-type HttpRouteHandler = (req: Bun.BunRequest) => Response | Promise<Response | undefined> | undefined;
 type LiveChangeListener = (doc: unknown, type: unknown, previous?: unknown) => void;
-type HttpMethodRoutes = Record<string, HttpRouteHandler>;
+type LiveRoute = (next: Record<string, unknown>, previous?: Record<string, unknown>) => Promise<LiveDelivery[]>;
+interface LiveDelivery {
+  roomId: string;
+  payload: LiveEventPayload;
+}
+type HttpMethodRoutes = Record<string, (req: Bun.BunRequest) => Response | Promise<Response | undefined> | undefined>;
 
 export class SignalResolver {
   static logger = new Logger("SignalResolver");
 
   static makeRoomId(key: string, args: unknown[]) {
-    return `${key}${args.length ? "-" : ""}${args.join("-")}`;
+    return websocketRoomContract.idOf(key, args);
   }
   static #localPublish: LocalPublish = () => {
     SignalResolver.logger.verbose(`Local publish is not initialized yet`);
   };
   static readonly #coalescingRooms = new Set<string>();
+  static readonly #liveRoutes = new Map<string, { store: DocumentStore; route: LiveRoute }>();
 
   static coalescesRoom(roomId: string): boolean {
     const separator = roomId.indexOf("-");
@@ -64,13 +72,26 @@ export class SignalResolver {
   static setLocalPublish(localPublish: LocalPublish, websocket: WebsocketAdaptor, live?: LiveRegistry) {
     SignalResolver.#localPublish = localPublish;
     websocket.setEventHandler((roomId, data) => localPublish(roomId, data as object | object[] | Uint8Array));
-
+    
     websocket.onRecovered?.(() => {
       for (const roomId of live?.syncHub.roomIds() ?? []) {
         const payload: LiveEventPayload = { op: "invalidate", id: "" };
         localPublish(roomId, payload);
       }
     });
+    websocket.onChange?.((change) => {
+      void SignalResolver.#routeChange(change, live).catch((error: unknown) =>
+        SignalResolver.logger.warn(`Live routing failed for ${change.refName}: ${String(error)}`),
+      );
+    });
+  }
+  static async #routeChange({ refName, next, previous }: LiveChange, live?: LiveRegistry) {
+    const target = SignalResolver.#liveRoutes.get(refName);
+    if (!target || !live?.syncHub.roomCountOf(refName)) return;
+    await target.route(
+      target.store.deserialize(next) as Record<string, unknown>,
+      previous ? (target.store.deserialize(previous) as Record<string, unknown>) : undefined,
+    );
   }
   static resolveServerSignal(
     serverSignalCls: ServerSignalCls,
@@ -81,7 +102,6 @@ export class SignalResolver {
     const websocket = SignalResolver.#getWebsocket(registry);
     Object.entries(endpointMeta).forEach(([key, endpointInfo]) => {
       if (endpointInfo.type !== "pubsub") throw new Error(`Endpoint ${key} is not a pubsub endpoint`);
-      websocket.registerEndpoint(key, endpointInfo.returns.returnRef as Cls, endpointInfo.returns.arrDepth);
       const isBinaryFrame = endpointInfo.returns.returnRef === Binary && !endpointInfo.returns.arrDepth;
       if (isBinaryFrame && endpointInfo.signalOption.backpressure !== "queue") SignalResolver.#coalescingRooms.add(key);
       let warnedRawBytes = false;
@@ -103,7 +123,7 @@ export class SignalResolver {
           const roomId = SignalResolver.makeRoomId(key, roomArgs);
           if (isBinaryFrame) {
             const bytes = Binary._parse(resolvedData as Uint8Array) as Uint8Array;
-            websocket.publish(roomId, bytes);
+            websocket.publish(roomId, bytes, { coalesce: SignalResolver.coalescesRoom(roomId) });
             SignalResolver.#localPublish(roomId, bytes);
             return;
           }
@@ -134,14 +154,7 @@ export class SignalResolver {
     });
     return serverSignalCls;
   }
-  /**
-   * Attaches the change listeners that feed live rooms, once per model that declares a `.live()` slice.
-   *
-   * Only the document write paths reach here. A query-level write — `updateManyByQuery`, the generated
-   * `update<Filter>` / `remove<Filter>`, `updateById` / `removeById` — is one atomic statement that fires no
-   * document hooks at all, exactly as it fires no cascade, so a model whose fields move that way will not push
-   * those moves to a live list. It is the same blind spot cascade has and it cannot be closed from here.
-   */
+
   static registerLiveSync(
     sliceCls: SliceCls,
     { registry, live }: { registry: InjectRegistry; live: LiveRegistry },
@@ -155,18 +168,20 @@ export class SignalResolver {
       .map(([key]) => `${refName}Live${capitalize(key)}`);
     if (!liveKeys.length) return [];
     const service = live.service.get(refName) as
-      | { listenPost: (type: "create" | "update" | "remove", listener: LiveChangeListener) => unknown }
+      | {
+          listenPost: (type: "create" | "update" | "remove", listener: LiveChangeListener) => unknown;
+          __databaseModel: { __store: DocumentStore };
+        }
       | undefined;
     if (!service) throw new Error(`Live slice on "${refName}" has no service to listen to`);
+    const store = service.__databaseModel.__store;
     const websocket = SignalResolver.#getWebsocket(registry);
-
-    for (const liveKey of liveKeys) websocket.registerEndpoint(liveKey, Any, 0);
-    const publish = async (next: Record<string, unknown>, previous?: Record<string, unknown>) => {
+    const route: LiveRoute = async (next, previous) => {
       const targets = live.syncHub.route(refName, next, previous);
-      if (!targets.length) return;
+      if (!targets.length) return [];
       const id = String(next.id);
       const needsLight = targets.some((target) => !target.invalidate && target.payload === "light");
-
+      
       const light = needsLight
         ? ((await SignalContext.resolveReturn(next, {
             signalContext: null,
@@ -177,15 +192,26 @@ export class SignalResolver {
           })) as object)
         : null;
       const lightData = light ? (serialize(cnst.light, 0, light, "object", {}) as object | null) : null;
-      for (const target of targets) {
+      return targets.map((target) => {
         const payload: LiveEventPayload = target.invalidate
           ? { op: "invalidate", id }
           : { op: target.op, id, light: target.payload === "light" ? lightData : null };
-        websocket.publish(target.roomId, payload);
         SignalResolver.#localPublish(target.roomId, payload);
-      }
+        return { roomId: target.roomId, payload };
+      });
     };
-
+    SignalResolver.#liveRoutes.set(refName, { store, route });
+    const publish = async (next: Record<string, unknown>, previous?: Record<string, unknown>) => {
+      websocket.publishChange?.({
+        refName,
+        next: store.serialize(next),
+        previous: previous ? store.serialize(previous) : undefined,
+      });
+      const delivered = await route(next, previous);
+      
+      if (!websocket.publishChange) for (const { roomId, payload } of delivered) websocket.publish(roomId, payload);
+    };
+    
     const listener: LiveChangeListener = (doc, _type, previous) => {
       void publish(doc as Record<string, unknown>, previous as Record<string, unknown> | undefined).catch(
         (error: unknown) => SignalResolver.logger.warn(`Live publish failed for ${refName}: ${String(error)}`),
@@ -208,7 +234,7 @@ export class SignalResolver {
         case "process": {
           if (!internalInfo.execFn) throw new Error(`Exec function is not set for ${key}`);
           const execFn = internalInfo.execFn.bind(internal);
-
+          
           internal.queue.registerProcessWorker(
             key,
             SignalResolver.#traced(
@@ -222,6 +248,7 @@ export class SignalResolver {
           internal.schedule.registerInit(
             key,
             SignalResolver.#traced(key, () => internalInfo.execFn?.bind(internal)()),
+            { once: internalInfo.signalOption.once },
           );
           break;
         case "destroy":
@@ -262,15 +289,11 @@ export class SignalResolver {
       }
     });
   }
-  /**
-   * Every run of an internal is one `internal:<key>` trace, so the handler's own logs carry a traceId. The
-   * schedule adaptor's started/finished/error lines wrap this call from outside and stay uncorrelated.
-   */
   static #traced<A extends unknown[], R>(key: string, fn: (...args: A) => R) {
     return async (...args: A) =>
       await runTraced(SignalTrace.create(key, "internal", "internal"), async () => await fn(...args));
   }
-  /** Why an internal is not scheduled on this server, or null when it is. `placement` marks a deliberate role split. */
+  
   static getScheduleSkipReason(
     internalInfo: InternalInfo,
     serverMode: "federation" | "batch" | "all",
@@ -290,10 +313,6 @@ export class SignalResolver {
     return null;
   }
 
-  /**
-   * A `process` producer is installed on every server regardless of placement, so a skipped worker means this
-   * server can enqueue jobs that nothing here consumes. Surface that asymmetry instead of failing silently.
-   */
   static #warnMissingProcessWorker(
     key: string,
     internalInfo: InternalInfo,
@@ -305,7 +324,6 @@ export class SignalResolver {
     else SignalResolver.logger.warn(message);
   }
 
-  /** Maps a job payload back onto the internal's declared `msg` args, deserializing each to its declared type. */
   static #getJobArgs(key: string, internalInfo: InternalInfo, job: AkanJob): unknown[] {
     const data = Array.isArray(job.data) ? (job.data as unknown[]) : job.data === undefined ? [] : [job.data];
     return internalInfo.args.map((arg, idx) =>
@@ -376,7 +394,7 @@ export class SignalResolver {
           SignalResolver.#assertLiveSort(refName, key, sliceInfo);
           SignalResolver.#assertLivePauseOn(refName, key, sliceInfo);
           const liveKey = `${refName}Live${capitalizedKey}`;
-
+          
           const liveBuilder = (builder as any).pubsub(Any, {
             ...sliceInfo.signalOption,
             mcp: false,
@@ -457,14 +475,7 @@ export class SignalResolver {
     }) {}
     return SliceEndpoint;
   }
-  /**
-   * The three things about a declared live sort that can be known without a request.
-   *
-   * A client places a new row itself only for a sort it can reproduce, so a sort key naming a field the row does
-   * not carry produces a list that is quietly in the wrong order — the one failure mode with no symptom. The
-   * `_doc` case is a warning rather than a refusal because it is the slice author's call: the two dialects order
-   * a JSON field differently from each other, so there is no single server answer to match.
-   */
+  
   static #assertLiveSort(refName: string, key: string, sliceInfo: SliceInfo) {
     const lightFields = (sliceInfo.light as unknown as { [FIELD_META]?: Record<string, unknown> })[FIELD_META] ?? {};
     for (const sortKey of sliceInfo.liveOption?.sort ?? []) {
@@ -485,7 +496,6 @@ export class SignalResolver {
       }
     }
   }
-  /** Refuses a subscribe carrying an argument the slice named in `pauseOn`, naming the argument it refused on. */
   static #assertNotPaused(
     key: string,
     liveOption: LiveEndpointOption,
@@ -501,13 +511,6 @@ export class SignalResolver {
       );
     }
   }
-  /**
-   * That every argument `pauseOn` names is one this slice has, and one that can actually be empty.
-   *
-   * A name that is not an argument would do nothing at all, and a `param` — which is never nullable, so it is
-   * present on every call — would switch the room off for good rather than while a box is filled. Both are the
-   * kind of mistake whose only symptom is a list that never updates, so neither is allowed to boot.
-   */
   static #assertLivePauseOn(refName: string, key: string, sliceInfo: SliceInfo) {
     for (const name of sliceInfo.liveOption?.pauseOn ?? []) {
       const arg = sliceInfo.args.find((candidate) => candidate.name === name);
@@ -523,10 +526,7 @@ export class SignalResolver {
         );
     }
   }
-  /**
-   * The model's field metadata, which membership routing reads for one thing: whether a path is an array, because
-   * a bare value on an array field means membership rather than equality.
-   */
+  
   static #queryFieldsOf(live: LiveRegistry, refName: string): QueryFieldMap {
     const sliceCls = live.sliceCls.get(refName);
     const doc = sliceCls?.srv.db?.doc as { [FIELD_META]?: QueryFieldMap } | undefined;
@@ -536,11 +536,7 @@ export class SignalResolver {
     Bun.ServerWebSocket<unknown>,
     Map<string, SignalContext<WebSocketExecutionContext>>
   >();
-  /**
-   * Message contexts that registered a lifecycle handler. A message context is otherwise dropped the moment it
-   * answers, so `ws.on("disconnect", …)` from one would land in an object nothing reads again — a silent
-   * no-op beside the same call working from a pubsub subscribe.
-   */
+  
   static #liveWsMessageCtx = new WeakMap<Bun.ServerWebSocket<unknown>, Set<SignalContext<WebSocketExecutionContext>>>();
   static #retainWsContext(ws: Bun.ServerWebSocket<unknown>, context: SignalContext<WebSocketExecutionContext>) {
     const wsCtx = context.getWebSocketContext();
@@ -549,13 +545,7 @@ export class SignalResolver {
     contexts.add(context);
     SignalResolver.#liveWsMessageCtx.set(ws, contexts);
   }
-  /**
-   * Cleanup handlers belong to the app, so one that throws must not take the rest of the teardown with it: a
-   * rejection here would skip `unregisterSocket` and leak the socket's room membership in Redis for good.
-   *
-   * A close ends both the subscription and the connection, so it passes both events — and a handler registered
-   * for both, the way a cleanup that must happen either way is written, runs once rather than twice.
-   */
+
   static async #runLifecycleHandlers(
     contexts: Iterable<SignalContext<WebSocketExecutionContext>>,
     events: ("unsubscribe" | "disconnect")[],
@@ -572,11 +562,7 @@ export class SignalResolver {
       if (result.status === "rejected")
         SignalResolver.logger.error(`WebSocket cleanup handler failed: ${result.reason}`);
   }
-  /**
-   * A path may legitimately carry several methods — a `query` GET and a `mutation` POST sharing a custom `path` —
-   * so methods merge rather than replace. The same method twice leaves one of the two endpoints unreachable with
-   * nothing said about it, and the shadowed half is as easily the guarded one, so it fails the boot instead.
-   */
+  
   static #mountHttpRoute(routes: HttpRoutes, path: string, handlers: HttpMethodRoutes, owner?: string) {
     const table = routes as Record<string, HttpMethodRoutes | undefined>;
     const existing = table[path];
@@ -588,7 +574,6 @@ export class SignalResolver {
     table[path] = { ...existing, ...handlers };
   }
 
-  /** Same rule across endpoint classes, which are resolved one at a time and then folded into one table. */
   static mergeHttpRoutes(target: HttpRoutes, source: HttpRoutes) {
     for (const [path, handlers] of Object.entries((source ?? {}) as Record<string, HttpMethodRoutes>))
       SignalResolver.#mountHttpRoute(target, path, handlers);
@@ -610,7 +595,7 @@ export class SignalResolver {
     const wsRoutes: WebsocketRoutes = {};
     const defaultPrefix = endpointCls.srv.cnst?.refName;
     Object.entries(endpointMeta).forEach(([key, endpointInfo]) => {
-      const servicePrefix = SignalResolver.#resolveServicePrefix(endpointInfo.signalOption.prefix, defaultPrefix);
+      const servicePrefix = SignalResolver.resolveServicePrefix(endpointInfo.signalOption.prefix, defaultPrefix);
       const path = `${servicePrefix}${endpointInfo.getPath(key)}`;
       if (endpointInfo.signalOption.globalPrefix !== undefined) {
         routeOptions[path] = { globalPrefix: endpointInfo.signalOption.globalPrefix };
@@ -625,7 +610,7 @@ export class SignalResolver {
             live,
             middleware,
           }).init();
-
+          
           return (await context.exec()) as Response | undefined;
         });
       if (endpointInfo.signalOption.method && endpointInfo.type !== "mutation")
@@ -640,8 +625,9 @@ export class SignalResolver {
             SignalResolver.#canUsePrimitiveQueryFastPath(endpointInfo, middleware)
               ? {
                   GET: async (req) => {
-                    if (SignalResolver.#hasAuthCredential(req)) return await normalHttpHandler(req);
-
+                    if (req.headers.get("authorization") || cookieHeaderHasAuthToken(req.headers.get("cookie")))
+                      return await normalHttpHandler(req);
+                    
                     return await SignalContext.try(
                       endpoint,
                       endpointInfo,
@@ -679,14 +665,15 @@ export class SignalResolver {
               ).init();
               const subscribe = event === "subscribe";
               const liveOption = endpointInfo.signalOption.live;
-
+              
               const requestRoomId = context.getRoomId(key);
               if (subscribe) {
-
+                
                 if (liveOption) SignalResolver.#assertNotPaused(key, liveOption, endpointInfo, context);
                 const query = await context.exec();
                 const roomId = liveOption ? context.getLiveRoomId(key) : requestRoomId;
-                if (liveOption)
+                const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws) ?? new Map();
+                if (liveOption && !roomCtxMap.has(roomId))
                   live.syncHub.join({
                     refName: liveOption.refName,
                     roomId,
@@ -695,10 +682,8 @@ export class SignalResolver {
                     fields: SignalResolver.#queryFieldsOf(live, liveOption.refName),
                   });
                 ws.subscribe(roomId);
-                const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws) ?? new Map();
                 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 };
@@ -708,13 +693,12 @@ export class SignalResolver {
               const roomId = liveOption ? context.getLiveRoomId(key) : requestRoomId;
               ws.unsubscribe(roomId);
               const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws);
-              if (roomCtxMap) {
-                const roomCtx = roomCtxMap.get(roomId);
-                if (roomCtx) await SignalResolver.#runLifecycleHandlers([roomCtx], ["unsubscribe"]);
+              const roomCtx = roomCtxMap?.get(roomId);
+              if (roomCtxMap && roomCtx) {
+                await SignalResolver.#runLifecycleHandlers([roomCtx], ["unsubscribe"]);
                 roomCtxMap.delete(roomId);
                 if (roomCtxMap.size === 0) SignalResolver.#liveWsPubsubRoomCtx.delete(ws);
                 if (liveOption) live.syncHub.leave(roomId);
-                
                 websocket.leaveRoom(ws, roomId);
                 SignalResolver.logger.verbose(`WebSocket unsubscribed from room ${roomId}`);
               }
@@ -744,7 +728,7 @@ export class SignalResolver {
     return { routes, wsRoutes, routeOptions };
   }
 
-  static #resolveServicePrefix(prefix: false | string | undefined, defaultPrefix?: string): string {
+  static resolveServicePrefix(prefix: false | string | undefined, defaultPrefix?: string): string {
     if (prefix === false || prefix === "") return "";
     const resolved = prefix ?? defaultPrefix;
     if (!resolved) return "";
@@ -776,15 +760,6 @@ export class SignalResolver {
     );
   }
 
-  static #hasAuthCredential(req: Request) {
-    return Boolean(req.headers.get("authorization") || cookieHeaderHasAuthToken(req.headers.get("cookie")));
-  }
-
-  /**
-   * Re-checks the guards of every room this socket is subscribed to and drops the ones that no
-   * longer pass. Called when the socket's credential changes: a pubsub room is authorized once at
-   * subscribe time, so without this a signed-out socket would keep receiving its old rooms.
-   */
   static async revalidateWsRooms(
     ws: Bun.ServerWebSocket<any>,
     registry: InjectRegistry,
@@ -816,7 +791,7 @@ export class SignalResolver {
     const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws);
     const contexts = [...(roomCtxMap?.values() ?? []), ...(SignalResolver.#liveWsMessageCtx.get(ws) ?? [])];
     await SignalResolver.#runLifecycleHandlers(contexts, ["unsubscribe", "disconnect"]);
-
+    
     for (const roomId of roomCtxMap?.keys() ?? []) live?.syncHub.leave(roomId);
     SignalResolver.#liveWsPubsubRoomCtx.delete(ws);
     SignalResolver.#liveWsMessageCtx.delete(ws);

package/server/routeElementComposer.tsx

@@ -10,9 +10,13 @@ import type {
 } from "akanjs/client";
 import { Children, cloneElement, isValidElement, type ReactElement, type ReactNode, Suspense } from "react";
 import { getExplicitPageConfigKeys, resolvePageState } from "../client/frameConfig";
-import { resolveHeadResult } from "./metadata";
-import { type AkanRouteSegmentState, createAkanRouteSegments, createAkanSegmentOutletKey } from "./routeState";
-import { isAkanRscPartialCommitEnabled } from "./rscPartialCommit";
+import { resolveHeadResult } from "./head";
+import {
+  type AkanRouteSegmentState,
+  createAkanRouteSegments,
+  createAkanSegmentOutletKey,
+  isAkanRscPartialCommitEnabled,
+} from "./routeState";
 import { AkanSegmentOutletReference } from "./rscSegmentOutletReference";
 
 export class RouteElementComposer {
@@ -26,14 +30,7 @@ export class RouteElementComposer {
     const pageConfigChain = await RouteElementComposer.#resolvePageConfigChain(pathRoute);
     return {
       ...pathRoute,
-      pageState: resolvePageState({
-        configChain: pageConfigChain,
-        path: pathRoute.path,
-        basePath: basePath ?? undefined,
-        platform: "web",
-        deviceSafeArea: { top: 0, bottom: 0 },
-        cssSafeArea: { top: 0, bottom: 0 },
-      }),
+      pageState: RouteElementComposer.#webPageState(pageConfigChain, pathRoute.path, basePath),
       pageConfigChain,
       explicitPageConfigKeys: getExplicitPageConfigKeys(pageConfigChain),
     };
@@ -47,9 +44,13 @@ export class RouteElementComposer {
     basePath?: string | null;
   }) {
     const pageConfigChain = await RouteElementComposer.#resolveLayoutPageConfigChain(route);
+    return RouteElementComposer.#webPageState(pageConfigChain, route.path, basePath);
+  }
+
+  static #webPageState(configChain: PageConfig[], path: string, basePath?: string | null) {
     return resolvePageState({
-      configChain: pageConfigChain,
-      path: route.path,
+      configChain,
+      path,
       basePath: basePath ?? undefined,
       platform: "web",
       deviceSafeArea: { top: 0, bottom: 0 },
@@ -118,7 +119,7 @@ export class RouteElementComposer {
     searchParams: Record<string, string | string[]>;
   }): Promise<Head | null | undefined> {
     return (
-      await RouteElementComposer.resolveHeadWithMetadata({
+      await RouteElementComposer.resolveHeadWithSnapshot({
         pathRoute,
         params,
         searchParams,
@@ -126,7 +127,7 @@ export class RouteElementComposer {
     ).node;
   }
 
-  static async resolveHeadWithMetadata({
+  static async resolveHeadWithSnapshot({
     pathRoute,
     params,
     searchParams,
@@ -164,15 +165,7 @@ export class RouteElementComposer {
       if (!fallback) continue;
       const renders = [
         ...layoutStack.slice(0, index + 1),
-        RouteElementComposer.#makeFallbackRouteRender({
-          kind,
-          fallback,
-          params,
-          searchParams,
-          pathname,
-          error,
-          digest,
-        }),
+        RouteElementComposer.#makeFallbackRouteRender({ kind, fallback, pathname, error, digest }),
       ];
       return RouteElementComposer.composeRenders({ renders, params, searchParams });
     }
@@ -207,12 +200,10 @@ export class RouteElementComposer {
         </Suspense>
       );
       const segment = segments?.[i];
-      if (segment?.kind === "page") {
-        const routeSegments = segments;
-        if (!routeSegments) continue;
+      if (segments && segment?.kind === "page") {
         const outletKey =
           createAkanSegmentOutletKey(
-            routeSegments.slice(0, i + 1).map((item) => item.key),
+            segments.slice(0, i + 1).map((item) => item.key),
             i,
           ) ?? segment.key;
         element = <AkanSegmentOutletReference segmentKey={outletKey}>{element}</AkanSegmentOutletReference>;
@@ -221,7 +212,7 @@ export class RouteElementComposer {
     return element;
   }
 
-  static async renderAsync({
+  static AsyncRender = async ({
     routeRender,
     children,
     params,
@@ -231,17 +222,7 @@ export class RouteElementComposer {
     children: ReactNode;
     params: Record<string, string>;
     searchParams: Record<string, string | string[]>;
-  }) {
-    const node = await routeRender.render({ children, params, searchParams } as never);
-    return RouteElementComposer.#normalizeReactNode(node);
-  }
-
-  static AsyncRender = (props: {
-    routeRender: RouteRender;
-    children: ReactNode;
-    params: Record<string, string>;
-    searchParams: Record<string, string | string[]>;
-  }) => RouteElementComposer.renderAsync(props);
+  }) => RouteElementComposer.#normalizeReactNode(await routeRender.render({ children, params, searchParams } as never));
 
   static #makeFallbackRouteRender({
     kind,
@@ -252,18 +233,13 @@ export class RouteElementComposer {
   }: {
     kind: "not-found" | "error";
     fallback: LayoutNotFoundRender | LayoutErrorRender;
-    params: Record<string, string>;
-    searchParams: Record<string, string | string[]>;
     pathname: string;
     error?: unknown;
     digest?: string;
   }): RouteRender {
     return {
       render: (props: { params: Record<string, string>; searchParams: Record<string, string | string[]> }) => {
-        const { params, searchParams } = props as {
-          params: Record<string, string>;
-          searchParams: Record<string, string | string[]>;
-        };
+        const { params, searchParams } = props;
         return kind === "not-found"
           ? (fallback as LayoutNotFoundRender)({ params, searchParams, pathname })
           : (fallback as LayoutErrorRender)({ params, searchParams, pathname, error, digest });
@@ -278,17 +254,12 @@ export class RouteElementComposer {
     const props = node.props as { children?: ReactNode };
     if (!("children" in props)) return node;
 
-    const normalizedChildren = RouteElementComposer.#normalizeReactChildren(props.children);
+    const normalizedChildren = RouteElementComposer.#normalizeReactNode(props.children);
     if (normalizedChildren === props.children) return node;
 
     return cloneElement(node as ReactElement<{ children?: ReactNode }>, undefined, normalizedChildren);
   }
 
-  static #normalizeReactChildren(children: ReactNode): ReactNode {
-    if (Array.isArray(children)) return Children.toArray(children).map(RouteElementComposer.#normalizeReactNode);
-    return RouteElementComposer.#normalizeReactNode(children);
-  }
-
   static #getRenderStack(pathRoute: PathRoute): RouteRender[] {
     return [...pathRoute.renderRootLayouts, ...pathRoute.renderLayouts, pathRoute.renderPage];
   }

package/server/routeState.ts

@@ -73,7 +73,8 @@ function encodeBase64Url(value: string): string {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
 }
 
-function decodeBase64Url(value: string): string | null {
+function decodeBase64UrlJson(value: string | null | undefined): unknown {
+  if (!value) return undefined;
   try {
     const padded = value
       .replace(/-/g, "+")
@@ -82,9 +83,9 @@ function decodeBase64Url(value: string): string | null {
     const binary = atob(padded);
     const bytes = new Uint8Array(binary.length);
     for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
-    return new TextDecoder().decode(bytes);
+    return JSON.parse(new TextDecoder().decode(bytes)) as unknown;
   } catch {
-    return null;
+    return undefined;
   }
 }
 
@@ -150,30 +151,13 @@ export function decodeAkanHeadSnapshot(value: string | null | undefined): AkanHe
   if (new TextEncoder().encode(value).byteLength > AKAN_RSC_HEAD_SNAPSHOT_MAX_HEADER_BYTES) {
     return { status: "too-large" };
   }
-  const json = decodeBase64Url(value);
-  if (!json) return { status: "invalid" };
-  try {
-    const parsed = JSON.parse(json) as unknown;
-    return isAkanHeadSnapshotV1(parsed) ? { status: "ok", snapshot: parsed } : { status: "invalid" };
-  } catch {
-    return { status: "invalid" };
-  }
-}
-
-export function readAkanHeadSnapshotResponseHeader(headers: Headers): AkanHeadSnapshotDecodeResult {
-  return decodeAkanHeadSnapshot(headers.get(AKAN_RSC_PATCH_HEAD_SNAPSHOT_HEADER));
+  const parsed = decodeBase64UrlJson(value);
+  return isAkanHeadSnapshotV1(parsed) ? { status: "ok", snapshot: parsed } : { status: "invalid" };
 }
 
 export function decodeAkanRouterState(value: string | null | undefined): AkanRouterStateV1 | null {
-  if (!value) return null;
-  const json = decodeBase64Url(value);
-  if (!json) return null;
-  try {
-    const parsed = JSON.parse(json) as unknown;
-    return isAkanRouterStateV1(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
+  const parsed = decodeBase64UrlJson(value);
+  return isAkanRouterStateV1(parsed) ? parsed : null;
 }
 
 export function appendAkanRouterStateRequestHeaders(
@@ -195,15 +179,8 @@ export function encodeAkanRscPatchSegmentPath(segmentPath: string[]): string {
 }
 
 export function decodeAkanRscPatchSegmentPath(value: string | null | undefined): string[] | null {
-  if (!value) return null;
-  const json = decodeBase64Url(value);
-  if (!json) return null;
-  try {
-    const parsed = JSON.parse(json) as unknown;
-    return Array.isArray(parsed) && parsed.every((segment) => typeof segment === "string") ? parsed : null;
-  } catch {
-    return null;
-  }
+  const parsed = decodeBase64UrlJson(value);
+  return Array.isArray(parsed) && parsed.every((segment) => typeof segment === "string") ? parsed : null;
 }
 
 export function readAkanRscPatchMetadataResponseHeaders(headers: Headers): AkanRscPatchMetadata | null {
@@ -214,7 +191,7 @@ export function readAkanRscPatchMetadataResponseHeaders(headers: Headers): AkanR
   const segmentPath = decodeAkanRscPatchSegmentPath(headers.get(AKAN_RSC_PATCH_SEGMENT_PATH_HEADER));
   if (!Number.isInteger(patchStartIndex) || patchStartIndex < 0 || !patchStartSegmentKey || !segmentPath) return null;
   if (segmentPath[patchStartIndex] !== patchStartSegmentKey) return null;
-  const headSnapshotResult = readAkanHeadSnapshotResponseHeader(headers);
+  const headSnapshotResult = decodeAkanHeadSnapshot(headers.get(AKAN_RSC_PATCH_HEAD_SNAPSHOT_HEADER));
   return {
     patchStartIndex,
     patchStartSegmentKey,
@@ -377,3 +354,7 @@ export function countCommonRouteSegments(
   }
   return length;
 }
+
+export function isAkanRscPartialCommitEnabled(): boolean {
+  return process.env.AKAN_PUBLIC_RSC_PARTIAL_COMMIT === "1";
+}