akanjs 3.0.0-beta.23 → 3.0.0-beta.24

package/client/csrTypes.ts

@@ -103,6 +103,9 @@ export type LayoutErrorRender = (props: LayoutErrorProps) => PromiseOrObject<Rea
 export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
+  /** CSR: a page's render reads the query; a layout's reads only the params of its own path (`paramNames`). */
+  kind?: "page" | "layout";
+  paramNames?: string[];
   Loading?: LayoutLoadingRender | PageLoadingRender;
   /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
   resolveLoading?: () => void | Promise<void>;
@@ -221,6 +224,7 @@ export interface Location {
   searchParams: { [key: string]: string | string[] };
   pathRoute: PathRoute;
   hash: string;
+  entryId?: string; 
 }
 export type CsrNavigationPhase = "idle" | "preparing" | "transitioning";
 export type CsrNavigationKind = "push" | "replace" | "back" | "popForward" | "popBack";
@@ -247,6 +251,7 @@ export interface History {
   idxMap: Map<string, number>;
   cachedLocationMap: Map<string, Location>;
   idx: number;
+  dormant?: Set<string>; 
 }
 
 export interface RouterProps {
@@ -256,14 +261,24 @@ export interface RouterProps {
   back: () => void | Promise<void>;
 }
 
+export type CsrPageType = "current" | "prev" | "pending" | "cached";
+export interface CsrStackEntry {
+  key: string; 
+  location: Location;
+  pageType: CsrPageType;
+  zIndex: number;
+}
+
 export interface RouteState {
   clientWidth: number;
   clientHeight: number;
   location: Location;
   prevLocation: Location | null;
   pendingLocation: Location | null;
+  stackEntries: CsrStackEntry[];
   navigationIntent: NavigationIntent | null;
   phase: CsrNavigationPhase;
+  isBackgrounded: boolean;
   history: RefObject<History>;
   topSafeAreaRef: RefObject<HTMLDivElement | null>;
   bottomSafeAreaRef: RefObject<HTMLDivElement | null>;
@@ -304,7 +319,8 @@ export const useCsr = () => {
 };
 
 export interface PathContextType {
-  pageType: "current" | "prev" | "cached" | "pending";
+  pageType: CsrPageType;
+  pageKey?: string;
   location: Location;
   prefix?: string;
   gestureEnabled: boolean;
@@ -317,6 +333,16 @@ export const usePathCtx = () => {
   return contextValues;
 };
 
+export type PageActivity = "current" | "prev" | "pending" | "hidden";
+export interface PageActivityState {
+  activity: PageActivity;
+  focused: boolean;
+}
+export const pageActivityContext = sharedContext<PageActivityState>("pageActivity", {
+  activity: "current",
+  focused: true,
+});
+
 export interface PathRoute {
   path: string;
   pathSegments: string[];

package/client/native.ts

@@ -35,6 +35,9 @@ export const isNativeApp = () => isNative && (platform === "ios" || platform ===
 
 export const nativePlatform = () => (isNativeApp() ? (platform as "ios" | "android") : null);
 
+export const desktopPlatform = () =>
+  isNative && (platform === "macos" || platform === "windows" || platform === "linux") ? platform : null;
+
 /** http(s) in the in-app browser, anything else (mailto:, tel:) in the app the system picks. */
 export const openExternalUrl = async (url: string) => {
   if (!isNativeApp()) {

package/client/route/RouteDefinition.ts

@@ -17,6 +17,8 @@ export type RouteArgsShape = Record<string, unknown>;
 export type RouteKind = "page" | "layout" | "rootLayout";
 /** Interned: a definition built inside the pages bundle must be recognised by a loader bundled apart from it. */
 export const routeDefinitionMarker = Symbol.for("akan.routeDefinition");
+/** Interned like the marker: the declared args ride on the module's render function, read by the CSR render cache. */
+export const routeArgsMarker = Symbol.for("akan.routeArgs");
 
 type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
 
@@ -44,6 +46,11 @@ export abstract class RouteDefinition<
   #head?: HeadStage<never>;
   #loading?: (args: never) => PromiseOrObject<ReactNode>;
   #render?: (args: never) => PromiseOrObject<ReactNode>;
+  #renderRoute?: {
+    render: (args: never) => PromiseOrObject<ReactNode>;
+    argCount: number;
+    route: (props: RouteRenderProps) => Promise<ReactNode>;
+  };
 
   config(config: PageConfig) {
     this.#config = config;
@@ -122,7 +129,7 @@ export abstract class RouteDefinition<
     const head = this.#head;
     const loading = this.#loading;
     const module: PageModule & LayoutModule = {
-      default: (async (props: RouteRenderProps) => await render(this.#argsOf(props) as never)) as never,
+      default: this.#renderRouteOf(render) as never,
       ...(this.#config ? { pageConfig: this.#config } : {}),
       ...(head === undefined
         ? {}
@@ -143,6 +150,39 @@ export abstract class RouteDefinition<
     return module;
   }
 
+  #renderRouteOf(render: (args: never) => PromiseOrObject<ReactNode>) {
+    const kept = this.#renderRoute;
+    if (kept?.render === render && kept.argCount === this.args.length) return kept.route;
+    const route = async (props: RouteRenderProps) => await render(this.#argsOf(props) as never);
+    Object.defineProperty(route, routeArgsMarker, { value: this.args.map(({ kind, name }) => ({ kind, name })) });
+    this.#renderRoute = { render, argCount: this.args.length, route };
+    return route;
+  }
+
+  /**
+   * What a route's render output depends on: a chain's declared args plus `lang`. A legacy module declares nothing,
+   * so it depends on the params of its own path (`paramNames`, every param when unknown) and, for a page, every
+   * search value — a layout reads no query.
+   */
+  static renderArgsKey(
+    render: unknown,
+    props: { params: Record<string, string>; searchParams?: Record<string, string | string[]> },
+    { isPage, paramNames }: { isPage: boolean; paramNames?: string[] },
+  ): string {
+    const declared = (render as { [routeArgsMarker]?: Pick<RouteArgInfo, "kind" | "name">[] } | null)?.[
+      routeArgsMarker
+    ];
+    const searchParams = props.searchParams ?? {};
+    if (!declared) {
+      const params = paramNames ? paramNames.map((name) => props.params[name]) : props.params;
+      return JSON.stringify([params, isPage ? searchParams : null]);
+    }
+    return JSON.stringify([
+      props.params.lang,
+      ...declared.map(({ kind, name }) => (kind === "param" ? props.params[name] : searchParams[name])),
+    ]);
+  }
+
   #argsOf(props: RouteRenderProps): RouteBaseArgs & Args & Extra {
     const { lang = parseAkanI18nEnv().defaultLocale } = props.params;
     const resolved = this.resolveArgs({ params: props.params, searchParams: props.searchParams ?? {} });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.23",
+  "version": "3.0.0-beta.24",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -200,6 +200,16 @@
       "types": "./types/server/logging/logTailClient.d.ts",
       "import": "./server/logging/logTailClient.ts",
       "default": "./server/logging/logTailClient.ts"
+    },
+    "./server/hmr/csrDevManifest": {
+      "types": "./types/server/hmr/csrDevManifest.d.ts",
+      "import": "./server/hmr/csrDevManifest.ts",
+      "default": "./server/hmr/csrDevManifest.ts"
+    },
+    "./server/hmr/runtimeMetadataFile": {
+      "types": "./types/server/hmr/runtimeMetadataFile.d.ts",
+      "import": "./server/hmr/runtimeMetadataFile.ts",
+      "default": "./server/hmr/runtimeMetadataFile.ts"
     }
   },
   "dependencies": {
@@ -224,13 +234,13 @@
     "ioredis": "^5.10.1",
     "postgres": "^3.4.9",
     "protobufjs": "^8.4.0",
-    "react": "19.2.7",
-    "react-dom": "19.2.7",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "react-icons": "^5.6.0",
-    "react-refresh": "^0.18.0",
-    "react-server-dom-webpack": "^19.2.7",
+    "react-refresh": "^0.19.0",
+    "react-server-dom-webpack": "^19.3.0",
     "react-spring": "^10.0.4",
-    "scheduler": "^0.27.0",
+    "scheduler": "^0.28.0",
     "tailwind-scrollbar": "^4.0.2",
     "typescript": "^6.0.3"
   },

package/server/akanApp.ts

@@ -762,9 +762,7 @@ export class AkanApp {
       return await this.#proxyResponse(req, upstreamRes);
     } catch (error) {
       if (AkanApp.#isUpstreamOpenFailure(error)) {
-        this.logger.error(
-          `Child ${child.idx}/${child.role} upstream is unreachable (${socketPath}); restarting`,
-        );
+        this.logger.error(`Child ${child.idx}/${child.role} upstream is unreachable (${socketPath}); restarting`);
         this.#scheduleChildRestart(child, child.proc, "upstream-open-failed");
         return AkanApp.#unavailableResponse(req, "Federation child upstream is unreachable; restarting");
       }
@@ -1055,6 +1053,7 @@ export class AkanApp {
       case "invalidate":
       case "css-updated":
       case "pages-updated":
+      case "csr-updated":
       case "build-status":
         this.#fanoutToFederation(message);
         return;

package/server/artifact/builderRpc.ts

@@ -8,6 +8,7 @@ import type {
   BuilderRes,
   BuildRouteClientResult,
   BuildRouteResultPayload,
+  CsrUpdatedPayload,
   CssPayload,
   DevBuildStatus,
   PagesBundlePayload,
@@ -19,6 +20,7 @@ export interface BuilderRpcEventHandlers {
   onCssUpdated?: (css: CssPayload) => void;
   /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
   onPagesUpdated?: (bundle: PagesBundlePayload) => void;
+  onCsrUpdated?: (update: CsrUpdatedPayload) => void;
   onBuildStatus?: (status: DevBuildStatus) => void;
 }
 
@@ -59,6 +61,9 @@ export class BuilderRpc {
         case "pages-updated":
           handlers.onPagesUpdated?.(ev.data);
           return;
+        case "csr-updated":
+          handlers.onCsrUpdated?.(ev.data);
+          return;
         case "build-status":
           handlers.onBuildStatus?.(ev.data);
           return;

package/server/artifact/ipcTypes.ts

@@ -94,6 +94,15 @@ export interface BuilderMetrics {
   workCount: number;
 }
 
+export interface CsrUpdatedPayload {
+  generation: number;
+  mode: "registry" | "artifact";
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds?: string[];
+}
+
 export type BuilderEvent =
   
   | { type: "builder-ready"; buildId?: string }
@@ -107,6 +116,7 @@ export type BuilderEvent =
     }
   | { type: "css-updated"; data: CssPayload }
   | { type: "pages-updated"; data: PagesBundlePayload }
+  | { type: "csr-updated"; data: CsrUpdatedPayload }
   | { type: "build-status"; data: DevBuildStatus }
   | { type: "builder-metrics"; data: BuilderMetrics };
 

package/server/hmr/clientScript.ts

@@ -5,8 +5,9 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   self.__AKAN_HMR_INSTALLED__ = true;
   var syncNavigationEnabled = ${JSON.stringify(isSyncNavigationEnabled())};
   var syncNavigationClientId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+  var clientKind = self.__AKAN_HMR_CLIENT__ === "csr" ? "csr" : "ssr";
   var proto = location.protocol === "https:" ? "wss:" : "ws:";
-  var url = proto + "//" + location.host + "/_akan/hmr";
+  var url = proto + "//" + location.host + "/_akan/hmr" + (clientKind === "csr" ? "?client=csr" : "");
   var attempts = 0;
   var socket = null;
   var lastBuildId = null;
@@ -43,7 +44,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     else pendingRefreshRegistrations.push([type, id]);
   };
   self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };
-  ensureRefreshRuntime().catch(function(err){
+  if (clientKind === "ssr") ensureRefreshRuntime().catch(function(err){
     console.warn("[akan-hmr] React Refresh runtime preload failed", err);
   });
 
@@ -56,6 +57,10 @@ export const HMR_CLIENT_SCRIPT = `(function(){
       try { msg = JSON.parse(ev.data); } catch (e){ return; }
       if (!msg || typeof msg.type !== "string") return;
       if (msg.type === "hello") {
+        if (clientKind === "csr") {
+          if (csrGenerationMoved(msg.csrGeneration)) reloadForCsr("missed a CSR update while disconnected");
+          return;
+        }
         if (lastBuildId !== null && msg.buildId !== lastBuildId) {
           location.reload();
           return;
@@ -77,6 +82,10 @@ export const HMR_CLIENT_SCRIPT = `(function(){
         refreshClient(msg);
         return;
       }
+      if (msg.type === "csr-update") {
+        applyCsrUpdate(msg);
+        return;
+      }
       if (msg.type === "css-update") {
         var cssUrl = selectCssUrl(msg.cssAssets);
         if (cssUrl) swapCss(cssUrl);
@@ -112,6 +121,26 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     socket.addEventListener("error", function(){ try { socket && socket.close(); } catch(e){} });
   }
 
+  function csrGenerationMoved(generation){
+    if (typeof generation !== "number") return false;
+    var current = self.__akan ? self.__akan.generation : self.__AKAN_CSR_GENERATION__;
+    return typeof current === "number" && current !== generation;
+  }
+
+  function reloadForCsr(reason){
+    console.warn("[akan-hmr] reloading the CSR page: " + reason);
+    beginHmrOverlay("Reloading...", true);
+    setTimeout(function(){ location.reload(); }, 30);
+  }
+
+  function applyCsrUpdate(msg){
+    if (msg.reload || !self.__akan || typeof self.__akan.hot !== "function") {
+      reloadForCsr(msg.reason || "the CSR bundle was rebuilt");
+      return;
+    }
+    self.__akan.hot(msg);
+  }
+
   function schedule(){
     attempts = Math.min(attempts + 1, 6);
     var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));

package/server/hmr/csrDevManifest.ts

@@ -0,0 +1,25 @@
+export const CSR_DEV_DIRNAME = "csr-dev";
+export const CSR_DEV_ROUTE_PREFIX = "/_akan/csr-dev/";
+export const CSR_DEV_APP_FILE = "app.js";
+export const CSR_DEV_MANIFEST_FILE = "manifest.json";
+
+export type DevCsrMode = "registry" | "artifact";
+
+export interface CsrDevManifest {
+  version: 1;
+  generation: number;
+  vendorFile: string;
+  entries: Record<string, string>;
+}
+
+/** Where each module's generated code starts in a combined file (`app.js`, a patch), for its source map. */
+export interface CsrDevLayout {
+  lineCount: number;
+  modules: [id: string, line: number][];
+}
+
+export const csrDevModuleFile = (id: string, extension: ".js" | ".js.map") =>
+  `modules/${Bun.hash(id).toString(36)}${extension}`;
+
+export const resolveDevCsrMode = (env: Record<string, string | undefined> = process.env): DevCsrMode =>
+  env.AKAN_DEV_CSR === "artifact" ? "artifact" : "registry";